first commit

curl/docs/libcurl/ABI.md

@@ -0,0 +1,63 @@
+ABI - Application Binary Interface
+==================================
+
+ "ABI" describes the low-level interface between an application program and a
+ library. Calling conventions, function arguments, return values, struct
+ sizes/defines and more.
+
+ [Wikipedia has a longer description](https://en.wikipedia.org/wiki/Application_binary_interface)
+
+## Upgrades
+
+ In the vast majority of all cases, a typical libcurl upgrade does not break
+ the ABI at all. Your application can remain using libcurl just as before,
+ only with less bugs and possibly with added new features. You need to read
+ the release notes, and if they mention an ABI break/soname bump, you may have
+ to verify that your application still builds fine and uses libcurl as it now
+ is defined to work.
+
+## Version Numbers
+
+ In libcurl land, you really can't tell by the libcurl version number if that
+ libcurl is binary compatible or not with another libcurl version.
+
+## Soname Bumps
+
+ Whenever there are changes done to the library that will cause an ABI
+ breakage, that may require your application to get attention or possibly be
+ changed to adhere to new things, we will bump the soname. Then the library
+ will get a different output name and thus can in fact be installed in
+ parallel with an older installed lib (on most systems). Thus, old
+ applications built against the previous ABI version will remain working and
+ using the older lib, while newer applications build and use the newer one.
+
+ During the first seven years of libcurl releases, there have only been four
+ ABI breakages.
+
+ We are determined to bump the SONAME as rarely as possible.  Ideally, we
+ never do it again.
+
+## Downgrades
+
+ Going to an older libcurl version from one you're currently using can be a
+ tricky thing. Mostly we add features and options to newer libcurls as that
+ won't break ABI or hamper existing applications. This has the implication
+ that going backwards may get you in a situation where you pick a libcurl that
+ doesn't support the options your application needs. Or possibly you even
+ downgrade so far so you cross an ABI break border and thus a different
+ soname, and then your application may need to adapt to the modified ABI.
+
+## History
+
+ The previous major library soname number bumps (breaking backwards
+ compatibility) have happened the following times:
+
+ 0 - libcurl 7.1,   August 2000
+
+ 1 - libcurl 7.5    December 2000
+
+ 2 - libcurl 7.7    March 2001
+
+ 3 - libcurl 7.12.0 June 2004
+
+ 4 - libcurl 7.16.0 October 2006

curl/docs/libcurl/CMakeLists.txt

@@ -0,0 +1,76 @@
+#***************************************************************************
+#                                  _   _ ____  _
+#  Project                     ___| | | |  _ \| |
+#                             / __| | | | |_) | |
+#                            | (__| |_| |  _ <| |___
+#                             \___|\___/|_| \_\_____|
+#
+# Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+#
+###########################################################################
+# Load man_MANS from shared file
+transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
+include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
+
+function(add_manual_pages _listname)
+  foreach(_file IN LISTS ${_listname})
+    if(_file STREQUAL "libcurl-symbols.3")
+      # Special case, an auto-generated file.
+      set(_srcfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}")
+    else()
+      set(_srcfile "${CMAKE_CURRENT_SOURCE_DIR}/${_file}")
+    endif()
+
+    string(REPLACE ".3" ".html" _htmlfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}")
+    add_custom_command(OUTPUT "${_htmlfile}"
+      COMMAND roffit "--mandir=${CMAKE_CURRENT_SOURCE_DIR}" "${_srcfile}" > "${_htmlfile}"
+      DEPENDS "${_srcfile}"
+      VERBATIM
+    )
+
+    string(REPLACE ".3" ".pdf" _pdffile "${CMAKE_CURRENT_BINARY_DIR}/${_file}")
+    string(REPLACE ".3" ".ps" _psfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}")
+    # XXX any reason why groff -Tpdf (for gropdf) is not used?
+    add_custom_command(OUTPUT "${_pdffile}"
+      COMMAND groff -Tps -man "${_srcfile}" > "${_psfile}"
+      COMMAND ps2pdf "${_psfile}" "${_pdffile}"
+      COMMAND "${CMAKE_COMMAND}" -E remove "${_psfile}"
+      DEPENDS "${_srcfile}"
+      #BYPRODUCTS "${_psfile}"
+      VERBATIM
+    )
+    # "BYPRODUCTS" for add_custom_command requires CMake 3.2. For now hope that
+    # the temporary files are removed (i.e. the command is not interrupted).
+  endforeach()
+endfunction()
+
+add_custom_command(OUTPUT libcurl-symbols.3
+  COMMAND
+    "${PERL_EXECUTABLE}"
+    "${CMAKE_CURRENT_SOURCE_DIR}/mksymbolsmanpage.pl" <
+    "${CMAKE_CURRENT_SOURCE_DIR}/symbols-in-versions" > libcurl-symbols.3
+  DEPENDS
+    "${CMAKE_CURRENT_SOURCE_DIR}/symbols-in-versions"
+    "${CMAKE_CURRENT_SOURCE_DIR}/mksymbolsmanpage.pl"
+  VERBATIM
+)
+
+add_manual_pages(man_MANS)
+
+string(REPLACE ".3" ".html" HTMLPAGES "${man_MANS}")
+string(REPLACE ".3" ".pdf" PDFPAGES "${man_MANS}")
+add_custom_target(html DEPENDS ${HTMLPAGES})
+add_custom_target(pdf DEPENDS ${PDFPAGES})
+
+add_subdirectory(opts)

curl/docs/libcurl/Makefile.am

@@ -0,0 +1,78 @@
+#***************************************************************************
+#                                  _   _ ____  _
+#  Project                     ___| | | |  _ \| |
+#                             / __| | | | |_) | |
+#                            | (__| |_| |  _ <| |___
+#                             \___|\___/|_| \_\_____|
+#
+# Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+#
+###########################################################################
+
+AUTOMAKE_OPTIONS = foreign no-dependencies
+
+SUBDIRS = opts
+
+include Makefile.inc
+
+man_DISTMANS = $(man_MANS:.3=.3.dist)
+
+HTMLPAGES = $(man_MANS:.3=.html)
+
+PDFPAGES = $(man_MANS:.3=.pdf)
+
+m4macrodir = $(datadir)/aclocal
+dist_m4macro_DATA = libcurl.m4
+
+CLEANFILES = $(HTMLPAGES) $(PDFPAGES) $(TESTS) $(man_DISTMANS) \
+  libcurl-symbols.3
+
+EXTRA_DIST = $(man_MANS) ABI.md symbols-in-versions symbols.pl  \
+  mksymbolsmanpage.pl CMakeLists.txt
+MAN2HTML= roffit --mandir=. $< >$@
+
+SUFFIXES = .3 .html
+
+libcurl-symbols.3: $(srcdir)/symbols-in-versions $(srcdir)/mksymbolsmanpage.pl
+	perl $(srcdir)/mksymbolsmanpage.pl < $(srcdir)/symbols-in-versions > $@
+
+html: $(HTMLPAGES)
+	cd opts && $(MAKE) html
+
+.3.html:
+	$(MAN2HTML)
+
+pdf: $(PDFPAGES)
+	cd opts && $(MAKE) pdf
+
+.3.pdf:
+	@(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \
+	groff -Tps -man $< >$$foo.ps; \
+	ps2pdf $$foo.ps $@; \
+	rm $$foo.ps; \
+	echo "converted $< to $@")
+
+# Make sure each option man page is referenced in the main man page
+TESTS = check-easy check-multi
+LOG_COMPILER = $(PERL)
+# The test fails if the log file contains any text
+AM_LOG_FLAGS = -p -e 'die "$$_" if ($$_);'
+
+check-easy: $(srcdir)/curl_easy_setopt.3 $(srcdir)/opts/CURLOPT*.3
+	OPTS="$$(ls $(srcdir)/opts/CURLOPT*.3 | $(SED) -e 's,^.*/,,' -e 's,\.3$$,,')" && \
+	for opt in $$OPTS; do grep "^\.IP $$opt$$" $(srcdir)/curl_easy_setopt.3 >/dev/null || echo Missing $$opt; done > $@
+
+check-multi: $(srcdir)/curl_multi_setopt.3 $(srcdir)/opts/CURLMOPT*.3
+	OPTS="$$(ls $(srcdir)/opts/CURLMOPT*.3 | $(SED) -e 's,^.*/,,' -e 's,\.3$$,,')" && \
+	for opt in $$OPTS; do grep "^\.IP $$opt$$" $(srcdir)/curl_multi_setopt.3 >/dev/null || echo Missing $$opt; done > $@

curl/docs/libcurl/Makefile.inc

@@ -0,0 +1,110 @@
+#***************************************************************************
+#                                  _   _ ____  _
+#  Project                     ___| | | |  _ \| |
+#                             / __| | | | |_) | |
+#                            | (__| |_| |  _ <| |___
+#                             \___|\___/|_| \_\_____|
+#
+# Copyright (C) 2008 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+#
+###########################################################################
+
+# Shared between Makefile.am and CMakeLists.txt
+
+man_MANS = \
+ curl_easy_cleanup.3 \
+ curl_easy_duphandle.3 \
+ curl_easy_escape.3 \
+ curl_easy_getinfo.3 \
+ curl_easy_init.3 \
+ curl_easy_option_by_id.3 \
+ curl_easy_option_by_name.3 \
+ curl_easy_option_next.3 \
+ curl_easy_pause.3 \
+ curl_easy_perform.3 \
+ curl_easy_recv.3 \
+ curl_easy_reset.3 \
+ curl_easy_send.3 \
+ curl_easy_setopt.3 \
+ curl_easy_strerror.3 \
+ curl_easy_unescape.3 \
+ curl_easy_upkeep.3 \
+ curl_escape.3 \
+ curl_formadd.3 \
+ curl_formfree.3 \
+ curl_formget.3 \
+ curl_free.3 \
+ curl_getdate.3 \
+ curl_getenv.3 \
+ curl_global_cleanup.3 \
+ curl_global_init.3 \
+ curl_global_init_mem.3 \
+ curl_global_sslset.3 \
+ curl_mime_addpart.3 \
+ curl_mime_data.3 \
+ curl_mime_data_cb.3 \
+ curl_mime_encoder.3 \
+ curl_mime_filedata.3 \
+ curl_mime_filename.3 \
+ curl_mime_free.3 \
+ curl_mime_headers.3 \
+ curl_mime_init.3 \
+ curl_mime_name.3 \
+ curl_mime_subparts.3 \
+ curl_mime_type.3 \
+ curl_mprintf.3 \
+ curl_multi_add_handle.3 \
+ curl_multi_assign.3 \
+ curl_multi_cleanup.3 \
+ curl_multi_fdset.3 \
+ curl_multi_info_read.3 \
+ curl_multi_init.3 \
+ curl_multi_perform.3 \
+ curl_multi_poll.3 \
+ curl_multi_remove_handle.3 \
+ curl_multi_setopt.3 \
+ curl_multi_socket.3 \
+ curl_multi_socket_action.3 \
+ curl_multi_socket_all.3 \
+ curl_multi_strerror.3 \
+ curl_multi_timeout.3 \
+ curl_multi_wakeup.3 \
+ curl_multi_wait.3 \
+ curl_share_cleanup.3 \
+ curl_share_init.3 \
+ curl_share_setopt.3 \
+ curl_share_strerror.3 \
+ curl_slist_append.3 \
+ curl_slist_free_all.3 \
+ curl_strequal.3 \
+ curl_strnequal.3 \
+ curl_unescape.3 \
+ curl_url.3 \
+ curl_url_cleanup.3 \
+ curl_url_dup.3 \
+ curl_url_get.3 \
+ curl_url_set.3 \
+ curl_version.3 \
+ curl_version_info.3 \
+ libcurl-easy.3 \
+ libcurl-env.3 \
+ libcurl-errors.3 \
+ libcurl-multi.3 \
+ libcurl-security.3 \
+ libcurl-share.3 \
+ libcurl-symbols.3 \
+ libcurl-thread.3 \
+ libcurl-tutorial.3 \
+ libcurl-url.3 \
+ libcurl.3

curl/docs/libcurl/curl_easy_cleanup.3

@@ -0,0 +1,72 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH curl_easy_cleanup 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_cleanup - End a libcurl easy handle
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+.BI "void curl_easy_cleanup(CURL *" handle ");"
+.SH DESCRIPTION
+This function must be the last function to call for an easy session. It is the
+opposite of the \fIcurl_easy_init(3)\fP function and must be called with the
+same \fIhandle\fP as input that a \fIcurl_easy_init(3)\fP call returned.
+
+This might close all connections this handle has used and possibly has kept
+open until now - unless it was attached to a multi handle while doing the
+transfers. Don't call this function if you intend to transfer more files,
+re-using handles is a key to good performance with libcurl.
+
+Occasionally you may get your progress callback or header callback called from
+within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using
+\fIcurl_easy_setopt(3)\fP). Like if libcurl decides to shut down the
+connection and the protocol is of a kind that requires a command/response
+sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP.
+
+Any use of the \fBhandle\fP after this function has been called and have
+returned, is illegal. \fIcurl_easy_cleanup(3)\fP kills the handle and all
+memory associated with it!
+
+Passing in a NULL pointer in \fIhandle\fP will make this function return
+immediately with no action.
+.SH "OLD TIMES"
+For libcurl versions before 7.17,: after you've called this function, you can
+safely remove all the strings you've previously told libcurl to use, as it
+won't use them anymore now.
+.SH RETURN VALUE
+None
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  CURLcode res;
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+  res = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH "SEE ALSO"
+.BR curl_easy_init "(3), " curl_easy_duphandle "(3), "
+.BR curl_easy_reset "(3), "
+.BR curl_multi_cleanup "(3), " curl_multi_remove_handle "(3) "

curl/docs/libcurl/curl_easy_duphandle.3

@@ -0,0 +1,54 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_easy_duphandle 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_duphandle - Clone a libcurl session handle
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+.BI "CURL *curl_easy_duphandle(CURL *"handle ");"
+
+.SH DESCRIPTION
+This function will return a new curl handle, a duplicate, using all the
+options previously set in the input curl \fIhandle\fP. Both handles can
+subsequently be used independently and they must both be freed with
+\fIcurl_easy_cleanup(3)\fP.
+
+All strings that the input handle has been told to point to (as opposed to
+copy) with previous calls to \fIcurl_easy_setopt(3)\fP using char * inputs,
+will be pointed to by the new handle as well. You must therefore make sure to
+keep the data around until both handles have been cleaned up.
+
+The new handle will \fBnot\fP inherit any state information, no connections,
+no SSL sessions and no cookies. It also will not inherit any share object
+states or options (it will be made as if \fICURLOPT_SHARE(3)\fP was set to
+NULL).
+
+In multi-threaded programs, this function must be called in a synchronous way,
+the input handle may not be in use when cloned.
+.SH RETURN VALUE
+If this function returns NULL, something went wrong and no valid handle was
+returned.
+.SH "SEE ALSO"
+.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_easy_reset "(3),"
+.BR curl_global_init "(3)"

curl/docs/libcurl/curl_easy_escape.3

@@ -0,0 +1,69 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH curl_easy_escape 3 "November 09, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_escape - URL encodes the given string
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "char *curl_easy_escape( CURL *" curl ", const char *" string
+.BI ", int "length " );"
+.ad
+.SH DESCRIPTION
+This function converts the given input \fIstring\fP to a URL encoded string
+and returns that as a new allocated string. All input characters that are not
+a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped"
+version (%NN where NN is a two-digit hexadecimal number).
+
+If \fIlength\fP is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on
+the input \fIstring\fP to find out the size. This function does not accept
+input strings longer than \fBCURL_MAX_INPUT_LENGTH\fP (8 MB).
+
+You must \fIcurl_free(3)\fP the returned string when you're done with it.
+.SH ENCODING
+libcurl is typically not aware of, nor does it care about, character
+encodings. \fIcurl_easy_escape(3)\fP encodes the data byte-by-byte into the
+URL encoded version without knowledge or care for what particular character
+encoding the application or the receiving server may assume that the data
+uses.
+
+The caller of \fIcurl_easy_escape(3)\fP must make sure that the data passed in
+to the function is encoded correctly.
+.SH AVAILABILITY
+Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function.
+.SH RETURN VALUE
+A pointer to a null-terminated string or NULL if it failed.
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  char *output = curl_easy_escape(curl, "data to convert", 15);
+  if(output) {
+    printf("Encoded: %s\\n", output);
+    curl_free(output);
+  }
+}
+.fi
+.SH "SEE ALSO"
+.BR curl_easy_unescape "(3), " curl_free "(3), " RFC 3986

curl/docs/libcurl/curl_easy_getinfo.3

@@ -0,0 +1,287 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH curl_easy_getinfo 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_getinfo - extract information from a curl handle
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+.B "CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );"
+
+.SH DESCRIPTION
+Request internal information from the curl session with this function.  The
+third argument \fBMUST\fP be a pointer to a long, a pointer to a char *, a
+pointer to a struct curl_slist * or a pointer to a double (as this
+documentation describes further down).  The data pointed-to will be filled in
+accordingly and can be relied upon only if the function returns CURLE_OK.  Use
+this function AFTER a performed transfer if you want to get transfer related
+data.
+
+You should not free the memory returned by this function unless it is
+explicitly mentioned below.
+.SH AVAILABLE INFORMATION
+The following information can be extracted:
+.IP CURLINFO_EFFECTIVE_METHOD
+Last used HTTP method.
+See \fICURLINFO_EFFECTIVE_METHOD(3)\fP
+.IP CURLINFO_EFFECTIVE_URL
+Last used URL.
+See \fICURLINFO_EFFECTIVE_URL(3)\fP
+.IP CURLINFO_RESPONSE_CODE
+Last received response code.
+See \fICURLINFO_RESPONSE_CODE(3)\fP
+.IP CURLINFO_HTTP_CONNECTCODE
+Last proxy CONNECT response code.
+See \fICURLINFO_HTTP_CONNECTCODE(3)\fP
+.IP CURLINFO_HTTP_VERSION
+The http version used in the connection.
+See \fICURLINFO_HTTP_VERSION(3)\fP
+.IP CURLINFO_FILETIME
+Remote time of the retrieved document. See \fICURLINFO_FILETIME(3)\fP
+.IP CURLINFO_FILETIME_T
+Remote time of the retrieved document. See \fICURLINFO_FILETIME_T(3)\fP
+.IP CURLINFO_TOTAL_TIME
+Total time of previous transfer.
+See \fICURLINFO_TOTAL_TIME(3)\fP
+.IP CURLINFO_TOTAL_TIME_T
+Total time of previous transfer.
+See \fICURLINFO_TOTAL_TIME_T(3)\fP
+.IP CURLINFO_NAMELOOKUP_TIME
+Time from start until name resolving completed.
+See \fICURLINFO_NAMELOOKUP_TIME(3)\fP
+.IP CURLINFO_NAMELOOKUP_TIME_T
+Time from start until name resolving completed.
+See \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP
+.IP CURLINFO_CONNECT_TIME
+Time from start until remote host or proxy completed.
+See \fICURLINFO_CONNECT_TIME(3)\fP
+.IP CURLINFO_CONNECT_TIME_T
+Time from start until remote host or proxy completed.
+See \fICURLINFO_CONNECT_TIME_T(3)\fP
+.IP CURLINFO_APPCONNECT_TIME
+Time from start until SSL/SSH handshake completed.
+See \fICURLINFO_APPCONNECT_TIME(3)\fP
+.IP CURLINFO_APPCONNECT_TIME_T
+Time from start until SSL/SSH handshake completed.
+See \fICURLINFO_APPCONNECT_TIME_T(3)\fP
+.IP CURLINFO_PRETRANSFER_TIME
+Time from start until just before the transfer begins.
+See \fICURLINFO_PRETRANSFER_TIME(3)\fP
+.IP CURLINFO_PRETRANSFER_TIME_T
+Time from start until just before the transfer begins.
+See \fICURLINFO_PRETRANSFER_TIME_T(3)\fP
+.IP CURLINFO_STARTTRANSFER_TIME
+Time from start until just when the first byte is received.
+See \fICURLINFO_STARTTRANSFER_TIME(3)\fP
+.IP CURLINFO_STARTTRANSFER_TIME_T
+Time from start until just when the first byte is received.
+See \fICURLINFO_STARTTRANSFER_TIME_T(3)\fP
+.IP CURLINFO_REDIRECT_TIME
+Time taken for all redirect steps before the final transfer.
+See \fICURLINFO_REDIRECT_TIME(3)\fP
+.IP CURLINFO_REDIRECT_TIME_T
+Time taken for all redirect steps before the final transfer.
+See \fICURLINFO_REDIRECT_TIME_T(3)\fP
+.IP CURLINFO_REDIRECT_COUNT
+Total number of redirects that were followed.
+See \fICURLINFO_REDIRECT_COUNT(3)\fP
+.IP CURLINFO_REDIRECT_URL
+URL a redirect would take you to, had you enabled redirects.
+See \fICURLINFO_REDIRECT_URL(3)\fP
+.IP CURLINFO_SIZE_UPLOAD
+(Deprecated) Number of bytes uploaded.
+See \fICURLINFO_SIZE_UPLOAD(3)\fP
+.IP CURLINFO_SIZE_UPLOAD_T
+Number of bytes uploaded.
+See \fICURLINFO_SIZE_UPLOAD_T(3)\fP
+.IP CURLINFO_SIZE_DOWNLOAD
+(Deprecated) Number of bytes downloaded.
+See \fICURLINFO_SIZE_DOWNLOAD(3)\fP
+.IP CURLINFO_SIZE_DOWNLOAD_T
+Number of bytes downloaded.
+See \fICURLINFO_SIZE_DOWNLOAD_T(3)\fP
+.IP CURLINFO_SPEED_DOWNLOAD
+(Deprecated) Average download speed.
+See \fICURLINFO_SPEED_DOWNLOAD(3)\fP
+.IP CURLINFO_SPEED_DOWNLOAD_T
+Average download speed.
+See \fICURLINFO_SPEED_DOWNLOAD_T(3)\fP
+.IP CURLINFO_SPEED_UPLOAD
+(Deprecated) Average upload speed.
+See \fICURLINFO_SPEED_UPLOAD(3)\fP
+.IP CURLINFO_SPEED_UPLOAD_T
+Average upload speed.
+See \fICURLINFO_SPEED_UPLOAD_T(3)\fP
+.IP CURLINFO_HEADER_SIZE
+Number of bytes of all headers received.
+See \fICURLINFO_HEADER_SIZE(3)\fP
+.IP CURLINFO_REQUEST_SIZE
+Number of bytes sent in the issued HTTP requests.
+See \fICURLINFO_REQUEST_SIZE(3)\fP
+.IP CURLINFO_SSL_VERIFYRESULT
+Certificate verification result.
+See \fICURLINFO_SSL_VERIFYRESULT(3)\fP
+.IP CURLINFO_PROXY_ERROR
+Detailed proxy error.
+See \fICURLINFO_PROXY_ERROR(3)\fP
+.IP CURLINFO_PROXY_SSL_VERIFYRESULT
+Proxy certificate verification result.
+See \fICURLINFO_PROXY_SSL_VERIFYRESULT(3)\fP
+.IP CURLINFO_SSL_ENGINES
+A list of OpenSSL crypto engines.
+See \fICURLINFO_SSL_ENGINES(3)\fP
+.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD
+(Deprecated) Content length from the Content-Length header.
+See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD(3)\fP
+.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T
+Content length from the Content-Length header.
+See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP
+.IP CURLINFO_CONTENT_LENGTH_UPLOAD
+(Deprecated) Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD(3)\fP
+.IP CURLINFO_CONTENT_LENGTH_UPLOAD_T
+Upload size.  See \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP
+.IP CURLINFO_CONTENT_TYPE
+Content type from the Content-Type header.
+See \fICURLINFO_CONTENT_TYPE(3)\fP
+.IP CURLINFO_RETRY_AFTER
+The value from the from the Retry-After header.
+See \fICURLINFO_RETRY_AFTER(3)\fP
+.IP CURLINFO_PRIVATE
+User's private data pointer.
+See \fICURLINFO_PRIVATE(3)\fP
+.IP CURLINFO_HTTPAUTH_AVAIL
+Available HTTP authentication methods.
+See \fICURLINFO_HTTPAUTH_AVAIL(3)\fP
+.IP CURLINFO_PROXYAUTH_AVAIL
+Available HTTP proxy authentication methods.
+See \fICURLINFO_PROXYAUTH_AVAIL(3)\fP
+.IP CURLINFO_OS_ERRNO
+The errno from the last failure to connect.
+See \fICURLINFO_OS_ERRNO(3)\fP
+.IP CURLINFO_NUM_CONNECTS
+Number of new successful connections used for previous transfer.
+See \fICURLINFO_NUM_CONNECTS(3)\fP
+.IP CURLINFO_PRIMARY_IP
+IP address of the last connection.
+See \fICURLINFO_PRIMARY_IP(3)\fP
+.IP CURLINFO_PRIMARY_PORT
+Port of the last connection.
+See \fICURLINFO_PRIMARY_PORT(3)\fP
+.IP CURLINFO_LOCAL_IP
+Local-end IP address of last connection.
+See \fICURLINFO_LOCAL_IP(3)\fP
+.IP CURLINFO_LOCAL_PORT
+Local-end port of last connection.
+See \fICURLINFO_LOCAL_PORT(3)\fP
+.IP CURLINFO_COOKIELIST
+List of all known cookies.
+See \fICURLINFO_COOKIELIST(3)\fP
+.IP CURLINFO_LASTSOCKET
+Last socket used.
+See \fICURLINFO_LASTSOCKET(3)\fP
+.IP CURLINFO_ACTIVESOCKET
+The session's active socket.
+See \fICURLINFO_ACTIVESOCKET(3)\fP
+.IP CURLINFO_FTP_ENTRY_PATH
+The entry path after logging in to an FTP server.
+See \fICURLINFO_FTP_ENTRY_PATH(3)\fP
+.IP CURLINFO_CERTINFO
+Certificate chain.
+See \fICURLINFO_CERTINFO(3)\fP
+.IP CURLINFO_TLS_SSL_PTR
+TLS session info that can be used for further processing.
+See \fICURLINFO_TLS_SSL_PTR(3)\fP
+.IP CURLINFO_TLS_SESSION
+TLS session info that can be used for further processing.  See
+\fICURLINFO_TLS_SESSION(3)\fP. Deprecated option, use
+\fICURLINFO_TLS_SSL_PTR(3)\fP instead!
+.IP CURLINFO_CONDITION_UNMET
+Whether or not a time conditional was met or 304 HTTP response.
+See \fICURLINFO_CONDITION_UNMET(3)\fP
+.IP CURLINFO_RTSP_SESSION_ID
+RTSP session ID.
+See \fICURLINFO_RTSP_SESSION_ID(3)\fP
+.IP CURLINFO_RTSP_CLIENT_CSEQ
+RTSP CSeq that will next be used.
+See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP
+.IP CURLINFO_RTSP_SERVER_CSEQ
+RTSP CSeq that will next be expected.
+See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP
+.IP CURLINFO_RTSP_CSEQ_RECV
+RTSP CSeq last received.
+See \fICURLINFO_RTSP_CSEQ_RECV(3)\fP
+.IP CURLINFO_PROTOCOL
+The protocol used for the connection. (Added in 7.52.0)
+See \fICURLINFO_PROTOCOL(3)\fP
+.IP CURLINFO_SCHEME
+The scheme used for the connection. (Added in 7.52.0)
+See \fICURLINFO_SCHEME(3)\fP
+.SH TIMES
+.nf
+An overview of the six time values available from curl_easy_getinfo()
+
+curl_easy_perform()
+    |
+    |--NAMELOOKUP
+    |--|--CONNECT
+    |--|--|--APPCONNECT
+    |--|--|--|--PRETRANSFER
+    |--|--|--|--|--STARTTRANSFER
+    |--|--|--|--|--|--TOTAL
+    |--|--|--|--|--|--REDIRECT
+.fi
+.IP NAMELOOKUP
+\fICURLINFO_NAMELOOKUP_TIME\fP and \fICURLINFO_NAMELOOKUP_TIME_T\fP.
+The time it took from the start until the name resolving was completed.
+.IP CONNECT
+\fICURLINFO_CONNECT_TIME\fP and \fICURLINFO_CONNECT_TIME_T\fP.
+The time it took from the start until the connect
+to the remote host (or proxy) was completed.
+.IP APPCONNECT
+\fICURLINFO_APPCONNECT_TIME\fP and \fICURLINFO_APPCONNECT_TIME_T\fP.
+The time it took from the start until the SSL
+connect/handshake with the remote host was completed. (Added in 7.19.0)
+The latter is the integer version (measuring microseconds).  (Added in 7.60.0)
+.IP PRETRANSFER
+\fICURLINFO_PRETRANSFER_TIME\fP and \fICURLINFO_PRETRANSFER_TIME_T\fP.
+The time it took from the start until the
+file transfer is just about to begin. This includes all pre-transfer commands
+and negotiations that are specific to the particular protocol(s) involved.
+.IP STARTTRANSFER
+\fICURLINFO_STARTTRANSFER_TIME\fP and \fICURLINFO_STARTTRANSFER_TIME_T\fP.
+The time it took from the start until the
+first byte is received by libcurl.
+.IP TOTAL
+\fICURLINFO_TOTAL_TIME\fP and \fICURLINFO_TOTAL_TIME_T\fP.
+Total time of the previous request.
+.IP REDIRECT
+\fICURLINFO_REDIRECT_TIME\fP and \fICURLINFO_REDIRECT_TIME_T\fP.
+The time it took for all redirection steps
+include name lookup, connect, pretransfer and transfer before final
+transaction was started. So, this is zero if no redirection took place.
+.SH RETURN VALUE
+If the operation was successful, CURLE_OK is returned. Otherwise an
+appropriate error code will be returned.
+.SH "SEE ALSO"
+.BR curl_easy_setopt "(3)"

curl/docs/libcurl/curl_easy_init.3

@@ -0,0 +1,60 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_easy_init 3 "December 31, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_init - Start a libcurl easy session
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+.BI "CURL *curl_easy_init( );"
+.SH DESCRIPTION
+This function must be the first function to call, and it returns a CURL easy
+handle that you must use as input to other functions in the easy
+interface. This call \fBMUST\fP have a corresponding call to
+\fIcurl_easy_cleanup(3)\fP when the operation is complete.
+
+If you did not already call \fIcurl_global_init(3)\fP, \fIcurl_easy_init(3)\fP
+does it automatically.  This may be lethal in multi-threaded cases, since
+\fIcurl_global_init(3)\fP is not thread-safe, and it may result in resource
+problems because there is no corresponding cleanup.
+
+You are strongly advised to not allow this automatic behavior, by calling
+\fIcurl_global_init(3)\fP yourself properly.  See the description in
+\fBlibcurl\fP(3) of global environment requirements for details of how to use
+this function.
+.SH RETURN VALUE
+If this function returns NULL, something went wrong and you cannot use the
+other curl functions.
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  CURLcode res;
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+  res = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH "SEE ALSO"
+.BR curl_easy_cleanup "(3), " curl_global_init "(3), " curl_easy_reset "(3), "
+.BR curl_easy_perform "(3) "

curl/docs/libcurl/curl_easy_option_by_id.3

@@ -0,0 +1,47 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_easy_option_by_id 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_option_by_id - find an easy setopt option by id
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+const struct curl_easyoption *curl_easy_option_by_id(CURLoption id);
+.fi
+.SH DESCRIPTION
+Given a CURLoption \fBid\fP, this function returns a pointer to the
+curl_easyoption struct, holding information about the
+\fIcurl_easy_setopt(3)\fP option using that id. The option id is the CURLOPT_
+prefix ones provided in the standard curl/curl.h header file. This function
+will return the non-aliases version for the cases where there is an alias
+function as well.
+
+If libcurl has no option with the given id, this function returns NULL.
+.SH AVAILABILITY
+This function was added in libcurl 7.73.0
+.SH RETURN VALUE
+A pointer to the curl_easyoption struct for the option or NULL.
+.SH "SEE ALSO"
+.BR curl_easy_option_by_name "(3)," curl_easy_option_next "(3),"
+.BR curl_easy_setopt "(3),"

curl/docs/libcurl/curl_easy_option_by_name.3

@@ -0,0 +1,45 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_easy_option_by_name 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_option_by_name - find an easy setopt option by name
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+const struct curl_easyoption *curl_easy_option_by_name(const char *name);
+.fi
+.SH DESCRIPTION
+Given a \fBname\fP, this function returns a pointer to the curl_easyoption
+struct, holding information about the \fIcurl_easy_setopt(3)\fP option using
+that name. The name should be specified without the "CURLOPT_" prefix and the
+name comparison is made case insensitive.
+
+If libcurl has no option with the given name, this function returns NULL.
+.SH AVAILABILITY
+This function was added in libcurl 7.73.0
+.SH RETURN VALUE
+A pointer to the curl_easyoption struct for the option or NULL.
+.SH "SEE ALSO"
+.BR curl_easy_option_next "(3)," curl_easy_option_by_id "(3),"
+.BR curl_easy_setopt "(3),"

curl/docs/libcurl/curl_easy_option_next.3

@@ -0,0 +1,75 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_easy_option_next 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_option_next - iterate over easy setopt options
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+typedef enum {
+  CURLOT_LONG,    /* long (a range of values) */
+  CURLOT_VALUES,  /*      (a defined set or bitmask) */
+  CURLOT_OFF_T,   /* curl_off_t (a range of values) */
+  CURLOT_OBJECT,  /* pointer (void *) */
+  CURLOT_STRING,  /*         (char * to zero terminated buffer) */
+  CURLOT_SLIST,   /*         (struct curl_slist *) */
+  CURLOT_CBPTR,   /*         (void * passed as-is to a callback) */
+  CURLOT_BLOB,    /* blob (struct curl_blob *) */
+  CURLOT_FUNCTION /* function pointer */
+} curl_easytype;
+
+/* The CURLOPTTYPE_* id ranges can still be used to figure out what type/size
+   to use for curl_easy_setopt() for the given id */
+struct curl_easyoption {
+  const char *name;
+  CURLoption id;
+  curl_easytype type;
+  unsigned int flags;
+};
+
+const struct curl_easyoption *
+curl_easy_option_next(const struct curl_easyoption *prev);
+.fi
+.SH DESCRIPTION
+This function returns a pointer to the first or the next curl_easyoption
+struct, providing an ability to iterate over all known options for
+\fIcurl_easy_setopt(3)\fP in this instance of libcurl.
+
+Pass a \fBNULL\fP argument as \fBprev\fP to get the first option returned, or
+pass in the current option to get the next one returned. If there is no more
+option to return, \fIcurl_easy_option_next(3)\fP returns NULL.
+
+The options returned by this functions are the ones known to this libcurl and
+information about what argument type they want.
+
+If the \fBCURLOT_FLAG_ALIAS\fP bit is set in the flags field, it means the
+name is provided for backwards compatibility as an alias.
+.SH AVAILABILITY
+This function was added in libcurl 7.73.0
+.SH RETURN VALUE
+A pointer to the curl_easyoption struct for the next option or NULL if no more
+options.
+.SH "SEE ALSO"
+.BR curl_easy_option_by_name "(3)," curl_easy_option_by_id "(3),"
+.BR curl_easy_setopt "(3),"

curl/docs/libcurl/curl_easy_pause.3

@@ -0,0 +1,108 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_easy_pause 3 "December 22, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_pause - pause and unpause a connection
+.SH SYNOPSIS
+.nf
+.B #include <curl/curl.h>
+
+.BI "CURLcode curl_easy_pause(CURL *"handle ", int "bitmask ");"
+.fi
+.SH DESCRIPTION
+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 or
+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 transfer is unpaused.
+
+While it may feel tempting, take care and notice that you cannot call this
+function from another thread. To unpause, you may for example call it from the
+progress callback (\fICURLOPT_PROGRESSFUNCTION(3)\fP), which gets called at
+least once per second, even if the connection is paused.
+
+When this function is called to unpause receiving, the chance is high that you
+will get your write callback called before this function returns.
+
+The \fBhandle\fP argument identifies the transfer you want to pause or
+unpause.
+
+A paused transfer is excluded from low speed cancels via the
+\fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer will reset
+the time period required for the low speed limit to be met.
+
+The \fBbitmask\fP argument is a set of bits that sets the new state of the
+connection. The following bits can be used:
+.IP CURLPAUSE_RECV
+Pause receiving data. There will be no data received on this connection until
+this function is called again without this bit set. Thus, the write callback
+(\fICURLOPT_WRITEFUNCTION(3)\fP) won't be called.
+.IP CURLPAUSE_SEND
+Pause sending data. There will be no data sent on this connection until this
+function is called again without this bit set. Thus, the read callback
+(\fICURLOPT_READFUNCTION(3)\fP) won't be called.
+.IP CURLPAUSE_ALL
+Convenience define that pauses both directions.
+.IP CURLPAUSE_CONT
+Convenience define that unpauses both directions.
+.SH RETURN VALUE
+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 MULTIPLEXED
+When a connection is used multiplexed, like for HTTP/2, and one of the
+transfers over the connection is paused and the others continue flowing,
+libcurl might end up buffering contents for the paused transfer. It has to do
+this because it needs to drain the socket for the other transfers and the
+already announced window size for the paused transfer will allow the server to
+continue sending data up to that window size amount. By default, libcurl
+announces a 32 megabyte window size, which thus can make libcurl end up
+buffering 32 megabyte of data for a paused stream.
+
+When such a paused stream is unpaused again, any buffered data will be
+delivered first.
+.SH AVAILABILITY
+Added in libcurl 7.18.0.
+.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
+it in an allocated buffer until the receiving is again unpaused using this
+function.
+
+If the downloaded data is compressed and is asked to get uncompressed
+automatically on download, libcurl will continue to uncompress the entire
+downloaded chunk and it will cache the data uncompressed. This has the side-
+effect that if you download something that is compressed a lot, it can result
+in a very large data amount needing to be allocated to save the data during
+the pause. This said, you should probably consider not using paused receiving
+if you allow libcurl to uncompress data automatically.
+.SH "SEE ALSO"
+.BR curl_easy_cleanup "(3), " curl_easy_reset "(3)"

curl/docs/libcurl/curl_easy_perform.3

@@ -0,0 +1,75 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_easy_perform 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_perform - perform a blocking file transfer
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_easy_perform(CURL *" easy_handle ");"
+.ad
+.SH DESCRIPTION
+Invoke this function after \fIcurl_easy_init(3)\fP and all the
+\fIcurl_easy_setopt(3)\fP calls are made, and will perform the transfer as
+described in the options. It must be called with the same \fBeasy_handle\fP as
+input as the \fIcurl_easy_init(3)\fP 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 \fBeasy_handle\fP. If you intend to transfer more than one file, you are
+even encouraged to do so. libcurl will then attempt to re-use the same
+connection for the following transfers, thus making the operations faster,
+less CPU intense and using less network resources. Just note that you will
+have to use \fIcurl_easy_setopt(3)\fP between the invokes to set options for
+the following curl_easy_perform.
+
+You must never call this function simultaneously from two places using the
+same \fBeasy_handle\fP. Let the function return first before invoking it
+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
+CURLE_OK (0) means everything was ok, non-zero means an error occurred as
+.I <curl/curl.h>
+defines - see \fIlibcurl-errors(3)\fP. If the \fICURLOPT_ERRORBUFFER(3)\fP was
+set with \fIcurl_easy_setopt(3)\fP there will be a readable error message in
+the error buffer when non-zero is returned.
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  CURLcode res;
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+  res = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
+.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), "

curl/docs/libcurl/curl_easy_recv.3

@@ -0,0 +1,85 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH curl_easy_recv 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_recv - receives raw data on an "easy" connection
+.SH SYNOPSIS
+.B #include <curl/easy.h>
+.sp
+.BI "CURLcode curl_easy_recv( CURL *" curl ", void *" buffer ","
+.BI "size_t " buflen ", size_t *" n ");"
+.ad
+.SH DESCRIPTION
+This function receives raw data from the established connection. You may use
+it together with \fIcurl_easy_send(3)\fP to implement custom protocols using
+libcurl. This functionality can be particularly useful if you use proxies
+and/or SSL encryption: libcurl will take care of proxy negotiation and
+connection set-up.
+
+\fBbuffer\fP is a pointer to your buffer that will get the received
+data. \fBbuflen\fP is the maximum amount of data you can get in that
+buffer. The variable \fBn\fP points to will receive the number of received
+bytes.
+
+To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before
+calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that
+\fIcurl_easy_recv(3)\fP does not work on connections that were created without
+this option.
+
+The call will return \fBCURLE_AGAIN\fP if there is no data to read - the
+socket is used in non-blocking mode internally. When \fBCURLE_AGAIN\fP is
+returned, use your operating system facilities like \fIselect(2)\fP to wait
+for data. The socket may be obtained using \fIcurl_easy_getinfo(3)\fP with
+\fICURLINFO_ACTIVESOCKET(3)\fP.
+
+Wait on the socket only if \fIcurl_easy_recv(3)\fP returns \fBCURLE_AGAIN\fP.
+The reason for this is libcurl or the SSL library may internally cache some
+data, therefore you should call \fIcurl_easy_recv(3)\fP until all data is
+read which would include any cached data.
+
+Furthermore if you wait on the socket and it tells you there is data to read,
+\fIcurl_easy_recv(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was
+read was for internal SSL processing, and no other data is available.
+
+.SH AVAILABILITY
+Added in 7.18.2.
+.SH RETURN VALUE
+On success, returns \fBCURLE_OK\fP, stores the received data into
+\fBbuffer\fP, and the number of bytes it actually read into \fB*n\fP.
+
+On failure, returns the appropriate error code.
+
+The function may return \fBCURLE_AGAIN\fP. In this case, use your operating
+system facilities to wait until data can be read, and retry.
+
+Reading exactly 0 bytes indicates a closed connection.
+
+If there's no socket available to use from the previous transfer, this function
+returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
+.SH EXAMPLE
+See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example.
+.SH "SEE ALSO"
+.BR curl_easy_setopt "(3), " curl_easy_perform "(3), "
+.BR curl_easy_getinfo "(3), "
+.BR curl_easy_send "(3) "

curl/docs/libcurl/curl_easy_reset.3

@@ -0,0 +1,45 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_easy_reset 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_reset - reset all options of a libcurl session handle
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+.BI "void curl_easy_reset(CURL *"handle ");"
+
+.SH DESCRIPTION
+Re-initializes all options previously set on a specified CURL handle to the
+default values. This puts back the handle to the same state as it was in when
+it was just created with \fIcurl_easy_init(3)\fP.
+
+It does not change the following information kept in the handle: live
+connections, the Session ID cache, the DNS cache, the cookies, the shares or
+the alt-svc cache.
+.SH AVAILABILITY
+This function was added in libcurl 7.12.1
+.SH RETURN VALUE
+Nothing
+.SH "SEE ALSO"
+.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_easy_setopt "(3),"
+.BR curl_easy_duphandle "(3)"

curl/docs/libcurl/curl_easy_send.3

@@ -0,0 +1,76 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH curl_easy_send 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_send - sends raw data over an "easy" connection
+.SH SYNOPSIS
+.B #include <curl/easy.h>
+.sp
+.BI "CURLcode curl_easy_send( CURL *" curl ", const void *" buffer ","
+.BI " size_t " buflen ", size_t *" n ");"
+.ad
+.SH DESCRIPTION
+This function sends arbitrary data over the established connection. You may
+use it together with \fIcurl_easy_recv(3)\fP to implement custom protocols
+using libcurl. This functionality can be particularly useful if you use
+proxies and/or SSL encryption: libcurl will take care of proxy negotiation and
+connection set-up.
+
+\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want sent.
+The variable \fBn\fP points to will receive the number of sent bytes.
+
+To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before
+calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that
+\fIcurl_easy_send(3)\fP will not work on connections that were created without
+this option.
+
+The call will return \fBCURLE_AGAIN\fP if it's not possible to send data right
+now - the socket is used in non-blocking mode internally. When
+\fBCURLE_AGAIN\fP is returned, use your operating system facilities like
+\fIselect(2)\fP to wait until the socket is writable. The socket may be
+obtained using \fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP.
+
+Furthermore if you wait on the socket and it tells you it's writable,
+\fIcurl_easy_send(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was
+sent was for internal SSL processing, and no other data could be sent.
+
+.SH AVAILABILITY
+Added in 7.18.2.
+.SH RETURN VALUE
+On success, returns \fBCURLE_OK\fP and stores the number of bytes actually
+sent into \fB*n\fP. Note that this may very well be less than the amount you
+wanted to send.
+
+On failure, returns the appropriate error code.
+
+This function may return \fBCURLE_AGAIN\fP. In this case, use your operating
+system facilities to wait until the socket is writable, and retry.
+
+If there's no socket available to use from the previous transfer, this function
+returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
+.SH EXAMPLE
+See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example.
+.SH "SEE ALSO"
+.BR curl_easy_setopt "(3), " curl_easy_perform "(3), " curl_easy_getinfo "(3), "
+.BR curl_easy_recv "(3) "

curl/docs/libcurl/curl_easy_setopt.3

@@ -0,0 +1,684 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH curl_easy_setopt 3 "July 03, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_setopt \- set options for a curl easy handle
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
+.SH DESCRIPTION
+\fIcurl_easy_setopt(3)\fP is used to tell libcurl how to behave. By setting
+the appropriate options, the application can change libcurl's behavior.  All
+options are set with an \fIoption\fP followed by a \fIparameter\fP. That
+parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject
+pointer\fP or a \fBcurl_off_t\fP, depending on what the specific option
+expects. Read this manual carefully as bad input values may cause libcurl to
+behave badly!  You can only set one option in each function call. A typical
+application uses many \fIcurl_easy_setopt(3)\fP calls in the setup phase.
+
+Options set with this function call are valid for all forthcoming transfers
+performed using this \fIhandle\fP.  The options are not in any way reset
+between transfers, so if you want subsequent transfers with different options,
+you must change them between the transfers. You can optionally reset all
+options back to internal default with \fIcurl_easy_reset(3)\fP.
+
+Strings passed to libcurl as 'char *' arguments, are copied by the library;
+thus the string storage associated to the pointer argument may be overwritten
+after \fIcurl_easy_setopt(3)\fP returns. The only exception to this rule is
+really \fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies the string
+\fICURLOPT_COPYPOSTFIELDS(3)\fP has some usage characteristics you need to
+read up on. This function does not accept input strings longer than
+\fBCURL_MAX_INPUT_LENGTH\fP (8 MB).
+
+The order in which the options are set does not matter.
+
+Before version 7.17.0, strings were not copied. Instead the user was forced
+keep them available until libcurl no longer needed them.
+
+The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or
+\fIcurl_easy_duphandle(3)\fP call.
+.SH BEHAVIOR OPTIONS
+.IP CURLOPT_VERBOSE
+Display verbose information. See \fICURLOPT_VERBOSE(3)\fP
+.IP CURLOPT_HEADER
+Include the header in the body output. See \fICURLOPT_HEADER(3)\fP
+.IP CURLOPT_NOPROGRESS
+Shut off the progress meter. See \fICURLOPT_NOPROGRESS(3)\fP
+.IP CURLOPT_NOSIGNAL
+Do not install signal handlers. See \fICURLOPT_NOSIGNAL(3)\fP
+.IP CURLOPT_WILDCARDMATCH
+Transfer multiple files according to a file name pattern. See \fICURLOPT_WILDCARDMATCH(3)\fP
+.SH CALLBACK OPTIONS
+.IP CURLOPT_WRITEFUNCTION
+Callback for writing data. See \fICURLOPT_WRITEFUNCTION(3)\fP
+.IP CURLOPT_WRITEDATA
+Data pointer to pass to the write callback. See \fICURLOPT_WRITEDATA(3)\fP
+.IP CURLOPT_READFUNCTION
+Callback for reading data. See \fICURLOPT_READFUNCTION(3)\fP
+.IP CURLOPT_READDATA
+Data pointer to pass to the read callback. See \fICURLOPT_READDATA(3)\fP
+.IP CURLOPT_IOCTLFUNCTION
+Callback for I/O operations. See \fICURLOPT_IOCTLFUNCTION(3)\fP
+.IP CURLOPT_IOCTLDATA
+Data pointer to pass to the I/O callback. See \fICURLOPT_IOCTLDATA(3)\fP
+.IP CURLOPT_SEEKFUNCTION
+Callback for seek operations. See \fICURLOPT_SEEKFUNCTION(3)\fP
+.IP CURLOPT_SEEKDATA
+Data pointer to pass to the seek callback. See \fICURLOPT_SEEKDATA(3)\fP
+.IP CURLOPT_SOCKOPTFUNCTION
+Callback for sockopt operations. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP
+.IP CURLOPT_SOCKOPTDATA
+Data pointer to pass to the sockopt callback. See \fICURLOPT_SOCKOPTDATA(3)\fP
+.IP CURLOPT_OPENSOCKETFUNCTION
+Callback for socket creation. See \fICURLOPT_OPENSOCKETFUNCTION(3)\fP
+.IP CURLOPT_OPENSOCKETDATA
+Data pointer to pass to the open socket callback. See \fICURLOPT_OPENSOCKETDATA(3)\fP
+.IP CURLOPT_CLOSESOCKETFUNCTION
+Callback for closing socket. See \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP
+.IP CURLOPT_CLOSESOCKETDATA
+Data pointer to pass to the close socket callback. See \fICURLOPT_CLOSESOCKETDATA(3)\fP
+.IP CURLOPT_PROGRESSFUNCTION
+OBSOLETE callback for progress meter. See \fICURLOPT_PROGRESSFUNCTION(3)\fP
+.IP CURLOPT_PROGRESSDATA
+Data pointer to pass to the progress meter callback. See \fICURLOPT_PROGRESSDATA(3)\fP
+.IP CURLOPT_XFERINFOFUNCTION
+Callback for progress meter. See \fICURLOPT_XFERINFOFUNCTION(3)\fP
+.IP CURLOPT_XFERINFODATA
+Data pointer to pass to the progress meter callback. See \fICURLOPT_XFERINFODATA(3)\fP
+.IP CURLOPT_HEADERFUNCTION
+Callback for writing received headers. See \fICURLOPT_HEADERFUNCTION(3)\fP
+.IP CURLOPT_HEADERDATA
+Data pointer to pass to the header callback. See \fICURLOPT_HEADERDATA(3)\fP
+.IP CURLOPT_DEBUGFUNCTION
+Callback for debug information. See \fICURLOPT_DEBUGFUNCTION(3)\fP
+.IP CURLOPT_DEBUGDATA
+Data pointer to pass to the debug callback. See \fICURLOPT_DEBUGDATA(3)\fP
+.IP CURLOPT_SSL_CTX_FUNCTION
+Callback for SSL context logic. See \fICURLOPT_SSL_CTX_FUNCTION(3)\fP
+.IP CURLOPT_SSL_CTX_DATA
+Data pointer to pass to the SSL context callback. See \fICURLOPT_SSL_CTX_DATA(3)\fP
+.IP CURLOPT_CONV_TO_NETWORK_FUNCTION
+Callback for code base conversion. See \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP
+.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
+Callback for code base conversion. See \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP
+.IP CURLOPT_CONV_FROM_UTF8_FUNCTION
+Callback for code base conversion. See \fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP
+.IP CURLOPT_INTERLEAVEFUNCTION
+Callback for RTSP interleaved data. See \fICURLOPT_INTERLEAVEFUNCTION(3)\fP
+.IP CURLOPT_INTERLEAVEDATA
+Data pointer to pass to the RTSP interleave callback. See \fICURLOPT_INTERLEAVEDATA(3)\fP
+.IP CURLOPT_CHUNK_BGN_FUNCTION
+Callback for wildcard download start of chunk. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP
+.IP CURLOPT_CHUNK_END_FUNCTION
+Callback for wildcard download end of chunk. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP
+.IP CURLOPT_CHUNK_DATA
+Data pointer to pass to the chunk callbacks. See \fICURLOPT_CHUNK_DATA(3)\fP
+.IP CURLOPT_FNMATCH_FUNCTION
+Callback for wildcard matching. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP
+.IP CURLOPT_FNMATCH_DATA
+Data pointer to pass to the wildcard matching callback. See \fICURLOPT_FNMATCH_DATA(3)\fP
+.IP CURLOPT_SUPPRESS_CONNECT_HEADERS
+Suppress proxy CONNECT response headers from user callbacks. See \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP
+.IP CURLOPT_RESOLVER_START_FUNCTION
+Callback to be called before a new resolve request is started. See \fICURLOPT_RESOLVER_START_FUNCTION(3)\fP
+.IP CURLOPT_RESOLVER_START_DATA
+Data pointer to pass to resolver start callback. See \fICURLOPT_RESOLVER_START_DATA(3)\fP
+.SH ERROR OPTIONS
+.IP CURLOPT_ERRORBUFFER
+Error message buffer. See \fICURLOPT_ERRORBUFFER(3)\fP
+.IP CURLOPT_STDERR
+stderr replacement stream. See \fICURLOPT_STDERR(3)\fP
+.IP CURLOPT_FAILONERROR
+Fail on HTTP 4xx errors. \fICURLOPT_FAILONERROR(3)\fP
+.IP CURLOPT_KEEP_SENDING_ON_ERROR
+Keep sending on HTTP >= 300 errors. \fICURLOPT_KEEP_SENDING_ON_ERROR(3)\fP
+.SH NETWORK OPTIONS
+.IP CURLOPT_URL
+URL to work on. See \fICURLOPT_URL(3)\fP
+.IP CURLOPT_PATH_AS_IS
+Disable squashing /../ and /./ sequences in the path. See \fICURLOPT_PATH_AS_IS(3)\fP
+.IP CURLOPT_PROTOCOLS
+Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP
+.IP CURLOPT_REDIR_PROTOCOLS
+Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS(3)\fP
+.IP CURLOPT_DEFAULT_PROTOCOL
+Default protocol. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP
+.IP CURLOPT_PROXY
+Proxy to use. See \fICURLOPT_PROXY(3)\fP
+.IP CURLOPT_PRE_PROXY
+Socks proxy to use. See \fICURLOPT_PRE_PROXY(3)\fP
+.IP CURLOPT_PROXYPORT
+Proxy port to use. See \fICURLOPT_PROXYPORT(3)\fP
+.IP CURLOPT_PROXYTYPE
+Proxy type. See \fICURLOPT_PROXYTYPE(3)\fP
+.IP CURLOPT_NOPROXY
+Filter out hosts from proxy use. \fICURLOPT_NOPROXY(3)\fP
+.IP CURLOPT_HTTPPROXYTUNNEL
+Tunnel through the HTTP proxy. \fICURLOPT_HTTPPROXYTUNNEL(3)\fP
+.IP CURLOPT_CONNECT_TO
+Connect to a specific host and port. See \fICURLOPT_CONNECT_TO(3)\fP
+.IP CURLOPT_SOCKS5_AUTH
+Socks5 authentication methods. See \fICURLOPT_SOCKS5_AUTH(3)\fP
+.IP CURLOPT_SOCKS5_GSSAPI_SERVICE
+Socks5 GSSAPI service name. \fICURLOPT_SOCKS5_GSSAPI_SERVICE(3)\fP
+.IP CURLOPT_SOCKS5_GSSAPI_NEC
+Socks5 GSSAPI NEC mode. See \fICURLOPT_SOCKS5_GSSAPI_NEC(3)\fP
+.IP CURLOPT_PROXY_SERVICE_NAME
+Proxy authentication service name. \fICURLOPT_PROXY_SERVICE_NAME(3)\fP
+.IP CURLOPT_HAPROXYPROTOCOL
+Send an HAProxy PROXY protocol v1 header. See \fICURLOPT_HAPROXYPROTOCOL(3)\fP
+.IP CURLOPT_SERVICE_NAME
+Authentication service name. \fICURLOPT_SERVICE_NAME(3)\fP
+.IP CURLOPT_INTERFACE
+Bind connection locally to this. See \fICURLOPT_INTERFACE(3)\fP
+.IP CURLOPT_LOCALPORT
+Bind connection locally to this port. See \fICURLOPT_LOCALPORT(3)\fP
+.IP CURLOPT_LOCALPORTRANGE
+Bind connection locally to port range. See \fICURLOPT_LOCALPORTRANGE(3)\fP
+.IP CURLOPT_DNS_CACHE_TIMEOUT
+Timeout for DNS cache. See \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP
+.IP CURLOPT_DNS_USE_GLOBAL_CACHE
+OBSOLETE Enable global DNS cache. See \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP
+.IP CURLOPT_DOH_URL
+Use this DOH server for name resolves. See \fICURLOPT_DOH_URL(3)\fP
+.IP CURLOPT_BUFFERSIZE
+Ask for alternate buffer size. See \fICURLOPT_BUFFERSIZE(3)\fP
+.IP CURLOPT_PORT
+Port number to connect to. See \fICURLOPT_PORT(3)\fP
+.IP CURLOPT_TCP_FASTOPEN
+Enable TFO, TCP Fast Open. See \fICURLOPT_TCP_FASTOPEN(3)\fP
+.IP CURLOPT_TCP_NODELAY
+Disable the Nagle algorithm. See \fICURLOPT_TCP_NODELAY(3)\fP
+.IP CURLOPT_ADDRESS_SCOPE
+IPv6 scope for local addresses. See \fICURLOPT_ADDRESS_SCOPE(3)\fP
+.IP CURLOPT_TCP_KEEPALIVE
+Enable TCP keep-alive. See \fICURLOPT_TCP_KEEPALIVE(3)\fP
+.IP CURLOPT_TCP_KEEPIDLE
+Idle time before sending keep-alive. See \fICURLOPT_TCP_KEEPIDLE(3)\fP
+.IP CURLOPT_TCP_KEEPINTVL
+Interval between keep-alive probes. See \fICURLOPT_TCP_KEEPINTVL(3)\fP
+.IP CURLOPT_UNIX_SOCKET_PATH
+Path to a Unix domain socket. See \fICURLOPT_UNIX_SOCKET_PATH(3)\fP
+.IP CURLOPT_ABSTRACT_UNIX_SOCKET
+Path to an abstract Unix domain socket. See \fICURLOPT_ABSTRACT_UNIX_SOCKET(3)\fP
+.SH NAMES and PASSWORDS OPTIONS (Authentication)
+.IP CURLOPT_NETRC
+Enable .netrc parsing. See \fICURLOPT_NETRC(3)\fP
+.IP CURLOPT_NETRC_FILE
+\&.netrc file name. See \fICURLOPT_NETRC_FILE(3)\fP
+.IP CURLOPT_USERPWD
+User name and password. See \fICURLOPT_USERPWD(3)\fP
+.IP CURLOPT_PROXYUSERPWD
+Proxy user name and password. See \fICURLOPT_PROXYUSERPWD(3)\fP
+.IP CURLOPT_USERNAME
+User name. See \fICURLOPT_USERNAME(3)\fP
+.IP CURLOPT_PASSWORD
+Password. See \fICURLOPT_PASSWORD(3)\fP
+.IP CURLOPT_LOGIN_OPTIONS
+Login options. See \fICURLOPT_LOGIN_OPTIONS(3)\fP
+.IP CURLOPT_PROXYUSERNAME
+Proxy user name. See \fICURLOPT_PROXYUSERNAME(3)\fP
+.IP CURLOPT_PROXYPASSWORD
+Proxy password. See \fICURLOPT_PROXYPASSWORD(3)\fP
+.IP CURLOPT_HTTPAUTH
+HTTP server authentication methods. See \fICURLOPT_HTTPAUTH(3)\fP
+.IP CURLOPT_TLSAUTH_USERNAME
+TLS authentication user name. See \fICURLOPT_TLSAUTH_USERNAME(3)\fP
+.IP CURLOPT_PROXY_TLSAUTH_USERNAME
+Proxy TLS authentication user name. See \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP
+.IP CURLOPT_TLSAUTH_PASSWORD
+TLS authentication password. See \fICURLOPT_TLSAUTH_PASSWORD(3)\fP
+.IP CURLOPT_PROXY_TLSAUTH_PASSWORD
+Proxy TLS authentication password. See \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP
+.IP CURLOPT_TLSAUTH_TYPE
+TLS authentication methods. See \fICURLOPT_TLSAUTH_TYPE(3)\fP
+.IP CURLOPT_PROXY_TLSAUTH_TYPE
+Proxy TLS authentication methods. See \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP
+.IP CURLOPT_PROXYAUTH
+HTTP proxy authentication methods. See \fICURLOPT_PROXYAUTH(3)\fP
+.IP CURLOPT_SASL_AUTHZID
+SASL authorisation identity (identity to act as). See \fICURLOPT_SASL_AUTHZID(3)\fP
+.IP CURLOPT_SASL_IR
+Enable SASL initial response. See \fICURLOPT_SASL_IR(3)\fP
+.IP CURLOPT_XOAUTH2_BEARER
+OAuth2 bearer token. See \fICURLOPT_XOAUTH2_BEARER(3)\fP
+.IP CURLOPT_DISALLOW_USERNAME_IN_URL
+Don't allow username in URL. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP
+.SH HTTP OPTIONS
+.IP CURLOPT_AUTOREFERER
+Automatically set Referer: header. See \fICURLOPT_AUTOREFERER(3)\fP
+.IP CURLOPT_ACCEPT_ENCODING
+Accept-Encoding and automatic decompressing data. See \fICURLOPT_ACCEPT_ENCODING(3)\fP
+.IP CURLOPT_TRANSFER_ENCODING
+Request Transfer-Encoding. See \fICURLOPT_TRANSFER_ENCODING(3)\fP
+.IP CURLOPT_FOLLOWLOCATION
+Follow HTTP redirects. See \fICURLOPT_FOLLOWLOCATION(3)\fP
+.IP CURLOPT_UNRESTRICTED_AUTH
+Do not restrict authentication to original host. \fICURLOPT_UNRESTRICTED_AUTH(3)\fP
+.IP CURLOPT_MAXREDIRS
+Maximum number of redirects to follow. See \fICURLOPT_MAXREDIRS(3)\fP
+.IP CURLOPT_POSTREDIR
+How to act on redirects after POST. See \fICURLOPT_POSTREDIR(3)\fP
+.IP CURLOPT_PUT
+Issue an HTTP PUT request. See \fICURLOPT_PUT(3)\fP
+.IP CURLOPT_POST
+Issue an HTTP POST request. See \fICURLOPT_POST(3)\fP
+.IP CURLOPT_POSTFIELDS
+Send a POST with this data. See \fICURLOPT_POSTFIELDS(3)\fP
+.IP CURLOPT_POSTFIELDSIZE
+The POST data is this big. See \fICURLOPT_POSTFIELDSIZE(3)\fP
+.IP CURLOPT_POSTFIELDSIZE_LARGE
+The POST data is this big. See \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP
+.IP CURLOPT_COPYPOSTFIELDS
+Send a POST with this data - and copy it. See \fICURLOPT_COPYPOSTFIELDS(3)\fP
+.IP CURLOPT_HTTPPOST
+Multipart formpost HTTP POST. See \fICURLOPT_HTTPPOST(3)\fP
+.IP CURLOPT_REFERER
+Referer: header. See \fICURLOPT_REFERER(3)\fP
+.IP CURLOPT_USERAGENT
+User-Agent: header. See \fICURLOPT_USERAGENT(3)\fP
+.IP CURLOPT_HTTPHEADER
+Custom HTTP headers. See \fICURLOPT_HTTPHEADER(3)\fP
+.IP CURLOPT_HEADEROPT
+Control custom headers. See \fICURLOPT_HEADEROPT(3)\fP
+.IP CURLOPT_PROXYHEADER
+Custom HTTP headers sent to proxy. See \fICURLOPT_PROXYHEADER(3)\fP
+.IP CURLOPT_HTTP200ALIASES
+Alternative versions of 200 OK. See \fICURLOPT_HTTP200ALIASES(3)\fP
+.IP CURLOPT_COOKIE
+Cookie(s) to send. See \fICURLOPT_COOKIE(3)\fP
+.IP CURLOPT_COOKIEFILE
+File to read cookies from. See \fICURLOPT_COOKIEFILE(3)\fP
+.IP CURLOPT_COOKIEJAR
+File to write cookies to. See \fICURLOPT_COOKIEJAR(3)\fP
+.IP CURLOPT_COOKIESESSION
+Start a new cookie session. See \fICURLOPT_COOKIESESSION(3)\fP
+.IP CURLOPT_COOKIELIST
+Add or control cookies. See \fICURLOPT_COOKIELIST(3)\fP
+.IP CURLOPT_ALTSVC
+Specify the Alt-Svc: cache file name. See \fICURLOPT_ALTSVC(3)\fP
+.IP CURLOPT_ALTSVC_CTRL
+Enable and configure Alt-Svc: treatment. See \fICURLOPT_ALTSVC_CTRL(3)\fP
+.IP CURLOPT_HSTS
+Set HSTS cache file. See \fICURLOPT_HSTS(3)\fP
+.IP CURLOPT_HSTS_CTRL
+Enable HSTS. See \fICURLOPT_HSTS_CTRL(3)\fP
+.IP CURLOPT_HSTSREADFUNCTION
+Set HSTS read callback. See \fICURLOPT_HSTSREADFUNCTION(3)\fP
+.IP CURLOPT_HSTSREADDATA
+Pass pointer to the HSTS read callback. See \fICURLOPT_HSTSREADDATA(3)\fP
+.IP CURLOPT_HSTSWRITEFUNCTION
+Set HSTS write callback. See \fICURLOPT_HSTSWRITEFUNCTION(3)\fP
+.IP CURLOPT_HSTSWRITEDATA
+Pass pointer to the HSTS write callback. See \fICURLOPT_HSTSWRITEDATA(3)\fP
+.IP CURLOPT_HTTPGET
+Do an HTTP GET request. See \fICURLOPT_HTTPGET(3)\fP
+.IP CURLOPT_REQUEST_TARGET
+Set the request target. \fICURLOPT_REQUEST_TARGET(3)\fP
+.IP CURLOPT_HTTP_VERSION
+HTTP version to use. \fICURLOPT_HTTP_VERSION(3)\fP
+.IP CURLOPT_HTTP09_ALLOWED
+Allow HTTP/0.9 responses. \fICURLOPT_HTTP09_ALLOWED(3)\fP
+.IP CURLOPT_IGNORE_CONTENT_LENGTH
+Ignore Content-Length. See \fICURLOPT_IGNORE_CONTENT_LENGTH(3)\fP
+.IP CURLOPT_HTTP_CONTENT_DECODING
+Disable Content decoding. See \fICURLOPT_HTTP_CONTENT_DECODING(3)\fP
+.IP CURLOPT_HTTP_TRANSFER_DECODING
+Disable Transfer decoding. See \fICURLOPT_HTTP_TRANSFER_DECODING(3)\fP
+.IP CURLOPT_EXPECT_100_TIMEOUT_MS
+100-continue timeout. See \fICURLOPT_EXPECT_100_TIMEOUT_MS(3)\fP
+.IP CURLOPT_TRAILERFUNCTION
+Set callback for sending trailing headers. See
+\fICURLOPT_TRAILERFUNCTION(3)\fP
+.IP CURLOPT_TRAILERDATA
+Custom pointer passed to the trailing headers callback. See
+\fICURLOPT_TRAILERDATA(3)\fP
+.IP CURLOPT_PIPEWAIT
+Wait on connection to pipeline on it. See \fICURLOPT_PIPEWAIT(3)\fP
+.IP CURLOPT_STREAM_DEPENDS
+This HTTP/2 stream depends on another. See \fICURLOPT_STREAM_DEPENDS(3)\fP
+.IP CURLOPT_STREAM_DEPENDS_E
+This HTTP/2 stream depends on another exclusively. See
+\fICURLOPT_STREAM_DEPENDS_E(3)\fP
+.IP CURLOPT_STREAM_WEIGHT
+Set this HTTP/2 stream's weight. See \fICURLOPT_STREAM_WEIGHT(3)\fP
+.SH SMTP OPTIONS
+.IP CURLOPT_MAIL_FROM
+Address of the sender. See \fICURLOPT_MAIL_FROM(3)\fP
+.IP CURLOPT_MAIL_RCPT
+Address of the recipients. See \fICURLOPT_MAIL_RCPT(3)\fP
+.IP CURLOPT_MAIL_AUTH
+Authentication address. See \fICURLOPT_MAIL_AUTH(3)\fP
+.IP CURLOPT_MAIL_RCPT_ALLLOWFAILS
+Allow RCPT TO command to fail for some recipients. See \fICURLOPT_MAIL_RCPT_ALLLOWFAILS(3)\fP
+.SH TFTP OPTIONS
+.IP CURLOPT_TFTP_BLKSIZE
+TFTP block size. See \fICURLOPT_TFTP_BLKSIZE(3)\fP
+.IP CURLOPT_TFTP_NO_OPTIONS
+Do not send TFTP options requests. See \fICURLOPT_TFTP_NO_OPTIONS(3)\fP
+.SH FTP OPTIONS
+.IP CURLOPT_FTPPORT
+Use active FTP. See \fICURLOPT_FTPPORT(3)\fP
+.IP CURLOPT_QUOTE
+Commands to run before transfer. See \fICURLOPT_QUOTE(3)\fP
+.IP CURLOPT_POSTQUOTE
+Commands to run after transfer. See \fICURLOPT_POSTQUOTE(3)\fP
+.IP CURLOPT_PREQUOTE
+Commands to run just before transfer. See \fICURLOPT_PREQUOTE(3)\fP
+.IP CURLOPT_APPEND
+Append to remote file. See \fICURLOPT_APPEND(3)\fP
+.IP CURLOPT_FTP_USE_EPRT
+Use EPTR. See \fICURLOPT_FTP_USE_EPRT(3)\fP
+.IP CURLOPT_FTP_USE_EPSV
+Use EPSV. See \fICURLOPT_FTP_USE_EPSV(3)\fP
+.IP CURLOPT_FTP_USE_PRET
+Use PRET. See \fICURLOPT_FTP_USE_PRET(3)\fP
+.IP CURLOPT_FTP_CREATE_MISSING_DIRS
+Create missing directories on the remote server. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP
+.IP CURLOPT_FTP_RESPONSE_TIMEOUT
+Timeout for FTP responses. See \fICURLOPT_FTP_RESPONSE_TIMEOUT(3)\fP
+.IP CURLOPT_FTP_ALTERNATIVE_TO_USER
+Alternative to USER. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP
+.IP CURLOPT_FTP_SKIP_PASV_IP
+Ignore the IP address in the PASV response. See \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP
+.IP CURLOPT_FTPSSLAUTH
+Control how to do TLS. See \fICURLOPT_FTPSSLAUTH(3)\fP
+.IP CURLOPT_FTP_SSL_CCC
+Back to non-TLS again after authentication. See \fICURLOPT_FTP_SSL_CCC(3)\fP
+.IP CURLOPT_FTP_ACCOUNT
+Send ACCT command. See \fICURLOPT_FTP_ACCOUNT(3)\fP
+.IP CURLOPT_FTP_FILEMETHOD
+Specify how to reach files. See \fICURLOPT_FTP_FILEMETHOD(3)\fP
+.SH RTSP OPTIONS
+.IP CURLOPT_RTSP_REQUEST
+RTSP request. See \fICURLOPT_RTSP_REQUEST(3)\fP
+.IP CURLOPT_RTSP_SESSION_ID
+RTSP session-id. See \fICURLOPT_RTSP_SESSION_ID(3)\fP
+.IP CURLOPT_RTSP_STREAM_URI
+RTSP stream URI. See \fICURLOPT_RTSP_STREAM_URI(3)\fP
+.IP CURLOPT_RTSP_TRANSPORT
+RTSP Transport: header. See \fICURLOPT_RTSP_TRANSPORT(3)\fP
+.IP CURLOPT_RTSP_CLIENT_CSEQ
+Client CSEQ number. See \fICURLOPT_RTSP_CLIENT_CSEQ(3)\fP
+.IP CURLOPT_RTSP_SERVER_CSEQ
+CSEQ number for RTSP Server->Client request. See \fICURLOPT_RTSP_SERVER_CSEQ(3)\fP
+.IP CURLOPT_AWS_SIGV4
+AWS HTTP V4 Signature. See \fICURLOPT_AWS_SIGV4(3)\fP
+.SH PROTOCOL OPTIONS
+.IP CURLOPT_TRANSFERTEXT
+Use text transfer. See \fICURLOPT_TRANSFERTEXT(3)\fP
+.IP CURLOPT_PROXY_TRANSFER_MODE
+Add transfer mode to URL over proxy. See \fICURLOPT_PROXY_TRANSFER_MODE(3)\fP
+.IP CURLOPT_CRLF
+Convert newlines. See \fICURLOPT_CRLF(3)\fP
+.IP CURLOPT_RANGE
+Range requests. See \fICURLOPT_RANGE(3)\fP
+.IP CURLOPT_RESUME_FROM
+Resume a transfer. See \fICURLOPT_RESUME_FROM(3)\fP
+.IP CURLOPT_RESUME_FROM_LARGE
+Resume a transfer. See \fICURLOPT_RESUME_FROM_LARGE(3)\fP
+.IP CURLOPT_CURLU
+Set URL to work on with CURLU *. See \fICURLOPT_CURLU(3)\fP
+.IP CURLOPT_CUSTOMREQUEST
+Custom request/method. See \fICURLOPT_CUSTOMREQUEST(3)\fP
+.IP CURLOPT_FILETIME
+Request file modification date and time. See \fICURLOPT_FILETIME(3)\fP
+.IP CURLOPT_DIRLISTONLY
+List only. See \fICURLOPT_DIRLISTONLY(3)\fP
+.IP CURLOPT_NOBODY
+Do not get the body contents. See \fICURLOPT_NOBODY(3)\fP
+.IP CURLOPT_INFILESIZE
+Size of file to send. \fICURLOPT_INFILESIZE(3)\fP
+.IP CURLOPT_INFILESIZE_LARGE
+Size of file to send. \fICURLOPT_INFILESIZE_LARGE(3)\fP
+.IP CURLOPT_UPLOAD
+Upload data. See \fICURLOPT_UPLOAD(3)\fP
+.IP CURLOPT_UPLOAD_BUFFERSIZE
+Set upload buffer size. See \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP
+.IP CURLOPT_MIMEPOST
+Post/send MIME data. See \fICURLOPT_MIMEPOST(3)\fP
+.IP CURLOPT_MAXFILESIZE
+Maximum file size to get. See \fICURLOPT_MAXFILESIZE(3)\fP
+.IP CURLOPT_MAXFILESIZE_LARGE
+Maximum file size to get. See \fICURLOPT_MAXFILESIZE_LARGE(3)\fP
+.IP CURLOPT_TIMECONDITION
+Make a time conditional request. See \fICURLOPT_TIMECONDITION(3)\fP
+.IP CURLOPT_TIMEVALUE
+Time value for the time conditional request. See \fICURLOPT_TIMEVALUE(3)\fP
+.IP CURLOPT_TIMEVALUE_LARGE
+Time value for the time conditional request. See \fICURLOPT_TIMEVALUE_LARGE(3)\fP
+.SH CONNECTION OPTIONS
+.IP CURLOPT_TIMEOUT
+Timeout for the entire request. See \fICURLOPT_TIMEOUT(3)\fP
+.IP CURLOPT_TIMEOUT_MS
+Millisecond timeout for the entire request. See \fICURLOPT_TIMEOUT_MS(3)\fP
+.IP CURLOPT_LOW_SPEED_LIMIT
+Low speed limit to abort transfer. See \fICURLOPT_LOW_SPEED_LIMIT(3)\fP
+.IP CURLOPT_LOW_SPEED_TIME
+Time to be below the speed to trigger low speed abort. See \fICURLOPT_LOW_SPEED_TIME(3)\fP
+.IP CURLOPT_MAX_SEND_SPEED_LARGE
+Cap the upload speed to this. See \fICURLOPT_MAX_SEND_SPEED_LARGE(3)\fP
+.IP CURLOPT_MAX_RECV_SPEED_LARGE
+Cap the download speed to this. See \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP
+.IP CURLOPT_MAXCONNECTS
+Maximum number of connections in the connection pool. See \fICURLOPT_MAXCONNECTS(3)\fP
+.IP CURLOPT_FRESH_CONNECT
+Use a new connection. \fICURLOPT_FRESH_CONNECT(3)\fP
+.IP CURLOPT_FORBID_REUSE
+Prevent subsequent connections from re-using this. See \fICURLOPT_FORBID_REUSE(3)\fP
+.IP CURLOPT_MAXAGE_CONN
+Limit the age of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP
+.IP CURLOPT_CONNECTTIMEOUT
+Timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT(3)\fP
+.IP CURLOPT_CONNECTTIMEOUT_MS
+Millisecond timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
+.IP CURLOPT_IPRESOLVE
+IP version to resolve to. See \fICURLOPT_IPRESOLVE(3)\fP
+.IP CURLOPT_CONNECT_ONLY
+Only connect, nothing else. See \fICURLOPT_CONNECT_ONLY(3)\fP
+.IP CURLOPT_USE_SSL
+Use TLS/SSL. See \fICURLOPT_USE_SSL(3)\fP
+.IP CURLOPT_RESOLVE
+Provide fixed/fake name resolves. See \fICURLOPT_RESOLVE(3)\fP
+.IP CURLOPT_DNS_INTERFACE
+Bind name resolves to this interface. See \fICURLOPT_DNS_INTERFACE(3)\fP
+.IP CURLOPT_DNS_LOCAL_IP4
+Bind name resolves to this IP4 address. See \fICURLOPT_DNS_LOCAL_IP4(3)\fP
+.IP CURLOPT_DNS_LOCAL_IP6
+Bind name resolves to this IP6 address. See \fICURLOPT_DNS_LOCAL_IP6(3)\fP
+.IP CURLOPT_DNS_SERVERS
+Preferred DNS servers. See \fICURLOPT_DNS_SERVERS(3)\fP
+.IP CURLOPT_DNS_SHUFFLE_ADDRESSES
+Shuffle addresses before use. See \fICURLOPT_DNS_SHUFFLE_ADDRESSES(3)\fP
+.IP CURLOPT_ACCEPTTIMEOUT_MS
+Timeout for waiting for the server's connect back to be accepted. See \fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP
+.IP CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS
+Timeout for happy eyeballs. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP
+.IP CURLOPT_UPKEEP_INTERVAL_MS
+Sets the interval at which connection upkeep are performed. See
+\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP
+.SH SSL and SECURITY OPTIONS
+.IP CURLOPT_SSLCERT
+Client cert. See \fICURLOPT_SSLCERT(3)\fP
+.IP CURLOPT_SSLCERT_BLOB
+Client cert memory buffer. See \fICURLOPT_SSLCERT_BLOB(3)\fP
+.IP CURLOPT_PROXY_SSLCERT
+Proxy client cert. See \fICURLOPT_PROXY_SSLCERT(3)\fP
+.IP CURLOPT_PROXY_SSLCERT_BLOB
+Proxy client cert memory buffer. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP
+.IP CURLOPT_SSLCERTTYPE
+Client cert type.  See \fICURLOPT_SSLCERTTYPE(3)\fP
+.IP CURLOPT_PROXY_SSLCERTTYPE
+Proxy client cert type.  See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP
+.IP CURLOPT_SSLKEY
+Client key. See \fICURLOPT_SSLKEY(3)\fP
+.IP CURLOPT_SSLKEY_BLOB
+Client key memory buffer. See \fICURLOPT_SSLKEY_BLOB(3)\fP
+.IP CURLOPT_PROXY_SSLKEY
+Proxy client key. See \fICURLOPT_PROXY_SSLKEY(3)\fP
+.IP CURLOPT_PROXY_SSLKEY_BLOB
+Proxy client key. See \fICURLOPT_PROXY_SSLKEY_BLOB(3)\fP
+.IP CURLOPT_SSLKEYTYPE
+Client key type. See \fICURLOPT_SSLKEYTYPE(3)\fP
+.IP CURLOPT_PROXY_SSLKEYTYPE
+Proxy client key type. See \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP
+.IP CURLOPT_KEYPASSWD
+Client key password. See \fICURLOPT_KEYPASSWD(3)\fP
+.IP CURLOPT_PROXY_KEYPASSWD
+Proxy client key password. See \fICURLOPT_PROXY_KEYPASSWD(3)\fP
+.IP CURLOPT_SSL_EC_CURVES
+Set key exchange curves. See \fICURLOPT_SSL_EC_CURVES(3)\fP
+.IP CURLOPT_SSL_ENABLE_ALPN
+Enable use of ALPN. See \fICURLOPT_SSL_ENABLE_ALPN(3)\fP
+.IP CURLOPT_SSL_ENABLE_NPN
+Enable use of NPN. See \fICURLOPT_SSL_ENABLE_NPN(3)\fP
+.IP CURLOPT_SSLENGINE
+Use identifier with SSL engine. See \fICURLOPT_SSLENGINE(3)\fP
+.IP CURLOPT_SSLENGINE_DEFAULT
+Default SSL engine. See \fICURLOPT_SSLENGINE_DEFAULT(3)\fP
+.IP CURLOPT_SSL_FALSESTART
+Enable TLS False Start. See \fICURLOPT_SSL_FALSESTART(3)\fP
+.IP CURLOPT_SSLVERSION
+SSL version to use. See \fICURLOPT_SSLVERSION(3)\fP
+.IP CURLOPT_PROXY_SSLVERSION
+Proxy SSL version to use. See \fICURLOPT_PROXY_SSLVERSION(3)\fP
+.IP CURLOPT_SSL_VERIFYHOST
+Verify the host name in the SSL certificate. See \fICURLOPT_SSL_VERIFYHOST(3)\fP
+.IP CURLOPT_PROXY_SSL_VERIFYHOST
+Verify the host name in the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP
+.IP CURLOPT_SSL_VERIFYPEER
+Verify the SSL certificate. See \fICURLOPT_SSL_VERIFYPEER(3)\fP
+.IP CURLOPT_PROXY_SSL_VERIFYPEER
+Verify the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP
+.IP CURLOPT_SSL_VERIFYSTATUS
+Verify the SSL certificate's status. See \fICURLOPT_SSL_VERIFYSTATUS(3)\fP
+.IP CURLOPT_CAINFO
+CA cert bundle. See \fICURLOPT_CAINFO(3)\fP
+.IP CURLOPT_PROXY_CAINFO
+Proxy CA cert bundle. See \fICURLOPT_PROXY_CAINFO(3)\fP
+.IP CURLOPT_ISSUERCERT
+Issuer certificate. See \fICURLOPT_ISSUERCERT(3)\fP
+.IP CURLOPT_ISSUERCERT_BLOB
+Issuer certificate memory buffer. See \fICURLOPT_ISSUERCERT_BLOB(3)\fP
+.IP CURLOPT_PROXY_ISSUERCERT
+Proxy issuer certificate. See \fICURLOPT_PROXY_ISSUERCERT(3)\fP
+.IP CURLOPT_PROXY_ISSUERCERT_BLOB
+Proxy issuer certificate memory buffer. See \fICURLOPT_PROXY_ISSUERCERT_BLOB(3)\fP
+.IP CURLOPT_CAPATH
+Path to CA cert bundle. See \fICURLOPT_CAPATH(3)\fP
+.IP CURLOPT_PROXY_CAPATH
+Path to proxy CA cert bundle. See \fICURLOPT_PROXY_CAPATH(3)\fP
+.IP CURLOPT_CRLFILE
+Certificate Revocation List. See \fICURLOPT_CRLFILE(3)\fP
+.IP CURLOPT_PROXY_CRLFILE
+Proxy Certificate Revocation List. See \fICURLOPT_PROXY_CRLFILE(3)\fP
+.IP CURLOPT_CERTINFO
+Extract certificate info. See \fICURLOPT_CERTINFO(3)\fP
+.IP CURLOPT_PINNEDPUBLICKEY
+Set pinned SSL public key . See \fICURLOPT_PINNEDPUBLICKEY(3)\fP
+.IP CURLOPT_PROXY_PINNEDPUBLICKEY
+Set the proxy's pinned SSL public key. See
+\fICURLOPT_PROXY_PINNEDPUBLICKEY(3)\fP
+.IP CURLOPT_RANDOM_FILE
+Provide source for entropy random data. See \fICURLOPT_RANDOM_FILE(3)\fP
+.IP CURLOPT_EGDSOCKET
+Identify EGD socket for entropy. See \fICURLOPT_EGDSOCKET(3)\fP
+.IP CURLOPT_SSL_CIPHER_LIST
+Ciphers to use. See \fICURLOPT_SSL_CIPHER_LIST(3)\fP
+.IP CURLOPT_PROXY_SSL_CIPHER_LIST
+Proxy ciphers to use. See \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP
+.IP CURLOPT_TLS13_CIPHERS
+TLS 1.3 cipher suites to use. See \fICURLOPT_TLS13_CIPHERS(3)\fP
+.IP CURLOPT_PROXY_TLS13_CIPHERS
+Proxy TLS 1.3 cipher suites to use. See \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP
+.IP CURLOPT_SSL_SESSIONID_CACHE
+Disable SSL session-id cache. See \fICURLOPT_SSL_SESSIONID_CACHE(3)\fP
+.IP CURLOPT_SSL_OPTIONS
+Control SSL behavior. See \fICURLOPT_SSL_OPTIONS(3)\fP
+.IP CURLOPT_PROXY_SSL_OPTIONS
+Control proxy SSL behavior. See \fICURLOPT_PROXY_SSL_OPTIONS(3)\fP
+.IP CURLOPT_KRBLEVEL
+Kerberos security level. See \fICURLOPT_KRBLEVEL(3)\fP
+.IP CURLOPT_GSSAPI_DELEGATION
+Disable GSS-API delegation. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP
+.SH SSH OPTIONS
+.IP CURLOPT_SSH_AUTH_TYPES
+SSH authentication types. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP
+.IP CURLOPT_SSH_COMPRESSION
+Enable SSH compression. See \fICURLOPT_SSH_COMPRESSION(3)\fP
+.IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
+MD5 of host's public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)\fP
+.IP CURLOPT_SSH_PUBLIC_KEYFILE
+File name of public key. See \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP
+.IP CURLOPT_SSH_PRIVATE_KEYFILE
+File name of private key. See \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP
+.IP CURLOPT_SSH_KNOWNHOSTS
+File name with known hosts. See \fICURLOPT_SSH_KNOWNHOSTS(3)\fP
+.IP CURLOPT_SSH_KEYFUNCTION
+Callback for known hosts handling. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP
+.IP CURLOPT_SSH_KEYDATA
+Custom pointer to pass to ssh key callback. See \fICURLOPT_SSH_KEYDATA(3)\fP
+.SH OTHER OPTIONS
+.IP CURLOPT_PRIVATE
+Private pointer to store. See \fICURLOPT_PRIVATE(3)\fP
+.IP CURLOPT_SHARE
+Share object to use. See \fICURLOPT_SHARE(3)\fP
+.IP CURLOPT_NEW_FILE_PERMS
+Mode for creating new remote files. See \fICURLOPT_NEW_FILE_PERMS(3)\fP
+.IP CURLOPT_NEW_DIRECTORY_PERMS
+Mode for creating new remote directories. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\fP
+.SH TELNET OPTIONS
+.IP CURLOPT_TELNETOPTIONS
+TELNET options. See \fICURLOPT_TELNETOPTIONS(3)\fP
+.SH RETURN VALUE
+\fICURLE_OK\fP (zero) means that the option was set properly, non-zero means an
+error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors(3)\fP
+man page for the full list with descriptions.
+
+Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise
+\fIcurl_easy_setopt(3)\fP returns \fBCURLE_BAD_FUNCTION_ARGUMENT\fP (added in
+7.65.0).
+
+\fBCURLE_BAD_FUNCTION_ARGUMENT\fP is returned when the argument to an option
+is invalid, like perhaps out of range.a
+
+If you try to set an option that libcurl doesn't know about, perhaps because
+the library is too old to support it or the option was removed in a recent
+version, this function will return \fICURLE_UNKNOWN_OPTION\fP. If support for
+the option was disabled at compile-time, it will return
+\fICURLE_NOT_BUILT_IN\fP.
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  CURLcode res;
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+  res = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH "SEE ALSO"
+.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), "
+.BR curl_easy_getinfo "(3), " curl_multi_setopt "(3), "

curl/docs/libcurl/curl_easy_strerror.3

@@ -0,0 +1,41 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_easy_strerror 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_strerror - return string describing error code
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+const char *curl_easy_strerror(CURLcode errornum);
+.SH DESCRIPTION
+The \fIcurl_easy_strerror(3)\fP function returns a string describing the
+CURLcode error code passed in the argument \fIerrornum\fP.
+
+Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more
+specific error descriptions generated at run-time.
+.SH AVAILABILITY
+This function was added in libcurl 7.12.0
+.SH RETURN VALUE
+A pointer to a null-terminated string.
+.SH "SEE ALSO"
+.BR libcurl-errors "(3), " curl_multi_strerror "(3), " curl_share_strerror "(3)"

curl/docs/libcurl/curl_easy_unescape.3

@@ -0,0 +1,55 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH curl_easy_unescape 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_unescape - URL decodes the given string
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "char *curl_easy_unescape( CURL *" curl ", const char *" url
+.BI ", int "inlength ", int *" outlength " );"
+.ad
+.SH DESCRIPTION
+This function converts the given URL encoded input string to a "plain string"
+and returns that in an allocated memory area. All input characters that are
+URL encoded (%XX where XX is a two-digit hexadecimal number) are converted to
+their binary versions.
+
+If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP
+will use strlen() on the input \fIurl\fP string to find out the size.
+
+If \fBoutlength\fP is non-NULL, the function will write the length of the
+returned string in the integer it points to. This allows an escaped string
+containing %00 to still get used properly after unescaping. Since this is a
+pointer to an \fIint\fP type, it can only return a value up to INT_MAX so no
+longer string can be unescaped if the string length is returned in this
+parameter.
+
+You must \fIcurl_free(3)\fP the returned string when you're done with it.
+.SH AVAILABILITY
+Added in 7.15.4 and replaces the old \fIcurl_unescape(3)\fP function.
+.SH RETURN VALUE
+A pointer to a null-terminated string or NULL if it failed.
+.SH "SEE ALSO"
+.BR curl_easy_escape "(3), " curl_free "(3)," RFC 3986

curl/docs/libcurl/curl_easy_upkeep.3

@@ -0,0 +1,78 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH curl_easy_upkeep 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_easy_upkeep - Perform any connection upkeep checks.
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+.BI "CURLcode curl_easy_upkeep(CURL *" handle ");"
+.SH DESCRIPTION
+
+Some protocols have "connection upkeep" mechanisms. These mechanisms usually
+send some traffic on existing connections in order to keep them alive; this
+can prevent connections from being closed due to overzealous firewalls, for
+example.
+
+Currently the only protocol with a connection upkeep mechanism is HTTP/2: when
+the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP
+is called, an HTTP/2 PING frame is sent on the connection.
+
+This function must be explicitly called in order to perform the upkeep work.
+The connection upkeep interval is set with
+\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP.
+
+.SH AVAILABILITY
+Added in 7.62.0.
+.SH RETURN VALUE
+On success, returns \fBCURLE_OK\fP.
+
+On failure, returns the appropriate error code.
+
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  /* Make a connection to an HTTP/2 server. */
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+  /* Set the interval to 30000ms / 30s */
+  curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L);
+
+  curl_easy_perform(curl);
+
+  /* Perform more work here. */
+
+  /* While the connection is being held open, curl_easy_upkeep() can be
+     called. If curl_easy_upkeep() is called and the time since the last
+     upkeep exceeds the interval, then an HTTP/2 PING is sent. */
+  curl_easy_upkeep(curl);
+
+  /* Perform more work here. */
+
+  /* always cleanup */
+  curl_easy_cleanup(curl);
+}
+
+.fi

curl/docs/libcurl/curl_escape.3

@@ -0,0 +1,49 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_escape 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_escape - URL encodes the given string
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "char *curl_escape( const char *" url ", int "length " );"
+.ad
+.SH DESCRIPTION
+Obsolete function. Use \fIcurl_easy_escape(3)\fP instead!
+
+This function will convert the given input string to an URL encoded string and
+return that as a new allocated string. All input characters that are not a-z,
+A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a
+two-digit hexadecimal number).
+
+If the 'length' argument is set to 0, curl_escape() will use strlen() on the
+input 'url' string to find out the size.
+
+You must \fIcurl_free(3)\fP the returned string when you're done with it.
+.SH AVAILABILITY
+Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function will
+be removed in a future release.
+.SH RETURN VALUE
+A pointer to a null-terminated string or NULL if it failed.
+.SH "SEE ALSO"
+.BR curl_unescape "(3), " curl_free "(3), " RFC 2396

curl/docs/libcurl/curl_formadd.3

@@ -0,0 +1,268 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_formadd 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_formadd - add a section to a multipart/formdata HTTP POST
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem,
+.BI "struct curl_httppost ** " lastitem, " ...);"
+.ad
+.SH DESCRIPTION
+This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
+
+curl_formadd() is used to append sections when building a multipart/formdata
+HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
+at a time until you've added all the sections you want included and then you
+pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_HTTPPOST(3)\fP.
+\fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated
+invokes it should be left as set to allow repeated invokes to find the end of
+the list faster.
+
+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\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(3)\fP as usual.
+
+First, there are some basics you need to understand about multipart/formdata
+posts. Each part consists of at least a NAME and a CONTENTS part. If the part
+is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
+Below, we'll discuss what options you use to set these properties in the
+parts you want to add to your post.
+
+The options listed first are for making normal parts. The options from
+\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
+parts.
+.SH OPTIONS
+.IP CURLFORM_COPYNAME
+followed by a string which provides the \fIname\fP of this part. libcurl
+copies the string so your application doesn't need to keep it around after
+this function call. If the name isn't NUL-terminated, you must set its length
+with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to contain
+zero-valued bytes. The copied data will be freed by \fIcurl_formfree(3)\fP.
+.IP CURLFORM_PTRNAME
+followed by a string which provides the \fIname\fP of this part. libcurl
+will use the pointer and refer to the data in your application, so you
+must make sure it remains until curl no longer needs it. If the name
+isn't NUL-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
+The \fIname\fP is not allowed to contain zero-valued bytes.
+.IP CURLFORM_COPYCONTENTS
+followed by a pointer to the contents of this part, the actual data
+to send away. libcurl copies the provided data, so your application doesn't
+need to keep it around after this function call. If the data isn't null
+terminated, or if you'd like it to contain zero bytes, you must
+set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
+data will be freed by \fIcurl_formfree(3)\fP.
+.IP CURLFORM_PTRCONTENTS
+followed by a pointer to the contents of this part, the actual data
+to send away. libcurl will use the pointer and refer to the data in your
+application, so you must make sure it remains until curl no longer needs it.
+If the data isn't NUL-terminated, or if you'd like it to contain zero bytes,
+you must set its length  with \fBCURLFORM_CONTENTSLENGTH\fP.
+.IP CURLFORM_CONTENTLEN
+followed by a curl_off_t value giving the length of the contents. Note that
+for \fICURLFORM_STREAM\fP contents, this option is mandatory.
+
+If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
+the contents to figure out the size. If you really want to send a zero byte
+content then you must make sure strlen() on the data pointer returns zero.
+
+(Option added in 7.46.0)
+.IP CURLFORM_CONTENTSLENGTH
+(This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!)
+
+followed by a long giving the length of the contents. Note that for
+\fICURLFORM_STREAM\fP contents, this option is mandatory.
+
+If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
+the contents to figure out the size. If you really want to send a zero byte
+content then you must make sure strlen() on the data pointer returns zero.
+.IP CURLFORM_FILECONTENT
+followed by a filename, causes that file to be read and its contents used
+as data in this part. This part does \fInot\fP automatically become a file
+upload part simply because its data was read from a file.
+
+The specified file needs to kept around until the associated transfer is done.
+.IP CURLFORM_FILE
+followed by a filename, makes this part a file upload part. It sets the
+\fIfilename\fP field to the basename of the provided filename, it reads the
+contents of the file and passes them as data and sets the content-type if the
+given file match one of the internally known file extensions.  For
+\fBCURLFORM_FILE\fP the user may send one or more files in one part by
+providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
+(and each \fICURLFORM_FILE\fP is allowed to have a
+\fICURLFORM_CONTENTTYPE\fP).
+
+The given upload file has to exist in its full in the file system already when
+the upload starts, as libcurl needs to read the correct file size beforehand.
+
+The specified file needs to kept around until the associated transfer is done.
+.IP CURLFORM_CONTENTTYPE
+is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
+string which provides the content-type for this part, possibly instead of an
+internally chosen one.
+.IP CURLFORM_FILENAME
+is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
+string, it tells libcurl to use the given string as the \fIfilename\fP in the
+file upload part instead of the actual file name.
+.IP CURLFORM_BUFFER
+is used for custom file upload parts without use of \fICURLFORM_FILE\fP.  It
+tells libcurl that the file contents are already present in a buffer.  The
+parameter is a string which provides the \fIfilename\fP field in the content
+header.
+.IP CURLFORM_BUFFERPTR
+is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
+to the buffer to be uploaded. This buffer must not be freed until after
+\fIcurl_easy_cleanup(3)\fP is called. You must also use
+\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
+.IP CURLFORM_BUFFERLENGTH
+is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
+long which gives the length of the buffer.
+.IP CURLFORM_STREAM
+Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
+data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
+to the read callback's fourth argument. If you want the part to look like a
+file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
+when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
+set with the total expected length of the part unless the formpost is sent
+chunked encoded. (Option added in libcurl 7.18.2)
+.IP CURLFORM_ARRAY
+Another possibility to send options to curl_formadd() is the
+\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
+its value. Each curl_forms structure element has a CURLformoption and a char
+pointer. The final element in the array must be a CURLFORM_END. All available
+options can be used in an array, except the CURLFORM_ARRAY option itself!  The
+last argument in such an array must always be \fBCURLFORM_END\fP.
+.IP CURLFORM_CONTENTHEADER
+specifies extra headers for the form POST section.  This takes a curl_slist
+prepared in the usual way using \fBcurl_slist_append\fP and appends the list
+of headers to those libcurl automatically generates. The list must exist while
+the POST occurs, if you free it before the post completes you may experience
+problems.
+
+When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
+the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
+you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
+
+See example below.
+.SH AVAILABILITY
+Deprecated in 7.56.0. Before this release, field names were allowed to
+contain zero-valued bytes. The pseudo-filename "-" to read stdin is
+discouraged although still supported, but data is not read before being
+actually sent: the effective data size can then not be automatically
+determined, resulting in a chunked encoding transfer. Backslashes and
+double quotes in field and file names are now escaped before transmission.
+.SH RETURN VALUE
+0 means everything was ok, non-zero means an error occurred corresponding
+to a CURL_FORMADD_* constant defined in
+.I <curl/curl.h>
+.SH EXAMPLE
+.nf
+
+ struct curl_httppost* post = NULL;
+ struct curl_httppost* last = NULL;
+ char namebuffer[] = "name buffer";
+ long namelength = strlen(namebuffer);
+ char buffer[] = "test buffer";
+ char htmlbuffer[] = "<HTML>test buffer</HTML>";
+ long htmlbufferlength = strlen(htmlbuffer);
+ struct curl_forms forms[3];
+ char file1[] = "my-face.jpg";
+ char file2[] = "your-face.jpg";
+ /* add null character into htmlbuffer, to demonstrate that
+    transfers of buffers containing null characters actually work
+ */
+ htmlbuffer[8] = '\\0';
+
+ /* Add simple name/content section */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
+              CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
+
+ /* Add simple name/content/contenttype section */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
+              CURLFORM_COPYCONTENTS, "<HTML></HTML>",
+              CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
+
+ /* Add name/ptrcontent section */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
+              CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
+
+ /* Add ptrname/ptrcontent section */
+ curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
+              CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
+              namelength, CURLFORM_END);
+
+ /* Add name/ptrcontent/contenttype section */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
+              CURLFORM_PTRCONTENTS, htmlbuffer,
+              CURLFORM_CONTENTSLENGTH, htmlbufferlength,
+              CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
+
+ /* Add simple file section */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
+              CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
+
+ /* Add file/contenttype section */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
+              CURLFORM_FILE, "my-face.jpg",
+              CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
+
+ /* Add two file section */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
+              CURLFORM_FILE, "my-face.jpg",
+              CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
+
+ /* Add two file section using CURLFORM_ARRAY */
+ forms[0].option = CURLFORM_FILE;
+ forms[0].value  = file1;
+ forms[1].option = CURLFORM_FILE;
+ forms[1].value  = file2;
+ forms[2].option  = CURLFORM_END;
+
+ /* Add a buffer to upload */
+ curl_formadd(&post, &last,
+              CURLFORM_COPYNAME, "name",
+              CURLFORM_BUFFER, "data",
+              CURLFORM_BUFFERPTR, record,
+              CURLFORM_BUFFERLENGTH, record_length,
+              CURLFORM_END);
+
+ /* no option needed for the end marker */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
+              CURLFORM_ARRAY, forms, CURLFORM_END);
+ /* Add the content of a file as a normal post text value */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
+              CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
+ /* Set the form info */
+ curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
+
+.SH "SEE ALSO"
+.BR curl_easy_setopt "(3),"
+.BR curl_formfree "(3),"
+.BR curl_mime_init "(3)"

curl/docs/libcurl/curl_formfree.3

@@ -0,0 +1,52 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_formfree 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_formfree - free a previously build multipart/formdata HTTP POST chain
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "void curl_formfree(struct curl_httppost *" form);
+.ad
+.SH DESCRIPTION
+This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
+
+curl_formfree() is used to clean up data previously built/appended with
+\fIcurl_formadd(3)\fP. This must be called when the data has been used, which
+typically means after \fIcurl_easy_perform(3)\fP has been called.
+
+The pointer to free is the same pointer you passed to the
+\fICURLOPT_HTTPPOST(3)\fP option, which is the \fIfirstitem\fP pointer from
+the \fIcurl_formadd(3)\fP invoke(s).
+
+\fBform\fP is the pointer as returned from a previous call to
+\fIcurl_formadd(3)\fP and may be NULL.
+
+Passing in a NULL pointer in \fIform\fP will make this function return
+immediately with no action.
+.SH AVAILABILITY
+Deprecated in 7.56.0.
+.SH RETURN VALUE
+None
+.SH "SEE ALSO"
+.BR curl_formadd "(3), " curl_mime_init "(3), " curl_mime_free "(3)"

curl/docs/libcurl/curl_formget.3

@@ -0,0 +1,72 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_formget 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_formget - serialize a previously built multipart/formdata HTTP POST chain
+.SH SYNOPSIS
+.nf
+.B #include <curl/curl.h>
+
+int curl_formget(struct curl_httppost * form, void *userp,
+                  curl_formget_callback append );
+.SH DESCRIPTION
+curl_formget() is used to serialize data previously built/appended with
+\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named
+\fIuserp\fP which will be passed as the first argument to the
+curl_formget_callback function.
+
+.BI "typedef size_t (*curl_formget_callback)(void *" userp, " const char *" buf,
+.BI " size_t " len ");"
+
+The curl_formget_callback will be executed for each part of the HTTP POST
+chain. The character buffer passed to the callback must not be freed. The
+callback should return the buffer length passed to it on success.
+
+If the \fBCURLFORM_STREAM\fP option is used in the formpost, it will prevent
+\fIcurl_formget(3)\fP from working until you've performed the actual HTTP
+request as only then will libcurl get the actual read callback to use!
+.SH RETURN VALUE
+0 means everything was ok, non-zero means an error occurred
+.SH EXAMPLE
+.nf
+
+ size_t print_httppost_callback(void *arg, const char *buf, size_t len)
+ {
+   fwrite(buf, len, 1, stdout);
+   (*(size_t *) arg) += len;
+   return len;
+ }
+
+ size_t print_httppost(struct curl_httppost *post)
+ {
+   size_t total_size = 0;
+   if(curl_formget(post, &total_size, print_httppost_callback)) {
+     return (size_t) -1;
+   }
+   return total_size;
+ }
+.SH AVAILABILITY
+This function was added in libcurl 7.15.5. The form API is deprecated in
+libcurl 7.56.0.
+.SH "SEE ALSO"
+.BR curl_formadd "(3), " curl_mime_init "(3)"

curl/docs/libcurl/curl_free.3

@@ -0,0 +1,39 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_free 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_free - reclaim memory that has been obtained through a libcurl call
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "void curl_free( char *" ptr " );"
+.ad
+.SH DESCRIPTION
+curl_free reclaims memory that has been obtained through a libcurl call.  Use
+\fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from
+differences in memory management between your application and libcurl.
+
+Passing in a NULL pointer in \fIptr\fP will make this function return
+immediately with no action.
+.SH "SEE ALSO"
+.BR curl_easy_unescape "(3), " curl_easy_escape "(3) "

curl/docs/libcurl/curl_getdate.3

@@ -0,0 +1,111 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_getdate 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_getdate - Convert a date string to number of seconds
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "time_t curl_getdate(char *" datestring ", time_t *"now " );"
+.ad
+.SH DESCRIPTION
+\fIcurl_getdate(3)\fP returns the number of seconds since the Epoch, January
+1st 1970 00:00:00 in the UTC time zone, for the date and time that the
+\fIdatestring\fP parameter specifies. The \fInow\fP parameter is not used,
+pass a NULL there.
+.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
+items:
+.TP 0.8i
+.B calendar date items
+Can be specified several ways. Month names can only be three-letter english
+abbreviations, numbers can be zero-prefixed and the year may use 2 or 4 digits.
+Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6.
+.TP
+.B time of the day items
+This string specifies the time on a given day. You must specify it with 6
+digits with two colons: HH:MM:SS. To not include the time in a date string,
+will make the function assume 00:00:00. Example: 18:19:21.
+.TP
+.B time zone items
+Specifies international time zone. There are a few acronyms supported, but in
+general you should instead use the specific relative time compared to
+UTC. Supported formats include: -1200, MST, +0100.
+.TP
+.B day of the week items
+Specifies a day of the week. Days of the week may be spelled out in full
+(using english): `Sunday', `Monday', etc or they may be abbreviated to their
+first three letters. This is usually not info that adds anything.
+.TP
+.B pure numbers
+If a decimal number of the form YYYYMMDD appears, then YYYY is read as the
+year, MM as the month number and DD as the day of the month, for the specified
+calendar date.
+.PP
+.SH EXAMPLES
+.nf
+Sun, 06 Nov 1994 08:49:37 GMT
+Sunday, 06-Nov-94 08:49:37 GMT
+Sun Nov  6 08:49:37 1994
+06 Nov 1994 08:49:37 GMT
+06-Nov-94 08:49:37 GMT
+Nov  6 08:49:37 1994
+06 Nov 1994 08:49:37
+06-Nov-94 08:49:37
+1994 Nov 6 08:49:37
+GMT 08:49:37 06-Nov-94 Sunday
+94 6 Nov 08:49:37
+1994 Nov 6
+06-Nov-94
+Sun Nov 6 94
+1994.Nov.6
+Sun/Nov/6/94/GMT
+Sun, 06 Nov 1994 08:49:37 CET
+06 Nov 1994 08:49:37 EST
+Sun, 12 Sep 2004 15:05:58 -0700
+Sat, 11 Sep 2004 21:32:11 +0200
+20040912 15:05:58 -0700
+20040911 +0200
+.fi
+.SH STANDARDS
+This parser was written to handle date formats specified in RFC 822 (including
+the update in RFC 1123) using time zone name or time zone delta and RFC 850
+(obsoleted by RFC 1036) and ANSI C's asctime() format. These formats are the
+only ones RFC 7231 says HTTP applications may use.
+.SH RETURN VALUE
+This function returns -1 when it fails to parse the date string. Otherwise it
+returns the number of seconds as described.
+
+On systems with a signed 32 bit time_t: if the year is larger than 2037 or
+less than 1903, this function will return -1.
+
+On systems with an unsigned 32 bit time_t: if the year is larger than 2106 or
+less than 1970, this function will return -1.
+
+On systems with 64 bit time_t: if the year is less than 1583, this function
+will return -1. (The Gregorian calendar was first introduced 1582 so no "real"
+dates in this way of doing dates existed before then.)
+.SH "SEE ALSO"
+.BR curl_easy_escape "(3), " curl_easy_unescape "(3), "
+.BR CURLOPT_TIMECONDITION "(3), " CURLOPT_TIMEVALUE "(3) "

curl/docs/libcurl/curl_getenv.3

@@ -0,0 +1,50 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_getenv 3 "December 31, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_getenv - return value for environment name
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "char *curl_getenv(const char *" name ");"
+.ad
+.SH DESCRIPTION
+curl_getenv() is a portable wrapper for the getenv() function, meant to
+emulate its behavior and provide an identical interface for all operating
+systems libcurl builds on (including win32).
+
+You must \fIcurl_free(3)\fP the returned string when you're done with it.
+.SH AVAILABILITY
+This function will be removed from the public libcurl API in a near future. It
+will instead be made "available" by source code access only, and then as
+curlx_getenv().
+.SH RETURN VALUE
+A pointer to a null-terminated string or NULL if it failed to find the
+specified name.
+.SH NOTE
+Under unix operating systems, there isn't any point in returning an allocated
+memory, although other systems won't work properly if this isn't done. The
+unix implementation thus has to suffer slightly from the drawbacks of other
+systems.
+.SH "SEE ALSO"
+.BR getenv "(3C), "

curl/docs/libcurl/curl_global_cleanup.3

@@ -0,0 +1,56 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_global_cleanup 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_global_cleanup - global libcurl cleanup
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "void curl_global_cleanup(void);"
+.ad
+.SH DESCRIPTION
+This function releases resources acquired by \fIcurl_global_init(3)\fP.
+
+You should call \fIcurl_global_cleanup(3)\fP once for each call you make to
+\fIcurl_global_init(3)\fP, after you are done using libcurl.
+
+\fBThis function is not thread safe.\fP You must not call it when any other
+thread in the program (i.e. a thread sharing the same memory) is running.
+This doesn't just mean no other thread that is using libcurl.  Because
+\fIcurl_global_cleanup(3)\fP calls functions of other libraries that are
+similarly thread unsafe, it could conflict with any other thread that uses
+these other libraries.
+
+See the description in \fIlibcurl(3)\fP of global environment requirements for
+details of how to use this function.
+.SH CAUTION
+\fIcurl_global_cleanup(3)\fP does not block waiting for any libcurl-created
+threads to terminate (such as threads used for name resolving). If a module
+containing libcurl is dynamically unloaded while libcurl-created threads are
+still running then your program may crash or other corruption may occur. We
+recommend you do not run libcurl from any module that may be unloaded
+dynamically. This behavior may be addressed in the future.
+.SH "SEE ALSO"
+.BR curl_global_init "(3), "
+.BR libcurl "(3), "
+.BR libcurl-thread "(3), "

curl/docs/libcurl/curl_global_init.3

@@ -0,0 +1,104 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_global_init 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_global_init - Global libcurl initialisation
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_global_init(long " flags ");"
+.ad
+.SH DESCRIPTION
+This function sets up the program environment that libcurl needs.  Think of it
+as an extension of the library loader.
+
+This function must be called at least once within a program (a program is all
+the code that shares a memory space) before the program calls any other
+function in libcurl.  The environment it sets up is constant for the life of
+the program and is the same for every program, so multiple calls have the same
+effect as one call.
+
+The flags option is a bit pattern that tells libcurl exactly what features to
+init, as described below. Set the desired bits by ORing the values together.
+In normal operation, you must specify CURL_GLOBAL_ALL.  Don't use any other
+value unless you are familiar with it and mean to control internal operations of
+libcurl.
+
+\fBThis function is not thread safe.\fP You must not call it when any other
+thread in the program (i.e. a thread sharing the same memory) is running.
+This doesn't just mean no other thread that is using libcurl.  Because
+\fIcurl_global_init(3)\fP calls functions of other libraries that are
+similarly thread unsafe, it could conflict with any other thread that uses
+these other libraries.
+
+If you are initializing libcurl from a Windows DLL you should not initialize it
+from DllMain or a static initializer because Windows holds the loader lock
+during that time and it could cause a deadlock.
+
+See the description in \fIlibcurl(3)\fP of global environment requirements for
+details of how to use this function.
+.SH FLAGS
+.IP CURL_GLOBAL_ALL
+Initialize everything possible. This sets all known bits except
+\fBCURL_GLOBAL_ACK_EINTR\fP.
+
+.IP CURL_GLOBAL_SSL
+(This flag's presence or absence serves no meaning since 7.57.0. The
+description below is for older libcurl versions.)
+
+Initialize SSL.
+
+The implication here is that if this bit is not set, the initialization of the
+SSL layer needs to be done by the application or at least outside of
+libcurl. The exact procedure how to do SSL initialization depends on the TLS
+backend libcurl uses.
+
+Doing TLS based transfers without having the TLS layer initialized may lead to
+unexpected behaviors.
+.IP CURL_GLOBAL_WIN32
+Initialize the Win32 socket libraries.
+
+The implication here is that if this bit is not set, the initialization of
+winsock has to be done by the application or you risk getting undefined
+behaviors. This option exists for when the initialization is handled outside
+of libcurl so there's no need for libcurl to do it again.
+.IP CURL_GLOBAL_NOTHING
+Initialise nothing extra. This sets no bit.
+.IP 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.
+.IP CURL_GLOBAL_ACK_EINTR
+This bit has no point since 7.69.0 but its behavior is instead the default.
+
+Before 7.69.0: when this flag is set, curl will acknowledge EINTR condition
+when connecting or when waiting for data.  Otherwise, curl waits until full
+timeout elapses. (Added in 7.30.0)
+.SH RETURN VALUE
+If this function returns non-zero, something went wrong and you cannot use the
+other curl functions.
+.SH "SEE ALSO"
+.BR curl_global_init_mem "(3), "
+.BR curl_global_cleanup "(3), "
+.BR curl_global_sslset "(3), "
+.BR curl_easy_init "(3) "
+.BR libcurl "(3) "

curl/docs/libcurl/curl_global_init_mem.3

@@ -0,0 +1,67 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_global_init_mem 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_global_init_mem - Global libcurl initialisation with memory callbacks
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.nf
+.B "CURLcode curl_global_init_mem(long " flags,
+.B " curl_malloc_callback "m,
+.B " curl_free_callback "f,
+.B " curl_realloc_callback "r,
+.B " curl_strdup_callback "s,
+.B " curl_calloc_callback "c ");"
+.SH DESCRIPTION
+This function works exactly as \fIcurl_global_init(3)\fP with one addition: it
+allows the application to set callbacks to replace the otherwise used internal
+memory functions.
+
+If you are using libcurl from multiple threads or libcurl was built with the
+threaded resolver option then the callback functions must be thread safe. The
+threaded resolver is a common build option to enable (and in some cases the
+default) so we strongly urge you to make your callback functions thread safe.
+
+All callback arguments must be set to valid function pointers. The
+prototypes for the given callbacks must match these:
+.IP "void *malloc_callback(size_t size);"
+To replace malloc()
+.IP "void free_callback(void *ptr);"
+To replace free()
+.IP "void *realloc_callback(void *ptr, size_t size);"
+To replace realloc()
+.IP "char *strdup_callback(const char *str);"
+To replace strdup()
+.IP "void *calloc_callback(size_t nmemb, size_t size);"
+To replace calloc()
+.RE
+This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer
+to that man page for documentation.
+.SH "CAUTION"
+Manipulating these gives considerable powers to the application to severely
+screw things up for libcurl. Take care!
+.SH AVAILABILITY
+Added in 7.12.0
+.SH "SEE ALSO"
+.BR curl_global_init "(3), "
+.BR curl_global_cleanup "(3), "

curl/docs/libcurl/curl_global_sslset.3

@@ -0,0 +1,103 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_global_sslset 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_global_sslset - Select SSL backend to use with libcurl
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.nf
+
+typedef struct {
+  curl_sslbackend id;
+  const char *name;
+} curl_ssl_backend;
+
+typedef enum {
+  CURLSSLBACKEND_NONE = 0,
+  CURLSSLBACKEND_OPENSSL = 1,
+  CURLSSLBACKEND_GNUTLS = 2,
+  CURLSSLBACKEND_NSS = 3,
+  CURLSSLBACKEND_GSKIT = 5,
+  CURLSSLBACKEND_POLARSSL = 6, /* deprecated */
+  CURLSSLBACKEND_WOLFSSL = 7,
+  CURLSSLBACKEND_SCHANNEL = 8,
+  CURLSSLBACKEND_SECURETRANSPORT = 9,
+  CURLSSLBACKEND_AXTLS = 10, /* deprecated */
+  CURLSSLBACKEND_MBEDTLS = 11,
+  CURLSSLBACKEND_MESALINK = 12,
+  CURLSSLBACKEND_BEARSSL = 13
+} curl_sslbackend;
+
+.B "CURLsslset curl_global_sslset(curl_sslbackend " id,
+.B "                              const char *" name,
+.B "                              curl_ssl_backend ***" avail ");"
+.fi
+.SH DESCRIPTION
+This function configures at runtime which SSL backend to use with
+libcurl. This function can only be used to select an SSL backend once, and it
+must be called \fBbefore\fP \fIcurl_global_init(3)\fP.
+
+The backend can be identified by the \fIid\fP
+(e.g. \fBCURLSSLBACKEND_OPENSSL\fP). The backend can also be specified via the
+\fIname\fP parameter for a case insensitive match (passing -1 as \fIid\fP). If
+both \fIid\fP and \fIname\fP are specified, the \fIname\fP will be ignored.
+
+If neither \fIid\fP nor \fPname\fP are specified, the function will fail with
+CURLSSLSET_UNKNOWN_BACKEND and set the \fIavail\fP pointer to the
+NULL-terminated list of available backends. The available backends are those
+that this particular build of libcurl supports.
+
+Since libcurl 7.60.0, the \fIavail\fP pointer will always be set to the list
+of alternatives if non-NULL.
+
+Upon success, the function returns CURLSSLSET_OK.
+
+If the specified SSL backend is not available, the function returns
+CURLSSLSET_UNKNOWN_BACKEND and sets the \fIavail\fP pointer to a
+NULL-terminated list of available SSL backends. In this case, you may call the
+function again to try to select a different backend.
+
+The SSL backend can be set only once. If it has already been set, a subsequent
+attempt to change it will result in a \fBCURLSSLSET_TOO_LATE\fP.
+
+\fBThis function is not thread safe.\fP You must not call it when any other
+thread in the program (i.e. a thread sharing the same memory) is running.
+This doesn't just mean no other thread that is using libcurl.
+
+.SH AVAILABILITY
+This function was added in libcurl 7.56.0. Before this version, there was no
+support for choosing SSL backends at runtime.
+.SH RETURN VALUE
+If this function returns CURLSSLSET_OK, the backend was successfully selected.
+
+If the chosen backend is unknown (or support for the chosen backend has not
+been compiled into libcurl), the function returns \fICURLSSLSET_UNKNOWN_BACKEND\fP.
+
+If the backend had been configured previously, or if \fIcurl_global_init(3)\fP
+has already been called, the function returns \fICURLSSLSET_TOO_LATE\fP.
+
+If this libcurl was built completely without SSL support, with no backends at
+all, this function returns \fICURLSSLSET_NO_BACKENDS\fP.
+.SH "SEE ALSO"
+.BR curl_global_init "(3), "
+.BR libcurl "(3) "

curl/docs/libcurl/curl_mime_addpart.3

@@ -0,0 +1,67 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_addpart 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_addpart - append a new empty part to a mime structure
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "curl_mimepart * curl_mime_addpart(curl_mime * " mime ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given
+mime structure and returns a handle to it.  The returned part handle can
+subsequently be populated using functions from the mime API.
+
+\fImime\fP is the handle of the mime structure in which the new part must be
+appended.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+A mime part structure handle, or NULL upon failure.
+.SH EXAMPLE
+.nf
+ curl_mime *mime;
+ curl_mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* continue and set name + data to the part */
+ curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED);
+ curl_mime_name(part, "data");
+.fi
+.SH "SEE ALSO"
+.BR curl_mime_init "(3),"
+.BR curl_mime_name "(3),"
+.BR curl_mime_data "(3),"
+.BR curl_mime_data_cb "(3),"
+.BR curl_mime_filedata "(3),"
+.BR curl_mime_filename "(3),"
+.BR curl_mime_subparts "(3),"
+.BR curl_mime_type "(3),"
+.BR curl_mime_headers "(3),"
+.BR curl_mime_encoder "(3)"

curl/docs/libcurl/curl_mime_data.3

@@ -0,0 +1,70 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_data 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_data - set a mime part's body data from memory
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_mime_data(curl_mimepart * " part ", const char * " data
+.BI ", size_t " datasize ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_data(3)\fP sets a mime part's body content from memory data.
+
+\fIdata\fP points to the data bytes: those are copied to the part and their
+storage may safely be reused after call.
+\fIdatasize\fP is the number of data bytes: it can be set to
+\fICURL_ZERO_TERMINATED\fP to indicate \fIdata\fP is a null-terminated
+character string.
+\fIpart\fP is the part's to assign contents to.
+
+Setting a part's contents twice is valid: only the value set by the last call
+is retained. It is possible to unassign part's contents by setting
+\fIdata\fP to NULL.
+
+Setting very large data is memory consuming: one might consider using
+\fIcurl_mime_data_cb(3)\fP in such a case.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
+.SH EXAMPLE
+.nf
+ curl_mime *mime;
+ curl_mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* add data to the part  */
+ curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED);
+.fi
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3),"
+.BR curl_mime_data_cb "(3),"
+.BR curl_mime_name "(3),"
+.BR curl_mime_type "(3)"

curl/docs/libcurl/curl_mime_data_cb.3

@@ -0,0 +1,168 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_data_cb 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_data_cb - set a callback-based data source for a mime part's body
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
+.br
+int seekfunc(void *arg, curl_off_t offset, int origin);
+.br
+void freefunc(void *arg);
+.sp
+.BI "CURLcode curl_mime_data_cb(curl_mimepart * " part ", curl_off_t " datasize ,
+.br
+.BI "        curl_read_callback " readfunc ", curl_seek_callback " seekfunc ,
+.br
+.BI "        curl_free_callback " freefunc ", void * " arg ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_data_cb(3)\fP sets the data source of a mime part's body content
+from a data read callback function.
+
+\fIpart\fP is the part's to assign contents to.
+
+\fIreadfunc\fP is a pointer to a data read callback function, with a signature
+as shown by the above prototype. It may not be set to NULL.
+
+\fIseekfunc\fP is a pointer to a seek callback function, with a signature as
+shown by the above prototype. This function will be used upon resending data
+(i.e.: after a redirect); this pointer may be set to NULL, in which case a
+resend is not possible.
+
+\fIfreefunc\fP is a pointer to a user resource freeing callback function, with
+a signature as shown by the above prototype. If no resource is to be freed, it
+may safely be set to NULL. This function will be called upon mime structure
+freeing.
+
+\fIarg\fP is a user defined argument to callback functions.
+
+The read callback function gets called by libcurl as soon as it needs to
+read data in order to send it to the peer - like if you ask it to upload or
+post data to the server. The data area pointed at by the pointer \fIbuffer\fP
+should be filled up with at most \fIsize\fP multiplied with \fInmemb\fP number
+of bytes by your function.
+
+Your read function must then return the actual number of bytes that it stored
+in that memory area. Returning 0 will signal end-of-file to the library and
+cause it to stop the current transfer.
+
+If you stop the current transfer by returning 0 "pre-maturely" (i.e. before the
+server expected it, like when you've said you will upload N bytes and you
+upload less than N bytes), you may experience that the server "hangs" waiting
+for the rest of the data that won't come.
+
+The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
+operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
+code from the transfer.
+
+The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
+connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
+
+The seek function gets called by libcurl to rewind input stream data or to
+seek to a certain position. The function shall work like fseek(3) or lseek(3)
+and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP,
+although libcurl currently only passes SEEK_SET.
+
+The callback function must return \fICURL_SEEKFUNC_OK\fP on success,
+\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or
+\fICURL_SEEKFUNC_CANTSEEK\fP 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.
+
+Care must be taken if the part is bound to a curl easy handle that is later
+duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in
+the pointed item to be shared between the original and the copied handle.
+In particular, special attention should be given to the \fIfreefunc\fP
+procedure code since it will be called twice with the same argument.
+
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
+.SH EXAMPLE
+Sending a huge data string will cause the same amount of memory to be
+allocated: to avoid overhead resources consumption, one might want to use a
+callback source to avoid data duplication. In this case, original data
+must be retained until after the transfer terminates.
+.nf
+
+char hugedata[512000];
+
+struct ctl {
+  char *buffer;
+  curl_off_t size;
+  curl_off_t position;
+};
+
+size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
+{
+  struct ctl *p = (struct ctl *) arg;
+  curl_off_t sz = p->size - p->position;
+
+  nitems *= size;
+  if(sz > nitems)
+    sz = nitems;
+  if(sz)
+    memcpy(buffer, p->buffer + p->position, sz);
+  p->position += sz;
+  return sz;
+}
+
+int seek_callback(void *arg, curl_off_t offset, int origin)
+{
+  struct ctl *p = (struct ctl *) arg;
+
+  switch(origin) {
+  case SEEK_END:
+    offset += p->size;
+    break;
+  case SEEK_CUR:
+    offset += p->position;
+    break;
+  }
+
+  if(offset < 0)
+    return CURL_SEEKFUNC_FAIL;
+  p->position = offset;
+  return CURL_SEEKFUNC_OK;
+}
+
+ CURL *easy = curl_easy_init();
+ curl_mime *mime = curl_mime_init(easy);
+ curl_mimepart *part = curl_mime_addpart(mime);
+ struct ctl hugectl;
+
+ hugectl.buffer = hugedata;
+ hugectl.size = sizeof hugedata;
+ hugectl.position = 0;
+ curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
+                   &hugectl);
+
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3),"
+.BR curl_mime_data "(3),"
+.BR curl_mime_name "(3),"
+.BR curl_easy_duphandle "(3)"

curl/docs/libcurl/curl_mime_encoder.3

@@ -0,0 +1,98 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_encoder 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_encoder - set a mime part's encoder and content transfer encoding
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_mime_encoder(curl_mimepart * " part ,
+.BI "const char * " encoding ");"
+.ad
+.SH DESCRIPTION
+curl_mime_encoder() requests a mime part's content to be encoded before being
+transmitted.
+
+\fIpart\fP is the part's handle to assign an encoder.
+\fIencoding\fP is a pointer to a null-terminated encoding scheme. It may be
+set to NULL to disable an encoder previously attached to the part. The encoding
+scheme storage may safely be reused after this function returns.
+
+Setting a part's encoder twice is valid: only the value set by the last call is
+retained.
+
+Upon multipart rendering, the part's content is encoded according to the
+pertaining scheme and a corresponding \fIContent-Transfer-Encoding"\fP header
+is added to the part.
+
+Supported encoding schemes are:
+.br
+"\fIbinary\fP": the data is left unchanged, the header is added.
+.br
+"\fI8bit\fP": header added, no data change.
+.br
+"\fI7bit\fP": the data is unchanged, but is each byte is checked
+to be a 7-bit value; if not, a read error occurs.
+.br
+"\fIbase64\fP": Data is converted to base64 encoding, then split in
+CRLF-terminated lines of at most 76 characters.
+.br
+"\fIquoted-printable\fP": data is encoded in quoted printable lines of
+at most 76 characters. Since the resulting size of the final data cannot be
+determined prior to reading the original data, it is left as unknown, causing
+chunked transfer in HTTP. For the same reason, this encoder may not be used
+with IMAP. This encoder targets text data that is mostly ASCII and should
+not be used with other types of data.
+
+If the original data is already encoded in such a scheme, a custom
+\fIContent-Transfer-Encoding\fP header should be added with
+\FIcurl_mime_headers\fP() instead of setting a part encoder.
+
+Encoding should not be applied to multiparts, thus the use of this
+function on a part with content set with \fIcurl_mime_subparts\fP() is
+strongly discouraged.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
+.SH EXAMPLE
+.nf
+ curl_mime *mime;
+ curl_mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* send a file */
+ curl_mime_filedata(part, "image.png");
+
+ /* encode file data in base64 for transfer */
+ curl_mime_encoder(part, "base64");
+.fi
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3),"
+.BR curl_mime_headers "(3),"
+.BR curl_mime_subparts "(3)"

curl/docs/libcurl/curl_mime_filedata.3

@@ -0,0 +1,85 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_filedata 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_filedata - set a mime part's body data from a file contents
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_mime_filedata(curl_mimepart * " part ,
+.BI " const char * " filename ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_filedata(3)\fP sets a mime part's body content from the named
+file's contents. This is an alternative to \fIcurl_mime_data(3)\fP for setting
+data to a mime part.
+
+\fIpart\fP is the part's to assign contents to.
+
+\fIfilename\fP points to the null-terminated file's path name. The pointer can
+be NULL to detach the previous part contents settings.  Filename storage can
+be safely be reused after this call.
+
+As a side effect, the part's remote file name is set to the base name of the
+given \fIfilename\fP if it is a valid named file. This can be undone or
+overridden by a subsequent call to \fIcurl_mime_filename(3)\fP.
+
+The contents of the file is read during the file transfer in a streaming
+manner to allow huge files to get transferred without using much memory. It
+therefore requires that the file is kept intact during the entire request.
+
+If the file size cannot be determined before actually reading it (such as for
+a device or named pipe), the whole mime structure containing the part
+will be transferred as chunks by HTTP and rejected by IMAP.
+
+Setting a part's contents twice is valid: only the value set by the last call
+is retained.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an
+indication that the file is not yet readable: it can be safely ignored at
+this time, but the file must be made readable before the pertaining
+easy handle is performed.
+.SH EXAMPLE
+.nf
+ curl_mime *mime;
+ curl_mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* send data from this file */
+ curl_mime_filedata(part, "image.png");
+
+ /* set name */
+ curl_mime_name(part, "data");
+.fi
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3),"
+.BR curl_mime_data "(3),"
+.BR curl_mime_filename "(3),"
+.BR curl_mime_name "(3)"

curl/docs/libcurl/curl_mime_filename.3

@@ -0,0 +1,73 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_filename 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_filename - set a mime part's remote file name
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_mime_filename(curl_mimepart * " part ,
+.BI "const char * " filename ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_filename(3)\fP sets a mime part's remote file name. When remote
+file name is set, content data is processed as a file, whatever is the part's
+content source. A part's remote file name is transmitted to the server in the
+associated Content-Disposition generated header.
+
+\fIpart\fP is the part's handle to assign the remote file name to.
+
+\fIfilename\fP points to the null-terminated file name string; it may be set
+to NULL to remove a previously attached remote file name.
+
+The remote file name string is copied into the part, thus the associated
+storage may safely be released or reused after call. Setting a part's file
+name twice is valid: only the value set by the last call is retained.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
+.SH EXAMPLE
+.nf
+ curl_mime *mime;
+ curl_mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* send image data from memory */
+ curl_mime_data(part, imagebuf, imagebuf_len);
+
+ /* set a file name to make it look like a file upload */
+ curl_mime_filename(part, "image.png");
+
+ /* set name */
+ curl_mime_name(part, "data");
+.fi
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3),"
+.BR curl_mime_filedata "(3),"
+.BR curl_mime_data "(3)"

curl/docs/libcurl/curl_mime_free.3

@@ -0,0 +1,51 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_free 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_free - free a previously built mime structure
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "void curl_mime_free(curl_mime *" mime);
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_free(3)\fP is used to clean up data previously built/appended
+with \fIcurl_mime_addpart(3)\fP and other mime-handling functions.  This must
+be called when the data has been used, which typically means after
+\fIcurl_easy_perform(3)\fP has been called.
+
+The handle to free is the one you passed to
+the \fICURLOPT_MIMEPOST(3)\fP option: attached subparts mime structures must
+not be explicitly freed as they are by the top structure freeing.
+
+\fBmime\fP is the handle as returned from a previous call to
+\fIcurl_mime_init(3)\fP and may be NULL.
+
+Passing in a NULL pointer in \fImime\fP will make this function return
+immediately with no action.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+None
+.SH "SEE ALSO"
+.BR curl_mime_init "(3)"

curl/docs/libcurl/curl_mime_headers.3

@@ -0,0 +1,66 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_headers 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_headers - set a mime part's custom headers
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_mime_headers(curl_mimepart * " part ,
+.BI "struct curl_slist * " headers ", int " take_ownership ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_headers(3)\fP sets a mime part's custom headers.
+
+\fIpart\fP is the part's handle to assign the custom headers list to.
+
+\fIheaders\fP is the head of a list of custom headers; it may be set to NULL
+to remove a previously attached custom header list.
+
+\fItake_ownership\fP: when non-zero, causes the list to be freed upon
+replacement or mime structure deletion; in this case the list must not be
+freed explicitly.
+
+Setting a part's custom headers list twice is valid: only the value set by
+the last call is retained.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
+.SH EXAMPLE
+.nf
+ struct curl_slist *headers = NULL;
+
+ headers = curl_slist_append(headers, "Custom-Header: mooo");
+
+ /* use these headers, please take ownership */
+ curl_mime_headers(part, headers, TRUE);
+
+ /* pass on this data */
+ curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED);
+
+ /* set name */
+ curl_mime_name(part, "numbers");
+.fi
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3)"

curl/docs/libcurl/curl_mime_init.3

@@ -0,0 +1,70 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_init 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_init - create a mime handle
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "curl_mime * curl_mime_init(CURL * " easy_handle ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure
+intended to be used with \fIeasy_handle\fP. This mime structure can be
+subsequently filled using the mime API, then attached to \fIeasy_handle\fP
+using option \fICURLOPT_MIMEPOST(3)\fP within a \fIcurl_easy_setopt(3)\fP
+call.
+
+Using a mime handle is the recommended way to post an HTTP form, format and
+send a multi-part e-mail with SMTP or upload such an e-mail to an IMAP server.
+
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+A mime struct handle, or NULL upon failure.
+.SH EXAMPLE
+.nf
+
+ CURL *easy = curl_easy_init();
+ curl_mime *mime;
+ curl_mimepart *part;
+
+ /* Build an HTTP form with a single field named "data", */
+ mime = curl_mime_init(easy);
+ part = curl_mime_addpart(mime);
+ curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED);
+ curl_mime_name(part, "data");
+
+ /* Post and send it. */
+ curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime);
+ curl_easy_setopt(easy, CURLOPT_URL, "https://example.com");
+ curl_easy_perform(easy);
+
+ /* Clean-up. */
+ curl_easy_cleanup(easy);
+ curl_mime_free(mime);
+
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3),"
+.BR curl_mime_free "(3),"
+.BR CURLOPT_MIMEPOST "(3)"

curl/docs/libcurl/curl_mime_name.3

@@ -0,0 +1,64 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_name 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_name - set a mime part's name
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_mime_name(curl_mimepart * " part ", const char * " name ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_name(3)\fP sets a mime part's name. This is the way HTTP form
+fields are named.
+
+\fIpart\fP is the part's handle to assign a name to.
+
+\fIname\fP points to the null-terminated name string.
+
+The name string is copied into the part, thus the associated storage may
+safely be released or reused after call. Setting a part's name twice is valid:
+only the value set by the last call is retained. It is possible to "unname" a
+part by setting \fIname\fP to NULL.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
+.SH EXAMPLE
+.nf
+ curl_mime *mime;
+ curl_mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* give the part a name */
+ curl_mime_name(part, "shoe_size");
+.fi
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3),"
+.BR curl_mime_data "(3),"
+.BR curl_mime_type "(3)"

curl/docs/libcurl/curl_mime_subparts.3

@@ -0,0 +1,54 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_subparts 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_subparts - set subparts of a multipart mime part
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_mime_subparts(curl_mimepart * " part ,
+.BI "curl_mime * " subparts ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_subparts(3)\fP sets a multipart mime part's content from a mime
+structure.
+
+\fIpart\fP is a handle to the multipart part.
+
+\fIsubparts\fP is a mime structure handle holding the subparts. After
+\fIcurl_mime_subparts\fP succeeds, the mime structure handle belongs to the
+multipart part and must not be freed explicitly. It may however be updated by
+subsequent calls to mime API functions.
+
+Setting a part's contents twice is valid: only the value set by the last call
+is retained. It is possible to unassign previous part's contents by setting
+\fIsubparts\fP to NULL.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
+.SH EXAMPLE
+TODO
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3),"
+.BR curl_mime_init "(3)"

curl/docs/libcurl/curl_mime_type.3

@@ -0,0 +1,84 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_mime_type 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_mime_type - set a mime part's content type
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLcode curl_mime_type(curl_mimepart * " part ,
+.BI "const char * " mimetype ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_mime_type(3)\fP sets a mime part's content type.
+
+\fIpart\fP is the part's handle to assign the content type to.
+
+\fImimetype\fP points to the null-terminated file mime type string; it may be
+set to NULL to remove a previously attached mime type.
+
+The mime type string is copied into the part, thus the associated storage may
+safely be released or reused after call. Setting a part's type twice is valid:
+only the value set by the last call is retained.
+
+In the absence of a mime type and if needed by the protocol specifications,
+a default mime type is determined by the context:
+.br
+- If set as a custom header, use this value.
+.br
+- application/form-data for an HTTP form post.
+.br
+- If a remote file name is set, the mime type is taken from the file name
+extension, or application/octet-stream by default.
+.br
+- For a multipart part, multipart/mixed.
+.br
+- text/plain in other cases.
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
+.SH EXAMPLE
+.nf
+ curl_mime *mime;
+ curl_mimepart *part;
+
+ /* create a mime handle */
+ mime = curl_mime_init(easy);
+
+ /* add a part */
+ part = curl_mime_addpart(mime);
+
+ /* get data from this file */
+ curl_mime_filedata(part, "image.png");
+
+ /* content-type for this part */
+ curl_mime_type(part, "image/png");
+
+ /* set name */
+ curl_mime_name(part, "image");
+.fi
+.SH "SEE ALSO"
+.BR curl_mime_addpart "(3),"
+.BR curl_mime_name "(3),"
+.BR curl_mime_data "(3)"

curl/docs/libcurl/curl_mprintf.3

@@ -0,0 +1,104 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_printf 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf
+curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf,
+curl_mvsprintf - formatted output conversion
+.SH SYNOPSIS
+.B #include <curl/mprintf.h>
+.sp
+.BI "int curl_mprintf(const char *" format ", ...);"
+.br
+.BI "int curl_mfprintf(FILE *" fd ", const char *" format ", ...);"
+.br
+.BI "int curl_msprintf(char *" buffer ", const char *" format ", ...);"
+.br
+.BI "int curl_msnprintf(char *" buffer ", size_t " maxlength ", const char *" format ", ...);"
+.br
+.BI "int curl_mvprintf(const char *" format ", va_list " args ");"
+.br
+.BI "int curl_mvfprintf(FILE *" fd ", const char *" format ", va_list " args ");"
+.br
+.BI "int curl_mvsprintf(char *" buffer ", const char *" format ", va_list " args ");"
+.br
+.BI "int curl_mvsnprintf(char *" buffer ", size_t " maxlength ", const char *" format ", va_list " args ");"
+.br
+.BI "char *curl_maprintf(const char *" format ", ...);"
+.br
+.BI "char *curl_mvaprintf(const char *" format ", va_list " args ");"
+.SH DESCRIPTION
+These are all functions that produce output according to a format string and
+given arguments. These are mostly clones of the well-known C-style functions
+and there will be no detailed explanation of all available formatting rules
+and usage here.
+
+See this table for notable exceptions.
+.RS
+.TP
+.B curl_mprintf()
+Normal printf() clone.
+.TP
+.B curl_mfprintf()
+Normal fprintf() clone.
+.TP
+.B curl_msprintf()
+Normal sprintf() clone.
+.TP
+.B curl_msnprintf()
+snprintf() clone. Many systems don't have this. It is just like \fBsprintf\fP
+but with an extra argument after the buffer that specifies the length of the
+target buffer.
+.TP
+.B curl_mvprintf()
+Normal vprintf() clone.
+.TP
+.B curl_mvfprintf()
+Normal vfprintf() clone.
+.TP
+.B curl_mvsprintf()
+Normal vsprintf() clone.
+.TP
+.B curl_mvsnprintf()
+vsnprintf() clone.  Many systems don't have this. It is just like
+\fBvsprintf\fP but with an extra argument after the buffer that specifies the
+length of the target buffer.
+.TP
+.B curl_maprintf()
+Like printf() but returns the output string as a malloc()ed string. The
+returned string must be free()ed by the receiver.
+.TP
+.B curl_mvaprintf()
+Like curl_maprintf() but takes a va_list pointer argument instead of a
+variable amount of arguments.
+.RE
+.SH AVAILABILITY
+These functions will be removed from the public libcurl API in the future. Do
+not use them in any new programs or projects.
+.SH RETURN VALUE
+The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to
+a newly allocated string, or NULL if it failed.
+
+All other functions return the number of characters they actually outputted.
+.SH "SEE ALSO"
+.BR printf "(3), " sprintf "(3), " fprintf "(3), " vprintf "(3) "

curl/docs/libcurl/curl_multi_add_handle.3

@@ -0,0 +1,72 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_add_handle 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_add_handle - add an easy handle to a multi session
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+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.
+
+While an easy handle is added to a multi stack, you cannot and you must not
+use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy
+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 (\fICURLOPT_SHARE(3)\fP) or
+global DNS cache (\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP), 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.
+
+When an easy interface is added to a multi handle, it will use a shared
+connection cache owned by the multi handle. Removing and adding new easy
+handles will not affect the pool of connections or the ability to do
+connection re-use.
+
+If you have \fICURLMOPT_TIMERFUNCTION(3)\fP 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 to the multi handle until you remove it
+again with \fIcurl_multi_remove_handle(3)\fP - even when a transfer with that
+specific easy handle is completed.
+
+You should remove the easy handle from the multi stack before you terminate
+first the easy handle and then the multi handle:
+
+1 - \fIcurl_multi_remove_handle(3)\fP
+
+2 - \fIcurl_easy_cleanup(3)\fP
+
+3 - \fIcurl_multi_cleanup(3)\fP
+.SH RETURN VALUE
+CURLMcode type, general libcurl multi interface error code.
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3)," curl_multi_init "(3), "
+.BR curl_multi_setopt "(3), " curl_multi_socket_action "(3) "

curl/docs/libcurl/curl_multi_assign.3

@@ -0,0 +1,64 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_assign 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_assign \- set data to associate with an internal socket
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,
+                            void *sockptr);
+.SH DESCRIPTION
+This function creates an association in the multi handle between the given
+socket and a private pointer of the application. This is designed for
+\fIcurl_multi_socket_action(3)\fP uses.
+
+When set, the \fIsockptr\fP pointer will be passed to all future socket
+callbacks for the specific \fIsockfd\fP socket.
+
+If the given \fIsockfd\fP isn't already in use by libcurl, this function will
+return an error.
+
+libcurl only keeps one single pointer associated with a socket, so calling
+this function several times for the same socket will make the last set pointer
+get used.
+
+The idea here being that this association (socket to private pointer) is
+something that just about every application that uses this API will need and
+then libcurl can just as well do it since it already has an internal hash
+table lookup for this.
+.SH "RETURN VALUE"
+The standard CURLMcode for multi interface error codes.
+.SH "TYPICAL USAGE"
+In a typical application you allocate a struct or at least use some kind of
+semi-dynamic data for each socket that we must wait for action on when using
+the \fIcurl_multi_socket_action(3)\fP approach.
+
+When our socket-callback gets called by libcurl and we get to know about yet
+another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out
+the particular data so that when we get updates about this same socket again,
+we don't have to find the struct associated with this socket by ourselves.
+.SH AVAILABILITY
+This function was added in libcurl 7.15.5.
+.SH "SEE ALSO"
+.BR curl_multi_setopt "(3), " curl_multi_socket_action "(3) "

curl/docs/libcurl/curl_multi_cleanup.3

@@ -0,0 +1,51 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_cleanup 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_cleanup - close down a multi session
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLMcode curl_multi_cleanup( CURLM *multi_handle );"
+.ad
+.SH DESCRIPTION
+Cleans up and removes a whole multi stack. It does not free or touch any
+individual easy handles in any way - they still need to be closed
+individually, using the usual \fIcurl_easy_cleanup(3)\fP way. The order of
+cleaning up should be:
+
+1 - \fIcurl_multi_remove_handle(3)\fP before any easy handles are cleaned up
+
+2 - \fIcurl_easy_cleanup(3)\fP can now be called independently since the easy
+handle is no longer connected to the multi handle
+
+3 - \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are
+removed
+
+Passing in a NULL pointer in \fImulti_handle\fP will make this function return
+CURLM_BAD_HANDLE immediately with no other action.
+.SH RETURN VALUE
+CURLMcode type, general libcurl multi interface error code. On success,
+CURLM_OK is returned.
+.SH "SEE ALSO"
+.BR curl_multi_init "(3)," curl_easy_cleanup "(3)," curl_easy_init "(3)"

curl/docs/libcurl/curl_multi_fdset.3

@@ -0,0 +1,85 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_fdset 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_fdset - extracts file descriptor information from a multi handle
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLMcode curl_multi_fdset(CURLM *multi_handle,
+                           fd_set *read_fd_set,
+                           fd_set *write_fd_set,
+                           fd_set *exc_fd_set,
+                           int *max_fd);
+.ad
+.SH DESCRIPTION
+This function extracts file descriptor information from a given multi_handle.
+libcurl returns its fd_set sets. The application can use these to select() on,
+but be sure to FD_ZERO them before calling this function as
+\fIcurl_multi_fdset(3)\fP only adds its own descriptors, it doesn't zero or
+otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should
+be called as soon as one of them is ready to be read from or written to.
+
+If the \fIread_fd_set\fP argument is not a null pointer, it points to an
+object of type fd_set that on returns specifies the file descriptors to be
+checked for being ready to read.
+
+If the \fIwrite_fd_set\fP argument is not a null pointer, it points to an
+object of type fd_set that on return specifies the file descriptors to be
+checked for being ready to write.
+
+If the \fIexc_fd_set\fP argument is not a null pointer, it points to an object
+of type fd_set that on return specifies the file descriptors to be checked for
+error conditions pending.
+
+If no file descriptors are set by libcurl, \fImax_fd\fP will contain -1 when
+this function returns. Otherwise it will contain the highest descriptor number
+libcurl set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl
+currently does something that isn't possible for your application to monitor
+with a socket and unfortunately you can then not know exactly when the current
+action is completed using select(). You then need to wait a while before you
+proceed and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless
+\fIcurl_multi_timeout(3)\fP gives you a lower number, we suggest 100
+milliseconds or so, but you may want to test it out in your own particular
+conditions to find a suitable value.
+
+When doing select(), you should use \fIcurl_multi_timeout(3)\fP to figure out
+how long to wait for action. Call \fIcurl_multi_perform(3)\fP even if no
+activity has been seen on the fd_sets after the timeout expires as otherwise
+internal retries and timeouts may not work as you'd think and want.
+
+If one of the sockets used by libcurl happens to be larger than what can be
+set in an fd_set, which on POSIX systems means that the file descriptor is
+larger than FD_SETSIZE, then libcurl will try to not set it. Setting a too
+large file descriptor in an fd_set implies an out of bounds write which can
+cause crashes, or worse. The effect of NOT storing it will possibly save you
+from the crash, but will make your program NOT wait for sockets it should wait
+for...
+.SH RETURN VALUE
+CURLMcode type, general libcurl multi interface error code. See
+\fIlibcurl-errors(3)\fP
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
+.BR curl_multi_wait "(3), "
+.BR curl_multi_timeout "(3), " curl_multi_perform "(3), " select "(2) "

curl/docs/libcurl/curl_multi_info_read.3

@@ -0,0 +1,95 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_info_read 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_info_read - read multi stack informationals
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMsg *curl_multi_info_read( CURLM *multi_handle,
+                               int *msgs_in_queue);
+.ad
+.SH DESCRIPTION
+Ask the multi handle if there are any messages/informationals from the
+individual transfers. Messages may include informationals such as an error
+code from the transfer or just the fact that a transfer is completed. More
+details on these should be written down as well.
+
+Repeated calls to this function will return a new struct each time, until a
+NULL is returned as a signal that there is no more to get at this point. The
+integer pointed to with \fImsgs_in_queue\fP will contain the number of
+remaining messages after this function was called.
+
+When you fetch a message using this function, it is removed from the internal
+queue so calling this function again will not return the same message
+again. It will instead return new messages at each new invoke until the queue
+is emptied.
+
+\fBWARNING:\fP The data the returned pointer points to will not survive
+calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or
+\fIcurl_easy_cleanup(3)\fP.
+
+The 'CURLMsg' struct is very simple and only contains very basic information.
+If more involved information is wanted, the particular "easy handle" is
+present in that struct and can be used in subsequent regular
+\fIcurl_easy_getinfo(3)\fP calls (or similar):
+
+.nf
+ struct CURLMsg {
+   CURLMSG msg;       /* what this message means */
+   CURL *easy_handle; /* the handle it concerns */
+   union {
+     void *whatever;    /* message-specific data */
+     CURLcode result;   /* return code for transfer */
+   } data;
+ };
+.fi
+When \fBmsg\fP is \fICURLMSG_DONE\fP, the message identifies a transfer that
+is done, and then \fBresult\fP contains the return code for the easy handle
+that just completed.
+
+At this point, there are no other \fBmsg\fP types defined.
+.SH EXAMPLE
+.nf
+struct CURLMsg *m;
+
+/* call curl_multi_perform or curl_multi_socket_action first, then loop
+   through and check if there are any transfers that have completed */
+
+do {
+  int msgq = 0;
+  m = curl_multi_info_read(multi_handle, &msgq);
+  if(m && (m->msg == CURLMSG_DONE)) {
+    CURL *e = m->easy_handle;
+    transfers--;
+    curl_multi_remove_handle(multi_handle, e);
+    curl_easy_cleanup(e);
+  }
+} while(m);
+.fi
+.SH "RETURN VALUE"
+A pointer to a filled-in struct, or NULL if it failed or ran out of
+structs. It also writes the number of messages left in the queue (after this
+read) in the integer the second argument points to.
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " curl_multi_perform "(3)"

curl/docs/libcurl/curl_multi_init.3

@@ -0,0 +1,40 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_init 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_init - create a multi handle
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLM *curl_multi_init( );"
+.ad
+.SH DESCRIPTION
+This function returns a CURLM handle to be used as input to all the other
+multi-functions, sometimes referred to as a multi handle in some places in the
+documentation. This init call MUST have a corresponding call to
+\fIcurl_multi_cleanup(3)\fP when the operation is complete.
+.SH RETURN VALUE
+If this function returns NULL, something went wrong and you cannot use the
+other curl functions.
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3)," curl_global_init "(3)," curl_easy_init "(3)"

curl/docs/libcurl/curl_multi_perform.3

@@ -0,0 +1,131 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_perform 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_perform - reads/writes available data from each easy handle
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles);
+.ad
+.SH DESCRIPTION
+This function handles transfers on all the added handles that need attention
+in an non-blocking fashion.
+
+When an application has found out there's data available for the multi_handle
+or a timeout has elapsed, the application should call this function to
+read/write whatever there is to read or write right now etc.
+\fIcurl_multi_perform(3)\fP returns as soon as the reads/writes are done. This
+function does not require that there actually is any data available for
+reading or that data can be written, it can be called just in case. It will
+write the number of handles that still transfer data in the second argument's
+integer-pointer.
+
+If the amount of \fIrunning_handles\fP is changed from the previous call (or
+is less than the amount of easy handles you've added to the multi handle), you
+know that there is one or more transfers less "running". You can then call
+\fIcurl_multi_info_read(3)\fP to get information about each individual
+completed transfer, and that returned info includes CURLcode and more. If an
+added handle fails very quickly, it may never be counted as a running_handle.
+You could use \fIcurl_multi_info_read(3)\fP to track actual status of the
+added handles in that case.
+
+When \fIrunning_handles\fP is set to zero (0) on the return of this function,
+there is no longer any transfers in progress.
+.SH EXAMPLE
+.nf
+#ifdef _WIN32
+#define SHORT_SLEEP Sleep(100)
+#else
+#define SHORT_SLEEP usleep(100000)
+#endif
+
+fd_set fdread;
+fd_set fdwrite;
+fd_set fdexcep;
+int maxfd = -1;
+
+long curl_timeo;
+
+curl_multi_timeout(multi_handle, &curl_timeo);
+if(curl_timeo < 0)
+  curl_timeo = 1000;
+
+timeout.tv_sec = curl_timeo / 1000;
+timeout.tv_usec = (curl_timeo % 1000) * 1000;
+
+FD_ZERO(&fdread);
+FD_ZERO(&fdwrite);
+FD_ZERO(&fdexcep);
+
+/* get file descriptors from the transfers */
+mc = curl_multi_fdset(multi_handle, &fdread, &fdwrite, &fdexcep, &maxfd);
+
+if(maxfd == -1) {
+  SHORT_SLEEP;
+  rc = 0;
+}
+else
+  rc = select(maxfd+1, &fdread, &fdwrite, &fdexcep, &timeout);
+
+switch(rc) {
+case -1:
+  /* select error */
+  break;
+case 0:
+default:
+  /* timeout or readable/writable sockets */
+  curl_multi_perform(multi_handle, &still_running);
+  break;
+}
+
+/* if there are still transfers, loop! */
+.fi
+.SH "RETURN VALUE"
+CURLMcode type, general libcurl multi interface error code.
+
+Before version 7.20.0 (released on February 9 2010): If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this
+basically means that you should call \fIcurl_multi_perform(3)\fP again, before
+you select() on more actions. You don't have to do it immediately, but the
+return code means that libcurl may have more data available to return or that
+there may be more data to send off before it is "satisfied". Do note that
+\fIcurl_multi_perform(3)\fP will return \fICURLM_CALL_MULTI_PERFORM\fP only
+when it wants to be called again \fBimmediately\fP. When things are fine and
+there is nothing immediate it wants done, it'll return \fICURLM_OK\fP and you
+need to wait for \&"action" and then call this function again.
+
+This function only returns errors etc regarding the whole multi stack.
+Problems still might have occurred on individual transfers even when this
+function returns \fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure
+out how individual transfers did.
+.SH "TYPICAL USAGE"
+Most applications will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's
+file descriptors, and \fIcurl_multi_timeout(3)\fP to get a suitable timeout
+period, then it'll wait for action on the file descriptors using
+\fBselect(3)\fP. As soon as one or more file descriptor is ready,
+\fIcurl_multi_perform(3)\fP gets called.
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
+.BR curl_multi_wait "(3), "
+.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
+.BR libcurl-errors "(3)"

curl/docs/libcurl/curl_multi_poll.3

@@ -0,0 +1,118 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_poll 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_poll - polls on all easy handles in a multi handle
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLMcode curl_multi_poll(CURLM *multi_handle,
+                          struct curl_waitfd extra_fds[],
+                          unsigned int extra_nfds,
+                          int timeout_ms,
+                          int *numfds);
+.ad
+.SH DESCRIPTION
+\fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy
+handles contained in the given multi handle set.  It will block until activity
+is detected on at least one of the handles or \fItimeout_ms\fP has passed.
+Alternatively, if the multi handle has a pending internal timeout that has a
+shorter expiry time than \fItimeout_ms\fP, that shorter time will be used
+instead to make sure timeout accuracy is reasonably kept.
+
+The calling application may pass additional curl_waitfd structures which are
+similar to \fIpoll(2)\fP's pollfd structure to be waited on in the same call.
+
+On completion, if \fInumfds\fP is non-NULL, it will be populated with the
+total number of file descriptors on which interesting events occurred. This
+number can include both libcurl internal descriptors as well as descriptors
+provided in \fIextra_fds\fP.
+
+The \fIcurl_multi_wakeup(3)\fP function can be used from another thread to
+wake up this function and return faster. This is one of the details
+that makes this function different than \fIcurl_multi_wait(3)\fP which cannot
+be woken up this way.
+
+If no extra file descriptors are provided and libcurl has no file descriptor
+to offer to wait for, this function will instead wait during \fItimeout_ms\fP
+milliseconds (or shorter if an internal timer indicates so). This is the
+other detail that makes this function different than
+\fIcurl_multi_wait(3)\fP.
+
+This function is encouraged to be used instead of select(3) when using the
+multi interface to allow applications to easier circumvent the common problem
+with 1024 maximum file descriptors.
+.SH curl_waitfd
+.nf
+struct curl_waitfd {
+  curl_socket_t fd;
+  short events;
+  short revents;
+};
+.fi
+.IP CURL_WAIT_POLLIN
+Bit flag to curl_waitfd.events indicating the socket should poll on read
+events such as new data received.
+.IP CURL_WAIT_POLLPRI
+Bit flag to curl_waitfd.events indicating the socket should poll on high
+priority read events such as out of band data.
+.IP CURL_WAIT_POLLOUT
+Bit flag to curl_waitfd.events indicating the socket should poll on write
+events such as the socket being clear to write without blocking.
+.SH EXAMPLE
+.nf
+CURL *easy_handle;
+CURLM *multi_handle;
+
+/* add the individual easy handle */
+curl_multi_add_handle(multi_handle, easy_handle);
+
+do {
+  CURLMcode mc;
+  int numfds;
+
+  mc = curl_multi_perform(multi_handle, &still_running);
+
+  if(mc == CURLM_OK) {
+    /* wait for activity or timeout */
+    mc = curl_multi_poll(multi_handle, NULL, 0, 1000, &numfds);
+  }
+
+  if(mc != CURLM_OK) {
+    fprintf(stderr, "curl_multi failed, code %d.\\n", mc);
+    break;
+  }
+
+} while(still_running);
+
+curl_multi_remove_handle(multi_handle, easy_handle);
+.fi
+.SH RETURN VALUE
+CURLMcode type, general libcurl multi interface error code. See
+\fIlibcurl-errors(3)\fP
+.SH AVAILABILITY
+This function was added in libcurl 7.66.0.
+.SH "SEE ALSO"
+.BR curl_multi_fdset "(3), " curl_multi_perform "(3), "
+.BR curl_multi_wait "(3), " curl_multi_wakeup "(3)"

curl/docs/libcurl/curl_multi_remove_handle.3

@@ -0,0 +1,48 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_remove_handle 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_remove_handle - remove an easy handle from a multi session
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle);
+.ad
+.SH DESCRIPTION
+Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This will make
+the specified easy handle be removed from this multi handle's control.
+
+When the easy handle has been removed from a multi stack, it is again
+perfectly legal to invoke \fIcurl_easy_perform(3)\fP on this easy handle.
+
+Removing an easy handle while being used is perfectly legal and will
+effectively halt the transfer in progress involving that easy handle. All
+other easy handles and transfers will remain unaffected.
+
+It is fine to remove a handle at any time during a transfer, just not from
+within any libcurl callback function.
+.SH RETURN VALUE
+CURLMcode type, general libcurl multi interface error code.
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3)," curl_multi_init "(3), "
+.BR curl_multi_add_handle "(3) "

curl/docs/libcurl/curl_multi_setopt.3

@@ -0,0 +1,81 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_setopt 3 "December 31, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_setopt \- set options for a curl multi handle
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_setopt(CURLM * multi_handle, CURLMoption option, param);
+.SH DESCRIPTION
+\fIcurl_multi_setopt(3)\fP is used to tell a libcurl multi handle how to
+behave. By using the appropriate options to \fIcurl_multi_setopt(3)\fP, you
+can change libcurl's behavior when using that multi handle.  All options are
+set with the \fIoption\fP followed by the parameter \fIparam\fP. That
+parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject
+pointer\fP or a \fBcurl_off_t\fP type, depending on what the specific option
+expects. Read this manual carefully as bad input values may cause libcurl to
+behave badly!  You can only set one option in each function call.
+
+.SH OPTIONS
+.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE
+See \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP
+.IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE
+See \fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP
+.IP CURLMOPT_MAX_HOST_CONNECTIONS
+See \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP
+.IP CURLMOPT_MAX_PIPELINE_LENGTH
+See \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP
+.IP CURLMOPT_MAX_TOTAL_CONNECTIONS
+See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP
+.IP CURLMOPT_MAXCONNECTS
+See \fICURLMOPT_MAXCONNECTS(3)\fP
+.IP CURLMOPT_PIPELINING
+See \fICURLMOPT_PIPELINING(3)\fP
+.IP CURLMOPT_PIPELINING_SITE_BL
+See \fICURLMOPT_PIPELINING_SITE_BL(3)\fP
+.IP CURLMOPT_PIPELINING_SERVER_BL
+See \fICURLMOPT_PIPELINING_SERVER_BL(3)\fP
+.IP CURLMOPT_PUSHFUNCTION
+See \fICURLMOPT_PUSHFUNCTION(3)\fP
+.IP CURLMOPT_PUSHDATA
+See \fICURLMOPT_PUSHDATA(3)\fP
+.IP CURLMOPT_SOCKETFUNCTION
+See \fICURLMOPT_SOCKETFUNCTION(3)\fP
+.IP CURLMOPT_SOCKETDATA
+See \fICURLMOPT_SOCKETDATA(3)\fP
+.IP CURLMOPT_TIMERFUNCTION
+See \fICURLMOPT_TIMERFUNCTION(3)\fP
+.IP CURLMOPT_TIMERDATA
+See \fICURLMOPT_TIMERDATA(3)\fP
+.IP CURLMOPT_MAX_CONCURRENT_STREAMS
+See \fICURLMOPT_MAX_CONCURRENT_STREAMS(3)\fP
+.SH RETURNS
+The standard CURLMcode for multi interface error codes. Note that it returns a
+CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl
+doesn't know of.
+.SH AVAILABILITY
+This function was added in libcurl 7.15.4.
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
+.BR curl_multi_socket "(3), " curl_multi_info_read "(3)"

curl/docs/libcurl/curl_multi_socket.3

@@ -0,0 +1,160 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_socket 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_socket \- reads/writes available data
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,
+                            int *running_handles);
+
+CURLMcode curl_multi_socket_all(CURLM *multi_handle,
+                                int *running_handles);
+.fi
+.SH DESCRIPTION
+These functions are deprecated. Do not use! See
+\fIcurl_multi_socket_action(3)\fP instead!
+
+At return, the integer \fBrunning_handles\fP points to will contain the number
+of still running easy handles within the multi handle. When this number
+reaches zero, all transfers are complete/done. Note that when you call
+\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
+decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
+is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
+which easy handle that completed.
+
+The \fIcurl_multi_socket_action(3)\fP functions inform the application about
+updates in the socket (file descriptor) status by doing none, one, or multiple
+calls to the socket callback function set with the
+\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
+update the status with changes since the previous time the callback was
+called.
+
+Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option
+with \fIcurl_multi_setopt(3)\fP. Your application will then get called with
+information on how long to wait for socket actions at most before doing the
+timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
+\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the
+\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
+for an event-based system using the callback is far better than relying on
+polling the timeout value.
+
+Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is
+equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to
+0.
+
+Force libcurl to (re-)check all its internal sockets and transfers instead of
+just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there
+should not be any reason to use this function!
+.SH "CALLBACK DETAILS"
+
+The socket \fBcallback\fP function uses a prototype like this
+.nf
+
+  int curl_socket_callback(CURL *easy,      /* easy handle */
+                           curl_socket_t s, /* socket */
+                           int action,      /* see values below */
+                           void *userp,    /* private callback pointer */
+                           void *socketp); /* private socket pointer */
+
+.fi
+The callback MUST return 0.
+
+The \fIeasy\fP argument is a pointer to the easy handle that deals with this
+particular socket. Note that a single handle may work with several sockets
+simultaneously.
+
+The \fIs\fP argument is the actual socket value as you use it within your
+system.
+
+The \fIaction\fP argument to the callback has one of five values:
+.RS
+.IP "CURL_POLL_NONE (0)"
+register, not interested in readiness (yet)
+.IP "CURL_POLL_IN (1)"
+register, interested in read readiness
+.IP "CURL_POLL_OUT (2)"
+register, interested in write readiness
+.IP "CURL_POLL_INOUT (3)"
+register, interested in both read and write readiness
+.IP "CURL_POLL_REMOVE (4)"
+unregister
+.RE
+
+The \fIsocketp\fP argument is a private pointer you have previously set with
+\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no
+pointer has been set, socketp will be NULL. This argument is of course a
+service to applications that want to keep certain data or structs that are
+strictly associated to the given socket.
+
+The \fIuserp\fP argument is a private pointer you have previously set with
+\fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_SOCKETDATA(3)\fP option.
+.SH "RETURN VALUE"
+CURLMcode type, general libcurl multi interface error code.
+
+Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means
+that you should call \fIcurl_multi_socket(3)\fP again, before you wait for
+more actions on libcurl's sockets. You don't have to do it immediately, but
+the return code means that libcurl may have more data available to return or
+that there may be more data to send off before it is "satisfied".
+
+In modern libcurls, \fICURLM_CALL_MULTI_PERFORM\fP or
+\fICURLM_CALL_MULTI_SOCKET\fP should not be returned and no application needs
+to care about them.
+
+NOTE that the return code is for the whole multi stack. Problems still might have
+occurred on individual transfers even when one of these functions
+return OK.
+.SH "TYPICAL USAGE"
+1. Create a multi handle
+
+2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP
+
+3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to
+know what timeout value to use when waiting for socket activities.
+
+4. Add easy handles with curl_multi_add_handle()
+
+5. Provide some means to manage the sockets libcurl is using, so you can check
+them for activity. This can be done through your application code, or by way
+of an external library such as libevent or glib.
+
+6. Wait for activity on any of libcurl's sockets, use the timeout value your
+callback has been told
+
+7, When activity is detected, call curl_multi_socket_action() for the
+socket(s) that got action. If no activity is detected and the timeout expires,
+call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP
+
+8. Go back to step 6.
+.SH AVAILABILITY
+This function was added in libcurl 7.15.4, and is deemed stable since
+7.16.0.
+
+\fIcurl_multi_socket(3)\fP is deprecated, use
+\fIcurl_multi_socket_action(3)\fP instead!
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
+.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
+.BR "the hiperfifo.c example"

curl/docs/libcurl/curl_multi_socket_action.3

@@ -0,0 +1,97 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_socket_action 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_socket_action \- reads/writes available data given an action
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLMcode curl_multi_socket_action(CURLM * multi_handle,
+                                   curl_socket_t sockfd,
+                                   int ev_bitmask,
+                                   int *running_handles);
+.fi
+.SH DESCRIPTION
+When the application has detected action on a socket handled by libcurl, it
+should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument
+set to the socket with the action. When the events on a socket are known, they
+can be passed as an events bitmask \fBev_bitmask\fP by first setting
+\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of
+events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
+CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
+libcurl will test the descriptor internally. It is also permissible to pass
+CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the
+whole process or when a timeout occurs.
+
+At return, \fBrunning_handles\fP points to the number of running easy handles
+within the multi handle. When this number reaches zero, all transfers are
+complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific
+socket and the counter decreases by one, it DOES NOT necessarily mean that
+this exact socket/transfer is the one that completed. Use
+\fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed.
+
+The \fIcurl_multi_socket_action(3)\fP function informs the application about
+updates in the socket (file descriptor) status by doing none, one, or multiple
+calls to the socket callback function set with the
+\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
+update the status with changes since the previous time the callback was
+called.
+
+Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option
+with \fIcurl_multi_setopt(3)\fP. Your application will then get called with
+information on how long to wait for socket actions at most before doing the
+timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
+\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the
+\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
+for an event-based system using the callback is far better than relying on
+polling the timeout value.
+.SH "TYPICAL USAGE"
+1. Create a multi handle
+
+2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP
+
+3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to
+know what timeout value to use when waiting for socket activities.
+
+4. Add easy handles with curl_multi_add_handle()
+
+5. Provide some means to manage the sockets libcurl is using, so you can check
+them for activity. This can be done through your application code, or by way
+of an external library such as libevent or glib.
+
+6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...)
+to kickstart everything. To get one or more callbacks called.
+
+7. Wait for activity on any of libcurl's sockets, use the timeout value your
+callback has been told.
+
+8, When activity is detected, call curl_multi_socket_action() for the
+socket(s) that got action. If no activity is detected and the timeout expires,
+call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP.
+.SH AVAILABILITY
+This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
+.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
+.BR "the hiperfifo.c example"

curl/docs/libcurl/curl_multi_socket_all.3

@@ -0,0 +1 @@
+.so man3/curl_multi_socket.3

curl/docs/libcurl/curl_multi_strerror.3

@@ -0,0 +1,38 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_strerror 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_strerror - return string describing error code
+.SH SYNOPSIS
+.nf
+.B #include <curl/curl.h>
+.BI "const char *curl_multi_strerror(CURLMcode " errornum ");"
+.SH DESCRIPTION
+The curl_multi_strerror() function returns a string describing the CURLMcode
+error code passed in the argument \fIerrornum\fP.
+.SH AVAILABILITY
+This function was added in libcurl 7.12.0
+.SH RETURN VALUE
+A pointer to a null-terminated string.
+.SH "SEE ALSO"
+.BR libcurl-errors "(3), " curl_easy_strerror "(3), " curl_share_strerror "(3)"

curl/docs/libcurl/curl_multi_timeout.3

@@ -0,0 +1,79 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_timeout 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_timeout \- how long to wait for action before proceeding
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout);
+.SH DESCRIPTION
+
+An application using the libcurl multi interface should call
+\fIcurl_multi_timeout(3)\fP to figure out how long it should wait for socket
+actions \- at most \- before proceeding.
+
+Proceeding means either doing the socket-style timeout action: call the
+\fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set
+to CURL_SOCKET_TIMEOUT, or call \fIcurl_multi_perform(3)\fP if you're using
+the simpler and older multi interface approach.
+
+The timeout value returned in the long \fBtimeout\fP points to, is in number
+of milliseconds at this very moment. If 0, it means you should proceed
+immediately without waiting for anything. If it returns -1, there's no timeout
+at all set.
+
+An application that uses the multi_socket API SHOULD NOT use this function, but
+SHOULD instead use \fIcurl_multi_setopt(3)\fP and its
+\fPCURLMOPT_TIMERFUNCTION\fP option for proper and desired behavior.
+
+Note: if libcurl returns a -1 timeout here, it just means that libcurl
+currently has no stored timeout value. You must not wait too long (more than a
+few seconds perhaps) before you call curl_multi_perform() again.
+.SH EXAMPLE
+.nf
+struct timeval timeout;
+long timeo;
+
+curl_multi_timeout(multi_handle, &timeo);
+if(timeo < 0)
+  /* no set timeout, use a default */
+  timeo = 980;
+
+timeout.tv_sec = timeo / 1000;
+timeout.tv_usec = (timeo % 1000) * 1000;
+
+/* wait for activities no longer than the set timeout */
+select(maxfd+1, &fdread, &fdwrite, &fdexcep, &timeout);
+.fi
+.SH "RETURN VALUE"
+The standard CURLMcode for multi interface error codes.
+.SH "TYPICAL USAGE"
+Call \fIcurl_multi_timeout(3)\fP, then wait for action on the sockets. You
+figure out which sockets to wait for by calling \fIcurl_multi_fdset(3)\fP or
+by a previous call to \fIcurl_multi_socket(3)\fP.
+.SH AVAILABILITY
+This function was added in libcurl 7.15.4.
+.SH "SEE ALSO"
+.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
+.BR curl_multi_socket "(3), " curl_multi_setopt "(3) "

curl/docs/libcurl/curl_multi_wait.3

@@ -0,0 +1,124 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_wait 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_wait - polls on all easy handles in a multi handle
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLMcode curl_multi_wait(CURLM *multi_handle,
+                          struct curl_waitfd extra_fds[],
+                          unsigned int extra_nfds,
+                          int timeout_ms,
+                          int *numfds);
+.ad
+.SH DESCRIPTION
+\fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy
+handles contained in the given multi handle set.  It will block until activity
+is detected on at least one of the handles or \fItimeout_ms\fP has passed.
+Alternatively, if the multi handle has a pending internal timeout that has a
+shorter expiry time than \fItimeout_ms\fP, that shorter time will be used
+instead to make sure timeout accuracy is reasonably kept.
+
+The calling application may pass additional curl_waitfd structures which are
+similar to \fIpoll(2)\fP's pollfd structure to be waited on in the same call.
+
+On completion, if \fInumfds\fP is non-NULL, it will be populated with the
+total number of file descriptors on which interesting events occurred. This
+number can include both libcurl internal descriptors as well as descriptors
+provided in \fIextra_fds\fP.
+
+If no extra file descriptors are provided and libcurl has no file descriptor
+to offer to wait for, this function will return immediately. (Try
+\fIcurl_multi_poll(3)\fP instead if you rather avoid this behavior.)
+
+This function is encouraged to be used instead of select(3) when using the
+multi interface to allow applications to easier circumvent the common problem
+with 1024 maximum file descriptors.
+.SH curl_waitfd
+.nf
+struct curl_waitfd {
+  curl_socket_t fd;
+  short events;
+  short revents;
+};
+.fi
+.IP CURL_WAIT_POLLIN
+Bit flag to curl_waitfd.events indicating the socket should poll on read
+events such as new data received.
+.IP CURL_WAIT_POLLPRI
+Bit flag to curl_waitfd.events indicating the socket should poll on high
+priority read events such as out of band data.
+.IP CURL_WAIT_POLLOUT
+Bit flag to curl_waitfd.events indicating the socket should poll on write
+events such as the socket being clear to write without blocking.
+.SH EXAMPLE
+.nf
+CURL *easy_handle;
+CURLM *multi_handle;
+
+/* add the individual easy handle */
+curl_multi_add_handle(multi_handle, easy_handle);
+
+do {
+  CURLMcode mc;
+  int numfds;
+
+  mc = curl_multi_perform(multi_handle, &still_running);
+
+  if(mc == CURLM_OK ) {
+    /* wait for activity, timeout or "nothing" */
+    mc = curl_multi_wait(multi_handle, NULL, 0, 1000, &numfds);
+  }
+
+  if(mc != CURLM_OK) {
+    fprintf(stderr, "curl_multi failed, code %d.\\n", mc);
+    break;
+  }
+
+  /* 'numfds' being zero means either a timeout or no file descriptors to
+     wait for. Try timeout on first occurrence, then assume no file
+     descriptors and no file descriptors to wait for means wait for 100
+     milliseconds. */
+
+  if(!numfds) {
+    repeats++; /* count number of repeated zero numfds */
+    if(repeats > 1) {
+      WAITMS(100); /* sleep 100 milliseconds */
+    }
+  }
+  else
+    repeats = 0;
+
+} while(still_running);
+
+curl_multi_remove_handle(multi_handle, easy_handle);
+.fi
+.SH RETURN VALUE
+CURLMcode type, general libcurl multi interface error code. See
+\fIlibcurl-errors(3)\fP
+.SH AVAILABILITY
+This function was added in libcurl 7.28.0.
+.SH "SEE ALSO"
+.BR curl_multi_fdset "(3), " curl_multi_perform "(3)", curl_multi_poll "(3) ",

curl/docs/libcurl/curl_multi_wakeup.3

@@ -0,0 +1,87 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_multi_wakeup 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_multi_wakeup - wakes up a sleeping curl_multi_poll call
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_wakeup(CURLM *multi_handle);
+.ad
+.SH DESCRIPTION
+This function can be called from any thread and it wakes up a
+sleeping \fIcurl_multi_poll(3)\fP call that is currently (or will be)
+waiting for activity or a timeout.
+
+If the function is called when there is no \fIcurl_multi_poll(3)\fP call,
+it will cause the next call to return immediately.
+
+Calling this function only guarantees to wake up the current (or the next
+if there is no current) \fIcurl_multi_poll(3)\fP call, which means it is
+possible that multiple calls to this function will wake up the same waiting
+operation.
+
+This function has no effect on \fIcurl_multi_wait(3)\fP calls.
+.SH RETURN VALUE
+CURLMcode type, general libcurl multi interface error code.
+.SH AVAILABILITY
+Added in 7.68.0
+.SH EXAMPLE
+.nf
+CURL *easy_handle;
+CURLM *multi_handle;
+
+/* add the individual easy handle */
+curl_multi_add_handle(multi_handle, easy_handle);
+
+/* this is thread 1 */
+do {
+  CURLMcode mc;
+  int numfds;
+
+  mc = curl_multi_perform(multi_handle, &still_running);
+
+  if(mc == CURLM_OK) {
+    /* wait for activity, timeout or wakeup */
+    mc = curl_multi_poll(multi_handle, NULL, 0, 10000, &numfds);
+  }
+
+  if(time_to_die())
+    exit(1);
+
+} while(still_running);
+
+curl_multi_remove_handle(multi_handle, easy_handle);
+
+/* this is thread 2 */
+
+if(something makes us decide to stop thread 1) {
+
+  set_something_to_signal_thread_1_to_exit();
+
+  curl_multi_wakeup(multi_handle);
+}
+
+.fi
+.SH "SEE ALSO"
+.BR curl_multi_poll "(3), " curl_multi_wait "(3)"

curl/docs/libcurl/curl_share_cleanup.3

@@ -0,0 +1,43 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_share_cleanup 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_share_cleanup - Clean up a shared object
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLSHcode curl_share_cleanup(CURLSH *" share_handle ");"
+.ad
+.SH DESCRIPTION
+This function deletes a shared object. The share handle cannot be used anymore
+when this function has been called.
+
+Passing in a NULL pointer in \fIshare_handle\fP will make this function return
+immediately with no action.
+.SH RETURN VALUE
+CURLSHE_OK (zero) means that the option was set properly, non-zero means an
+error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors.3\fP
+man page for the full list with descriptions. If an error occurs, then the
+share object will not be deleted.
+.SH "SEE ALSO"
+.BR curl_share_init "(3), " curl_share_setopt "(3)"

curl/docs/libcurl/curl_share_init.3

@@ -0,0 +1,44 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_share_init 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_share_init - Create a shared object
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "CURLSH *curl_share_init( );"
+.ad
+.SH DESCRIPTION
+This function returns a CURLSH handle to be used as input to all the other
+share-functions, sometimes referred to as a share handle in some places in the
+documentation. This init call MUST have a corresponding call to
+\fIcurl_share_cleanup\fP when all operations using the share are complete.
+
+This \fIshare handle\fP is what you pass to curl using the
+\fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, to make that
+specific curl handle use the data in this share.
+.SH RETURN VALUE
+If this function returns NULL, something went wrong (out of memory, etc.)
+and therefore the share object was not created.
+.SH "SEE ALSO"
+.BR curl_share_cleanup "(3), " curl_share_setopt "(3)"

curl/docs/libcurl/curl_share_setopt.3

@@ -0,0 +1,115 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_share_setopt 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_share_setopt - Set options for a shared object
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter);
+.ad
+.SH DESCRIPTION
+Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP.
+.SH OPTIONS
+.IP CURLSHOPT_LOCKFUNC
+The \fIparameter\fP must be a pointer to a function matching the following
+prototype:
+
+void lock_function(CURL *handle, curl_lock_data data, curl_lock_access access,
+void *userptr);
+
+The \fIdata\fP argument tells what kind of data libcurl wants to lock. Make
+sure that the callback uses a different lock for each kind of data.
+
+\fIaccess\fP defines what access type libcurl wants, shared or single.
+
+\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP.
+.IP CURLSHOPT_UNLOCKFUNC
+The \fIparameter\fP must be a pointer to a function matching the following
+prototype:
+
+void unlock_function(CURL *handle, curl_lock_data data, void *userptr);
+
+\fIdata\fP defines what data libcurl wants to unlock, and you must make sure
+that only one lock is given at any time for each kind of data.
+
+\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP.
+.IP CURLSHOPT_SHARE
+The \fIparameter\fP specifies a type of data that should be shared. This may
+be set to one of the values described below.
+.RS
+.IP CURL_LOCK_DATA_COOKIE
+Cookie data will be shared across the easy handles using this shared object.
+Note that this does not activate an easy handle's cookie handling. You can do
+that separately by using \fICURLOPT_COOKIEFILE(3)\fP for example.
+.IP CURL_LOCK_DATA_DNS
+Cached DNS hosts will be shared across the easy handles using this shared
+object. Note that when you use the multi interface, all easy handles added to
+the same multi handle will share DNS cache by default without using this
+option.
+.IP CURL_LOCK_DATA_SSL_SESSION
+SSL session IDs will be shared across the easy handles using this shared
+object. This will reduce the time spent in the SSL handshake when reconnecting
+to the same server. Note SSL session IDs are reused within the same easy handle
+by default. Note this symbol was added in 7.10.3 but was not implemented until
+7.23.0.
+.IP CURL_LOCK_DATA_CONNECT
+Put the connection cache in the share object and make all easy handles using
+this share object share the connection cache.
+
+Note that due to a known bug, it is not safe to share connections this way
+between multiple concurrent threads.
+
+Connections that are used for HTTP/1.1 Pipelining or HTTP/2 multiplexing only
+get additional transfers added to them if the existing connection is held by
+the same multi or easy handle. libcurl does not support doing HTTP/2 streams
+in different threads using a shared connection.
+
+Support for \fBCURL_LOCK_DATA_CONNECT\fP was added in 7.57.0, but the symbol
+existed before this.
+
+Note that when you use the multi interface, all easy handles added to the same
+multi handle will share connection cache by default without using this option.
+.IP CURL_LOCK_DATA_PSL
+The Public Suffix List stored in the share object is made available to all
+easy handle bound to the later. Since the Public Suffix List is periodically
+refreshed, this avoids updates in too many different contexts.
+
+\fBCURL_LOCK_DATA_PSL\fP exists since 7.61.0.
+
+Note that when you use the multi interface, all easy handles added to the same
+multi handle will share PSL cache by default without using this option.
+.RE
+.IP CURLSHOPT_UNSHARE
+This option does the opposite of \fICURLSHOPT_SHARE\fP. It specifies that
+the specified \fIparameter\fP will no longer be shared. Valid values are
+the same as those for \fICURLSHOPT_SHARE\fP.
+.IP CURLSHOPT_USERDATA
+The \fIparameter\fP allows you to specify a pointer to data that will be passed
+to the lock_function and unlock_function each time it is called.
+.SH RETURN VALUE
+CURLSHE_OK (zero) means that the option was set properly, non-zero means an
+error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors.3\fP
+man page for the full list with descriptions.
+.SH "SEE ALSO"
+.BR curl_share_cleanup "(3), " curl_share_init "(3)"

curl/docs/libcurl/curl_share_strerror.3

@@ -0,0 +1,38 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_share_strerror 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_share_strerror - return string describing error code
+.SH SYNOPSIS
+.nf
+.B #include <curl/curl.h>
+.BI "const char *curl_share_strerror(CURLSHcode " errornum ");"
+.SH DESCRIPTION
+The curl_share_strerror() function returns a string describing the CURLSHcode
+error code passed in the argument \fIerrornum\fP.
+.SH AVAILABILITY
+This function was added in libcurl 7.12.0
+.SH RETURN VALUE
+A pointer to a null-terminated string.
+.SH "SEE ALSO"
+.BR libcurl-errors "(3), " curl_multi_strerror "(3), " curl_easy_strerror "(3)"

curl/docs/libcurl/curl_slist_append.3

@@ -0,0 +1,73 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_slist_append 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_slist_append - add a string to an slist
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "struct curl_slist *curl_slist_append(struct curl_slist *" list,
+.BI "const char * "string ");"
+.ad
+.SH DESCRIPTION
+\fIcurl_slist_append(3)\fP appends a string to a linked list of strings. The
+existing \fBlist\fP should be passed as the first argument and the new list is
+returned from this function. Pass in NULL in the \fBlist\fP argument to create
+a new list. The specified \fBstring\fP has been appended when this function
+returns. \fIcurl_slist_append(3)\fP copies the string.
+
+The list should be freed again (after usage) with
+\fIcurl_slist_free_all(3)\fP.
+.SH RETURN VALUE
+A null pointer is returned if anything went wrong, otherwise the new list
+pointer is returned. To avoid overwriting an existing non-empty list on
+failure, the new list should be returned to a temporary variable which can
+be tested for NULL before updating the original list pointer.
+.SH EXAMPLE
+.nf
+CURL *handle;
+struct curl_slist *slist=NULL;
+struct curl_slist *temp=NULL;
+
+slist = curl_slist_append(slist, "pragma:");
+
+if (slist == NULL)
+  return -1;
+
+temp = curl_slist_append(slist, "Accept:")
+
+if (temp == NULL) {
+  curl_slist_free_all(slist);
+  return -1;
+}
+
+slist = temp;
+
+curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist);
+
+curl_easy_perform(handle);
+
+curl_slist_free_all(slist); /* free the list again */
+.fi
+.SH "SEE ALSO"
+.BR curl_slist_free_all "(3), "

curl/docs/libcurl/curl_slist_free_all.3

@@ -0,0 +1,56 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_slist_free_all 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_slist_free_all - free an entire curl_slist list
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "void curl_slist_free_all(struct curl_slist *" list);
+.ad
+.SH DESCRIPTION
+curl_slist_free_all() removes all traces of a previously built curl_slist
+linked list.
+
+Passing in a NULL pointer in \fIlist\fP will make this function return
+immediately with no action.
+.SH RETURN VALUE
+Nothing.
+.SH EXAMPLE
+.nf
+CURL *handle;
+struct curl_slist *slist=NULL;
+
+slist = curl_slist_append(slist, "X-libcurl: coolness");
+
+if (slist == NULL)
+  return -1;
+
+curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist);
+
+curl_easy_perform(handle);
+
+curl_slist_free_all(slist); /* free the list again */
+.fi
+.SH "SEE ALSO"
+.BR curl_slist_append "(3), "

curl/docs/libcurl/curl_strequal.3

@@ -0,0 +1,52 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_strequal 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_strequal, curl_strnequal - case insensitive string comparisons
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "int curl_strequal(char *" str1 ", char *" str2 ");"
+.sp
+.BI "int curl_strnequal(char *" str1 ", char *" str2 ", size_t " len ");"
+.SH DESCRIPTION
+The
+.B curl_strequal()
+function compares the two strings \fIstr1\fP and \fIstr2\fP, ignoring the case
+of the characters. It returns a non-zero (TRUE) integer if the strings are
+identical.
+.sp
+The \fBcurl_strnequal()\fP function is similar, except it only compares the
+first \fIlen\fP characters of \fIstr1\fP.
+.sp
+These functions are provided by libcurl to enable applications to compare
+strings in a truly portable manner. There are no standard portable case
+insensitive string comparison functions. These two work on all platforms.
+.SH AVAILABILITY
+These functions will be removed from the public libcurl API in a near
+future. They will instead be made "available" by source code access only, and
+then as curlx_strequal() and curlx_strenqual().
+.SH RETURN VALUE
+Non-zero if the strings are identical. Zero if they're not.
+.SH "SEE ALSO"
+.BR strcmp "(3), " strcasecmp "(3)"

curl/docs/libcurl/curl_strnequal.3

@@ -0,0 +1 @@
+.so man3/curl_strequal.3

curl/docs/libcurl/curl_unescape.3

@@ -0,0 +1,49 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_unescape 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_unescape - URL decodes the given string
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "char *curl_unescape( const char *" url ", int "length " );"
+.ad
+.SH DESCRIPTION
+Obsolete function. Use \fIcurl_easy_unescape(3)\fP instead!
+
+This function will convert the given URL encoded input string to a "plain
+string" and return that as a new allocated string. All input characters that
+are URL encoded (%XX where XX is a two-digit hexadecimal number) will be
+converted to their plain text versions.
+
+If the 'length' argument is set to 0, curl_unescape() will use strlen() on the
+input 'url' string to find out the size.
+
+You must \fIcurl_free(3)\fP the returned string when you're done with it.
+.SH AVAILABILITY
+Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function will
+be removed in a future release.
+.SH RETURN VALUE
+A pointer to a null-terminated string or NULL if it failed.
+.SH "SEE ALSO"
+.br curl_easy_escape "(3)," curl_easy_unescape "(3)," curl_free "(3)," RFC 2396

curl/docs/libcurl/curl_url.3

@@ -0,0 +1,54 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_url 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_url - returns a new CURLU handle
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+CURLU *curl_url();
+.SH DESCRIPTION
+This function will allocates and returns a pointer to a fresh CURLU handle, to
+be used for further use of the URL API.
+.SH RETURN VALUE
+Returns a \fBCURLU *\fP if successful, or NULL if out of memory.
+.SH EXAMPLE
+.nf
+  CURLUcode rc;
+  CURLU *url = curl_url();
+  rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
+  if(!rc) {
+    char *scheme;
+    rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
+    if(!rc) {
+      printf("the scheme is %s\\n", scheme);
+      curl_free(scheme);
+    }
+    curl_url_cleanup(url);
+  }
+.fi
+.SH AVAILABILITY
+Added in curl 7.62.0
+.SH "SEE ALSO"
+.BR curl_url_cleanup "(3), " curl_url_get "(3), " curl_url_set "(3), "
+.BR curl_url_dup "(3), "

curl/docs/libcurl/curl_url_cleanup.3

@@ -0,0 +1,45 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_url_cleanup 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_url_cleanup - free a CURLU handle
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+void curl_url_cleanup(CURLU *handle);
+.fi
+.SH DESCRIPTION
+Frees all the resources associated with the given CURLU handle!
+.SH RETURN VALUE
+none
+.SH EXAMPLE
+.nf
+  CURLU *url = curl_url();
+  curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
+  curl_url_cleanup(url);
+.fi
+.SH AVAILABILITY
+Added in curl 7.62.0
+.SH "SEE ALSO"
+.BR curl_url_dup "(3), " curl_url "(3), " curl_url_set "(3), "
+.BR curl_url_get "(3), "

curl/docs/libcurl/curl_url_dup.3

@@ -0,0 +1,53 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_url_dup 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_url_dup - duplicate a CURLU handle
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+CURLU *curl_url_dup(CURLU *inhandle);
+.fi
+.SH DESCRIPTION
+Duplicates a given CURLU \fIinhandle\fP and all its contents and returns a
+pointer to a new CURLU handle. The new handle also needs to be freed with
+\fIcurl_url_cleanup(3)\fP.
+.SH RETURN VALUE
+Returns a new handle or NULL if out of memory.
+.SH EXAMPLE
+.nf
+  CURLUcode rc;
+  CURLU *url = curl_url();
+  CURLU *url2;
+  rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
+  if(!rc) {
+    url2 = curl_url_dup(url); /* clone it! */
+    curl_url_cleanup(url2);
+  }
+  curl_url_cleanup(url);
+.fi
+.SH AVAILABILITY
+Added in curl 7.62.0
+.SH "SEE ALSO"
+.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), "
+.BR curl_url_get "(3), "

curl/docs/libcurl/curl_url_get.3

@@ -0,0 +1,116 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_url_get 3 "November 05, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_url_get - extract a part from a URL
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+.nf
+CURLUcode curl_url_get(CURLU *url,
+                       CURLUPart what,
+                       char **part,
+                       unsigned int flags)
+.fi
+.SH DESCRIPTION
+Given the \fIurl\fP handle of an already parsed URL, this function lets the
+user extract individual pieces from it.
+
+The \fIwhat\fP argument should be the particular part to extract (see list
+below) and \fIpart\fP points to a 'char *' to get updated to point to a newly
+allocated string with the contents.
+
+The \fIflags\fP argument is a bitmask with individual features.
+
+The returned part pointer must be freed with \fIcurl_free(3)\fP after use.
+.SH FLAGS
+The flags argument is zero, one or more bits set in a bitmask.
+.IP CURLU_DEFAULT_PORT
+If the handle has no port stored, this option will make \fIcurl_url_get(3)\fP
+return the default port for the used scheme.
+.IP CURLU_DEFAULT_SCHEME
+If the handle has no scheme stored, this option will make
+\fIcurl_url_get(3)\fP return the default scheme instead of error.
+.IP CURLU_NO_DEFAULT_PORT
+Instructs \fIcurl_url_get(3)\fP to not return a port number if it matches the
+default port for the scheme.
+.IP CURLU_URLDECODE
+Asks \fIcurl_url_get(3)\fP to URL decode the contents before returning it. It
+will not attempt to decode the scheme, the port number or the full URL.
+
+The query component will also get plus-to-space conversion as a bonus when
+this bit is set.
+
+Note that this URL decoding is charset unaware and you will get a zero
+terminated string back with data that could be intended for a particular
+encoding.
+
+If there's any byte values lower than 32 in the decoded string, the get
+operation will return an error instead.
+.SH PARTS
+.IP CURLUPART_URL
+When asked to return the full URL, \fIcurl_url_get(3)\fP will return a
+normalized and possibly cleaned up version of what was previously parsed.
+.IP CURLUPART_SCHEME
+Scheme cannot be URL decoded on get.
+.IP CURLUPART_USER
+.IP CURLUPART_PASSWORD
+.IP CURLUPART_OPTIONS
+.IP CURLUPART_HOST
+The host name. If it is an IPv6 numeric address, the zoneid will not be part
+of it but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical
+addresses are returned within brackets ([]).
+.IP CURLUPART_ZONEID
+If the host name is a numeric IPv6 address, this field might also be set.
+.IP CURLUPART_PORT
+Port cannot be URL decoded on get.
+.IP CURLUPART_PATH
+.IP CURLUPART_QUERY
+The query part will also get pluses converted to space when asked to URL
+decode on get with the CURLU_URLDECODE bit.
+.IP CURLUPART_FRAGMENT
+.SH RETURN VALUE
+Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
+fine.
+
+If this function returns an error, no URL part is returned.
+.SH EXAMPLE
+.nf
+  CURLUcode rc;
+  CURLU *url = curl_url();
+  rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
+  if(!rc) {
+    char *scheme;
+    rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
+    if(!rc) {
+      printf("the scheme is %s\\n", scheme);
+      curl_free(scheme);
+    }
+    curl_url_cleanup(url);
+  }
+.fi
+.SH AVAILABILITY
+Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
+.SH "SEE ALSO"
+.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), "
+.BR curl_url_dup "(3), "

curl/docs/libcurl/curl_url_set.3

@@ -0,0 +1,147 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_url_set 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_url_set - set a URL part
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+
+CURLUcode curl_url_set(CURLU *url,
+                       CURLUPart part,
+                       const char *content,
+                       unsigned int flags)
+.fi
+.SH DESCRIPTION
+Given the \fIurl\fP handle of an already parsed URL, this function lets the
+user set/update individual pieces of it.
+
+The \fIpart\fP argument should identify the particular URL part (see list
+below) to set or change, with \fIcontent\fP pointing to a null-terminated
+string with the new contents for that URL part. The contents should be in the
+form and encoding they'd use in a URL: URL encoded.
+
+Setting a part to a NULL pointer will effectively remove that part's contents
+from the CURLU handle.
+
+The \fIflags\fP argument is a bitmask with independent features.
+.SH PARTS
+.IP CURLUPART_URL
+Allows the full URL of the handle to be replaced. If the handle already is
+populated with a URL, the new URL can be relative to the previous.
+
+When successfully setting a new URL, relative or absolute, the handle contents
+will be replaced with the information of the newly set URL.
+
+Pass a pointer to a null-terminated string to the \fIurl\fP parameter. The
+string must point to a correctly formatted "RFC 3986+" URL or be a NULL
+pointer.
+.IP CURLUPART_SCHEME
+Scheme cannot be URL decoded on set.
+.IP CURLUPART_USER
+.IP CURLUPART_PASSWORD
+.IP CURLUPART_OPTIONS
+.IP CURLUPART_HOST
+The host name. If it is IDNA the string must then be encoded as your locale
+says or UTF-8 (when WinIDN is used). If it is a bracketed IPv6 numeric address
+it may contain a zone id (or you can use CURLUPART_ZONEID).
+.IP CURLUPART_ZONEID
+If the host name is a numeric IPv6 address, this field can also be set.
+.IP CURLUPART_PORT
+Port cannot be URL encoded on set. The given port number is provided as a
+string and the decimal number must be between 1 and 65535. Anything else will
+return an error.
+.IP CURLUPART_PATH
+If a path is set in the URL without a leading slash, a slash will be inserted
+automatically when this URL is read from the handle.
+.IP CURLUPART_QUERY
+The query part will also get spaces converted to pluses when asked to URL
+encode on set with the CURLU_URLENCODE bit.
+
+If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part will
+be appended on the end of the existing query - and if the previous part didn't
+end with an ampersand (&), an ampersand will be inserted before the new
+appended part.
+
+When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the
+first '=' symbol will not be URL encoded.
+
+The question mark in the URL is not part of the actual query contents.
+.IP CURLUPART_FRAGMENT
+The hash sign in the URL is not part of the actual fragment contents.
+.SH FLAGS
+The flags argument is zero, one or more bits set in a bitmask.
+.IP CURLU_NON_SUPPORT_SCHEME
+If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme.
+.IP CURLU_URLENCODE
+When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for
+scheme, port and URL.
+
+When setting the path component with URL encoding enabled, the slash character
+will be skipped.
+
+The query part gets space-to-plus conversion before the URL conversion.
+
+This URL encoding is charset unaware and will convert the input on a
+byte-by-byte manner.
+.IP CURLU_DEFAULT_SCHEME
+If set, will make libcurl allow the URL to be set without a scheme and then
+sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP
+option if both are set.
+.IP CURLU_GUESS_SCHEME
+If set, will make libcurl allow the URL to be set without a scheme and it
+instead "guesses" which scheme that was intended based on the host name.  If
+the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then
+that scheme will be used, otherwise it picks HTTP. Conflicts with the
+\fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set.
+.IP CURLU_NO_AUTHORITY
+If set, skips authority checks. The RFC allows individual schemes to omit the
+host part (normally the only mandatory part of the authority), but libcurl
+cannot know whether this is permitted for custom schemes. Specifying the flag
+permits empty authority sections, similar to how file scheme is handled.
+
+.SH RETURN VALUE
+Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
+fine.
+
+A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP
+part, must be shorter than 8000000 bytes otherwise it returns
+\fBCURLUE_MALFORMED_INPUT\fP (added in 7.65.0).
+
+If this function returns an error, no URL part is set.
+.SH EXAMPLE
+.nf
+  CURLUcode rc;
+  CURLU *url = curl_url();
+  rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
+  if(!rc) {
+    char *scheme;
+    /* change it to an FTP URL */
+    rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
+  }
+  curl_url_cleanup(url);
+.fi
+.SH AVAILABILITY
+Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
+.SH "SEE ALSO"
+.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
+.BR curl_url_dup "(3), "

curl/docs/libcurl/curl_version.3

@@ -0,0 +1,40 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH curl_version 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_version - returns the libcurl version string
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "char *curl_version( );"
+.ad
+.SH DESCRIPTION
+Returns a human readable string with the version number of libcurl and some of
+its important components (like OpenSSL version).
+
+We recommend using \fIcurl_version_info(3)\fP instead!
+.SH RETURN VALUE
+A pointer to a null-terminated string. The string resides in a statically
+allocated buffer and must not be freed by the caller.
+.SH "SEE ALSO"
+.BR curl_version_info "(3)"

curl/docs/libcurl/curl_version_info.3

@@ -0,0 +1,221 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH curl_version_info 3 "November 04, 2020" "libcurl 7.75.0" "libcurl Manual"
+
+.SH NAME
+curl_version_info - returns run-time libcurl version info
+.SH SYNOPSIS
+.B #include <curl/curl.h>
+.sp
+.BI "curl_version_info_data *curl_version_info( CURLversion "age ");"
+.ad
+.SH DESCRIPTION
+Returns a pointer to a filled in static struct with information about various
+features in the running version of libcurl. \fIage\fP should be set to the
+version of this functionality by the time you write your program. This way,
+libcurl will always return a proper struct that your program understands,
+while programs in the future might get a different
+struct. \fBCURLVERSION_NOW\fP will be the most recent one for the library you
+have installed:
+
+        data = curl_version_info(CURLVERSION_NOW);
+
+Applications should use this information to judge if things are possible to do
+or not, instead of using compile-time checks, as dynamic/DLL libraries can be
+changed independent of applications.
+
+The curl_version_info_data struct looks like this
+
+.nf
+typedef struct {
+  CURLversion age;          /* see description below */
+
+  const char *version;      /* human readable string */
+  unsigned int version_num; /* numeric representation */
+  const char *host;         /* human readable string */
+  int features;             /* bitmask, see below */
+  char *ssl_version;        /* human readable string */
+  long ssl_version_num;     /* not used, always zero */
+  const char *libz_version; /* human readable string */
+  const char * const *protocols; /* protocols */
+
+  /* when 'age' is CURLVERSION_SECOND or higher, the members below exist */
+  const char *ares;         /* human readable string */
+  int ares_num;             /* number */
+
+  /* when 'age' is CURLVERSION_THIRD or higher, the members below exist */
+  const char *libidn;       /* human readable string */
+
+  /* when 'age' is CURLVERSION_FOURTH or higher (>= 7.16.1), the members
+     below exist */
+  int iconv_ver_num;       /* '_libiconv_version' if iconv support enabled */
+
+  const char *libssh_version; /* human readable string */
+
+  /* when 'age' is CURLVERSION_FIFTH or higher (>= 7.57.0), the members
+     below exist */
+  unsigned int brotli_ver_num; /* Numeric Brotli version
+                                  (MAJOR << 24) | (MINOR << 12) | PATCH */
+  const char *brotli_version; /* human readable string. */
+
+  /* when 'age' is CURLVERSION_SIXTH or higher (>= 7.66.0), the members
+     below exist */
+  unsigned int nghttp2_ver_num; /* Numeric nghttp2 version
+                                   (MAJOR << 16) | (MINOR << 8) | PATCH */
+  const char *nghttp2_version; /* human readable string. */
+
+  const char *quic_version;    /* human readable quic (+ HTTP/3) library +
+                                  version or NULL */
+
+  /* when 'age' is CURLVERSION_SEVENTH or higher (>= 7.70.0), the members
+     below exist */
+  const char *cainfo;          /* the built-in default CURLOPT_CAINFO, might
+                                  be NULL */
+  const char *capath;          /* the built-in default CURLOPT_CAPATH, might
+                                  be NULL */
+  /* when 'age' is CURLVERSION_EIGHTH or higher (>= 7.71.0), the members
+     below exist */
+  unsigned int zstd_ver_num; /* Numeric Zstd version
+                                  (MAJOR << 24) | (MINOR << 12) | PATCH */
+  const char *zstd_version; /* human readable string. */
+} curl_version_info_data;
+.fi
+
+\fIage\fP describes what the age of this struct is. The number depends on how
+new the libcurl you're using is. You are however guaranteed to get a struct
+that you have a matching struct for in the header, as you tell libcurl your
+"age" with the input argument.
+
+\fIversion\fP is just an ascii string for the libcurl version.
+
+\fIversion_num\fP is a 24 bit number created like this: <8 bits major number>
+| <8 bits minor number> | <8 bits patch number>. Version 7.9.8 is therefore
+returned as 0x070908.
+
+\fIhost\fP is an ascii string showing what host information that this libcurl
+was built for. As discovered by a configure script or set by the build
+environment.
+
+\fIfeatures\fP can have none, one or more bits set, and the currently defined
+bits are:
+.RS
+.IP CURL_VERSION_ALTSVC
+HTTP Alt-Svc parsing and the associated options (Added in 7.64.1)
+.IP CURL_VERSION_ASYNCHDNS
+libcurl was built with support for asynchronous name lookups, which allows
+more exact timeouts (even on Windows) and less blocking when using the multi
+interface. (added in 7.10.7)
+.IP CURL_VERSION_BROTLI
+supports HTTP Brotli content encoding using libbrotlidec (Added in 7.57.0)
+.IP CURL_VERSION_ZSTD
+supports HTTP zstd content encoding using zstd library (Added in 7.72.0)
+.IP CURL_VERSION_CONV
+libcurl was built with support for character conversions, as provided by the
+CURLOPT_CONV_* callbacks. (Added in 7.15.4)
+.IP CURL_VERSION_CURLDEBUG
+libcurl was built with memory tracking debug capabilities. This is mainly of
+interest for libcurl hackers. (added in 7.19.6)
+.IP CURL_VERSION_DEBUG
+libcurl was built with debug capabilities (added in 7.10.6)
+.IP CURL_VERSION_GSSAPI
+libcurl was built with support for GSS-API. This makes libcurl use provided
+functions for Kerberos and SPNEGO authentication. It also allows libcurl
+to use the current user credentials without the app having to pass them on.
+(Added in 7.38.0)
+.IP CURL_VERSION_GSSNEGOTIATE
+supports HTTP GSS-Negotiate (added in 7.10.6)
+.IP CURL_VERSION_HSTS
+libcurl was built with support for HSTS (HTTP Strict Transport Security)
+(Added in 7.74.0)
+.IP CURL_VERSION_HTTPS_PROXY
+libcurl was built with support for HTTPS-proxy.
+(Added in 7.52.0)
+.IP CURL_VERSION_HTTP2
+libcurl was built with support for HTTP2.
+(Added in 7.33.0)
+.IP CURL_VERSION_HTTP3
+HTTP/3 and QUIC support are built-in (Added in 7.66.0)
+.IP CURL_VERSION_IDN
+libcurl was built with support for IDNA, domain names with international
+letters. (Added in 7.12.0)
+.IP CURL_VERSION_IPV6
+supports IPv6
+.IP CURL_VERSION_KERBEROS4
+supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0.
+.IP CURL_VERSION_KERBEROS5
+supports Kerberos V5 authentication for FTP, IMAP, POP3, SMTP and SOCKSv5 proxy
+(Added in 7.40.0)
+.IP CURL_VERSION_LARGEFILE
+libcurl was built with support for large files. (Added in 7.11.1)
+.IP CURL_VERSION_UNICODE
+libcurl was built with Unicode support on Windows. This makes non-ASCII
+characters work in filenames and options passed to libcurl. (Added in 7.72.0)
+.IP CURL_VERSION_LIBZ
+supports HTTP deflate using libz (Added in 7.10)
+.IP CURL_VERSION_MULTI_SSL
+libcurl was built with multiple SSL backends. For details, see
+\fIcurl_global_sslset(3)\fP.
+(Added in 7.56.0)
+.IP CURL_VERSION_NTLM
+supports HTTP NTLM (added in 7.10.6)
+.IP CURL_VERSION_NTLM_WB
+libcurl was built with support for NTLM delegation to a winbind helper.
+(Added in 7.22.0)
+.IP CURL_VERSION_PSL
+libcurl was built with support for Mozilla's Public Suffix List. This makes
+libcurl ignore cookies with a domain that's on the list.
+(Added in 7.47.0)
+.IP CURL_VERSION_SPNEGO
+libcurl was built with support for SPNEGO authentication (Simple and Protected
+GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8)
+.IP CURL_VERSION_SSL
+supports SSL (HTTPS/FTPS) (Added in 7.10)
+.IP CURL_VERSION_SSPI
+libcurl was built with support for SSPI. This is only available on Windows and
+makes libcurl use Windows-provided functions for Kerberos, NTLM, SPNEGO and
+Digest authentication. It also allows libcurl to use the current user
+credentials without the app having to pass them on. (Added in 7.13.2)
+.IP CURL_VERSION_TLSAUTH_SRP
+libcurl was built with support for TLS-SRP (in one or more of the built-in TLS
+backends). (Added in 7.21.4)
+.IP CURL_VERSION_UNIX_SOCKETS
+libcurl was built with support for Unix domain sockets.
+(Added in 7.40.0)
+.RE
+\fIssl_version\fP is an ASCII string for the TLS library name + version
+used. If libcurl has no SSL support, this is NULL. For example "Schannel",
+\&"SecureTransport" or "OpenSSL/1.1.0g".
+
+\fIssl_version_num\fP is always 0.
+
+\fIlibz_version\fP is an ASCII string (there is no numerical version). If
+libcurl has no libz support, this is NULL.
+
+\fIprotocols\fP is a pointer to an array of char * pointers, containing the
+names protocols that libcurl supports (using lowercase letters). The protocol
+names are the same as would be used in URLs. The array is terminated by a NULL
+entry.
+.SH RETURN VALUE
+A pointer to a curl_version_info_data struct.
+.SH "SEE ALSO"
+\fIcurl_version(3)\fP

curl/docs/libcurl/libcurl-easy.3

@@ -0,0 +1,59 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH libcurl 3 "November 04, 2020" "libcurl 7.75.0" "libcurl easy interface"
+
+.SH NAME
+libcurl-easy \- easy interface overview
+.SH DESCRIPTION
+When using libcurl's "easy" interface you init your session and get a handle
+(often referred to as an "easy handle"), which you use as input to the easy
+interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle.
+
+You continue by setting all the options you want in the upcoming transfer, the
+most important among them is the URL itself (you can't transfer anything
+without a specified URL as you may have figured out yourself). You might want
+to set some callbacks as well that will be called from the library when data
+is available etc. \fIcurl_easy_setopt(3)\fP is used for all this.
+
+\fICURLOPT_URL(3)\fP is only option you really must set, as otherwise there
+can be no transfer. Another commonly used option is \fICURLOPT_VERBOSE(3)\fP
+that will help you see what libcurl is doing under the hood, very useful when
+debugging for example. The \fIcurl_easy_setopt(3)\fP man page has a full index
+of the over 200 available options.
+
+If you at any point would like to blank all previously set options for a
+single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also
+make a clone of an easy handle (with all its set options) using
+\fIcurl_easy_duphandle(3)\fP.
+
+When all is setup, you tell libcurl to perform the transfer using
+\fIcurl_easy_perform(3)\fP.  It will then do the entire operation and won't
+return until it is done (successfully or not).
+
+After the transfer has been made, you can set new options and make another
+transfer, or if you're done, cleanup the session by calling
+\fIcurl_easy_cleanup(3)\fP. If you want persistent connections, you don't
+cleanup immediately, but instead run ahead and perform other transfers using
+the same easy handle.
+.SH "SEE ALSO"
+.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_easy_setopt "(3), "
+.BR libcurl-errors "(3), " libcurl-multi "(3), " libcurl "(3) "

curl/docs/libcurl/libcurl-env.3

@@ -0,0 +1,90 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 2018 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH libcurl-env 3 "November 04, 2020" "libcurl 7.75.0" "libcurl environment variables"
+
+.SH NAME
+libcurl-env \- environment variables libcurl understands
+.SH DESCRIPTION
+libcurl reads and understands a set of environment variables that if set will
+control and change behaviors. This is the full list of variables to set and
+description of what they do. Also note that curl, the command line tool,
+supports a set of additional environment variables independently of this.
+.IP "[scheme]_proxy"
+When libcurl is given a URL to use in a transfer, it first extracts the
+"scheme" part from the URL and checks if there is a given proxy set for that
+in its corresponding environment variable. A URL like "https://example.com"
+will hence use the "http_proxy" variable, while a URL like "ftp://example.com"
+will use the "ftp_proxy" variable.
+
+These proxy variables are also checked for in their uppercase versions, except
+the "http_proxy" one which is only used lowercase. Note also that some systems
+actually have a case insensitive handling of environment variables and then of
+course "HTTP_PROXY" will still work...
+.IP ALL_PROXY
+This is a setting to set proxy for all URLs, independently of what scheme is
+being used. Note that the scheme specific variables will override this one if
+set.
+.IP CURL_SSL_BACKEND
+When libcurl is built to support multiple SSL backends, it will select a
+specific backend at first use. If no selection is done by the program using
+libcurl, this variable's selection will be used. It should be set to the full
+SSL backend name to use (case insensitive).
+.IP HOME
+When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is
+checked as the primary way to find the "current" home directory in which
+the .netrc file is likely to exist.
+.IP LOGNAME
+User name to use when invoking the ntlm-wb tool, if NTLMUSER wasn't set.
+.IP NO_PROXY
+This has the same functionality as the \fICURLOPT_NOPROXY(3)\fP option: it
+gives libcurl a comma-separated list of host name patterns for which libcurl
+should not use a proxy.
+.IP NTLMUSER
+User name to use when invoking the ntlm-wb tool.
+.IP SSLKEYLOGFILE
+When set and libcurl runs with a SSL backend that supports this feature,
+libcurl will save SSL secrets into the given file name. Using those SSL
+secrets, other tools (such as Wireshark) can decrypt the SSL communication and
+analyze/view the traffic.
+.IP SSL_DIR
+When libcurl runs with the NSS backends for TLS features, this variable is
+used to find the directory for NSS PKI database instead of the built-in.
+.IP USER
+User name to use when invoking the ntlm-wb tool, if NTLMUSER and LOGNAME
+weren't set.
+.SH "Debug Variables"
+There's a set of variables only recognized and used if libcurl was built
+"debug enabled", which should never be true for a library used in production.
+.IP "CURL_GETHOSTNAME"
+Debug-only variable.
+.IP "CURL_FORCETIME"
+Debug-only variable.
+.IP "CURL_ENTROPY"
+Debug-only variable. Used to set a fixed faked value to use instead of a
+proper random number so that functions in libcurl that are otherwise getting
+random outputs can be tested for what they generate.
+.IP "CURL_TRACE"
+Debug-only variable. Used for debugging the lib/ldap implementation.
+.IP "CURL_NTLM_WB_FILE"
+Debug-only variable. Used to set to a debug-version of the ntlm-wb executable.
+.IP "CURL_OPENLDAP_TRACE"
+Debug-only variable. Used for debugging the lib/openldap.c implementation.

curl/docs/libcurl/libcurl-errors.3

@@ -0,0 +1,363 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH libcurl-errors 3 "November 04, 2020" "libcurl 7.75.0" "libcurl errors"
+
+.SH NAME
+libcurl-errors \- error codes in libcurl
+.SH DESCRIPTION
+This man page includes most, if not all, available error codes in libcurl.
+Why they occur and possibly what you can do to fix the problem are also included.
+.SH "CURLcode"
+Almost all "easy" interface functions return a CURLcode error code. No matter
+what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER(3)\fP
+is a good idea as it will give you a human readable error string that may
+offer more details about the cause of the error than just the error code.
+\fIcurl_easy_strerror(3)\fP can be called to get an error string from a given
+CURLcode number.
+
+CURLcode is one of the following:
+.IP "CURLE_OK (0)"
+All fine. Proceed as usual.
+.IP "CURLE_UNSUPPORTED_PROTOCOL (1)"
+The URL you passed to libcurl used a protocol that this libcurl does not
+support. The support might be a compile-time option that you didn't use, it
+can be a misspelled protocol string or just a protocol libcurl has no code
+for.
+.IP "CURLE_FAILED_INIT (2)"
+Very early initialization code failed. This is likely to be an internal error
+or problem, or a resource problem where something fundamental couldn't get
+done at init time.
+.IP "CURLE_URL_MALFORMAT (3)"
+The URL was not properly formatted.
+.IP "CURLE_NOT_BUILT_IN (4)"
+A requested feature, protocol or option was not found built-in in this libcurl
+due to a build-time decision. This means that a feature or option was not
+enabled or explicitly disabled when libcurl was built and in order to get it
+to function you have to get a rebuilt libcurl.
+.IP "CURLE_COULDNT_RESOLVE_PROXY (5)"
+Couldn't resolve proxy. The given proxy host could not be resolved.
+.IP "CURLE_COULDNT_RESOLVE_HOST (6)"
+Couldn't resolve host. The given remote host was not resolved.
+.IP "CURLE_COULDNT_CONNECT (7)"
+Failed to connect() to host or proxy.
+.IP "CURLE_WEIRD_SERVER_REPLY (8)"
+The server sent data libcurl couldn't parse. This error code was known as as
+\fICURLE_FTP_WEIRD_SERVER_REPLY\fP before 7.51.0.
+.IP "CURLE_REMOTE_ACCESS_DENIED (9)"
+We were denied access to the resource given in the URL.  For FTP, this occurs
+while trying to change to the remote directory.
+.IP "CURLE_FTP_ACCEPT_FAILED (10)"
+While waiting for the server to connect back when an active FTP session is
+used, an error code was sent over the control connection or similar.
+.IP "CURLE_FTP_WEIRD_PASS_REPLY (11)"
+After having sent the FTP password to the server, libcurl expects a proper
+reply. This error code indicates that an unexpected code was returned.
+.IP "CURLE_FTP_ACCEPT_TIMEOUT (12)"
+During an active FTP session while waiting for the server to connect, the
+\fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP (or the internal default) timeout expired.
+.IP "CURLE_FTP_WEIRD_PASV_REPLY (13)"
+libcurl failed to get a sensible result back from the server as a response to
+either a PASV or a EPSV command. The server is flawed.
+.IP "CURLE_FTP_WEIRD_227_FORMAT (14)"
+FTP servers return a 227-line as a response to a PASV command. If libcurl
+fails to parse that line, this return code is passed back.
+.IP "CURLE_FTP_CANT_GET_HOST (15)"
+An internal failure to lookup the host used for the new connection.
+.IP "CURLE_HTTP2 (16)"
+A problem was detected in the HTTP2 framing layer. This is somewhat generic
+and can be one out of several problems, see the error buffer for details.
+.IP "CURLE_FTP_COULDNT_SET_TYPE (17)"
+Received an error when trying to set the transfer mode to binary or ASCII.
+.IP "CURLE_PARTIAL_FILE (18)"
+A file transfer was shorter or larger than expected. This happens when the
+server first reports an expected transfer size, and then delivers data that
+doesn't match the previously given size.
+.IP "CURLE_FTP_COULDNT_RETR_FILE (19)"
+This was either a weird reply to a 'RETR' command or a zero byte transfer
+complete.
+.IP "CURLE_QUOTE_ERROR (21)"
+When sending custom "QUOTE" commands to the remote server, one of the commands
+returned an error code that was 400 or higher (for FTP) or otherwise
+indicated unsuccessful completion of the command.
+.IP "CURLE_HTTP_RETURNED_ERROR (22)"
+This is returned if \fICURLOPT_FAILONERROR(3)\fP is set TRUE and the HTTP
+server returns an error code that is >= 400.
+.IP "CURLE_WRITE_ERROR (23)"
+An error occurred when writing received data to a local file, or an error was
+returned to libcurl from a write callback.
+.IP "CURLE_UPLOAD_FAILED (25)"
+Failed starting the upload. For FTP, the server typically denied the STOR
+command. The error buffer usually contains the server's explanation for this.
+.IP "CURLE_READ_ERROR (26)"
+There was a problem reading a local file or an error returned by the read
+callback.
+.IP "CURLE_OUT_OF_MEMORY (27)"
+A memory allocation request failed. This is serious badness and
+things are severely screwed up if this ever occurs.
+.IP "CURLE_OPERATION_TIMEDOUT (28)"
+Operation timeout. The specified time-out period was reached according to the
+conditions.
+.IP "CURLE_FTP_PORT_FAILED (30)"
+The FTP PORT command returned error. This mostly happens when you haven't
+specified a good enough address for libcurl to use. See
+\fICURLOPT_FTPPORT(3)\fP.
+.IP "CURLE_FTP_COULDNT_USE_REST (31)"
+The FTP REST command returned error. This should never happen if the server is
+sane.
+.IP "CURLE_RANGE_ERROR (33)"
+The server does not support or accept range requests.
+.IP "CURLE_HTTP_POST_ERROR (34)"
+This is an odd error that mainly occurs due to internal confusion.
+.IP "CURLE_SSL_CONNECT_ERROR (35)"
+A problem occurred somewhere in the SSL/TLS handshake. You really want the
+error buffer and read the message there as it pinpoints the problem slightly
+more. Could be certificates (file formats, paths, permissions), passwords, and
+others.
+.IP "CURLE_BAD_DOWNLOAD_RESUME (36)"
+The download could not be resumed because the specified offset was out of the
+file boundary.
+.IP "CURLE_FILE_COULDNT_READ_FILE (37)"
+A file given with FILE:// couldn't be opened. Most likely because the file
+path doesn't identify an existing file. Did you check file permissions?
+.IP "CURLE_LDAP_CANNOT_BIND (38)"
+LDAP cannot bind. LDAP bind operation failed.
+.IP "CURLE_LDAP_SEARCH_FAILED (39)"
+LDAP search failed.
+.IP "CURLE_FUNCTION_NOT_FOUND (41)"
+Function not found. A required zlib function was not found.
+.IP "CURLE_ABORTED_BY_CALLBACK (42)"
+Aborted by callback. A callback returned "abort" to libcurl.
+.IP "CURLE_BAD_FUNCTION_ARGUMENT (43)"
+A function was called with a bad parameter.
+.IP "CURLE_INTERFACE_FAILED (45)"
+Interface error. A specified outgoing interface could not be used. Set which
+interface to use for outgoing connections' source IP address with
+\fICURLOPT_INTERFACE(3)\fP.
+.IP "CURLE_TOO_MANY_REDIRECTS (47)"
+Too many redirects. When following redirects, libcurl hit the maximum amount.
+Set your limit with \fICURLOPT_MAXREDIRS(3)\fP.
+.IP "CURLE_UNKNOWN_OPTION (48)"
+An option passed to libcurl is not recognized/known. Refer to the appropriate
+documentation. This is most likely a problem in the program that uses
+libcurl. The error buffer might contain more specific information about which
+exact option it concerns.
+.IP "CURLE_TELNET_OPTION_SYNTAX (49)"
+A telnet option string was Illegally formatted.
+.IP "CURLE_GOT_NOTHING (52)"
+Nothing was returned from the server, and under the circumstances, getting
+nothing is considered an error.
+.IP "CURLE_SSL_ENGINE_NOTFOUND (53)"
+The specified crypto engine wasn't found.
+.IP "CURLE_SSL_ENGINE_SETFAILED (54)"
+Failed setting the selected SSL crypto engine as default!
+.IP "CURLE_SEND_ERROR (55)"
+Failed sending network data.
+.IP "CURLE_RECV_ERROR (56)"
+Failure with receiving network data.
+.IP "CURLE_SSL_CERTPROBLEM (58)"
+problem with the local client certificate.
+.IP "CURLE_SSL_CIPHER (59)"
+Couldn't use specified cipher.
+.IP "CURLE_PEER_FAILED_VERIFICATION (60)"
+The remote server's SSL certificate or SSH md5 fingerprint was deemed not OK.
+This error code has been unified with CURLE_SSL_CACERT since 7.62.0. Its
+previous value was 51.
+.IP "CURLE_BAD_CONTENT_ENCODING (61)"
+Unrecognized transfer encoding.
+.IP "CURLE_LDAP_INVALID_URL (62)"
+Invalid LDAP URL.
+.IP "CURLE_FILESIZE_EXCEEDED (63)"
+Maximum file size exceeded.
+.IP "CURLE_USE_SSL_FAILED (64)"
+Requested FTP SSL level failed.
+.IP "CURLE_SEND_FAIL_REWIND (65)"
+When doing a send operation curl had to rewind the data to retransmit, but the
+rewinding operation failed.
+.IP "CURLE_SSL_ENGINE_INITFAILED (66)"
+Initiating the SSL Engine failed.
+.IP "CURLE_LOGIN_DENIED (67)"
+The remote server denied curl to login (Added in 7.13.1)
+.IP "CURLE_TFTP_NOTFOUND (68)"
+File not found on TFTP server.
+.IP "CURLE_TFTP_PERM (69)"
+Permission problem on TFTP server.
+.IP "CURLE_REMOTE_DISK_FULL (70)"
+Out of disk space on the server.
+.IP "CURLE_TFTP_ILLEGAL (71)"
+Illegal TFTP operation.
+.IP "CURLE_TFTP_UNKNOWNID (72)"
+Unknown TFTP transfer ID.
+.IP "CURLE_REMOTE_FILE_EXISTS (73)"
+File already exists and will not be overwritten.
+.IP "CURLE_TFTP_NOSUCHUSER (74)"
+This error should never be returned by a properly functioning TFTP server.
+.IP "CURLE_CONV_FAILED (75)"
+Character conversion failed.
+.IP "CURLE_CONV_REQD (76)"
+Caller must register conversion callbacks.
+.IP "CURLE_SSL_CACERT_BADFILE (77)"
+Problem with reading the SSL CA cert (path? access rights?)
+.IP "CURLE_REMOTE_FILE_NOT_FOUND (78)"
+The resource referenced in the URL does not exist.
+.IP "CURLE_SSH (79)"
+An unspecified error occurred during the SSH session.
+.IP "CURLE_SSL_SHUTDOWN_FAILED (80)"
+Failed to shut down the SSL connection.
+.IP "CURLE_AGAIN (81)"
+Socket is not ready for send/recv wait till it's ready and try again. This
+return code is only returned from \fIcurl_easy_recv(3)\fP and
+\fIcurl_easy_send(3)\fP (Added in 7.18.2)
+.IP "CURLE_SSL_CRL_BADFILE (82)"
+Failed to load CRL file (Added in 7.19.0)
+.IP "CURLE_SSL_ISSUER_ERROR (83)"
+Issuer check failed (Added in 7.19.0)
+.IP "CURLE_FTP_PRET_FAILED (84)"
+The FTP server does not understand the PRET command at all or does not support
+the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST(3)\fP, a
+custom LIST command will be sent with PRET CMD before PASV as well. (Added in
+7.20.0)
+.IP "CURLE_RTSP_CSEQ_ERROR (85)"
+Mismatch of RTSP CSeq numbers.
+.IP "CURLE_RTSP_SESSION_ERROR (86)"
+Mismatch of RTSP Session Identifiers.
+.IP "CURLE_FTP_BAD_FILE_LIST (87)"
+Unable to parse FTP file list (during FTP wildcard downloading).
+.IP "CURLE_CHUNK_FAILED (88)"
+Chunk callback reported error.
+.IP "CURLE_NO_CONNECTION_AVAILABLE (89)"
+(For internal use only, will never be returned by libcurl) No connection
+available, the session will be queued. (added in 7.30.0)
+.IP "CURLE_SSL_PINNEDPUBKEYNOTMATCH (90)"
+Failed to match the pinned key specified with \fICURLOPT_PINNEDPUBLICKEY(3)\fP.
+.IP "CURLE_SSL_INVALIDCERTSTATUS (91)"
+Status returned failure when asked with \fICURLOPT_SSL_VERIFYSTATUS(3)\fP.
+.IP "CURLE_HTTP2_STREAM (92)"
+Stream error in the HTTP/2 framing layer.
+.IP "CURLE_RECURSIVE_API_CALL (93)"
+An API function was called from inside a callback.
+.IP "CURLE_AUTH_ERROR (94)"
+An authentication function returned an error.
+.IP "CURLE_HTTP3 (95)"
+A problem was detected in the HTTP/3 layer. This is somewhat generic and can
+be one out of several problems, see the error buffer for details.
+.IP "CURLE_QUIC_CONNECT_ERROR (96)"
+QUIC connection error. This error may be caused by an SSL library error. QUIC
+is the protocol used for HTTP/3 transfers.
+.IP "CURLE_OBSOLETE*"
+These error codes will never be returned. They were used in an old libcurl
+version and are currently unused.
+.SH "CURLMcode"
+This is the generic return code used by functions in the libcurl multi
+interface. Also consider \fIcurl_multi_strerror(3)\fP.
+.IP "CURLM_CALL_MULTI_PERFORM (-1)"
+This is not really an error. It means you should call
+\fIcurl_multi_perform(3)\fP again without doing select() or similar in
+between. Before version 7.20.0 (released on February 9 2010) this could be returned by
+\fIcurl_multi_perform(3)\fP, but in later versions this return code is never
+used.
+.IP "CURLM_CALL_MULTI_SOCKET (-1)"
+An alias for CURLM_CALL_MULTI_PERFORM. Never returned by modern libcurl
+versions.
+.IP "CURLM_OK (0)"
+Things are fine.
+.IP "CURLM_BAD_HANDLE (1)"
+The passed-in handle is not a valid CURLM handle.
+.IP "CURLM_BAD_EASY_HANDLE (2)"
+An easy handle was not good/valid. It could mean that it isn't an easy handle
+at all, or possibly that the handle already is in use by this or another multi
+handle.
+.IP "CURLM_OUT_OF_MEMORY (3)"
+You are doomed.
+.IP "CURLM_INTERNAL_ERROR (4)"
+This can only be returned if libcurl bugs. Please report it to us!
+.IP "CURLM_BAD_SOCKET (5)"
+The passed-in socket is not a valid one that libcurl already knows about.
+(Added in 7.15.4)
+.IP "CURLM_UNKNOWN_OPTION (6)"
+curl_multi_setopt() with unsupported option
+(Added in 7.15.4)
+.IP "CURLM_ADDED_ALREADY (7)"
+An easy handle already added to a multi handle was attempted to get added a
+second time. (Added in 7.32.1)
+.IP "CURLM_RECURSIVE_API_CALL (8)"
+An API function was called from inside a callback.
+.IP "CURLM_WAKEUP_FAILURE (9)"
+Wakeup is unavailable or failed.
+.IP "CURLM_BAD_FUNCTION_ARGUMENT (10)"
+A function was called with a bad parameter.
+.SH "CURLSHcode"
+The "share" interface will return a CURLSHcode to indicate when an error has
+occurred.  Also consider \fIcurl_share_strerror(3)\fP.
+.IP "CURLSHE_OK (0)"
+All fine. Proceed as usual.
+.IP "CURLSHE_BAD_OPTION (1)"
+An invalid option was passed to the function.
+.IP "CURLSHE_IN_USE (2)"
+The share object is currently in use.
+.IP "CURLSHE_INVALID (3)"
+An invalid share object was passed to the function.
+.IP "CURLSHE_NOMEM (4)"
+Not enough memory was available.
+(Added in 7.12.0)
+.IP "CURLSHE_NOT_BUILT_IN (5)"
+The requested sharing could not be done because the library you use don't have
+that particular feature enabled. (Added in 7.23.0)
+.SH "CURLUcode"
+.IP "CURLUE_BAD_HANDLE (1)"
+An argument that should be a CURLU pointer was passed in as a NULL.
+.IP "CURLUE_BAD_PARTPOINTER (2)"
+A NULL pointer was passed to the 'part' argument of \fIcurl_url_get(3)\fP.
+.IP "CURLUE_MALFORMED_INPUT (3)"
+A malformed input was passed to a URL API function.
+.IP "CURLUE_BAD_PORT_NUMBER (4)"
+The port number was not a decimal number between 0 and 65535.
+.IP "CURLUE_UNSUPPORTED_SCHEME (5)"
+This libcurl build doesn't support the given URL scheme.
+.IP "CURLUE_URLDECODE (6)"
+URL decode error, most likely because of rubbish in the input.
+.IP "CURLUE_OUT_OF_MEMORY (7)"
+A memory function failed.
+.IP "CURLUE_USER_NOT_ALLOWED (8)"
+Credentials was passed in the URL when prohibited.
+.IP "CURLUE_UNKNOWN_PART (9)"
+An unknown part ID was passed to a URL API function.
+.IP "CURLUE_NO_SCHEME (10)"
+There is no scheme part in the URL.
+.IP "CURLUE_NO_USER (11)"
+There is no user part in the URL.
+.IP "CURLUE_NO_PASSWORD (12)"
+There is no password part in the URL.
+.IP "CURLUE_NO_OPTIONS (13)"
+There is no options part in the URL.
+.IP "CURLUE_NO_HOST (14)"
+There is no host part in the URL.
+.IP "CURLUE_NO_PORT (15)"
+There is no port part in the URL.
+.IP "CURLUE_NO_QUERY (16)"
+There is no query part in the URL.
+.IP "CURLUE_NO_FRAGMENT (17)"
+There is no fragment part in the URL.
+.SH "SEE ALSO"
+.BR curl_easy_strerror "(3), " curl_multi_strerror "(3), "
+.BR curl_share_strerror "(3), " CURLOPT_ERRORBUFFER "(3), "
+.BR CURLOPT_VERBOSE "(3), " CURLOPT_DEBUGFUNCTION "(3) "

curl/docs/libcurl/libcurl-multi.3

@@ -0,0 +1,181 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH libcurl-multi 3 "November 04, 2020" "libcurl 7.75.0" "libcurl multi interface"
+
+.SH NAME
+libcurl-multi \- how to use the multi interface
+.SH DESCRIPTION
+This is an overview on how to use the libcurl multi interface in your C
+programs. There are specific man pages for each function mentioned in
+here. There's also the \fIlibcurl-tutorial(3)\fP man page for a complete
+tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page
+for an overview of the libcurl easy interface.
+
+All functions in the multi interface are prefixed with curl_multi.
+.SH "OBJECTIVES"
+The multi interface offers several abilities that the easy interface doesn't.
+They are mainly:
+
+1. Enable a "pull" interface. The application that uses libcurl decides where
+and when to ask libcurl to get/send data.
+
+2. Enable multiple simultaneous transfers in the same thread without making it
+complicated for the application.
+
+3. Enable the application to wait for action on its own file descriptors and
+curl's file descriptors simultaneously.
+
+4. Enable event-based handling and scaling transfers up to and beyond
+thousands of parallel connections.
+.SH "ONE MULTI HANDLE MANY EASY HANDLES"
+To use the multi interface, you must first create a 'multi handle' with
+\fIcurl_multi_init(3)\fP. This handle is then used as input to all further
+curl_multi_* functions.
+
+With a multi handle and the multi interface you can do several simultaneous
+transfers in parallel. Each single transfer is built up around an easy
+handle. You create all the easy handles you need, and setup the appropriate
+options for each easy handle using \fIcurl_easy_setopt(3)\fP.
+
+There are two flavours of the multi interface, the select() oriented one and
+the event based one we call multi_socket. You will benefit from reading
+through the description of both versions to fully understand how they work and
+differentiate. We start out with the select() oriented version.
+
+When an easy handle is setup and ready for transfer, then instead of using
+\fIcurl_easy_perform(3)\fP like when using the easy interface for transfers,
+you should add the easy handle to the multi handle with
+\fIcurl_multi_add_handle(3)\fP. You can add more easy handles to a multi
+handle at any point, even if other transfers are already running.
+
+Should you change your mind, the easy handle is again removed from the multi
+stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi
+handle, you can again use other easy interface functions like
+\fIcurl_easy_perform(3)\fP on the handle or whatever you think is
+necessary. You can remove handles at any point in time during transfers.
+
+Adding the easy handle to the multi handle does not start the transfer.
+Remember that one of the main ideas with this interface is to let your
+application drive. You drive the transfers by invoking
+\fIcurl_multi_perform(3)\fP. libcurl will then transfer data if there is
+anything available to transfer. It'll use the callbacks and everything else
+you have setup in the individual easy handles. It'll transfer data on all
+current transfers in the multi stack that are ready to transfer anything. It
+may be all, it may be none. When there's nothing more to do for now, it
+returns back to the calling application.
+
+Your application extracts info from libcurl about when it would like to get
+invoked to transfer data or do other work. The most convenient way is to use
+\fIcurl_multi_poll(3)\fP that will help you wait until the application should
+call libcurl again. The older API to accomplish the same thing is
+\fIcurl_multi_fdset(3)\fP that extracts fd_sets from libcurl to use in
+select() or poll() calls in order to get to know when the transfers in the
+multi stack might need attention. Both these APIs allow for your program to
+wait for input on your own private file descriptors at the same time.
+\fIcurl_multi_timeout(3)\fP also helps you with providing a suitable timeout
+period for your select() calls.
+
+\fIcurl_multi_perform(3)\fP stores the number of still running transfers in
+one of its input arguments, and by reading that you can figure out when all
+the transfers in the multi handles are done. 'done' does not mean
+successful. One or more of the transfers may have failed. 
+
+To get information about completed transfers, to figure out success or not and
+similar, \fIcurl_multi_info_read(3)\fP should be called. It can return a
+message about a current or previous transfer. Repeated invokes of the function
+get more messages until the message queue is empty. The information you
+receive there includes an easy handle pointer which you may use to identify
+which easy handle the information regards.
+
+When a single transfer is completed, the easy handle is still left added to
+the multi stack. You need to first remove the easy handle with
+\fIcurl_multi_remove_handle(3)\fP and then close it with
+\fIcurl_easy_cleanup(3)\fP, or possibly set new options to it and add it again
+with \fIcurl_multi_add_handle(3)\fP to start another transfer.
+
+When all transfers in the multi stack are done, close the multi handle with
+\fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP
+invoke separate \fIcurl_easy_cleanup(3)\fP calls for every single easy handle
+to clean them up properly.
+
+If you want to re-use an easy handle that was added to the multi handle for
+transfer, you must first remove it from the multi stack and then re-add it
+again (possibly after having altered some options at your own choice).
+.SH "MULTI_SOCKET"
+\fIcurl_multi_socket_action(3)\fP function offers a way for applications to
+not only avoid being forced to use select(), but it also offers a much more
+high-performance API that will make a significant difference for applications
+using large numbers of simultaneous connections.
+
+\fIcurl_multi_socket_action(3)\fP is then used instead of
+\fIcurl_multi_perform(3)\fP.
+
+When using this API, you add easy handles to the multi handle just as with the
+normal multi interface. Then you also set two callbacks with the
+\fICURLMOPT_SOCKETFUNCTION(3)\fP and \fICURLMOPT_TIMERFUNCTION(3)\fP options
+to \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl
+will call with information about what sockets to wait for, and for what
+activity, and what the current timeout time is - if that expires libcurl
+should be notified.
+
+The multi_socket API is designed to inform your application about which
+sockets libcurl is currently using and for what activities (read and/or write)
+on those sockets your application is expected to wait for.
+
+Your application must make sure to receive all sockets informed about in the
+\fICURLMOPT_SOCKETFUNCTION(3)\fP callback and make sure it reacts on the given
+activity on them. When a socket has the given activity, you call
+\fIcurl_multi_socket_action(3)\fP specifying which socket and action there
+are.
+
+The \fICURLMOPT_TIMERFUNCTION(3)\fP callback is called to set a timeout. When
+that timeout expires, your application should call the
+\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout.
+
+This API is typically used with an event-driven underlying functionality (like
+libevent, libev, kqueue, epoll or similar) with which the application
+"subscribes" on socket changes. This allows applications and libcurl to much
+better scale upward and beyond thousands of simultaneous transfers without
+losing performance.
+
+When you've added your initial set of handles, you call
+\fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the sockfd
+argument, and you'll get callbacks call that sets you up and you then continue
+to call \fIcurl_multi_socket_action(3)\fP accordingly when you get activity on
+the sockets you've been asked to wait on, or if the timeout timer expires.
+
+You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has
+completed, as it then has a message saying so.
+.SH "BLOCKING"
+A few areas in the code are still using blocking code, even when used from the
+multi interface. While we certainly want and intend for these to get fixed in
+the future, you should be aware of the following current restrictions:
+
+.nf
+ - Name resolves unless the c-ares or threaded-resolver backends are used
+ - SOCKS proxy handshakes
+ - file:// transfers
+ - TELNET transfers
+.fi
+.SH "SEE ALSO"
+.BR libcurl-errors "(3), " libcurl-easy "(3), " libcurl "(3) "

curl/docs/libcurl/libcurl-security.3

@@ -0,0 +1,368 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH libcurl-security 3 "November 04, 2020" "libcurl 7.75.0" "libcurl security"
+
+.SH NAME
+libcurl-security \- security considerations when using libcurl
+.SH "Security"
+The libcurl project takes security seriously.  The library is written with
+caution and precautions are taken to mitigate many kinds of risks encountered
+while operating with potentially malicious servers on the Internet. It is a
+powerful library, however, which allows application writers to make trade-offs
+between ease of writing and exposure to potential risky operations. If used
+the right way, you can use libcurl to transfer data pretty safely.
+
+Many applications are used in closed networks where users and servers can
+(possibly) be trusted, but many others are used on arbitrary servers and are
+fed input from potentially untrusted users.  Following is a discussion about
+some risks in the ways in which applications commonly use libcurl and
+potential mitigations of those risks. It is by no means comprehensive, but
+shows classes of attacks that robust applications should consider. The Common
+Weakness Enumeration project at https://cwe.mitre.org/ is a good reference for
+many of these and similar types of weaknesses of which application writers
+should be aware.
+.SH "Command Lines"
+If you use a command line tool (such as curl) that uses libcurl, and you give
+options to the tool on the command line those options can very likely get read
+by other users of your system when they use 'ps' or other tools to list
+currently running processes.
+
+To avoid these problems, never feed sensitive things to programs using command
+line options. Write them to a protected file and use the \-K option to avoid
+this.
+.SH ".netrc"
+\&.netrc is a pretty handy file/feature that allows you to login quickly and
+automatically to frequently visited sites. The file contains passwords in
+clear text and is a real security risk. In some cases, your .netrc is also
+stored in a home directory that is NFS mounted or used on another network
+based file system, so the clear text password will fly through your network
+every time anyone reads that file!
+
+For applications that enable .netrc use, a user who manage to set the right
+URL might then be possible to pass on passwords.
+
+To avoid these problems, don't use .netrc files and never store passwords in
+plain text anywhere.
+.SH "Clear Text Passwords"
+Many of the protocols libcurl supports send name and password unencrypted as
+clear text (HTTP Basic authentication, FTP, TELNET etc). It is very easy for
+anyone on your network or a network nearby yours to just fire up a network
+analyzer tool and eavesdrop on your passwords. Don't let the fact that HTTP
+Basic uses base64 encoded passwords fool you. They may not look readable at a
+first glance, but they very easily "deciphered" by anyone within seconds.
+
+To avoid this problem, use an authentication mechanism or other protocol that
+doesn't let snoopers see your password: Digest, CRAM-MD5, Kerberos, SPNEGO or
+NTLM authentication. Or even better: use authenticated protocols that protect
+the entire connection and everything sent over it.
+.SH "Un-authenticated Connections"
+Protocols that don't have any form of cryptographic authentication cannot
+with any certainty know that they communicate with the right remote server.
+
+If your application is using a fixed scheme or fixed host name, it is not safe
+as long as the connection is un-authenticated. There can be a
+man-in-the-middle or in fact the whole server might have been replaced by an
+evil actor.
+
+Un-authenticated protocols are unsafe. The data that comes back to curl may
+have been injected by an attacker. The data that curl sends might be modified
+before it reaches the intended server. If it even reaches the intended server
+at all.
+
+Remedies:
+.IP "Restrict operations to authenticated transfers"
+Ie use authenticated protocols protected with HTTPS or SSH.
+.IP "Make sure the server's certificate etc is verified"
+Never ever switch off certificate verification.
+.SH "Redirects"
+The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP
+redirects sent by a remote server.  These redirects can refer to any kind of
+URL, not just HTTP. libcurl restricts the protocols allowed to be used in
+redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are
+enabled by default. Applications may opt to restrict that set further.
+
+A redirect to a file: URL would cause the libcurl to read (or write) arbitrary
+files from the local filesystem.  If the application returns the data back to
+the user (as would happen in some kinds of CGI scripts), an attacker could
+leverage this to read otherwise forbidden data (e.g.
+file://localhost/etc/passwd).
+
+If authentication credentials are stored in the ~/.netrc file, or Kerberos
+is in use, any other URL type (not just file:) that requires
+authentication is also at risk.  A redirect such as
+ftp://some-internal-server/private-file would then return data even when
+the server is password protected.
+
+In the same way, if an unencrypted SSH private key has been configured for the
+user running the libcurl application, SCP: or SFTP: URLs could access password
+or private-key protected resources,
+e.g. sftp://user@some-internal-server/etc/passwd
+
+The \fICURLOPT_REDIR_PROTOCOLS(3)\fP and \fICURLOPT_NETRC(3)\fP options can be
+used to mitigate against this kind of attack.
+
+A redirect can also specify a location available only on the machine running
+libcurl, including servers hidden behind a firewall from the attacker.
+e.g. http://127.0.0.1/ or http://intranet/delete-stuff.cgi?delete=all or
+tftp://bootp-server/pc-config-data
+
+Applications can mitigate against this by disabling
+\fICURLOPT_FOLLOWLOCATION(3)\fP and handling redirects itself, sanitizing URLs
+as necessary. Alternately, an app could leave \fICURLOPT_FOLLOWLOCATION(3)\fP
+enabled but set \fICURLOPT_REDIR_PROTOCOLS(3)\fP and install a
+\fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback function in which addresses are
+sanitized before use.
+.SH "Local Resources"
+A user who can control the DNS server of a domain being passed in within a URL
+can change the address of the host to a local, private address which a
+server-side libcurl-using application could then use. e.g. the innocuous URL
+http://fuzzybunnies.example.com/ could actually resolve to the IP address of a
+server behind a firewall, such as 127.0.0.1 or 10.1.2.3.  Applications can
+mitigate against this by setting a \fICURLOPT_OPENSOCKETFUNCTION(3)\fP and
+checking the address before a connection.
+
+All the malicious scenarios regarding redirected URLs apply just as well to
+non-redirected URLs, if the user is allowed to specify an arbitrary URL that
+could point to a private resource. For example, a web app providing a
+translation service might happily translate file://localhost/etc/passwd and
+display the result.  Applications can mitigate against this with the
+\fICURLOPT_PROTOCOLS(3)\fP option as well as by similar mitigation techniques
+for redirections.
+
+A malicious FTP server could in response to the PASV command return an IP
+address and port number for a server local to the app running libcurl but
+behind a firewall.  Applications can mitigate against this by using the
+\fICURLOPT_FTP_SKIP_PASV_IP(3)\fP option or \fICURLOPT_FTPPORT(3)\fP.
+
+Local servers sometimes assume local access comes from friends and trusted
+users. An application that expects https://example.com/file_to_read that and
+instead gets http://192.168.0.1/my_router_config might print a file that would
+otherwise be protected by the firewall.
+
+Allowing your application to connect to local hosts, be it the same machine
+that runs the application or a machine on the same local network, might be
+possible to exploit by an attacker who then perhaps can "port-scan" the
+particular hosts - depending on how the application and servers acts.
+.SH "IPv6 Addresses"
+libcurl will normally handle IPv6 addresses transparently and just as easily
+as IPv4 addresses. That means that a sanitizing function that filters out
+addresses like 127.0.0.1 isn't sufficient--the equivalent IPv6 addresses ::1,
+::, 0:00::0:1, ::127.0.0.1 and ::ffff:7f00:1 supplied somehow by an attacker
+would all bypass a naive filter and could allow access to undesired local
+resources.  IPv6 also has special address blocks like link-local and
+site-local that generally shouldn't be accessed by a server-side libcurl-using
+application.  A poorly-configured firewall installed in a data center,
+organization or server may also be configured to limit IPv4 connections but
+leave IPv6 connections wide open.  In some cases, setting
+\fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4 can be used to limit resolved
+addresses to IPv4 only and bypass these issues.
+.SH Uploads
+When uploading, a redirect can cause a local (or remote) file to be
+overwritten. Applications must not allow any unsanitized URL to be passed in
+for uploads. Also, \fICURLOPT_FOLLOWLOCATION(3)\fP should not be used on
+uploads.  Instead, the applications should consider handling redirects itself,
+sanitizing each URL first.
+.SH Authentication
+Use of \fICURLOPT_UNRESTRICTED_AUTH(3)\fP could cause authentication
+information to be sent to an unknown second server.  Applications can mitigate
+against this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP and handling
+redirects itself, sanitizing where necessary.
+
+Use of the CURLAUTH_ANY option to \fICURLOPT_HTTPAUTH(3)\fP could result in
+user name and password being sent in clear text to an HTTP server.  Instead,
+use CURLAUTH_ANYSAFE which ensures that the password is encrypted over the
+network, or else fail the request.
+
+Use of the CURLUSESSL_TRY option to \fICURLOPT_USE_SSL(3)\fP could result in
+user name and password being sent in clear text to an FTP server.  Instead,
+use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else
+fail the request.
+.SH Cookies
+If cookies are enabled and cached, then a user could craft a URL which
+performs some malicious action to a site whose authentication is already
+stored in a cookie. e.g. http://mail.example.com/delete-stuff.cgi?delete=all
+Applications can mitigate against this by disabling cookies or clearing them
+between requests.
+.SH "Dangerous SCP URLs"
+SCP URLs can contain raw commands within the scp: URL, which is a side effect
+of how the SCP protocol is designed. e.g.
+
+  scp://user:pass@host/a;date >/tmp/test;
+
+Applications must not allow unsanitized SCP: URLs to be passed in for
+downloads.
+.SH "file://"
+By default curl and libcurl support file:// URLs. Such a URL is always an
+access, or attempted access, to a local resource. If your application wants to
+avoid that, keep control of what URLs to use and/or prevent curl/libcurl from
+using the protocol.
+
+By default, libcurl prohibits redirects to file:// URLs.
+
+.SH "Warning: file:// on Windows"
+The Windows operating system will automatically, and without any way for
+applications to disable it, try to establish a connection to another host over
+the network and access it (over SMB or other protocols), if only the correct
+file path is accessed.
+
+When first realizing this, the curl team tried to filter out such attempts in
+order to protect applications for inadvertent probes of for example internal
+networks etc. This resulted in CVE-2019-15601 and the associated security fix.
+
+However, we've since been made aware of the fact that the previous fix was far
+from adequate as there are several other ways to accomplish more or less the
+same thing: accessing a remote host over the network instead of the local file
+system.
+
+The conclusion we have come to is that this is a weakness or feature in the
+Windows operating system itself, that we as an application cannot safely
+protect users against. It would just be a whack-a-mole race we don't want to
+participate in. There are too many ways to do it and there's no knob we can
+use to turn off the practice.
+
+If you use curl or libcurl on Windows (any version), disable the use of the
+FILE protocol in curl or be prepared that accesses to a range of "magic paths"
+will potentially make your system try to access other hosts on your
+network. curl cannot protect you against this.
+.SH "What if the user can set the URL"
+Applications may find it tempting to let users set the URL that it can work
+on. That's probably fine, but opens up for mischief and trickery that you as
+an application author may want to address or take precautions against.
+
+If your curl-using script allow a custom URL do you also, perhaps
+unintentionally, allow the user to pass other options to the curl command line
+if creative use of special characters are applied?
+
+If the user can set the URL, the user can also specify the scheme part to
+other protocols that you didn't intend for users to use and perhaps didn't
+consider. curl supports over 20 different URL schemes. "http://" might be what
+you thought, "ftp://" or "imap://" might be what the user gives your
+application. Also, cross-protocol operations might be done by using a
+particular scheme in the URL but point to a server doing a different protocol
+on a non-standard port.
+
+Remedies:
+.IP "Use --proto"
+curl command lines can use \fI--proto\fP to limit what URL schemes it accepts
+.IP "Use CURLOPT_PROTOCOLS"
+libcurl programs can use \fICURLOPT_PROTOCOLS(3)\fP to limit what URL schemes it accepts
+.IP "consider not allowing the user to set the full URL"
+Maybe just let the user provide data for parts of it? Or maybe filter input to
+only allow specific choices?
+.SH "RFC 3986 vs WHATWG URL"
+curl supports URLs mostly according to how they are defined in RFC 3986, and
+has done so since the beginning.
+
+Web browsers mostly adhere to the WHATWG URL Specification.
+
+This deviance makes some URLs copied between browsers (or returned over HTTP
+for redirection) and curl not work the same way. This can mislead users into
+getting the wrong thing, connecting to the wrong host or otherwise not work
+identically.
+.SH "FTP uses two connections"
+When performing an FTP transfer, two TCP connections are used: one for setting
+up the transfer and one for the actual data.
+
+FTP is not only un-authenticated, but the setting up of the second transfer is
+also a weak spot. The second connection to use for data, is either setup with
+the PORT/EPRT command that makes the server connect back to the client on the
+given IP+PORT, or with PASV/EPSV that makes the server setup a port to listen
+to and tells the client to connect to a given IP+PORT.
+
+Again, un-authenticated means that the connection might be meddled with by a
+man-in-the-middle or that there's a malicious server pretending to be the
+right one.
+
+A malicious FTP server can respond to PASV commands with the IP+PORT of a
+totally different machine. Perhaps even a third party host, and when there are
+many clients trying to connect to that third party, it could create a
+Distributed Denial-Of-Service attack out of it! If the client makes an upload
+operation, it can make the client send the data to another site. If the
+attacker can affect what data the client uploads, it can be made to work as a
+HTTP request and then the client could be made to issue HTTP requests to third
+party hosts.
+
+An attacker that manages to control curl's command line options can tell curl
+to send an FTP PORT command to ask the server to connect to a third party host
+instead of back to curl.
+
+The fact that FTP uses two connections makes it vulnerable in a way that is
+hard to avoid.
+.SH "Denial of Service"
+A malicious server could cause libcurl to effectively hang by sending data
+very slowly, or even no data at all but just keeping the TCP connection open.
+This could effectively result in a denial-of-service attack. The
+\fICURLOPT_TIMEOUT(3)\fP and/or \fICURLOPT_LOW_SPEED_LIMIT(3)\fP options can
+be used to mitigate against this.
+
+A malicious server could cause libcurl to download an infinite amount of data,
+potentially causing all of memory or disk to be filled. Setting the
+\fICURLOPT_MAXFILESIZE_LARGE(3)\fP option is not sufficient to guard against
+this.  Instead, applications should monitor the amount of data received within
+the write or progress callback and abort once the limit is reached.
+
+A malicious HTTP server could cause an infinite redirection loop, causing a
+denial-of-service. This can be mitigated by using the
+\fICURLOPT_MAXREDIRS(3)\fP option.
+.SH "Arbitrary Headers"
+User-supplied data must be sanitized when used in options like
+\fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_HTTPHEADER(3)\fP,
+\fICURLOPT_POSTFIELDS(3)\fP and others that are used to generate structured
+data. Characters like embedded carriage returns or ampersands could allow the
+user to create additional headers or fields that could cause malicious
+transactions.
+.SH "Server-supplied Names"
+A server can supply data which the application may, in some cases, use as a
+file name. The curl command-line tool does this with
+\fI--remote-header-name\fP, using the Content-disposition: header to generate
+a file name.  An application could also use \fICURLINFO_EFFECTIVE_URL(3)\fP to
+generate a file name from a server-supplied redirect URL. Special care must be
+taken to sanitize such names to avoid the possibility of a malicious server
+supplying one like "/etc/passwd", "\\autoexec.bat", "prn:" or even ".bashrc".
+.SH "Server Certificates"
+A secure application should never use the \fICURLOPT_SSL_VERIFYPEER(3)\fP
+option to disable certificate validation. There are numerous attacks that are
+enabled by applications that fail to properly validate server TLS/SSL
+certificates, thus enabling a malicious server to spoof a legitimate
+one. HTTPS without validated certificates is potentially as insecure as a
+plain HTTP connection.
+.SH "Report Security Problems"
+Should you detect or just suspect a security problem in libcurl or curl,
+contact the project curl security team immediately. See
+https://curl.se/dev/secprocess.html for details.
+.SH "Showing What You Do"
+Relatedly, be aware that in situations when you have problems with libcurl and
+ask someone for help, everything you reveal in order to get best possible help
+might also impose certain security related risks. Host names, user names,
+paths, operating system specifics, etc. (not to mention passwords of course)
+may in fact be used by intruders to gain additional information of a potential
+target.
+
+Be sure to limit access to application logs if they could hold private or
+security-related data.  Besides the obvious candidates like user names and
+passwords, things like URLs, cookies or even file names could also hold
+sensitive data.
+
+To avoid this problem, you must of course use your common sense. Often, you
+can just edit out the sensitive data or just search/replace your true
+information with faked data.

curl/docs/libcurl/libcurl-share.3

@@ -0,0 +1,66 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH libcurl-share 3 "November 05, 2020" "libcurl 7.75.0" "libcurl share interface"
+
+.SH NAME
+libcurl-share \- how to use the share interface
+.SH DESCRIPTION
+This is an overview on how to use the libcurl share interface in your C
+programs. There are specific man pages for each function mentioned in
+here.
+
+All functions in the share interface are prefixed with curl_share.
+
+.SH "OBJECTIVES"
+The share interface was added to enable sharing of data between curl
+\&"handles".
+.SH "ONE SET OF DATA - MANY TRANSFERS"
+You can have multiple easy handles share data between them. Have them update
+and use the \fBsame\fP cookie database, DNS cache, TLS session cache and/or
+connection cache! This way, each single transfer will take advantage from data
+updates made by the other transfer(s).
+.SH "SHARE OBJECT"
+You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle
+for a newly created one.
+
+You tell the shared object what data you want it to share by using
+\fIcurl_share_setopt(3)\fP.
+
+Since you can use this share from multiple threads, and libcurl has no
+internal thread synchronization, you must provide mutex callbacks if you're
+using this multi-threaded. You set lock and unlock functions with
+\fIcurl_share_setopt(3)\fP too.
+
+Then, you make an easy handle to use this share, you set the
+\fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, and pass in
+share handle. You can make any number of easy handles share the same share
+handle.
+
+To make an easy handle stop using that particular share, you set
+\fICURLOPT_SHARE(3)\fP to NULL for that easy handle. To make a handle stop
+sharing a particular data, you can \fICURLSHOPT_UNSHARE\fP it.
+
+When you're done using the share, make sure that no easy handle is still using
+it, and call \fIcurl_share_cleanup(3)\fP on the handle.
+.SH "SEE ALSO"
+.BR curl_share_init "(3), " curl_share_setopt "(3), " curl_share_cleanup "(3)"
+.BR libcurl-errors "(3), " libcurl-easy "(3), " libcurl-multi "(3) "

curl/docs/libcurl/libcurl-thread.3

@@ -0,0 +1,108 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 2015 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH libcurl-thread 3 "November 04, 2020" "libcurl 7.75.0" "libcurl thread safety"
+
+.SH NAME
+libcurl-thread \- libcurl thread safety
+.SH "Multi-threading with libcurl"
+libcurl is thread safe but has no internal thread synchronization. You may have
+to provide your own locking should you meet any of the thread safety exceptions
+below.
+
+\fBHandles.\fP You must \fBnever\fP share the same handle in multiple threads.
+You can pass the handles around among threads, but you must never use a single
+handle from more than one thread at any given time.
+
+\fBShared objects.\fP You can share certain data between multiple handles by
+using the share interface but you must provide your own locking and set
+\fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.
+.SH TLS
+If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
+then of course using the underlying SSL library multi-threaded and those libs
+might have their own requirements on this issue.  You may need to provide one
+or two functions to allow it to function properly:
+.IP OpenSSL
+OpenSSL 1.1.0+ "can be safely used in multi-threaded applications provided that
+support for the underlying OS threading API is built-in." In that case the
+engine is used by libcurl in a way that is fully thread-safe.
+
+https://www.openssl.org/docs/man1.1.0/man3/CRYPTO_THREAD_run_once.html#DESCRIPTION
+
+OpenSSL <= 1.0.2 the user must set callbacks.
+
+https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_set_locking_callback.html#DESCRIPTION
+
+https://curl.se/libcurl/c/opensslthreadlock.html
+
+.IP GnuTLS
+https://gnutls.org/manual/html_node/Thread-safety.html
+.IP NSS
+thread-safe already without anything required.
+.IP Secure-Transport
+The engine is used by libcurl in a way that is fully thread-safe.
+.IP Schannel
+The engine is used by libcurl in a way that is fully thread-safe.
+.IP wolfSSL
+The engine is used by libcurl in a way that is fully thread-safe.
+.IP BoringSSL
+The engine is used by libcurl in a way that is fully thread-safe.
+.SH "Other areas of caution"
+.IP Signals
+Signals are used for timing out name resolves (during DNS lookup) - when built
+without using either the c-ares or threaded resolver backends. When using
+multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP option to 1L for
+all handles. Everything will or might work fine except that timeouts are not
+honored during the DNS lookup - which you can work around by building libcurl
+with c-ares or threaded-resolver support. c-ares is a library that provides
+asynchronous name resolves. On some platforms, libcurl simply will not
+function properly multi-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option
+is set.
+
+When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal
+with the risk of a SIGPIPE (that at least the OpenSSL backend can
+trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L will not work in a
+threaded situation as there will be race where libcurl risks restoring the
+former signal handler while another thread should still ignore it.
+.IP "Name resolving"
+\fBgethostby* functions and other system calls.\fP These functions, provided
+by your operating system, must be thread safe. It is very important that
+libcurl can find and use thread safe versions of these and other system calls,
+as otherwise it can't function fully thread safe. Some operating systems are
+known to have faulty thread implementations. We have previously received
+problem reports on *BSD (at least in the past, they may be working fine these
+days).  Some operating systems that are known to have solid and working thread
+support are Linux, Solaris and Windows.
+.IP "curl_global_* functions"
+These functions are not thread safe. If you are using libcurl with multiple
+threads it is especially important that before use you call
+\fIcurl_global_init(3)\fP or \fIcurl_global_init_mem(3)\fP to explicitly
+initialize the library and its dependents, rather than rely on the "lazy"
+fail-safe initialization that takes place the first time
+\fIcurl_easy_init(3)\fP is called. For an in-depth explanation refer to
+\fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP.
+.IP "Memory functions"
+These functions, provided either by your operating system or your own
+replacements, must be thread safe. You can use \fIcurl_global_init_mem(3)\fP
+to set your own replacement memory functions.
+.IP "Non-safe functions"
+\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread-safe.

curl/docs/libcurl/libcurl-url.3

@@ -0,0 +1,138 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH libcurl 3 "November 05, 2020" "libcurl 7.75.0" "libcurl url interface"
+
+.SH NAME
+libcurl-url \- URL interface overview
+.SH DESCRIPTION
+The URL interface provides a set of functions for parsing and generating URLs.
+.SH INCLUDE
+You still only include <curl/curl.h> in your code. Note that the URL API was
+introduced in 7.62.0.
+.SH CREATE
+Create a handle that holds URL info and resources with \fIcurl_url(3)\fP:
+
+  CURLU *h = curl_url();
+.SH CLEANUP
+When done with it, clean it up with \fIcurl_url_cleanup(3)\fP:
+
+  curl_url_cleanup(h);
+.SH DUPLICATE
+When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP:
+
+  CURLU *nh = curl_url_dup(h);
+.SH PARSING
+By "setting" a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed
+and stored in the handle. If the URL is not syntactically correct it will
+return an error instead.
+
+.nf
+  rc = curl_url_set(h, CURLUPART_URL,
+                    "https://example.com:449/foo/bar?name=moo", 0);
+.fi
+
+The zero in the fourth argument is a bitmask for changing specific features.
+
+If successful, this stores the URL in its individual parts within the handle.
+.SH REDIRECT
+When a handle already contains info about a URL, setting a relative URL will
+make it "redirect" to adapt to it.
+
+  rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
+.SH "GET URL"
+The `CURLU` handle represents a URL and you can easily extract that with
+\fIcurl_url_get(3)\fP:
+
+  char *url;
+  rc = curl_url_get(h, CURLUPART_URL, &url, 0);
+  curl_free(url);
+
+The zero in the fourth argument is a bitmask for changing specific features.
+.SH "GET PARTS"
+When a URL has been parsed or parts have been set, you can extract those
+pieces from the handle at any time.
+
+.nf
+  rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
+  rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);
+  rc = curl_url_get(h, CURLUPART_USER, &user, 0);
+  rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
+  rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
+  rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
+  rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
+  rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);
+.fi
+
+Extracted parts are not URL decoded unless the user also asks for it with the
+CURLU_URLDECODE flag set in the fourth bitmask argument.
+
+Remember to free the returned string with \fIcurl_free(3)\fP when you're done
+with it!
+.SH "SET PARTS"
+A user set individual URL parts, either after having parsed a full URL or
+instead of parsing such.
+
+.nf
+  rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
+  rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
+  rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
+  rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
+  rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
+  rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
+  rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
+  rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
+.fi
+
+Set parts are not URL encoded unless the user asks for it with the
+`CURLU_URLENCODE` flag.
+.SH "APPENDQUERY"
+An application can append a string to the right end of the query part with the
+`CURLU_APPENDQUERY` flag to \fIcurl_url_set(3)\fP.
+
+Imagine a handle that holds the URL `https://example.com/?shoes=2`. An
+application can then add the string `hat=1` to the query part like this:
+
+.nf
+  rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
+.fi
+
+It will even notice the lack of an ampersand (`&`) separator so it will inject
+one too, and the handle's full URL will then equal
+`https://example.com/?shoes=2&hat=1`.
+
+The appended string can of course also get URL encoded on add, and if asked to
+URL encode, the encoding process will skip the '=' character. For example,
+append `candy=N&N` to what we already have, and URL encode it to deal with the
+ampersand in the data:
+
+.nf
+  rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
+                    CURLU_APPENDQUERY | CURLU_URLENCODE);
+.fi
+
+Now the URL looks like
+.nf
+  https://example.com/?shoes=2&hat=1&candy=N%26N`
+.fi
+.SH "SEE ALSO"
+.BR curl_url "(3), " curl_url_cleanup "(3), " curl_url_get "(3), "
+.BR curl_url_dup "(3), " curl_url_set "(3), " CURLOPT_URL "(3), "

curl/docs/libcurl/libcurl.3

@@ -0,0 +1,228 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.TH libcurl 3 "November 04, 2020" "libcurl 7.75.0" "libcurl overview"
+
+.SH NAME
+libcurl \- client-side URL transfers
+.SH DESCRIPTION
+This is a short overview on how to use libcurl in your C programs. There are
+specific man pages for each function mentioned in here. There are also the
+\fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the
+\fIlibcurl-share(3)\fP man page and the \fIlibcurl-tutorial(3)\fP man page for
+in-depth understanding on how to program with libcurl.
+
+There are many bindings available that bring libcurl access to your favourite
+language. Look elsewhere for documentation on those.
+
+libcurl has a global constant environment that you must set up and maintain
+while using libcurl.  This essentially means you call
+\fIcurl_global_init(3)\fP at the start of your program and
+\fIcurl_global_cleanup(3)\fP at the end.  See \fBGLOBAL CONSTANTS\fP below for
+details.
+
+If libcurl was compiled with support for multiple SSL backends, the function
+\fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP
+to select the active SSL backend.
+
+To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP
+for a single individual transfer (in either direction). You then set your
+desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options
+you set with \fIcurl_easy_setopt(3)\fP stick. They will be used on every
+repeated use of this handle until you either change the option, or you reset
+them all with \fIcurl_easy_reset(3)\fP.
+
+To actually transfer data you have the option of using the "easy" interface,
+or the "multi" interface.
+
+The easy interface is a synchronous interface with which you call
+\fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is
+completed, the function returns and you can continue. More details are found in
+the \fIlibcurl-easy(3)\fP man page.
+
+The multi interface on the other hand is an asynchronous interface, that you
+call and that performs only a little piece of the transfer on each invoke. It
+is perfect if you want to do things while the transfer is in progress, or
+similar. The multi interface allows you to select() on libcurl action, and
+even to easily download multiple files simultaneously using a single
+thread. See further details in the \fIlibcurl-multi(3)\fP man page.
+
+You can have multiple easy handles share certain data, even if they are used
+in different threads. This magic is setup using the share interface, as
+described in the \fIlibcurl-share(3)\fP man page.
+
+There is also a series of other helpful functions to use, including these:
+.RS
+.IP curl_version_info()
+gets detailed libcurl (and other used libraries) version info
+.IP curl_getdate()
+converts a date string to time_t
+.IP curl_easy_getinfo()
+get information about a performed transfer
+.IP curl_formadd()
+helps building an HTTP form POST
+.IP curl_formfree()
+free a list built with \fIcurl_formadd(3)\fP
+.IP curl_slist_append()
+builds a linked list
+.IP curl_slist_free_all()
+frees a whole curl_slist
+.RE
+
+.SH "LINKING WITH LIBCURL"
+On unix-like machines, there's a tool named curl-config that gets installed
+with the rest of the curl stuff when 'make install' is performed.
+
+curl-config is added to make it easier for applications to link with libcurl
+and developers to learn about libcurl and how to use it.
+
+Run 'curl-config --libs' to get the (additional) linker options you need to
+link with the particular version of libcurl you've installed. See the
+\fIcurl-config(1)\fP man page for further details.
+
+Unix-like operating system that ship libcurl as part of their distributions
+often don't provide the curl-config tool, but simply install the library and
+headers in the common path for this purpose.
+
+Many Linux and similar systems use pkg-config to provide build and link
+options about libraries and libcurl supports that as well.
+.SH "LIBCURL SYMBOL NAMES"
+All public functions in the libcurl interface are prefixed with 'curl_' (with
+a lowercase c). You can find other functions in the library source code, but
+other prefixes indicate that the functions are private and may change without
+further notice in the next release.
+
+Only use documented functions and functionality!
+.SH "PORTABILITY"
+libcurl works
+.B exactly
+the same, on any of the platforms it compiles and builds on.
+.SH "THREADS"
+libcurl is thread safe but there are a few exceptions. Refer to
+\fIlibcurl-thread(3)\fP for more information.
+
+.SH "PERSISTENT CONNECTIONS"
+Persistent connections means that libcurl can re-use the same connection for
+several transfers, if the conditions are right.
+
+libcurl will \fBalways\fP attempt to use persistent connections. Whenever you
+use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl
+will attempt to use an existing connection to do the transfer, and if none
+exists it'll open a new one that will be subject for re-use on a possible
+following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
+
+To allow libcurl to take full advantage of persistent connections, you should
+do as many of your file transfers as possible using the same handle.
+
+If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all
+the possibly open connections held by libcurl will be closed and forgotten.
+
+When you've created a multi handle and are using the multi interface, the
+connection pool is instead kept in the multi handle so closing and creating
+new easy handles to do transfers will not affect them. Instead all added easy
+handles can take advantage of the single shared pool.
+.SH "GLOBAL CONSTANTS"
+There are a variety of constants that libcurl uses, mainly through its
+internal use of other libraries, which are too complicated for the
+library loader to set up.  Therefore, a program must call a library
+function after the program is loaded and running to finish setting up
+the library code.  For example, when libcurl is built for SSL
+capability via the GNU TLS library, there is an elaborate tree inside
+that library that describes the SSL protocol.
+
+\fIcurl_global_init(3)\fP is the function that you must call.  This may
+allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so
+the companion function \fIcurl_global_cleanup(3)\fP releases them.
+
+The basic rule for constructing a program that uses libcurl is this: Call
+\fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately
+after the program starts, while it is still only one thread and before it uses
+libcurl at all.  Call \fIcurl_global_cleanup(3)\fP immediately before the
+program exits, when the program is again only one thread and after its last
+use of libcurl.
+
+You can call both of these multiple times, as long as all calls meet
+these requirements and the number of calls to each is the same.
+
+It isn't actually required that the functions be called at the beginning
+and end of the program -- that's just usually the easiest way to do it.
+It \fIis\fP required that the functions be called when no other thread
+in the program is running.
+
+These global constant functions are \fInot thread safe\fP, so you must
+not call them when any other thread in the program is running.  It
+isn't good enough that no other thread is using libcurl at the time,
+because these functions internally call similar functions of other
+libraries, and those functions are similarly thread-unsafe.  You can't
+generally know what these libraries are, or whether other threads are
+using them.
+
+The global constant situation merits special consideration when the
+code you are writing to use libcurl is not the main program, but rather
+a modular piece of a program, e.g. another library.  As a module,
+your code doesn't know about other parts of the program -- it doesn't
+know whether they use libcurl or not.  And its code doesn't necessarily
+run at the start and end of the whole program.
+
+A module like this must have global constant functions of its own, just like
+\fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP.  The module thus
+has control at the beginning and end of the program and has a place to call
+the libcurl functions.  Note that if multiple modules in the program use
+libcurl, they all will separately call the libcurl functions, and that's OK
+because only the first \fIcurl_global_init(3)\fP and the last
+\fIcurl_global_cleanup(3)\fP in a program change anything.  (libcurl uses a
+reference count in static memory).
+
+In a C++ module, it is common to deal with the global constant situation by
+defining a special class that represents the global constant environment of
+the module.  A program always has exactly one object of the class, in static
+storage.  That way, the program automatically calls the constructor of the
+object as the program starts up and the destructor as it terminates.  As the
+author of this libcurl-using module, you can make the constructor call
+\fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP
+and satisfy libcurl's requirements without your user having to think about it.
+(Caveat: If you are initializing libcurl from a Windows DLL you should not
+initialize it from DllMain or a static initializer because Windows holds the
+loader lock during that time and it could cause a deadlock.)
+
+\fIcurl_global_init(3)\fP has an argument that tells what particular parts of
+the global constant environment to set up.  In order to successfully use any
+value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you
+must have specific knowledge of internal workings of libcurl and all other
+parts of the program of which it is part.
+
+A special part of the global constant environment is the identity of the
+memory allocator.  \fIcurl_global_init(3)\fP selects the system default memory
+allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your
+own.  However, there is no way to use \fIcurl_global_init_mem(3)\fP in a
+modular program -- all modules in the program that might use libcurl would
+have to agree on one allocator.
+
+There is a failsafe in libcurl that makes it usable in simple situations
+without you having to worry about the global constant environment at all:
+\fIcurl_easy_init(3)\fP sets up the environment itself if it hasn't been done
+yet.  The resources it acquires to do so get released by the operating system
+automatically when the program exits.
+
+This failsafe feature exists mainly for backward compatibility because
+there was a time when the global functions didn't exist.  Because it
+is sufficient only in the simplest of programs, it is not recommended
+for any program to rely on it.

curl/docs/libcurl/libcurl.m4

@@ -0,0 +1,272 @@
+#***************************************************************************
+#                                  _   _ ____  _
+#  Project                     ___| | | |  _ \| |
+#                             / __| | | | |_) | |
+#                            | (__| |_| |  _ <| |___
+#                             \___|\___/|_| \_\_____|
+#
+# Copyright (C) 2006 - 2020, David Shaw <[email protected]>
+#
+# 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 https://curl.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.
+#
+###########################################################################
+# LIBCURL_CHECK_CONFIG ([DEFAULT-ACTION], [MINIMUM-VERSION],
+#                       [ACTION-IF-YES], [ACTION-IF-NO])
+# ----------------------------------------------------------
+#      David Shaw <[email protected]>   May-09-2006
+#
+# Checks for libcurl.  DEFAULT-ACTION is the string yes or no to
+# specify whether to default to --with-libcurl or --without-libcurl.
+# If not supplied, DEFAULT-ACTION is yes.  MINIMUM-VERSION is the
+# minimum version of libcurl to accept.  Pass the version as a regular
+# version number like 7.10.1. If not supplied, any version is
+# accepted.  ACTION-IF-YES is a list of shell commands to run if
+# libcurl was successfully found and passed the various tests.
+# ACTION-IF-NO is a list of shell commands that are run otherwise.
+# Note that using --without-libcurl does run ACTION-IF-NO.
+#
+# This macro #defines HAVE_LIBCURL if a working libcurl setup is
+# found, and sets @LIBCURL@ and @LIBCURL_CPPFLAGS@ to the necessary
+# values.  Other useful defines are LIBCURL_FEATURE_xxx where xxx are
+# the various features supported by libcurl, and LIBCURL_PROTOCOL_yyy
+# where yyy are the various protocols supported by libcurl.  Both xxx
+# and yyy are capitalized.  See the list of AH_TEMPLATEs at the top of
+# the macro for the complete list of possible defines.  Shell
+# variables $libcurl_feature_xxx and $libcurl_protocol_yyy are also
+# defined to 'yes' for those features and protocols that were found.
+# Note that xxx and yyy keep the same capitalization as in the
+# curl-config list (e.g. it's "HTTP" and not "http").
+#
+# Users may override the detected values by doing something like:
+# LIBCURL="-lcurl" LIBCURL_CPPFLAGS="-I/usr/myinclude" ./configure
+#
+# For the sake of sanity, this macro assumes that any libcurl that is
+# found is after version 7.7.2, the first version that included the
+# curl-config script.  Note that it is very important for people
+# packaging binary versions of libcurl to include this script!
+# Without curl-config, we can only guess what protocols are available,
+# or use curl_version_info to figure it out at runtime.
+
+AC_DEFUN([LIBCURL_CHECK_CONFIG],
+[
+  AH_TEMPLATE([LIBCURL_FEATURE_SSL],[Defined if libcurl supports SSL])
+  AH_TEMPLATE([LIBCURL_FEATURE_KRB4],[Defined if libcurl supports KRB4])
+  AH_TEMPLATE([LIBCURL_FEATURE_IPV6],[Defined if libcurl supports IPv6])
+  AH_TEMPLATE([LIBCURL_FEATURE_LIBZ],[Defined if libcurl supports libz])
+  AH_TEMPLATE([LIBCURL_FEATURE_ASYNCHDNS],[Defined if libcurl supports AsynchDNS])
+  AH_TEMPLATE([LIBCURL_FEATURE_IDN],[Defined if libcurl supports IDN])
+  AH_TEMPLATE([LIBCURL_FEATURE_SSPI],[Defined if libcurl supports SSPI])
+  AH_TEMPLATE([LIBCURL_FEATURE_NTLM],[Defined if libcurl supports NTLM])
+
+  AH_TEMPLATE([LIBCURL_PROTOCOL_HTTP],[Defined if libcurl supports HTTP])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_HTTPS],[Defined if libcurl supports HTTPS])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_FTP],[Defined if libcurl supports FTP])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_FTPS],[Defined if libcurl supports FTPS])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_FILE],[Defined if libcurl supports FILE])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_TELNET],[Defined if libcurl supports TELNET])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_LDAP],[Defined if libcurl supports LDAP])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_DICT],[Defined if libcurl supports DICT])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_TFTP],[Defined if libcurl supports TFTP])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_RTSP],[Defined if libcurl supports RTSP])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_POP3],[Defined if libcurl supports POP3])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_IMAP],[Defined if libcurl supports IMAP])
+  AH_TEMPLATE([LIBCURL_PROTOCOL_SMTP],[Defined if libcurl supports SMTP])
+
+  AC_ARG_WITH(libcurl,
+     AS_HELP_STRING([--with-libcurl=PREFIX],[look for the curl library in PREFIX/lib and headers in PREFIX/include]),
+     [_libcurl_with=$withval],[_libcurl_with=ifelse([$1],,[yes],[$1])])
+
+  if test "$_libcurl_with" != "no" ; then
+
+     AC_PROG_AWK
+
+     _libcurl_version_parse="eval $AWK '{split(\$NF,A,\".\"); X=256*256*A[[1]]+256*A[[2]]+A[[3]]; print X;}'"
+
+     _libcurl_try_link=yes
+
+     if test -d "$_libcurl_with" ; then
+        LIBCURL_CPPFLAGS="-I$withval/include"
+        _libcurl_ldflags="-L$withval/lib"
+        AC_PATH_PROG([_libcurl_config],[curl-config],[],
+                     ["$withval/bin"])
+     else
+        AC_PATH_PROG([_libcurl_config],[curl-config],[],[$PATH])
+     fi
+
+     if test x$_libcurl_config != "x" ; then
+        AC_CACHE_CHECK([for the version of libcurl],
+           [libcurl_cv_lib_curl_version],
+           [libcurl_cv_lib_curl_version=`$_libcurl_config --version | $AWK '{print $[]2}'`])
+
+        _libcurl_version=`echo $libcurl_cv_lib_curl_version | $_libcurl_version_parse`
+        _libcurl_wanted=`echo ifelse([$2],,[0],[$2]) | $_libcurl_version_parse`
+
+        if test $_libcurl_wanted -gt 0 ; then
+           AC_CACHE_CHECK([for libcurl >= version $2],
+              [libcurl_cv_lib_version_ok],
+              [
+              if test $_libcurl_version -ge $_libcurl_wanted ; then
+                 libcurl_cv_lib_version_ok=yes
+              else
+                 libcurl_cv_lib_version_ok=no
+              fi
+              ])
+        fi
+
+        if test $_libcurl_wanted -eq 0 || test x$libcurl_cv_lib_version_ok = xyes ; then
+           if test x"$LIBCURL_CPPFLAGS" = "x" ; then
+              LIBCURL_CPPFLAGS=`$_libcurl_config --cflags`
+           fi
+           if test x"$LIBCURL" = "x" ; then
+              LIBCURL=`$_libcurl_config --libs`
+
+              # This is so silly, but Apple actually has a bug in their
+              # curl-config script.  Fixed in Tiger, but there are still
+              # lots of Panther installs around.
+              case "${host}" in
+                 powerpc-apple-darwin7*)
+                    LIBCURL=`echo $LIBCURL | sed -e 's|-arch i386||g'`
+                 ;;
+              esac
+           fi
+
+           # All curl-config scripts support --feature
+           _libcurl_features=`$_libcurl_config --feature`
+
+           # Is it modern enough to have --protocols? (7.12.4)
+           if test $_libcurl_version -ge 461828 ; then
+              _libcurl_protocols=`$_libcurl_config --protocols`
+           fi
+        else
+           _libcurl_try_link=no
+        fi
+
+        unset _libcurl_wanted
+     fi
+
+     if test $_libcurl_try_link = yes ; then
+
+        # we didn't find curl-config, so let's see if the user-supplied
+        # link line (or failing that, "-lcurl") is enough.
+        LIBCURL=${LIBCURL-"$_libcurl_ldflags -lcurl"}
+
+        AC_CACHE_CHECK([whether libcurl is usable],
+           [libcurl_cv_lib_curl_usable],
+           [
+           _libcurl_save_cppflags=$CPPFLAGS
+           CPPFLAGS="$LIBCURL_CPPFLAGS $CPPFLAGS"
+           _libcurl_save_libs=$LIBS
+           LIBS="$LIBCURL $LIBS"
+
+           AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <curl/curl.h>]],[[
+/* Try and use a few common options to force a failure if we are
+   missing symbols or can't link. */
+int x;
+curl_easy_setopt(NULL,CURLOPT_URL,NULL);
+x=CURL_ERROR_SIZE;
+x=CURLOPT_WRITEFUNCTION;
+x=CURLOPT_WRITEDATA;
+x=CURLOPT_ERRORBUFFER;
+x=CURLOPT_STDERR;
+x=CURLOPT_VERBOSE;
+if (x) {;}
+]])],libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no)
+
+           CPPFLAGS=$_libcurl_save_cppflags
+           LIBS=$_libcurl_save_libs
+           unset _libcurl_save_cppflags
+           unset _libcurl_save_libs
+           ])
+
+        if test $libcurl_cv_lib_curl_usable = yes ; then
+
+           # Does curl_free() exist in this version of libcurl?
+           # If not, fake it with free()
+
+           _libcurl_save_cppflags=$CPPFLAGS
+           CPPFLAGS="$CPPFLAGS $LIBCURL_CPPFLAGS"
+           _libcurl_save_libs=$LIBS
+           LIBS="$LIBS $LIBCURL"
+
+           AC_CHECK_FUNC(curl_free,,
+              AC_DEFINE(curl_free,free,
+                [Define curl_free() as free() if our version of curl lacks curl_free.]))
+
+           CPPFLAGS=$_libcurl_save_cppflags
+           LIBS=$_libcurl_save_libs
+           unset _libcurl_save_cppflags
+           unset _libcurl_save_libs
+
+           AC_DEFINE(HAVE_LIBCURL,1,
+             [Define to 1 if you have a functional curl library.])
+           AC_SUBST(LIBCURL_CPPFLAGS)
+           AC_SUBST(LIBCURL)
+
+           for _libcurl_feature in $_libcurl_features ; do
+              AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_feature_$_libcurl_feature),[1])
+              eval AS_TR_SH(libcurl_feature_$_libcurl_feature)=yes
+           done
+
+           if test "x$_libcurl_protocols" = "x" ; then
+
+              # We don't have --protocols, so just assume that all
+              # protocols are available
+              _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP"
+
+              if test x$libcurl_feature_SSL = xyes ; then
+                 _libcurl_protocols="$_libcurl_protocols HTTPS"
+
+                 # FTPS wasn't standards-compliant until version
+                 # 7.11.0 (0x070b00 == 461568)
+                 if test $_libcurl_version -ge 461568; then
+                    _libcurl_protocols="$_libcurl_protocols FTPS"
+                 fi
+              fi
+
+              # RTSP, IMAP, POP3 and SMTP were added in
+              # 7.20.0 (0x071400 == 463872)
+              if test $_libcurl_version -ge 463872; then
+                 _libcurl_protocols="$_libcurl_protocols RTSP IMAP POP3 SMTP"
+              fi
+           fi
+
+           for _libcurl_protocol in $_libcurl_protocols ; do
+              AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_protocol_$_libcurl_protocol),[1])
+              eval AS_TR_SH(libcurl_protocol_$_libcurl_protocol)=yes
+           done
+        else
+           unset LIBCURL
+           unset LIBCURL_CPPFLAGS
+        fi
+     fi
+
+     unset _libcurl_try_link
+     unset _libcurl_version_parse
+     unset _libcurl_config
+     unset _libcurl_feature
+     unset _libcurl_features
+     unset _libcurl_protocol
+     unset _libcurl_protocols
+     unset _libcurl_version
+     unset _libcurl_ldflags
+  fi
+
+  if test x$_libcurl_with = xno || test x$libcurl_cv_lib_curl_usable != xyes ; then
+     # This is the IF-NO path
+     ifelse([$4],,:,[$4])
+  else
+     # This is the IF-YES path
+     ifelse([$3],,:,[$3])
+  fi
+
+  unset _libcurl_with
+])dnl

curl/docs/libcurl/mksymbolsmanpage.pl

@@ -0,0 +1,93 @@
+#!/usr/bin/env perl
+# ***************************************************************************
+# *                                  _   _ ____  _
+# *  Project                     ___| | | |  _ \| |
+# *                             / __| | | | |_) | |
+# *                            | (__| |_| |  _ <| |___
+# *                             \___|\___/|_| \_\_____|
+# *
+# * Copyright (C) 2015 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+# *
+# ***************************************************************************
+
+my $version="7.41.0";
+
+use POSIX qw(strftime);
+my $date = strftime "%b %e, %Y", localtime;
+my $year = strftime "%Y", localtime;
+
+print <<HEADER
+.\\" **************************************************************************
+.\\" *                                  _   _ ____  _
+.\\" *  Project                     ___| | | |  _ \\| |
+.\\" *                             / __| | | | |_) | |
+.\\" *                            | (__| |_| |  _ <| |___
+.\\" *                             \\___|\\___/|_| \\_\\_____|
+.\\" *
+.\\" * Copyright (C) 1998 - $year, 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 https://curl.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.
+.\\" *
+.\\" **************************************************************************
+.TH libcurl-symbols 3 "$date" "libcurl $version" "libcurl symbols"
+.SH NAME
+libcurl-symbols \\- libcurl symbol version information
+.SH "libcurl symbols"
+This man page details version information for public symbols provided in the
+libcurl header files. This lists the first version in which the symbol was
+introduced and for some symbols two additional information pieces:
+
+The first version in which the symbol is marked "deprecated" - meaning that
+since that version no new code should be written to use the symbol as it is
+marked for getting removed in a future.
+
+The last version that featured the specific symbol. Using the symbol in source
+code will make it no longer compile error-free after that specified version.
+
+This man page is automatically generated from the symbols-in-versions file.
+HEADER
+    ;
+
+while(<STDIN>) {
+    if($_ =~ /^(CURL[A-Z0-9_.]*) *(.*)/) {
+        my ($symbol, $rest)=($1,$2);
+        my ($intro, $dep, $rem);
+        if($rest =~ s/^([0-9.]*) *//) {
+           $intro = $1;
+        }
+        if($rest =~ s/^([0-9.]*) *//) {
+           $dep = $1;
+        }
+        if($rest =~ s/^([0-9.]*) *//) {
+           $rem = $1;
+        }
+        print ".IP $symbol\nIntroduced in $intro\n";
+        if($dep) {
+          print "Deprecated since $dep\n";
+        }
+        if($rem) {
+          print "Last used in $dep\n";
+        }
+    }
+
+}

curl/docs/libcurl/opts/CMakeLists.txt

@@ -0,0 +1,33 @@
+#***************************************************************************
+#                                  _   _ ____  _
+#  Project                     ___| | | |  _ \| |
+#                             / __| | | | |_) | |
+#                            | (__| |_| |  _ <| |___
+#                             \___|\___/|_| \_\_____|
+#
+# Copyright (C) 2009 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+#
+###########################################################################
+# Load man_MANS from shared file
+transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
+include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
+
+add_manual_pages(man_MANS)
+
+string(REPLACE ".3" ".html" HTMLPAGES "${man_MANS}")
+string(REPLACE ".3" ".pdf" PDFPAGES "${man_MANS}")
+add_custom_target(opts-html DEPENDS ${HTMLPAGES})
+add_custom_target(opts-pdf DEPENDS ${PDFPAGES})
+add_dependencies(html opts-html)
+add_dependencies(pdf opts-pdf)

curl/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3

@@ -0,0 +1,72 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLINFO_ACTIVESOCKET 3 "November 04, 2020" "libcurl 7.75.0" "curl_easy_getinfo options"
+
+.SH NAME
+CURLINFO_ACTIVESOCKET \- get the active socket
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_ACTIVESOCKET,
+                           curl_socket_t *socket);
+.SH DESCRIPTION
+Pass a pointer to a curl_socket_t to receive the most recently active socket
+used for the transfer connection by this curl session. If the socket is no
+longer valid, \fICURL_SOCKET_BAD\fP is returned. When you are finished working
+with the socket, you must call \fIcurl_easy_cleanup(3)\fP as usual on the easy
+handle and let libcurl close the socket and cleanup other resources associated
+with the handle. This option returns the active socket only after the transfer
+is complete, and is typically used in combination with
+\fICURLOPT_CONNECT_ONLY(3)\fP, which skips the transfer phase.
+
+\fICURLINFO_ACTIVESOCKET(3)\fP was added as a replacement for
+\fICURLINFO_LASTSOCKET(3)\fP since that one isn't working on all platforms.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_socket_t sockfd;
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+  /* Do not do the transfer - only connect to host */
+  curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
+  res = curl_easy_perform(curl);
+
+  /* Extract the socket from the curl handle */
+  res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
+
+  if(res != CURLE_OK) {
+    printf("Error: %s\\n", curl_easy_strerror(res));
+    return 1;
+  }
+}
+.fi
+.SH AVAILABILITY
+Added in 7.45.0
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
+.BR CURLINFO_LASTSOCKET "(3), "

curl/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3

@@ -0,0 +1,65 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLINFO_APPCONNECT_TIME 3 "November 04, 2020" "libcurl 7.75.0" "curl_easy_getinfo options"
+
+.SH NAME
+CURLINFO_APPCONNECT_TIME \- get the time until the SSL/SSH handshake is completed
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME, double *timep);
+.SH DESCRIPTION
+Pass a pointer to a double to receive the time, in seconds, it took from the
+start until the SSL/SSH connect/handshake to the remote host was completed.
+This time is most often very near to the \fICURLINFO_PRETRANSFER_TIME(3)\fP
+time, except for cases such as HTTP pipelining where the pretransfer time can
+be delayed due to waits in line for the pipeline and more.
+
+When a redirect is followed, the time from each request is added together.
+
+See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+curl = curl_easy_init();
+if(curl) {
+  double connect;
+  curl_easy_setopt(curl, CURLOPT_URL, url);
+  res = curl_easy_perform(curl);
+  if(CURLE_OK == res) {
+    res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME, &connect);
+    if(CURLE_OK == res) {
+      printf("Time: %.1f", connect);
+    }
+  }
+  /* always cleanup */
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.19.0
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_APPCONNECT_TIME_T "(3)"

curl/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3

@@ -0,0 +1,67 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 2018 - 2019, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLINFO_APPCONNECT_TIME_T 3 "November 04, 2020" "libcurl 7.75.0" "curl_easy_getinfo options"
+
+.SH NAME
+CURLINFO_APPCONNECT_TIME_T \- get the time until the SSL/SSH handshake is completed
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME_T, curl_off_t *timep);
+.SH DESCRIPTION
+Pass a pointer to a curl_off_t to receive the time, in microseconds,
+it took from the
+start until the SSL/SSH connect/handshake to the remote host was completed.
+This time is most often very near to the \fICURLINFO_PRETRANSFER_TIME_T(3)\fP
+time, except for cases such as HTTP pipelining where the pretransfer time can
+be delayed due to waits in line for the pipeline and more.
+
+When a redirect is followed, the time from each request is added together.
+
+See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+curl = curl_easy_init();
+if(curl) {
+  curl_off_t connect;
+  curl_easy_setopt(curl, CURLOPT_URL, url);
+  res = curl_easy_perform(curl);
+  if(CURLE_OK == res) {
+    res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME_T, &connect);
+    if(CURLE_OK == res) {
+      printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000,
+             (long)(connect % 1000000));
+    }
+  }
+  /* always cleanup */
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.61.0
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_APPCONNECT_TIME "(3)"

curl/docs/libcurl/opts/CURLINFO_CERTINFO.3

@@ -0,0 +1,82 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLINFO_CERTINFO 3 "November 04, 2020" "libcurl 7.75.0" "curl_easy_getinfo options"
+
+.SH NAME
+CURLINFO_CERTINFO \- get the TLS certificate chain
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO,
+                           struct curl_certinfo **chainp);
+.SH DESCRIPTION
+Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to
+a struct that holds a number of linked lists with info about the certificate
+chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the request was
+made. 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.
+.SH PROTOCOLS
+All TLS-based
+.SH EXAMPLE
+.nf
+curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
+
+  /* connect to any HTTPS site, trusted or not */
+  curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
+  curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
+
+  curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L);
+
+  res = curl_easy_perform(curl);
+
+  if (!res) {
+    struct curl_certinfo *ci;
+    res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci);
+
+    if (!res) {
+      printf("%d certs!\\n", ci->num_of_certs);
+
+      for(i = 0; i < ci->num_of_certs; i++) {
+        struct curl_slist *slist;
+
+        for(slist = ci->certinfo[i]; slist; slist = slist->next)
+          printf("%s\\n", slist->data);
+      }
+    }
+  }
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+This option is only working in libcurl built with OpenSSL, NSS, Schannel or
+GSKit support. Schannel support added in 7.50.0
+
+Added in 7.19.1
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "

curl/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3

@@ -0,0 +1,71 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLINFO_CONDITION_UNMET 3 "November 04, 2020" "libcurl 7.75.0" "curl_easy_getinfo options"
+
+.SH NAME
+CURLINFO_CONDITION_UNMET \- get info on unmet time conditional or 304 HTTP response.
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONDITION_UNMET, long *unmet);
+.SH DESCRIPTION
+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(3)\fP). Alas,
+if this returns a 1 you know that the reason you didn't get data in return is
+because it didn't fulfill the condition. The long this argument points to will
+get a zero stored if the condition instead was met. This can also return 1 if
+the server responded with a 304 HTTP status code, for example after sending a
+custom "If-Match-*" header.
+.SH PROTOCOLS
+HTTP and some
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+  /* January 1, 2020 is 1577833200 */
+  curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L);
+
+  /* If-Modified-Since the above time stamp */
+  curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE);
+
+  /* Perform the request */
+  res = curl_easy_perform(curl);
+
+  if(!res) {
+    /* check the time condition */
+    long unmet;
+    res = curl_easy_getinfo(curl, CURLINFO_CONDITION_UNMET, &unmet);
+    if(!res) {
+      printf("The time condition was %sfulfilled\\n", unmet?"NOT":"");
+    }
+  }
+}
+.fi
+.SH AVAILABILITY
+Added in 7.19.4
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "

curl/docs/libcurl/opts/CURLINFO_CONNECT_TIME.3

@@ -0,0 +1,62 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLINFO_CONNECT_TIME 3 "November 04, 2020" "libcurl 7.75.0" "curl_easy_getinfo options"
+
+.SH NAME
+CURLINFO_CONNECT_TIME \- get the time until connect
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME, double *timep);
+.SH DESCRIPTION
+Pass a pointer to a double to receive the total time in seconds from the start
+until the connection to the remote host (or proxy) was completed.
+
+When a redirect is followed, the time from each request is added together.
+
+See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+curl = curl_easy_init();
+if(curl) {
+  double connect;
+  curl_easy_setopt(curl, CURLOPT_URL, url);
+  res = curl_easy_perform(curl);
+  if(CURLE_OK == res) {
+    res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME, &connect);
+    if(CURLE_OK == res) {
+      printf("Time: %.1f", connect);
+    }
+  }
+  /* always cleanup */
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.4.1
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_CONNECT_TIME_T "(3)"

curl/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3

@@ -0,0 +1,63 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 2018 - 2019, Daniel Stenberg, <[email protected]>, 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 https://curl.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.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLINFO_CONNECT_TIME_T 3 "November 04, 2020" "libcurl 7.75.0" "curl_easy_getinfo options"
+
+.SH NAME
+CURLINFO_CONNECT_TIME_T \- get the time until connect
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME_T, curl_off_t *timep);
+.SH DESCRIPTION
+Pass a pointer to a curl_off_t to receive the total time in microseconds
+from the start until the connection to the remote host (or proxy) was completed.
+
+When a redirect is followed, the time from each request is added together.
+
+See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+curl = curl_easy_init();
+if(curl) {
+  curl_off_t connect;
+  curl_easy_setopt(curl, CURLOPT_URL, url);
+  res = curl_easy_perform(curl);
+  if(CURLE_OK == res) {
+    res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME_T, &connect);
+    if(CURLE_OK == res) {
+      printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000,
+             (long)(connect % 1000000));
+    }
+  }
+  /* always cleanup */
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.61.0
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_CONNECT_TIME "(3)"