docs: introduce "curldown" for libcurl man page format

curldown is this new file format for libcurl man pages. It is markdown
inspired with differences:

- Each file has a set of leading headers with meta-data
- Supports a small subset of markdown
- Uses .md file extensions for editors/IDE/GitHub to treat them nicely
- Generates man pages very similar to the previous ones
- Generates man pages that still convert nicely to HTML on the website
- Detects and highlights mentions of curl symbols automatically (when
  their man page section is specified)

tools:

- cd2nroff: converts from curldown to nroff man page
- nroff2cd: convert an (old) nroff man page to curldown
- cdall: convert many nroff pages to curldown versions
- cd2cd: verifies and updates a curldown to latest curldown

This setup generates .3 versions of all the curldown versions at build time.

CI:

Since the documentation is now technically markdown in the eyes of many
things, the CI runs many more tests and checks on this documentation,
including proselint, link checkers and tests that make sure we capitalize the
first letter after a period...

Closes #12730

.github/scripts/cleanspell.pl

@@ -71,6 +71,7 @@ while(<F>) {
         $_ =~ s/curl_url_(dup)//g;
         $_ =~ s/curl_pushheader_by(name|num)//g;
         $_ =~ s/libcurl-(env|ws)//g;
+        $_ =~ s/libcurl\\-(env|ws)//g;
         $_ =~ s/(^|\W)((tftp|https|http|ftp):\/\/[a-z0-9\-._~%:\/?\#\[\]\@!\$&'()*+,;=]+)//gi;
         print O $_;
     }

.github/scripts/spellcheck.words

@@ -83,6 +83,7 @@ CCC
 CDN
 CentOS
 CFLAGS
+cflags
 CGI's
 CHACHA
 chacha
@@ -138,10 +139,11 @@ cshrc
 CTRL
 cURL
 CURLcode
+curldown
 CURLE
 CURLH
-CURLINFO
 curlimages
+CURLINFO
 curlrc
 curltest
 customizable
@@ -161,8 +163,8 @@ deepcode
 DELE
 DER
 deselectable
-Deserialized
 deserialization
+Deserialized
 destructor
 detections
 dev
@@ -350,11 +352,10 @@ interoperable
 interoperates
 IoT
 ipadOS
+IPCXN
 IPFS
-IPNS
 ipld
-trustless
-IPCXN
+IPNS
 IPv
 IPv4
 IPv4/6
@@ -804,6 +805,7 @@ TPF
 TrackMemory
 transcode
 Tru
+trustless
 Tse
 Tsujikawa
 TTL
@@ -826,6 +828,7 @@ unencoded
 unencrypted
 unescape
 Unglobbed
+Unicode
 UNICOS
 unix
 UnixSockets

.github/scripts/verify-examples.pl

@@ -91,12 +91,20 @@ sub extract {
     return ($fail ? 0 : $l);
 }
 
+my $count;
 for my $m (@files) {
-    print "Verify $m\n";
+    #print "Verify $m\n";
     my $out = extract($m);
     if($out) {
       $error |= testcompile($m);
       $error |= checksrc($m);
     }
+    $count++;
+}
+if(!$error) {
+    print "Verified $count man pages ok\n";
+}
+else {
+    print "Detected problems\n";
 }
 exit $error;

.github/workflows/man-examples.yml

@@ -28,5 +28,8 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: render nroff versions
+        run: autoreconf -fi && ./configure --without-ssl --without-libpsl && make -C docs
+
       - name: verify examples
         run: ./.github/scripts/verify-examples.pl docs/libcurl/curl*.3 docs/libcurl/opts/*.3

.github/workflows/proselint.yml

@@ -42,7 +42,8 @@ jobs:
             "checks": {
               "typography.diacritical_marks": false,
               "typography.symbols": false,
-              "annotations.misc": false
+              "annotations.misc": false,
+              "security.password": false
             }
           }
           JSON

Makefile.am

@@ -153,12 +153,6 @@ dist-hook:
 	  cp -p $$file $(distdir)$$strip; \
 	done)
 
-html:
-	cd docs && $(MAKE) html
-
-pdf:
-	cd docs && $(MAKE) pdf
-
 check: test examples check-docs
 
 if CROSSCOMPILING

appveyor.yml

@@ -84,7 +84,7 @@ environment:
       ENABLE_UNICODE: 'OFF'
       HTTP_ONLY: 'OFF'
       TESTING: 'ON'
-      DISABLED_TESTS: '!1139 !1501'
+      DISABLED_TESTS: '!1139 !1501 !1140 !1173 !1177 !1477'
     - job_name: 'CMake, VS2022, Debug, x64, Schannel, Static, Unicode'
       APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022'
       BUILD_SYSTEM: CMake
@@ -95,7 +95,7 @@ environment:
       ENABLE_UNICODE: 'ON'
       HTTP_ONLY: 'OFF'
       TESTING: 'ON'
-      DISABLED_TESTS: '!1139 !1501'
+      DISABLED_TESTS: '!1139 !1501 !1140 !1173 !1177 !1477'
     - job_name: 'CMake, VS2022, Debug, x64, no SSL, Static'
       APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022'
       BUILD_SYSTEM: CMake
@@ -106,7 +106,7 @@ environment:
       ENABLE_UNICODE: 'OFF'
       HTTP_ONLY: 'OFF'
       TESTING: 'ON'
-      DISABLED_TESTS: '!1139 !1501'
+      DISABLED_TESTS: '!1139 !1501 !1140 !1173 !1177 !1477'
     - job_name: 'CMake, VS2022, Debug, x64, no SSL, Static, HTTP only'
       APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022'
       BUILD_SYSTEM: CMake
@@ -117,7 +117,7 @@ environment:
       ENABLE_UNICODE: 'OFF'
       HTTP_ONLY: 'ON'
       TESTING: 'ON'
-      DISABLED_TESTS: '!1139 !1501'
+      DISABLED_TESTS: '!1139 !1501 !1140 !1173 !1177 !1477'
     # generated CMake-based MSYS Makefiles builds (mingw cross-compiling)
     - job_name: 'CMake, mingw-w64, gcc 13, Debug, x64, Schannel, Static, Unicode, Unity'
       APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022'
@@ -128,7 +128,7 @@ environment:
       ENABLE_UNICODE: 'ON'
       HTTP_ONLY: 'OFF'
       TESTING: 'ON'
-      DISABLED_TESTS: '!1086 !1139 !1451 !1501'
+      DISABLED_TESTS: '!1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477'
       ADD_PATH: 'C:/msys64/mingw64/bin'
       MSYS2_ARG_CONV_EXCL: '/*'
       BUILD_OPT: -k
@@ -142,7 +142,7 @@ environment:
       ENABLE_UNICODE: 'ON'
       HTTP_ONLY: 'OFF'
       TESTING: 'ON'
-      DISABLED_TESTS: '!1086 !1139 !1451 !1501'
+      DISABLED_TESTS: '!1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477'
       ADD_PATH: 'C:/mingw-w64/x86_64-7.2.0-posix-seh-rt_v5-rev1/mingw64/bin'
       MSYS2_ARG_CONV_EXCL: '/*'
       BUILD_OPT: -k
@@ -156,7 +156,7 @@ environment:
       HTTP_ONLY: 'OFF'
       TESTING: 'ON'
       # test 286 disabled due to https://github.com/curl/curl/issues/12040
-      DISABLED_TESTS: '~286 !1086 !1139 !1451 !1501'
+      DISABLED_TESTS: '~286 !1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477'
       ADD_PATH: 'C:/msys64/mingw64/bin'
       MSYS2_ARG_CONV_EXCL: '/*'
       BUILD_OPT: -k
@@ -170,7 +170,7 @@ environment:
       ENABLE_UNICODE: 'OFF'
       HTTP_ONLY: 'OFF'
       TESTING: 'ON'
-      DISABLED_TESTS: '!1086 !1139 !1451 !1501'
+      DISABLED_TESTS: '!1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477'
       ADD_PATH: 'C:/mingw-w64/i686-6.3.0-posix-dwarf-rt_v5-rev1/mingw32/bin'
       MSYS2_ARG_CONV_EXCL: '/*'
       BUILD_OPT: -k

docs/.gitignore

@@ -2,7 +2,5 @@
 #
 # SPDX-License-Identifier: curl
 
-*.html
-*.pdf
-curl.1
-*.1.dist
+*.1
+*.3

docs/CONTRIBUTE.md

@@ -116,7 +116,7 @@ features are working as they are supposed to. To maintain this situation and
 improve it, all new features and functions that are added need to be tested
 in the test suite. Every feature that is added should get at least one valid
 test case that verifies that it works as documented. If every submitter also
-posts a few test cases, it will not end up as a heavy burden on a single person!
+posts a few test cases, it will not end up as a heavy burden on a single person.
 
 If you do not have test cases or perhaps you have done something that is hard
 to write tests for, do explain exactly how you have otherwise tested and

docs/CURLDOWN.md

@@ -0,0 +1,125 @@
+# curldown
+
+A markdown-like syntax for libcurl man pages.
+
+## Purpose
+
+A text format for writing libcurl documentation in the shape of man pages.
+
+Make it easier for users to contribute and write documentation. A format that
+is easier on the eye in its source format.
+
+Make it harder to do syntactical mistakes.
+
+Use a format that allows creating man pages that end up looking exactly like
+the man pages did when we wrote them in nroff format.
+
+Take advantage of the fact that people these days are accustomed to markdown
+by using a markdown-like syntax.
+
+This allows us to fix issues in the nroff format easier since now we generate
+them. For example: escaping minus to prevent them from being turned into
+Unicode by man.
+
+Generate nroff output that looks (next to) *identical* to the previous files,
+so that the look, existing test cases, HTML conversions, existing
+infrastructure etc remain mostly intact.
+
+Contains meta-data in a structured way to allow better output (for example the
+see also information) and general awareness of what the file is about.
+
+## File extension
+
+Since curldown looks similar to markdown, we use `.md` extensions on the
+files.
+
+## Conversion
+
+Convert **from curldown to nroff** with `cd2nroff`. Generates nroff man pages.
+
+Convert **from nroff to curldown** with `nroff2cd`. This is only meant to be
+used for the initial conversion to curldown and should ideally never be needed
+again.
+
+Convert, check or clean up an existing curldown to nicer, better, cleaner
+curldown with **cd2cd**.
+
+Mass-convert all curldown files to nroff in specified directories with
+`cdall`:
+
+    cdall [dir1] [dir2] [dir3] ..
+
+## Known issues
+
+The `cd2nroff` tool does not yet handle *italics* or **bold** where the start
+and the end markers are used on separate lines.
+
+The `nroff2cd` tool generates code style quotes for all `.fi` sections since
+the nroff format does not carry a distinction.
+
+# Format
+
+Each curldown starts with a header with meta-data:
+
+    ---
+    c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+    SPDX-License-Identifier: curl
+    Title: CURLOPT_AWS_SIGV4
+    Section: 3
+    Source: libcurl
+    See-also:
+      - CURLOPT_HEADEROPT (3)
+      - CURLOPT_HTTPAUTH (3)
+    ---
+
+All curldown files *must* have all the headers present and at least one
+`See-also:` entry specified.
+
+Following the header in the file, is the manual page using markdown-like
+syntax:
+
+~~~
+    # NAME
+    a page - this is a page descriving something
+
+    # SYNOPSIS
+    ~~~c
+    #include <curl/curl.h>
+
+    CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param);
+    ~~~
+~~~
+
+Quoted source code should start with `~~~c` and end with `~~~` while regular
+quotes can start with `~~~` or just be indented with 4 spaces.
+
+Headers at top-level `#` get converted to `.SH`.
+
+`nroff2cd` supports the `##` next level header which gets converted to `.IP`.
+
+Write bold words or phrases within `**` like:
+
+    This is a **bold** word.
+
+Write italics like:
+
+    This is *italics*.
+
+Due to how man pages don't support backticks especially formatted, such
+occurrences in the source will instead just use italics in the generated
+output:
+
+    This `word` appears in italics.
+
+When generating the nroff output, the tooling will remove superfluous newlines,
+meaning they can be used freely in the source file to make the text more
+readable.
+
+All mentioned curl symbols that have their own man pages, like
+`curl_easy_perform(3)` will automatically be rendered using italics in the
+output without having to enclose it with asterisks. This helps ensuring that
+they get converted to links properly later in the HTML version on the website,
+as converted with `roffit`. This makes the curldown text easier to read even
+when mentioning many curl symbols.
+
+This auto-linking works for patterns matching `(lib|)curl[^ ]*(3)`.

docs/GOVERNANCE.md

@@ -179,4 +179,4 @@ this.
 ### Stop being a maintainer
 
 If you (appear to) not be active in the project anymore, you may be removed as
-a maintainer. Thank you for your service!
+a maintainer. Thank you for your service.

docs/HISTORY.md

@@ -327,7 +327,7 @@ April: added the cyassl backend (later renamed to WolfSSL)
 
  January: the curl tool defaults to HTTP/2 for HTTPS URLs
 
- December: curl 7.52.0 introduced support for HTTPS-proxy!
+ December: curl 7.52.0 introduced support for HTTPS-proxy
 
  First TLS 1.3 support
 

docs/Makefile.am

@@ -26,24 +26,21 @@ AUTOMAKE_OPTIONS = foreign no-dependencies
 
 # EXTRA_DIST breaks with $(abs_builddir) so build it using this variable
 # but distribute it (using the relative file name) in the next variable
-man_MANS = $(abs_builddir)/curl.1
+man_MANS = $(abs_builddir)/curl.1 mk-ca-bundle.1
 noinst_man_MANS = curl.1 mk-ca-bundle.1
 dist_man_MANS = curl-config.1
-GENHTMLPAGES = curl.html curl-config.html mk-ca-bundle.html
-PDFPAGES = curl.pdf curl-config.pdf mk-ca-bundle.pdf
-MANDISTPAGES = curl.1.dist curl-config.1.dist
-
-HTMLPAGES = $(GENHTMLPAGES)
+CURLPAGES = curl-config.md mk-ca-bundle.md
 
 # Build targets in this file (.) before cmdline-opts to ensure that
 # the curl.1 rule below runs first
-SUBDIRS = . cmdline-opts
-DIST_SUBDIRS = $(SUBDIRS) examples libcurl
+SUBDIRS = . cmdline-opts libcurl
+DIST_SUBDIRS = $(SUBDIRS) examples
 
-CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES) $(MANDISTPAGES) curl.1
+CLEANFILES = $(man_MANS) curl.1 curl-config.1 mk-ca-bundle.1
+nodist_MANS = $(CLEANFILES)
 
 EXTRA_DIST =                                    \
- $(noinst_man_MANS)                             \
+ $(CURLPAGES)                                   \
  ALTSVC.md                                      \
  BINDINGS.md                                    \
  BUFREF.md                                      \
@@ -59,6 +56,7 @@ EXTRA_DIST =                                    \
  CONNECTION-FILTERS.md                          \
  CONTRIBUTE.md                                  \
  CURL-DISABLE.md                                \
+ CURLDOWN.md                                    \
  DEPRECATE.md                                   \
  DYNBUF.md                                      \
  EARLY-RELEASE.md                               \
@@ -98,9 +96,14 @@ EXTRA_DIST =                                    \
  VULN-DISCLOSURE-POLICY.md                      \
  WEBSOCKET.md
 
-MAN2HTML= roffit $< >$@
+CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@
+
+CD2 = $(CD2_$(V))
+CD2_0 = @echo "  RENDER " $@;
+CD2_1 =
+CD2_ = $(CD2_0)
 
-SUFFIXES = .1 .html .pdf
+SUFFIXES = .1 .md
 
 # $(abs_builddir) is to disable VPATH when searching for this file, which
 # would otherwise find the copy in $(srcdir) which breaks the $(HUGE)
@@ -116,21 +119,10 @@ $(abs_builddir)/curl.1:
 		&& touch -r "$(srcdir)/curl.1" $@; fi
 	cd cmdline-opts && $(MAKE)
 
-html: $(HTMLPAGES)
-	cd libcurl && $(MAKE) html
-
-pdf: $(PDFPAGES)
-	cd libcurl && $(MAKE) pdf
-
-.1.html:
-	$(MAN2HTML)
+.md.1:
+	$(CD2)$(CD2NROFF)
 
-.1.pdf:
-	@(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \
-	groff -Tps -man $< >$$foo.ps; \
-	ps2pdf $$foo.ps $@; \
-	rm $$foo.ps; \
-	echo "converted $< to $@")
+curl-config.1: curl-config.md
 
 distclean:
 	rm -f $(CLEANFILES)

docs/SSLCERTS.md

@@ -116,10 +116,10 @@ server, do one of the following:
       4. Windows Directory (e.g. C:\windows)
       5. all directories along %PATH%
 
- 5. Get a better/different/newer CA cert bundle! One option is to extract the
-    one a recent Firefox browser uses by running 'make ca-bundle' in the curl
-    build tree root, or possibly download a version that was generated this
-    way for you: [CA Extract](https://curl.se/docs/caextract.html)
+ 5. Get another CA cert bundle. One option is to extract the one a recent
+    Firefox browser uses by running 'make ca-bundle' in the curl build tree
+    root, or possibly download a version that was generated this way for you:
+    [CA Extract](https://curl.se/docs/caextract.html)
 
 Neglecting to use one of the above methods when dealing with a server using a
 certificate that is not signed by one of the certificates in the installed CA

docs/curl-config.1

@@ -1,105 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.\"
-.TH curl-config 1 "25 Oct 2007" curl-config curl-config
-.SH NAME
-curl-config \- Get information about a libcurl installation
-.SH SYNOPSIS
-.B curl-config [options]
-.SH DESCRIPTION
-.B curl-config
-displays information about the curl and libcurl installation.
-.SH OPTIONS
-.IP "--ca"
-Displays the built-in path to the CA cert bundle this libcurl uses.
-.IP "--cc"
-Displays the compiler used to build libcurl.
-.IP "--cflags"
-Set of compiler options (CFLAGS) to use when compiling files that use
-libcurl. Currently that is only the include path to the curl include files.
-.IP "--checkfor [version]"
-Specify the oldest possible libcurl version string you want, and this
-script will return 0 if the current installation is new enough or it
-returns 1 and outputs a text saying that the current version is not new
-enough. (Added in 7.15.4)
-.IP "--configure"
-Displays the arguments given to configure when building curl.
-.IP "--feature"
-Lists what particular main features the installed libcurl was built with. At
-the time of writing, this list may include SSL, KRB4 or IPv6. Do not assume
-any particular order. The keywords will be separated by newlines. There may be
-none, one, or several keywords in the list.
-.IP "--help"
-Displays the available options.
-.IP "--libs"
-Shows the complete set of libs and other linker options you will need in order
-to link your application with libcurl.
-.IP "--prefix"
-This is the prefix used when libcurl was installed. Libcurl is then installed
-in $prefix/lib and its header files are installed in $prefix/include and so
-on. The prefix is set with "configure --prefix".
-.IP "--protocols"
-Lists what particular protocols the installed libcurl was built to support. At
-the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, FILE,
-TELNET, LDAP, DICT and many more. Do not assume any particular order. The
-protocols will be listed using uppercase and are separated by newlines. There
-may be none, one, or several protocols in the list. (Added in 7.13.0)
-.IP "--ssl-backends"
-Lists the SSL backends that were enabled when libcurl was built. It might be
-no, one or several names. If more than one name, they will appear
-comma-separated. (Added in 7.58.0)
-.IP "--static-libs"
-Shows the complete set of libs and other linker options you will need in order
-to link your application with libcurl statically. (Added in 7.17.1)
-.IP "--version"
-Outputs version information about the installed libcurl.
-.IP "--vernum"
-Outputs version information about the installed libcurl, in numerical mode.
-This outputs the version number, in hexadecimal, with 8 bits for each part:
-major, minor, and patch. So that libcurl 7.7.4 would appear as 070704 and libcurl
-12.13.14 would appear as 0c0d0e... Note that the initial zero might be
-omitted. (This option was broken in the 7.15.0 release.)
-.SH "EXAMPLES"
-What linker options do I need when I link with libcurl?
-.nf
-  $ curl-config --libs
-.fi
-What compiler options do I need when I compile using libcurl functions?
-.nf
-  $ curl-config --cflags
-.fi
-How do I know if libcurl was built with SSL support?
-.nf
-  $ curl-config --feature | grep SSL
-.fi
-What's the installed libcurl version?
-.nf
-  $ curl-config --version
-.fi
-How do I build a single file with a one-line command?
-.nf
-  $ `curl-config --cc --cflags` -o example example.c `curl-config --libs`
-.fi
-.SH "SEE ALSO"
-.BR curl (1)

docs/curl-config.md

@@ -0,0 +1,124 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl-config
+Section: 1
+Source: curl-config
+See-also:
+  - curl (1)
+---
+
+# NAME
+
+curl-config - Get information about a libcurl installation
+
+# SYNOPSIS
+
+**curl-config [options]**
+
+# DESCRIPTION
+
+**curl-config**
+displays information about the curl and libcurl installation.
+
+# OPTIONS
+
+## --ca
+
+Displays the built-in path to the CA cert bundle this libcurl uses.
+
+## --cc
+
+Displays the compiler used to build libcurl.
+
+## --cflags
+
+Set of compiler options (CFLAGS) to use when compiling files that use
+libcurl. Currently that is only the include path to the curl include files.
+
+## --checkfor [version]
+
+Specify the oldest possible libcurl version string you want, and this
+script will return 0 if the current installation is new enough or it
+returns 1 and outputs a text saying that the current version is not new
+enough. (Added in 7.15.4)
+
+## --configure
+
+Displays the arguments given to configure when building curl.
+
+## --feature
+
+Lists what particular main features the installed libcurl was built with. At
+the time of writing, this list may include SSL, KRB4 or IPv6. Do not assume
+any particular order. The keywords will be separated by newlines. There may be
+none, one, or several keywords in the list.
+
+## --help
+
+Displays the available options.
+
+## --libs
+
+Shows the complete set of libs and other linker options you will need in order
+to link your application with libcurl.
+
+## --prefix
+
+This is the prefix used when libcurl was installed. Libcurl is then installed
+in $prefix/lib and its header files are installed in $prefix/include and so
+on. The prefix is set with "configure --prefix".
+
+## --protocols
+
+Lists what particular protocols the installed libcurl was built to support. At
+the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, FILE,
+TELNET, LDAP, DICT and many more. Do not assume any particular order. The
+protocols will be listed using uppercase and are separated by newlines. There
+may be none, one, or several protocols in the list. (Added in 7.13.0)
+
+## --ssl-backends
+
+Lists the SSL backends that were enabled when libcurl was built. It might be
+no, one or several names. If more than one name, they will appear
+comma-separated. (Added in 7.58.0)
+
+## --static-libs
+
+Shows the complete set of libs and other linker options you will need in order
+to link your application with libcurl statically. (Added in 7.17.1)
+
+## --version
+
+Outputs version information about the installed libcurl.
+
+## --vernum
+
+Outputs version information about the installed libcurl, in numerical mode.
+This outputs the version number, in hexadecimal, with 8 bits for each part:
+major, minor, and patch. So that libcurl 7.7.4 would appear as 070704 and libcurl
+12.13.14 would appear as 0c0d0e... Note that the initial zero might be
+omitted. (This option was broken in the 7.15.0 release.)
+
+# EXAMPLES
+
+What linker options do I need when I link with libcurl?
+~~~
+  $ curl-config --libs
+~~~
+What compiler options do I need when I compile using libcurl functions?
+~~~
+  $ curl-config --cflags
+~~~
+How do I know if libcurl was built with SSL support?
+~~~
+  $ curl-config --feature | grep SSL
+~~~
+What's the installed libcurl version?
+~~~
+  $ curl-config --version
+~~~
+How do I build a single file with a one-line command?
+~~~
+  $ `curl-config --cc --cflags` -o example source.c `curl-config --libs`
+~~~

docs/libcurl/.gitignore

@@ -1,8 +0,0 @@
-# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
-#
-# SPDX-License-Identifier: curl
-
-*.html
-*.pdf
-*.3.dist
-libcurl-symbols.3

docs/libcurl/Makefile.am

@@ -28,53 +28,27 @@ SUBDIRS = opts
 
 include Makefile.inc
 
-man_DISTMANS = $(man_MANS:.3=.3.dist)
-
-HTMLPAGES = $(man_MANS:.3=.html)
-
-PDFPAGES = $(man_MANS:.3=.pdf)
+CURLPAGES = $(man_MANS:.3=.md)
 
 m4macrodir = $(datadir)/aclocal
 dist_m4macro_DATA = libcurl.m4
 
-CLEANFILES = $(HTMLPAGES) $(PDFPAGES) $(TESTS) $(man_DISTMANS) \
-  libcurl-symbols.3
+CLEANFILES = $(man_MANS) libcurl-symbols.md
+nodist_MANS = $(man_MANS)
 
-EXTRA_DIST = $(man_MANS) ABI.md symbols-in-versions symbols.pl  \
+EXTRA_DIST = $(CURLPAGES) 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 $@")
+CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@
+CD2 = $(CD2_$(V))
+CD2_0 = @echo "  RENDER " $@;
+CD2_1 =
+CD2_ = $(CD2_0)
 
-# 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 ($$_);'
+SUFFIXES = .3 .md
 
-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 > $@
+libcurl-symbols.md: $(srcdir)/symbols-in-versions $(srcdir)/mksymbolsmanpage.pl
+	$(CD2)perl $(srcdir)/mksymbolsmanpage.pl < $(srcdir)/symbols-in-versions > $@
 
-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 > $@
+.md.3:
+	$(CD2)$(CD2NROFF)

docs/libcurl/curl_easy_cleanup.3

@@ -1,82 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.\"
-.TH curl_easy_cleanup 3 "22 Aug 2007" "libcurl" "libcurl"
-.SH NAME
-curl_easy_cleanup - End a libcurl easy handle
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-void curl_easy_cleanup(CURL *handle);
-.fi
-.SH DESCRIPTION
-This function is the opposite of \fIcurl_easy_init(3)\fP. It closes down and
-frees all resources previously associated with this easy handle.
-
-This call closes all connections this handle has used and possibly has kept
-open until now unless the easy handle was attached to a multi handle while
-doing the transfers. Do not call this function if you intend to transfer more
-files, reusing 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 easy \fBhandle\fP after this function has been called and have
-returned, is illegal.
-
-To close an easy handle that has been used with the multi interface, make sure
-to first call \fIcurl_multi_remove_handle(3)\fP to remove it from the multi
-handle before it is closed.
-
-Passing in a NULL pointer in \fIhandle\fP makes this function return
-immediately with no action.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    CURLcode res;
-    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
-    res = curl_easy_perform(curl);
-    if(res)
-      printf("error: %s\\n", curl_easy_strerror(res));
-    curl_easy_cleanup(curl);
-  }
-}
-.fi
-.SH AVAILABILITY
-Added in 7.1
-.SH RETURN VALUE
-None
-.SH "SEE ALSO"
-.BR curl_easy_duphandle (3),
-.BR curl_easy_init (3),
-.BR curl_easy_reset (3),
-.BR curl_multi_cleanup (3),
-.BR curl_multi_remove_handle (3)

docs/libcurl/curl_easy_cleanup.md

@@ -0,0 +1,76 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_cleanup
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_duphandle (3)
+  - curl_easy_init (3)
+  - curl_easy_reset (3)
+  - curl_multi_cleanup (3)
+  - curl_multi_remove_handle (3)
+---
+
+# NAME
+
+curl_easy_cleanup - End a libcurl easy handle
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+void curl_easy_cleanup(CURL *handle);
+~~~
+
+# DESCRIPTION
+
+This function is the opposite of curl_easy_init(3). It closes down and frees
+all resources previously associated with this easy handle.
+
+This call closes all connections this handle has used and possibly has kept
+open until now unless the easy handle was attached to a multi handle while
+doing the transfers. Do not call this function if you intend to transfer more
+files, reusing handles is a key to good performance with libcurl.
+
+Occasionally you may get your progress callback or header callback called from
+within curl_easy_cleanup(3) (if previously set for the handle using
+curl_easy_setopt(3)). 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 easy **handle** after this function has been called and have
+returned, is illegal.
+
+To close an easy handle that has been used with the multi interface, make sure
+to first call curl_multi_remove_handle(3) to remove it from the multi handle
+before it is closed.
+
+Passing in a NULL pointer in *handle* makes this function return immediately
+with no action.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    CURLcode res;
+    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+    res = curl_easy_perform(curl);
+    if(res)
+      printf("error: %s\n", curl_easy_strerror(res));
+    curl_easy_cleanup(curl);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.1
+
+# RETURN VALUE
+
+None

docs/libcurl/curl_easy_duphandle.3

@@ -1,78 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_duphandle 3 "19 Sep 2014" "libcurl" "libcurl"
-.SH NAME
-curl_easy_duphandle - Clone a libcurl session handle
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURL *curl_easy_duphandle(CURL *handle);
-.fi
-.SH DESCRIPTION
-This function returns 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.
-
-Any options that the input handle has been told to point to (as opposed to
-copy) with previous calls to \fIcurl_easy_setopt(3)\fP, are 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 does \fBnot\fP inherit any state information, no connections,
-no SSL sessions and no cookies. It also does not inherit any share object
-states or options (created as if \fICURLOPT_SHARE(3)\fP was set to NULL).
-
-If the source handle has HSTS or alt-svc enabled, the duplicate gets data read
-data from the main file name to populate the cache.
-
-In multi-threaded programs, this function must be called in a synchronous way,
-the input handle may not be in use when cloned.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    CURLcode res;
-    CURL *nother;
-    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
-    nother = curl_easy_duphandle(curl);
-    res = curl_easy_perform(nother);
-    curl_easy_cleanup(nother);
-    curl_easy_cleanup(curl);
-  }
-}
-.fi
-.SH AVAILABILITY
-Added in 7.9
-.SH RETURN VALUE
-If this function returns NULL, something went wrong and no valid handle was
-returned.
-.SH SEE ALSO
-.BR curl_easy_cleanup (3),
-.BR curl_easy_init (3),
-.BR curl_easy_reset (3),
-.BR curl_global_init (3)

docs/libcurl/curl_easy_duphandle.md

@@ -0,0 +1,72 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_duphandle
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_cleanup (3)
+  - curl_easy_init (3)
+  - curl_easy_reset (3)
+  - curl_global_init (3)
+---
+
+# NAME
+
+curl_easy_duphandle - Clone a libcurl session handle
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURL *curl_easy_duphandle(CURL *handle);
+~~~
+
+# DESCRIPTION
+
+This function returns a new curl handle, a duplicate, using all the options
+previously set in the input curl *handle*. Both handles can subsequently be
+used independently and they must both be freed with curl_easy_cleanup(3).
+
+Any options that the input handle has been told to point to (as opposed to
+copy) with previous calls to curl_easy_setopt(3), are 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 does **not** inherit any state information, no connections, no
+SSL sessions and no cookies. It also does not inherit any share object states
+or options (created as if CURLOPT_SHARE(3) was set to NULL).
+
+If the source handle has HSTS or alt-svc enabled, the duplicate gets data read
+data from the main file name to populate the cache.
+
+In multi-threaded programs, this function must be called in a synchronous way,
+the input handle may not be in use when cloned.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    CURLcode res;
+    CURL *nother;
+    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+    nother = curl_easy_duphandle(curl);
+    res = curl_easy_perform(nother);
+    curl_easy_cleanup(nother);
+    curl_easy_cleanup(curl);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.9
+
+# RETURN VALUE
+
+If this function returns NULL, something went wrong and no valid handle was
+returned.

docs/libcurl/curl_easy_escape.3

@@ -1,79 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.\"
-.TH curl_easy_escape 3 "7 April 2006" "libcurl" "libcurl"
-.SH NAME
-curl_easy_escape - URL encodes the given string
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-char *curl_easy_escape(CURL *curl, const char *string, int length);
-.fi
-.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 (\fB%NN\fP where \fBNN\fP 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).
-
-Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was
-per-handle character conversion support for some old operating systems such as
-TPF, but it was otherwise ignored.
-
-You must \fIcurl_free(3)\fP the returned string when you are 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 EXAMPLE
-.nf
-int main(void)
-{
-  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);
-    }
-    curl_easy_cleanup(curl);
-  }
-}
-.fi
-.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 "SEE ALSO"
-.BR curl_easy_unescape (3),
-.BR curl_free (3)

docs/libcurl/curl_easy_escape.md

@@ -0,0 +1,75 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_escape
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_unescape (3)
+  - curl_free (3)
+---
+
+# NAME
+
+curl_easy_escape - URL encodes the given string
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+char *curl_easy_escape(CURL *curl, const char *string, int length);
+~~~
+
+# DESCRIPTION
+
+This function converts the given input *string* 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 *length* is set to 0 (zero), curl_easy_escape(3) uses strlen() on
+the input *string* to find out the size. This function does not accept
+input strings longer than **CURL_MAX_INPUT_LENGTH** (8 MB).
+
+Since 7.82.0, the **curl** parameter is ignored. Prior to that there was
+per-handle character conversion support for some old operating systems such as
+TPF, but it was otherwise ignored.
+
+You must curl_free(3) the returned string when you are done with it.
+
+# ENCODING
+
+libcurl is typically not aware of, nor does it care about, character
+encodings. curl_easy_escape(3) 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 curl_easy_escape(3) must make sure that the data passed in
+to the function is encoded correctly.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  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);
+    }
+    curl_easy_cleanup(curl);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.15.4 and replaces the old curl_escape(3) function.
+
+# RETURN VALUE
+
+A pointer to a null-terminated string or NULL if it failed.

docs/libcurl/curl_easy_getinfo.3

@@ -1,336 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.\"
-.TH curl_easy_getinfo 3 "11 Feb 2009" "libcurl" "libcurl"
-.SH NAME
-curl_easy_getinfo - extract information from a curl handle
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );
-.fi
-.SH DESCRIPTION
-Get the \fIinfo\fP kept in the \fIcurl\fP handle. The third argument
-\fBMUST\fP be pointing to the specific type of the used option which is
-documented in each man page of the \fIinfo\fP option. The data is stored
-accordingly and can be relied upon only if this 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_REFERER
-Referrer header.
-See \fICURLINFO_REFERER(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_QUEUE_TIME_T
-Time during which this transfer was held in a waiting queue.
-See \fICURLINFO_QUEUE_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 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
-Destination IP address of the last connection.
-See \fICURLINFO_PRIMARY_IP(3)\fP
-.IP CURLINFO_PRIMARY_PORT
-Destination port of the last connection.
-See \fICURLINFO_PRIMARY_PORT(3)\fP
-.IP CURLINFO_LOCAL_IP
-Source IP address of the last connection.
-See \fICURLINFO_LOCAL_IP(3)\fP
-.IP CURLINFO_LOCAL_PORT
-Source port number of the last connection.
-See \fICURLINFO_LOCAL_PORT(3)\fP
-.IP CURLINFO_COOKIELIST
-List of all known cookies.
-See \fICURLINFO_COOKIELIST(3)\fP
-.IP CURLINFO_LASTSOCKET
-(Deprecated) 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_CAPATH
-Get the default value for \fICURLOPT_CAPATH(3)\fP.
-See \fICURLINFO_CAPATH(3)\fP
-.IP CURLINFO_CAINFO
-Get the default value for \fICURLOPT_CAINFO(3)\fP.
-See \fICURLINFO_CAINFO(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
-The RTSP client CSeq that is expected next.
-See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP
-.IP CURLINFO_RTSP_SERVER_CSEQ
-The RTSP server CSeq that is expected next.
-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
-(Deprecated) 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
-.IP CURLINFO_CONN_ID
-The ID of the last connection used by the transfer. (Added in 8.2.0)
-See \fICURLINFO_CONN_ID(3)\fP
-.IP CURLINFO_XFER_ID
-The ID of the transfer. (Added in 8.2.0)
-See \fICURLINFO_XFER_ID(3)\fP
-.SH TIMES
-An overview of the time values available from \fIcurl_easy_getinfo(3)\fP
-.nf
-
-curl_easy_perform()
-    |
-    |--QUEUE_TIME
-    |--|--NAMELOOKUP
-    |--|--|--CONNECT
-    |--|--|--|--APPCONNECT
-    |--|--|--|--|--PRETRANSFER
-    |--|--|--|--|--|--STARTTRANSFER
-    |--|--|--|--|--|--|--TOTAL
-    |--|--|--|--|--|--|--REDIRECT
-.fi
-.IP "QUEUE_TIME"
-\fICURLINFO_QUEUE_TIME_T(3\fP. The time during which the transfer was held in
-a waiting queue before it could start for real. (Added in 8.6.0)
-.IP NAMELOOKUP
-\fICURLINFO_NAMELOOKUP_TIME(3)\fP and \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP.
-The time it took from the start until the name resolving was completed.
-.IP CONNECT
-\fICURLINFO_CONNECT_TIME(3)\fP and \fICURLINFO_CONNECT_TIME_T(3)\fP.  The time
-it took from the start until the connect to the remote host (or proxy) was
-completed.
-.IP APPCONNECT
-\fICURLINFO_APPCONNECT_TIME(3)\fP and \fICURLINFO_APPCONNECT_TIME_T(3)\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(3)\fP and \fICURLINFO_PRETRANSFER_TIME_T(3)\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(3)\fP and
-\fICURLINFO_STARTTRANSFER_TIME_T(3)\fP. The time it took from the start until
-the first byte is received by libcurl.
-.IP TOTAL
-\fICURLINFO_TOTAL_TIME(3)\fP and \fICURLINFO_TOTAL_TIME_T(3)\fP. Total time
-of the previous request.
-.IP REDIRECT
-\fICURLINFO_REDIRECT_TIME(3)\fP and \fICURLINFO_REDIRECT_TIME_T(3)\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 EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    CURLcode res;
-    curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
-    res = curl_easy_perform(curl);
-
-    if(CURLE_OK == res) {
-      char *ct;
-      /* ask for the content-type */
-      res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct);
-
-      if((CURLE_OK == res) && ct)
-        printf("We received Content-Type: %s\\n", ct);
-    }
-
-    /* always cleanup */
-    curl_easy_cleanup(curl);
-  }
-}
-.fi
-.SH AVAILABILITY
-Added in 7.4.1
-.SH RETURN VALUE
-If the operation was successful, CURLE_OK is returned. Otherwise an
-appropriate error code is returned.
-.SH "SEE ALSO"
-.BR curl_easy_setopt (3)

docs/libcurl/curl_easy_getinfo.md

@@ -0,0 +1,483 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_getinfo
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_setopt (3)
+---
+
+# NAME
+
+curl_easy_getinfo - extract information from a curl handle
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );
+~~~
+
+# DESCRIPTION
+
+Get the *info* kept in the *curl* handle. The third argument **MUST** be
+pointing to the specific type of the used option which is documented in each
+man page of the *info* option. The data is stored accordingly and can be
+relied upon only if this 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.
+
+# AVAILABLE INFORMATION
+
+The following information can be extracted:
+
+## CURLINFO_EFFECTIVE_METHOD
+
+Last used HTTP method. See CURLINFO_EFFECTIVE_METHOD(3)
+
+## CURLINFO_EFFECTIVE_URL
+
+Last used URL. See CURLINFO_EFFECTIVE_URL(3)
+
+## CURLINFO_RESPONSE_CODE
+
+Last received response code. See CURLINFO_RESPONSE_CODE(3)
+
+## CURLINFO_REFERER
+
+Referrer header. See CURLINFO_REFERER(3)
+
+## CURLINFO_HTTP_CONNECTCODE
+
+Last proxy CONNECT response code. See CURLINFO_HTTP_CONNECTCODE(3)
+
+## CURLINFO_HTTP_VERSION
+
+The http version used in the connection. See CURLINFO_HTTP_VERSION(3)
+
+## CURLINFO_FILETIME
+
+Remote time of the retrieved document. See CURLINFO_FILETIME(3)
+
+## CURLINFO_FILETIME_T
+
+Remote time of the retrieved document. See CURLINFO_FILETIME_T(3)
+
+## CURLINFO_TOTAL_TIME
+
+Total time of previous transfer. See CURLINFO_TOTAL_TIME(3)
+
+## CURLINFO_TOTAL_TIME_T
+
+Total time of previous transfer. See CURLINFO_TOTAL_TIME_T(3)
+
+## CURLINFO_NAMELOOKUP_TIME
+
+Time from start until name resolving completed. See
+CURLINFO_NAMELOOKUP_TIME(3)
+
+## CURLINFO_NAMELOOKUP_TIME_T
+
+Time from start until name resolving completed. See
+CURLINFO_NAMELOOKUP_TIME_T(3)
+
+## CURLINFO_CONNECT_TIME
+
+Time from start until remote host or proxy completed.
+See CURLINFO_CONNECT_TIME(3)
+
+## CURLINFO_CONNECT_TIME_T
+
+Time from start until remote host or proxy completed.
+See CURLINFO_CONNECT_TIME_T(3)
+
+## CURLINFO_APPCONNECT_TIME
+
+Time from start until SSL/SSH handshake completed.
+See CURLINFO_APPCONNECT_TIME(3)
+
+## CURLINFO_APPCONNECT_TIME_T
+
+Time from start until SSL/SSH handshake completed.
+See CURLINFO_APPCONNECT_TIME_T(3)
+
+## CURLINFO_PRETRANSFER_TIME
+
+Time from start until just before the transfer begins.
+See CURLINFO_PRETRANSFER_TIME(3)
+
+## CURLINFO_PRETRANSFER_TIME_T
+
+Time from start until just before the transfer begins.
+See CURLINFO_PRETRANSFER_TIME_T(3)
+
+## CURLINFO_QUEUE_TIME_T
+
+Time during which this transfer was held in a waiting queue.
+See CURLINFO_QUEUE_TIME_T(3)
+
+## CURLINFO_STARTTRANSFER_TIME
+
+Time from start until just when the first byte is received.
+See CURLINFO_STARTTRANSFER_TIME(3)
+
+## CURLINFO_STARTTRANSFER_TIME_T
+
+Time from start until just when the first byte is received.
+See CURLINFO_STARTTRANSFER_TIME_T(3)
+
+## CURLINFO_REDIRECT_TIME
+
+Time taken for all redirect steps before the final transfer.
+See CURLINFO_REDIRECT_TIME(3)
+
+## CURLINFO_REDIRECT_TIME_T
+
+Time taken for all redirect steps before the final transfer.
+See CURLINFO_REDIRECT_TIME_T(3)
+
+## CURLINFO_REDIRECT_COUNT
+
+Total number of redirects that were followed.
+See CURLINFO_REDIRECT_COUNT(3)
+
+## CURLINFO_REDIRECT_URL
+
+URL a redirect would take you to, had you enabled redirects.
+See CURLINFO_REDIRECT_URL(3)
+
+## CURLINFO_SIZE_UPLOAD
+
+(Deprecated) Number of bytes uploaded.
+See CURLINFO_SIZE_UPLOAD(3)
+
+## CURLINFO_SIZE_UPLOAD_T
+
+Number of bytes uploaded.
+See CURLINFO_SIZE_UPLOAD_T(3)
+
+## CURLINFO_SIZE_DOWNLOAD
+
+(Deprecated) Number of bytes downloaded.
+See CURLINFO_SIZE_DOWNLOAD(3)
+
+## CURLINFO_SIZE_DOWNLOAD_T
+
+Number of bytes downloaded.
+See CURLINFO_SIZE_DOWNLOAD_T(3)
+
+## CURLINFO_SPEED_DOWNLOAD
+
+(Deprecated) Average download speed.
+See CURLINFO_SPEED_DOWNLOAD(3)
+
+## CURLINFO_SPEED_DOWNLOAD_T
+
+Average download speed.
+See CURLINFO_SPEED_DOWNLOAD_T(3)
+
+## CURLINFO_SPEED_UPLOAD
+
+(Deprecated) Average upload speed.
+See CURLINFO_SPEED_UPLOAD(3)
+
+## CURLINFO_SPEED_UPLOAD_T
+
+Average upload speed.
+See CURLINFO_SPEED_UPLOAD_T(3)
+
+## CURLINFO_HEADER_SIZE
+
+Number of bytes of all headers received.
+See CURLINFO_HEADER_SIZE(3)
+
+## CURLINFO_REQUEST_SIZE
+
+Number of bytes sent in the issued HTTP requests.
+See CURLINFO_REQUEST_SIZE(3)
+
+## CURLINFO_SSL_VERIFYRESULT
+
+Certificate verification result.
+See CURLINFO_SSL_VERIFYRESULT(3)
+
+## CURLINFO_PROXY_ERROR
+
+Detailed proxy error.
+See CURLINFO_PROXY_ERROR(3)
+
+## CURLINFO_PROXY_SSL_VERIFYRESULT
+
+Proxy certificate verification result.
+See CURLINFO_PROXY_SSL_VERIFYRESULT(3)
+
+## CURLINFO_SSL_ENGINES
+
+A list of OpenSSL crypto engines.
+See CURLINFO_SSL_ENGINES(3)
+
+## CURLINFO_CONTENT_LENGTH_DOWNLOAD
+
+(Deprecated) Content length from the Content-Length header.
+See CURLINFO_CONTENT_LENGTH_DOWNLOAD(3)
+
+## CURLINFO_CONTENT_LENGTH_DOWNLOAD_T
+
+Content length from the Content-Length header.
+See CURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)
+
+## CURLINFO_CONTENT_LENGTH_UPLOAD
+
+(Deprecated) Upload size. See CURLINFO_CONTENT_LENGTH_UPLOAD(3)
+
+## CURLINFO_CONTENT_LENGTH_UPLOAD_T
+
+Upload size. See CURLINFO_CONTENT_LENGTH_UPLOAD_T(3)
+
+## CURLINFO_CONTENT_TYPE
+
+Content type from the Content-Type header.
+See CURLINFO_CONTENT_TYPE(3)
+
+## CURLINFO_RETRY_AFTER
+
+The value from the Retry-After header.
+See CURLINFO_RETRY_AFTER(3)
+
+## CURLINFO_PRIVATE
+
+User's private data pointer.
+See CURLINFO_PRIVATE(3)
+
+## CURLINFO_HTTPAUTH_AVAIL
+
+Available HTTP authentication methods.
+See CURLINFO_HTTPAUTH_AVAIL(3)
+
+## CURLINFO_PROXYAUTH_AVAIL
+
+Available HTTP proxy authentication methods.
+See CURLINFO_PROXYAUTH_AVAIL(3)
+
+## CURLINFO_OS_ERRNO
+
+The errno from the last failure to connect.
+See CURLINFO_OS_ERRNO(3)
+
+## CURLINFO_NUM_CONNECTS
+
+Number of new successful connections used for previous transfer.
+See CURLINFO_NUM_CONNECTS(3)
+
+## CURLINFO_PRIMARY_IP
+
+Destination IP address of the last connection.
+See CURLINFO_PRIMARY_IP(3)
+
+## CURLINFO_PRIMARY_PORT
+
+Destination port of the last connection.
+See CURLINFO_PRIMARY_PORT(3)
+
+## CURLINFO_LOCAL_IP
+
+Source IP address of the last connection.
+See CURLINFO_LOCAL_IP(3)
+
+## CURLINFO_LOCAL_PORT
+
+Source port number of the last connection.
+See CURLINFO_LOCAL_PORT(3)
+
+## CURLINFO_COOKIELIST
+
+List of all known cookies.
+See CURLINFO_COOKIELIST(3)
+
+## CURLINFO_LASTSOCKET
+
+(Deprecated) Last socket used.
+See CURLINFO_LASTSOCKET(3)
+
+## CURLINFO_ACTIVESOCKET
+
+The session's active socket.
+See CURLINFO_ACTIVESOCKET(3)
+
+## CURLINFO_FTP_ENTRY_PATH
+
+The entry path after logging in to an FTP server.
+See CURLINFO_FTP_ENTRY_PATH(3)
+
+## CURLINFO_CAPATH
+
+Get the default value for CURLOPT_CAPATH(3).
+See CURLINFO_CAPATH(3)
+
+## CURLINFO_CAINFO
+
+Get the default value for CURLOPT_CAINFO(3).
+See CURLINFO_CAINFO(3)
+
+## CURLINFO_CERTINFO
+
+Certificate chain.
+See CURLINFO_CERTINFO(3)
+
+## CURLINFO_TLS_SSL_PTR
+
+TLS session info that can be used for further processing.
+See CURLINFO_TLS_SSL_PTR(3)
+
+## CURLINFO_TLS_SESSION
+
+TLS session info that can be used for further processing. See
+CURLINFO_TLS_SESSION(3). Deprecated option, use
+CURLINFO_TLS_SSL_PTR(3) instead!
+
+## CURLINFO_CONDITION_UNMET
+
+Whether or not a time conditional was met or 304 HTTP response.
+See CURLINFO_CONDITION_UNMET(3)
+
+## CURLINFO_RTSP_SESSION_ID
+
+RTSP session ID.
+See CURLINFO_RTSP_SESSION_ID(3)
+
+## CURLINFO_RTSP_CLIENT_CSEQ
+
+The RTSP client CSeq that is expected next.
+See CURLINFO_RTSP_CLIENT_CSEQ(3)
+
+## CURLINFO_RTSP_SERVER_CSEQ
+
+The RTSP server CSeq that is expected next.
+See CURLINFO_RTSP_SERVER_CSEQ(3)
+
+## CURLINFO_RTSP_CSEQ_RECV
+
+RTSP CSeq last received.
+See CURLINFO_RTSP_CSEQ_RECV(3)
+
+## CURLINFO_PROTOCOL
+
+(Deprecated) The protocol used for the connection. (Added in 7.52.0)
+See CURLINFO_PROTOCOL(3)
+
+## CURLINFO_SCHEME
+
+The scheme used for the connection. (Added in 7.52.0)
+See CURLINFO_SCHEME(3)
+
+## CURLINFO_CONN_ID
+
+The ID of the last connection used by the transfer. (Added in 8.2.0)
+See CURLINFO_CONN_ID(3)
+
+## CURLINFO_XFER_ID
+
+The ID of the transfer. (Added in 8.2.0)
+See CURLINFO_XFER_ID(3)
+
+# TIMES
+
+An overview of the time values available from curl_easy_getinfo(3)
+
+~~~
+curl_easy_perform()
+    |
+    |--QUEUE_TIME
+    |--|--NAMELOOKUP
+    |--|--|--CONNECT
+    |--|--|--|--APPCONNECT
+    |--|--|--|--|--PRETRANSFER
+    |--|--|--|--|--|--STARTTRANSFER
+    |--|--|--|--|--|--|--TOTAL
+    |--|--|--|--|--|--|--REDIRECT
+~~~
+
+## QUEUE_TIME
+
+CURLINFO_QUEUE_TIME_T(3). The time during which the transfer was held in a
+waiting queue before it could start for real. (Added in 8.6.0)
+
+## NAMELOOKUP
+
+CURLINFO_NAMELOOKUP_TIME(3) and CURLINFO_NAMELOOKUP_TIME_T(3). The time it
+took from the start until the name resolving was completed.
+
+## CONNECT
+
+CURLINFO_CONNECT_TIME(3) and CURLINFO_CONNECT_TIME_T(3). The time it took from
+the start until the connect to the remote host (or proxy) was completed.
+
+## APPCONNECT
+
+CURLINFO_APPCONNECT_TIME(3) and CURLINFO_APPCONNECT_TIME_T(3). 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)
+
+## PRETRANSFER
+
+CURLINFO_PRETRANSFER_TIME(3) and CURLINFO_PRETRANSFER_TIME_T(3). 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.
+
+## STARTTRANSFER
+
+CURLINFO_STARTTRANSFER_TIME(3) and CURLINFO_STARTTRANSFER_TIME_T(3). The time
+it took from the start until the first byte is received by libcurl.
+
+## TOTAL
+
+CURLINFO_TOTAL_TIME(3) and CURLINFO_TOTAL_TIME_T(3). Total time
+of the previous request.
+
+## REDIRECT
+
+CURLINFO_REDIRECT_TIME(3) and CURLINFO_REDIRECT_TIME_T(3). 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.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    CURLcode res;
+    curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
+    res = curl_easy_perform(curl);
+
+    if(CURLE_OK == res) {
+      char *ct;
+      /* ask for the content-type */
+      res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct);
+
+      if((CURLE_OK == res) && ct)
+        printf("We received Content-Type: %s\n", ct);
+    }
+
+    /* always cleanup */
+    curl_easy_cleanup(curl);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.4.1
+
+# RETURN VALUE
+
+If the operation was successful, CURLE_OK is returned. Otherwise an
+appropriate error code is returned.

docs/libcurl/curl_easy_header.3

@@ -1,152 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_header 3 "13 March 2022" "libcurl" "libcurl"
-.SH NAME
-curl_easy_header - get an HTTP header
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLHcode curl_easy_header(CURL *easy,
-                           const char *name,
-                           size_t index,
-                           unsigned int origin,
-                           int request,
-                           struct curl_header **hout);
-.fi
-.SH DESCRIPTION
-\fIcurl_easy_header(3)\fP returns a pointer to a "curl_header" struct in
-\fBhout\fP with data for the HTTP response header \fIname\fP. The case
-insensitive null-terminated header name should be specified without colon.
-
-\fIindex\fP 0 means asking for the first instance of the header. If the
-returned header struct has \fBamount\fP set larger than 1, it means there are
-more instances of the same header name available to get. Asking for a too big
-index makes \fBCURLHE_BADINDEX\fP get returned.
-
-The \fIorigin\fP argument is for specifying which headers to receive, as a
-single HTTP transfer might provide headers from several different places and
-they may then have different importance to the user and headers using the same
-name might be used. The \fIorigin\fP is a bitmask for what header sources you
-want. See the descriptions below.
-
-The \fIrequest\fP argument tells libcurl from which request you want headers
-from. A single transfer might consist of a series of HTTP requests and this
-argument lets you specify which particular individual request you want the
-headers from. 0 being the first request and then the number increases for
-further redirects or when multi-state authentication is used. Passing in -1 is
-a shortcut to "the last" request in the series, independently of the actual
-amount of requests used.
-
-libcurl stores and provides the actually used "correct" headers. If for
-example two headers with the same name arrive and the latter overrides the
-former, then only the latter is provided. If the first header survives the
-second, then only the first one is provided. An application using this API
-does not have to bother about multiple headers used wrongly.
-
-The memory for the returned struct is associated with the easy handle and
-subsequent calls to \fIcurl_easy_header(3)\fP clobber the struct used in the
-previous calls for the same easy handle. Applications need to copy the data if
-it wants to keep it around. The memory used for the struct gets freed with
-calling \fIcurl_easy_cleanup(3)\fP of the easy handle.
-
-The first line in an HTTP response is called the status line. It is not
-considered a header by this function. Headers are the "name: value" lines
-following the status.
-
-This function can be used before (all) headers have been received and is fine
-to call from within libcurl callbacks. It returns the state of the headers at
-the time it is called.
-.SH "The header struct"
-.nf
-struct curl_header {
-   char *name;
-   char *value;
-   size_t amount;
-   size_t index;
-   unsigned int origin;
-   void *anchor;
-};
-.fi
-
-The data \fBname\fP field points to, is the same as the requested name, but
-might have a different case.
-
-The data \fBvalue\fP field points to, comes exactly as delivered over the
-network but with leading and trailing whitespace and newlines stripped
-off. The `value` data is null-terminated. For legacy HTTP/1 "folded headers",
-this API provides the full single value in an unfolded manner with a single
-whitespace between the lines.
-
-\fBamount\fP is how many headers using this name that exist, within the origin
-and request scope asked for.
-
-\fBindex\fP is the zero based entry number of this particular header, which in
-case this header was used more than once in the requested scope can be larger
-than 0 but is always less than \fBamount\fP.
-
-The \fBorigin\fP field in the "curl_header" struct has one of the origin bits
-set, indicating where from the header originates. At the time of this writing,
-there are 5 bits with defined use. The undocumented 27 remaining bits are
-reserved for future use and must not be assumed to have any particular value.
-
-\fBanchor\fP is a private handle used by libcurl internals. Do not modify.
-.SH ORIGINS
-.IP CURLH_HEADER
-The header arrived as a header from the server.
-.IP CURLH_TRAILER
-The header arrived as a trailer. A header that arrives after the body.
-.IP CURLH_CONNECT
-The header arrived in a CONNECT response. A CONNECT request is being done to
-setup a transfer "through" an HTTP(S) proxy.
-.IP CURLH_1XX
-The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate"
-response that might happen before the "real" response.
-.IP CURLH_PSEUDO
-The header is an HTTP/2 or HTTP/3 pseudo header
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  struct curl_header *type;
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    CURLHcode h;
-    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
-    curl_easy_perform(curl);
-    h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type);
-    curl_easy_cleanup(curl);
-  }
-}
-.fi
-.SH AVAILABILITY
-Added in 7.83.0. Officially supported since 7.84.0.
-.SH RETURN VALUE
-This function returns a CURLHcode indicating success or error.
-.SH "SEE ALSO"
-.BR curl_easy_nextheader (3),
-.BR curl_easy_perform (3),
-.BR CURLINFO_CONTENT_TYPE (3),
-.BR CURLOPT_HEADERFUNCTION (3),
-.BR libcurl-errors (3)

docs/libcurl/curl_easy_header.md

@@ -0,0 +1,160 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_header
+Section: 3
+Source: libcurl
+See-also:
+  - CURLINFO_CONTENT_TYPE (3)
+  - CURLOPT_HEADERFUNCTION (3)
+  - curl_easy_nextheader (3)
+  - curl_easy_perform (3)
+  - libcurl-errors (3)
+---
+
+# NAME
+
+curl_easy_header - get an HTTP header
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLHcode curl_easy_header(CURL *easy,
+                           const char *name,
+                           size_t index,
+                           unsigned int origin,
+                           int request,
+                           struct curl_header **hout);
+~~~
+
+# DESCRIPTION
+
+curl_easy_header(3) returns a pointer to a "curl_header" struct in **hout**
+with data for the HTTP response header *name*. The case insensitive
+null-terminated header name should be specified without colon.
+
+*index* 0 means asking for the first instance of the header. If the returned
+header struct has **amount** set larger than 1, it means there are more
+instances of the same header name available to get. Asking for a too big index
+makes **CURLHE_BADINDEX** get returned.
+
+The *origin* argument is for specifying which headers to receive, as a single
+HTTP transfer might provide headers from several different places and they may
+then have different importance to the user and headers using the same name
+might be used. The *origin* is a bitmask for what header sources you want. See
+the descriptions below.
+
+The *request* argument tells libcurl from which request you want headers
+from. A single transfer might consist of a series of HTTP requests and this
+argument lets you specify which particular individual request you want the
+headers from. 0 being the first request and then the number increases for
+further redirects or when multi-state authentication is used. Passing in -1 is
+a shortcut to "the last" request in the series, independently of the actual
+amount of requests used.
+
+libcurl stores and provides the actually used "correct" headers. If for
+example two headers with the same name arrive and the latter overrides the
+former, then only the latter is provided. If the first header survives the
+second, then only the first one is provided. An application using this API
+does not have to bother about multiple headers used wrongly.
+
+The memory for the returned struct is associated with the easy handle and
+subsequent calls to curl_easy_header(3) clobber the struct used in the
+previous calls for the same easy handle. Applications need to copy the data if
+it wants to keep it around. The memory used for the struct gets freed with
+calling curl_easy_cleanup(3) of the easy handle.
+
+The first line in an HTTP response is called the status line. It is not
+considered a header by this function. Headers are the "name: value" lines
+following the status.
+
+This function can be used before (all) headers have been received and is fine
+to call from within libcurl callbacks. It returns the state of the headers at
+the time it is called.
+
+# The header struct
+
+~~~c
+struct curl_header {
+   char *name;
+   char *value;
+   size_t amount;
+   size_t index;
+   unsigned int origin;
+   void *anchor;
+};
+~~~
+
+The data **name** field points to, is the same as the requested name, but
+might have a different case.
+
+The data **value** field points to, comes exactly as delivered over the
+network but with leading and trailing whitespace and newlines stripped
+off. The `value` data is null-terminated. For legacy HTTP/1 "folded headers",
+this API provides the full single value in an unfolded manner with a single
+whitespace between the lines.
+
+**amount** is how many headers using this name that exist, within the origin
+and request scope asked for.
+
+**index** is the zero based entry number of this particular header, which in
+case this header was used more than once in the requested scope can be larger
+than 0 but is always less than **amount**.
+
+The **origin** field in the "curl_header" struct has one of the origin bits
+set, indicating where from the header originates. At the time of this writing,
+there are 5 bits with defined use. The undocumented 27 remaining bits are
+reserved for future use and must not be assumed to have any particular value.
+
+**anchor** is a private handle used by libcurl internals. Do not modify.
+
+# ORIGINS
+
+## CURLH_HEADER
+
+The header arrived as a header from the server.
+
+## CURLH_TRAILER
+
+The header arrived as a trailer. A header that arrives after the body.
+
+## CURLH_CONNECT
+
+The header arrived in a CONNECT response. A CONNECT request is being done to
+setup a transfer "through" an HTTP(S) proxy.
+
+## CURLH_1XX
+
+The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate"
+response that might happen before the "real" response.
+
+## CURLH_PSEUDO
+
+The header is an HTTP/2 or HTTP/3 pseudo header
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  struct curl_header *type;
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    CURLHcode h;
+    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+    curl_easy_perform(curl);
+    h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type);
+    curl_easy_cleanup(curl);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.83.0. Officially supported since 7.84.0.
+
+# RETURN VALUE
+
+This function returns a CURLHcode indicating success or error.

docs/libcurl/curl_easy_init.3

@@ -1,82 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_init 3 "4 March 2002" "libcurl" "libcurl"
-.SH NAME
-curl_easy_init - Start a libcurl easy session
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURL *curl_easy_init();
-.fi
-.SH DESCRIPTION
-This function allocates and returns a CURL easy handle. Such a handle is used
-as input to other functions in the easy interface. This call must have a
-corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is
-complete.
-
-The easy handle is used to hold and control a single network transfer. It is
-encouraged to reuse easy handles for repeated transfers.
-
-An alternative way to get a new easy handle is to duplicate an already
-existing one with \fIcurl_easy_duphandle(3)\fP, which has the upside that it
-gets all the options that were set in the source handle set in the new copy as
-well.
-
-If you did not already call \fIcurl_global_init(3)\fP before calling this
-function, \fIcurl_easy_init(3)\fP does it automatically. This may be lethal in
-multi-threaded cases, if \fIcurl_global_init(3)\fP is not thread-safe in your
-system, and it may then 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 EXAMPLE
-.nf
-int main(void)
-{
-  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 AVAILABILITY
-Always
-.SH RETURN VALUE
-If this function returns NULL, something went wrong and you cannot use the
-other curl functions.
-.SH "SEE ALSO"
-.BR curl_easy_cleanup (3),
-.BR curl_easy_duphandle (3),
-.BR curl_easy_perform (3),
-.BR curl_easy_reset (3),
-.BR curl_global_init (3),
-.BR curl_multi_init (3)

docs/libcurl/curl_easy_init.md

@@ -0,0 +1,73 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_init
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_cleanup (3)
+  - curl_easy_duphandle (3)
+  - curl_easy_perform (3)
+  - curl_easy_reset (3)
+  - curl_global_init (3)
+  - curl_multi_init (3)
+---
+
+# NAME
+
+curl_easy_init - Start a libcurl easy session
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURL *curl_easy_init();
+~~~
+
+# DESCRIPTION
+
+This function allocates and returns a CURL easy handle. Such a handle is used
+as input to other functions in the easy interface. This call must have a
+corresponding call to curl_easy_cleanup(3) when the operation is complete.
+
+The easy handle is used to hold and control a single network transfer. It is
+encouraged to reuse easy handles for repeated transfers.
+
+An alternative way to get a new easy handle is to duplicate an already
+existing one with curl_easy_duphandle(3), which has the upside that it gets
+all the options that were set in the source handle set in the new copy as
+well.
+
+If you did not already call curl_global_init(3) before calling this function,
+curl_easy_init(3) does it automatically. This may be lethal in multi-threaded
+cases, if curl_global_init(3) is not thread-safe in your system, and it may
+then result in resource problems because there is no corresponding cleanup.
+
+You are strongly advised to not allow this automatic behavior, by calling
+curl_global_init(3) yourself properly. See the description in libcurl(3) of
+global environment requirements for details of how to use this function.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  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);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Always
+
+# RETURN VALUE
+
+If this function returns NULL, something went wrong and you cannot use the
+other curl functions.

docs/libcurl/curl_easy_nextheader.3

@@ -1,106 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_nextheader 3 "13 March 2022" "libcurl" "libcurl"
-.SH NAME
-curl_easy_nextheader - get the next HTTP header
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-struct curl_header *curl_easy_nextheader(CURL *easy,
-                                         unsigned int origin,
-                                         int request,
-                                         struct curl_header *prev);
-.fi
-.SH DESCRIPTION
-This function lets an application iterate over all previously received HTTP
-headers.
-
-The \fIorigin\fP argument is for specifying which headers to receive, as a
-single HTTP transfer might provide headers from several different places and
-they may then have different importance to the user and headers using the same
-name might be used. The \fIorigin\fP is a bitmask for what header sources you
-want. See the \fIcurl_easy_header(3)\fP man page for the origin descriptions.
-
-The \fIrequest\fP argument tells libcurl from which request you want headers
-from. A single transfer might consist of a series of HTTP requests and this
-argument lets you specify which particular individual request you want the
-headers from. 0 being the first request and then the number increases for
-further redirects or when multi-state authentication is used. Passing in -1 is
-a shortcut to "the last" request in the series, independently of the actual
-amount of requests used.
-
-It is suggested that you pass in the same \fBorigin\fP and \fBrequest\fP when
-iterating over a range of headers as changing the value mid-loop might give
-you unexpected results.
-
-If \fIprev\fP is NULL, this function returns a pointer to the first header
-stored within the given scope (origin + request).
-
-If \fIprev\fP is a pointer to a previously returned header struct,
-\fIcurl_easy_nextheader(3)\fP returns a pointer the next header stored within
-the given scope. This way, an application can iterate over all available
-headers.
-
-The memory for the struct this points to, is owned and managed by libcurl and
-is associated with the easy handle. Applications must copy the data if they
-want it to survive subsequent API calls or the life-time of the easy handle.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  struct curl_header *prev = NULL;
-  struct curl_header *h;
-
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
-    curl_easy_perform(curl);
-
-    /* extract the normal headers from the first request */
-    while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) {
-      printf("%s: %s\\n", h->name, h->value);
-      prev = h;
-    }
-
-    /* extract the normal headers + 1xx + trailers from the last request */
-    unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER;
-    while((h = curl_easy_nextheader(curl, origin, -1, prev))) {
-      printf("%s: %s\\n", h->name, h->value);
-      prev = h;
-    }
-  }
-}
-.fi
-.SH AVAILABILITY
-Added in 7.83.0. Officially supported since 7.84.0.
-.SH RETURN VALUE
-This function returns the next header, or NULL when there are no more
-(matching) headers or an error occurred.
-
-If this function returns NULL when \fIprev\fP was set to NULL, then there are
-no headers available within the scope to return.
-.SH "SEE ALSO"
-.BR curl_easy_header (3),
-.BR curl_easy_perform (3)

docs/libcurl/curl_easy_nextheader.md

@@ -0,0 +1,100 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_nextheader
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_header (3)
+  - curl_easy_perform (3)
+---
+
+# NAME
+
+curl_easy_nextheader - get the next HTTP header
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+struct curl_header *curl_easy_nextheader(CURL *easy,
+                                         unsigned int origin,
+                                         int request,
+                                         struct curl_header *prev);
+~~~
+
+# DESCRIPTION
+
+This function lets an application iterate over all previously received HTTP
+headers.
+
+The *origin* argument is for specifying which headers to receive, as a single
+HTTP transfer might provide headers from several different places and they may
+then have different importance to the user and headers using the same name
+might be used. The *origin* is a bitmask for what header sources you want. See
+the curl_easy_header(3) man page for the origin descriptions.
+
+The *request* argument tells libcurl from which request you want headers
+from. A single transfer might consist of a series of HTTP requests and this
+argument lets you specify which particular individual request you want the
+headers from. 0 being the first request and then the number increases for
+further redirects or when multi-state authentication is used. Passing in -1 is
+a shortcut to "the last" request in the series, independently of the actual
+amount of requests used.
+
+It is suggested that you pass in the same **origin** and **request** when
+iterating over a range of headers as changing the value mid-loop might give
+you unexpected results.
+
+If *prev* is NULL, this function returns a pointer to the first header stored
+within the given scope (origin + request).
+
+If *prev* is a pointer to a previously returned header struct,
+curl_easy_nextheader(3) returns a pointer the next header stored within the
+given scope. This way, an application can iterate over all available headers.
+
+The memory for the struct this points to, is owned and managed by libcurl and
+is associated with the easy handle. Applications must copy the data if they
+want it to survive subsequent API calls or the life-time of the easy handle.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  struct curl_header *prev = NULL;
+  struct curl_header *h;
+
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+    curl_easy_perform(curl);
+
+    /* extract the normal headers from the first request */
+    while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) {
+      printf("%s: %s\n", h->name, h->value);
+      prev = h;
+    }
+
+    /* extract the normal headers + 1xx + trailers from the last request */
+    unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER;
+    while((h = curl_easy_nextheader(curl, origin, -1, prev))) {
+      printf("%s: %s\n", h->name, h->value);
+      prev = h;
+    }
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.83.0. Officially supported since 7.84.0.
+
+# RETURN VALUE
+
+This function returns the next header, or NULL when there are no more
+(matching) headers or an error occurred.
+
+If this function returns NULL when *prev* was set to NULL, then there are no
+headers available within the scope to return.

docs/libcurl/curl_easy_option_by_id.3

@@ -1,59 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_option_by_id 3 "27 Aug 2020" "libcurl" "libcurl"
-.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 \fICURLoption\fP \fBid\fP, this function returns a pointer to the
-\fIcurl_easyoption\fP 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
-returns the non-alias version of the cases where there is an alias function as
-well.
-
-If libcurl has no option with the given id, this function returns NULL.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  const struct curl_easyoption *opt = curl_easy_option_by_id(CURLOPT_URL);
-  if(opt) {
-    printf("This option wants type %x\\n", opt->type);
-  }
-}
-.fi
-.SH AVAILABILITY
-This function was added in libcurl 7.73.0
-.SH RETURN VALUE
-A pointer to the \fIcurl_easyoption\fP struct for the option or NULL.
-.SH "SEE ALSO"
-.BR curl_easy_option_by_name (3),
-.BR curl_easy_option_next (3),
-.BR curl_easy_setopt (3)

docs/libcurl/curl_easy_option_by_id.md

@@ -0,0 +1,54 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_option_by_id
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_option_by_name (3)
+  - curl_easy_option_next (3)
+  - curl_easy_setopt (3)
+---
+
+# NAME
+
+curl_easy_option_by_id - find an easy setopt option by id
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+const struct curl_easyoption *curl_easy_option_by_id(CURLoption id);
+~~~
+
+# DESCRIPTION
+
+Given a *CURLoption* **id**, this function returns a pointer to the
+*curl_easyoption* struct, holding information about the
+curl_easy_setopt(3) option using that id. The option id is the CURLOPT_
+prefix ones provided in the standard curl/curl.h header file. This function
+returns the non-alias version of the cases where there is an alias function as
+well.
+
+If libcurl has no option with the given id, this function returns NULL.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  const struct curl_easyoption *opt = curl_easy_option_by_id(CURLOPT_URL);
+  if(opt) {
+    printf("This option wants type %x\n", opt->type);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+This function was added in libcurl 7.73.0
+
+# RETURN VALUE
+
+A pointer to the *curl_easyoption* struct for the option or NULL.

docs/libcurl/curl_easy_option_by_name.3

@@ -1,58 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_option_by_name 3 "27 Aug 2020" "libcurl" "libcurl"
-.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
-\fIcurl_easyoption\fP 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 EXAMPLE
-.nf
-int main(void)
-{
-  const struct curl_easyoption *opt = curl_easy_option_by_name("URL");
-  if(opt) {
-    printf("This option wants CURLoption %x\\n", (int)opt->id);
-  }
-}
-.fi
-.SH AVAILABILITY
-This function was added in libcurl 7.73.0
-.SH RETURN VALUE
-A pointer to the \fIcurl_easyoption\fP struct for the option or NULL.
-.SH "SEE ALSO"
-.BR curl_easy_option_by_id (3),
-.BR curl_easy_option_next (3),
-.BR curl_easy_setopt (3)

docs/libcurl/curl_easy_option_by_name.md

@@ -0,0 +1,53 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_option_by_name
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_option_by_id (3)
+  - curl_easy_option_next (3)
+  - curl_easy_setopt (3)
+---
+
+# NAME
+
+curl_easy_option_by_name - find an easy setopt option by name
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+const struct curl_easyoption *curl_easy_option_by_name(const char *name);
+~~~
+
+# DESCRIPTION
+
+Given a **name**, this function returns a pointer to the
+*curl_easyoption* struct, holding information about the
+curl_easy_setopt(3) 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.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  const struct curl_easyoption *opt = curl_easy_option_by_name("URL");
+  if(opt) {
+    printf("This option wants CURLoption %x\n", (int)opt->id);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+This function was added in libcurl 7.73.0
+
+# RETURN VALUE
+
+A pointer to the *curl_easyoption* struct for the option or NULL.

docs/libcurl/curl_easy_option_next.3

@@ -1,92 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_option_next 3 "27 Aug 2020" "libcurl" "libcurl"
-.SH NAME
-curl_easy_option_next - iterate over easy setopt options
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-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 \fIcurl_easyoption\fP
-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 struct
-.nf
-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 null-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;
-};
-.fi
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  /* iterate over all available options */
-  const struct curl_easyoption *opt;
-  opt = curl_easy_option_next(NULL);
-  while(opt) {
-    printf("Name: %s\\n", opt->name);
-    opt = curl_easy_option_next(opt);
-  }
-}
-.fi
-.SH AVAILABILITY
-This function was added in libcurl 7.73.0
-.SH RETURN VALUE
-A pointer to the \fIcurl_easyoption\fP struct for the next option or NULL if
-no more options.
-.SH "SEE ALSO"
-.BR curl_easy_option_by_id (3),
-.BR curl_easy_option_by_name (3),
-.BR curl_easy_setopt (3)

docs/libcurl/curl_easy_option_next.md

@@ -0,0 +1,89 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_option_next
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_option_by_id (3)
+  - curl_easy_option_by_name (3)
+  - curl_easy_setopt (3)
+---
+
+# NAME
+
+curl_easy_option_next - iterate over easy setopt options
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+const struct curl_easyoption *
+curl_easy_option_next(const struct curl_easyoption *prev);
+~~~
+
+# 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
+curl_easy_setopt(3) in this instance of libcurl.
+
+Pass a **NULL** argument as **prev** 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, curl_easy_option_next(3) 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 **CURLOT_FLAG_ALIAS** bit is set in the flags field, it means the
+name is provided for backwards compatibility as an alias.
+
+# struct
+
+~~~c
+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 null-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;
+};
+~~~
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  /* iterate over all available options */
+  const struct curl_easyoption *opt;
+  opt = curl_easy_option_next(NULL);
+  while(opt) {
+    printf("Name: %s\n", opt->name);
+    opt = curl_easy_option_next(opt);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+This function was added in libcurl 7.73.0
+
+# RETURN VALUE
+
+A pointer to the *curl_easyoption* struct for the next option or NULL if
+no more options.

docs/libcurl/curl_easy_pause.3

@@ -1,131 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_pause 3 "17 Dec 2007" "libcurl" "libcurl"
-.SH NAME
-curl_easy_pause - pause and unpause a connection
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-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. Unlike
-most other libcurl functions, \fIcurl_easy_pause(3)\fP can be used from within
-callbacks.
-
-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 could not take care of any
-data at all, and that data is then 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).
-
-When this function is called to unpause receiving, the write callback might
-get called before this function returns to deliver cached content. When
-libcurl delivers such cached data to the write callback, it is delivered as
-fast as possible, which may overstep the boundary set in
-\fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP etc.
-
-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 resets 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 is no data received on this connection until this
-function is called again without this bit set. Thus, the write callback
-(\fICURLOPT_WRITEFUNCTION(3)\fP) is not called.
-.IP CURLPAUSE_SEND
-Pause sending data. There is no data sent on this connection until this
-function is called again without this bit set. Thus, the read callback
-(\fICURLOPT_READFUNCTION(3)\fP) is not called.
-.IP CURLPAUSE_ALL
-Convenience define that pauses both directions.
-.IP CURLPAUSE_CONT
-Convenience define that unpauses both directions.
-.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, might cause problems or error.
-.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 allows 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 is delivered
-first.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    /* pause a transfer in both directions */
-    curl_easy_pause(curl, CURL_READFUNC_PAUSE | CURL_WRITEFUNC_PAUSE);
-
-  }
-}
-.fi
-.SH "MEMORY USE"
-When pausing a download transfer by returning the magic return code from a
-write callback, the read data is already in libcurl's internal buffers so it
-has 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 continues to uncompress the entire
-downloaded chunk and it caches the data uncompressed. This has the side-
-effect that if you download something that is compressed a lot, it can result
-in a large data amount needing to be allocated to save the data during the
-pause. consider not using paused receiving if you allow libcurl to uncompress
-data automatically.
-
-If the download is done with HTTP/2 or HTTP/3, there is up to a stream window
-size worth of data that curl cannot stop but instead needs to cache while the
-transfer is paused. This means that if a window size of 64 MB is used, libcurl
-might end up having to cache 64 MB of data.
-.SH AVAILABILITY
-Added in 7.18.0.
-.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 "SEE ALSO"
-.BR curl_easy_cleanup (3),
-.BR curl_easy_reset (3)

docs/libcurl/curl_easy_pause.md

@@ -0,0 +1,140 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_pause
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_cleanup (3)
+  - curl_easy_reset (3)
+---
+
+# NAME
+
+curl_easy_pause - pause and unpause a connection
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_pause(CURL *handle, int bitmask );
+~~~
+
+# DESCRIPTION
+
+Using this function, you can explicitly mark a running connection to get
+paused, and you can unpause a connection that was previously paused. Unlike
+most other libcurl functions, curl_easy_pause(3) can be used from within
+callbacks.
+
+A connection can be paused by using this function or by letting the read or
+the write callbacks return the proper magic return code
+(*CURL_READFUNC_PAUSE* and *CURL_WRITEFUNC_PAUSE*). A write callback
+that returns pause signals to the library that it could not take care of any
+data at all, and that data is then 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 (CURLOPT_PROGRESSFUNCTION(3)).
+
+When this function is called to unpause receiving, the write callback might
+get called before this function returns to deliver cached content. When
+libcurl delivers such cached data to the write callback, it is delivered as
+fast as possible, which may overstep the boundary set in
+CURLOPT_MAX_RECV_SPEED_LARGE(3) etc.
+
+The **handle** argument identifies the transfer you want to pause or
+unpause.
+
+A paused transfer is excluded from low speed cancels via the
+CURLOPT_LOW_SPEED_LIMIT(3) option and unpausing a transfer resets the
+time period required for the low speed limit to be met.
+
+The **bitmask** argument is a set of bits that sets the new state of the
+connection. The following bits can be used:
+
+## CURLPAUSE_RECV
+
+Pause receiving data. There is no data received on this connection until this
+function is called again without this bit set. Thus, the write callback
+(CURLOPT_WRITEFUNCTION(3)) is not called.
+
+## CURLPAUSE_SEND
+
+Pause sending data. There is no data sent on this connection until this
+function is called again without this bit set. Thus, the read callback
+(CURLOPT_READFUNCTION(3)) is not called.
+
+## CURLPAUSE_ALL
+
+Convenience define that pauses both directions.
+
+## CURLPAUSE_CONT
+
+Convenience define that unpauses both directions.
+
+# 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, might cause problems or error.
+
+# 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 allows 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 is delivered
+first.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    /* pause a transfer in both directions */
+    curl_easy_pause(curl, CURL_READFUNC_PAUSE | CURL_WRITEFUNC_PAUSE);
+
+  }
+}
+~~~
+
+# MEMORY USE
+
+When pausing a download transfer by returning the magic return code from a
+write callback, the read data is already in libcurl's internal buffers so it
+has 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 continues to uncompress the entire
+downloaded chunk and it caches the data uncompressed. This has the side-
+effect that if you download something that is compressed a lot, it can result
+in a large data amount needing to be allocated to save the data during the
+pause. Consider not using paused receiving if you allow libcurl to uncompress
+data automatically.
+
+If the download is done with HTTP/2 or HTTP/3, there is up to a stream window
+size worth of data that curl cannot stop but instead needs to cache while the
+transfer is paused. This means that if a window size of 64 MB is used, libcurl
+might end up having to cache 64 MB of data.
+
+# AVAILABILITY
+
+Added in 7.18.0.
+
+# 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
+libcurl-errors(3) man page for the full list with descriptions.

docs/libcurl/curl_easy_perform.3

@@ -1,90 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_perform 3 "5 Mar 2001" "libcurl" "libcurl"
-.SH NAME
-curl_easy_perform - perform a blocking file transfer
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_easy_perform(CURL *easy_handle);
-.fi
-.SH DESCRIPTION
-\fIcurl_easy_perform(3)\fP performs a network transfer in a blocking manner
-and returns when done, or earlier if it fails. For non-blocking behavior, see
-\fIcurl_multi_perform(3)\fP.
-
-Invoke this function after \fIcurl_easy_init(3)\fP and all the
-\fIcurl_easy_setopt(3)\fP calls are made, and it performs 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.
-
-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 attempts to reuse existing connections for
-the following transfers, thus making the operations faster, less CPU intense
-and using less network resources. You probably want to use
-\fIcurl_easy_setopt(3)\fP between the invokes to set options for the following
-\fIcurl_easy_perform(3)\fP call.
-
-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.
-
-A network transfer moves data to a peer or from a peer. An application tells
-libcurl how to receive data by setting the \fICURLOPT_WRITEFUNCTION(3)\fP and
-\fICURLOPT_WRITEDATA(3)\fP options. To tell libcurl what data to send, there
-are a few more alternatives but two common ones are
-\fICURLOPT_READFUNCTION(3)\fP and \fICURLOPT_POSTFIELDS(3)\fP.
-
-While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by
-\fIcurl_easy_perform(3)\fP.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  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 AVAILABILITY
-Always
-.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 is a readable error message stored in
-the error buffer when non-zero is returned.
-.SH "SEE ALSO"
-.BR curl_easy_init (3),
-.BR curl_easy_setopt (3),
-.BR curl_multi_add_handle (3),
-.BR curl_multi_perform (3),
-.BR libcurl-errors (3)

docs/libcurl/curl_easy_perform.md

@@ -0,0 +1,83 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_perform
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_init (3)
+  - curl_easy_setopt (3)
+  - curl_multi_add_handle (3)
+  - curl_multi_perform (3)
+  - libcurl-errors (3)
+---
+
+# NAME
+
+curl_easy_perform - perform a blocking file transfer
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_perform(CURL *easy_handle);
+~~~
+
+# DESCRIPTION
+
+curl_easy_perform(3) performs a network transfer in a blocking manner and
+returns when done, or earlier if it fails. For non-blocking behavior, see
+curl_multi_perform(3).
+
+Invoke this function after curl_easy_init(3) and all the curl_easy_setopt(3)
+calls are made, and it performs the transfer as described in the options. It
+must be called with the same **easy_handle** as input as the curl_easy_init(3)
+call returned.
+
+You can do any amount of calls to curl_easy_perform(3) while using the same
+**easy_handle**. If you intend to transfer more than one file, you are even
+encouraged to do so. libcurl attempts to reuse existing connections for the
+following transfers, thus making the operations faster, less CPU intense and
+using less network resources. You probably want to use curl_easy_setopt(3)
+between the invokes to set options for the following curl_easy_perform(3)
+call.
+
+You must never call this function simultaneously from two places using the
+same **easy_handle**. Let the function return first before invoking it another
+time. If you want parallel transfers, you must use several curl easy_handles.
+
+A network transfer moves data to a peer or from a peer. An application tells
+libcurl how to receive data by setting the CURLOPT_WRITEFUNCTION(3) and
+CURLOPT_WRITEDATA(3) options. To tell libcurl what data to send, there are a
+few more alternatives but two common ones are CURLOPT_READFUNCTION(3) and
+CURLOPT_POSTFIELDS(3).
+
+While the **easy_handle** is added to a multi handle, it cannot be used by
+curl_easy_perform(3).
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  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);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Always
+
+# RETURN VALUE
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred as
+*<curl/curl.h>* defines - see libcurl-errors(3). If the CURLOPT_ERRORBUFFER(3)
+was set with curl_easy_setopt(3) there is a readable error message stored in
+the error buffer when non-zero is returned.

docs/libcurl/curl_easy_recv.3

@@ -1,109 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.\"
-.TH curl_easy_recv 3 "29 April 2008" "libcurl" "libcurl"
-.SH NAME
-curl_easy_recv - receives raw data on an "easy" connection
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n);
-.fi
-.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 takes care of proxy negotiation and connection
-setup.
-
-\fBbuffer\fP is a pointer to your buffer memory that gets populated by the
-received data. \fBbuflen\fP is the maximum amount of data you can get in that
-buffer. The variable \fBn\fP points to receives 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 returns \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 EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    CURLcode res;
-    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);
-
-    if(res == CURLE_OK) {
-      char buf[256];
-      size_t nread;
-      long sockfd;
-
-      /* Extract the socket from the curl handle - we need it for waiting. */
-      res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
-
-      /* read data */
-      res = curl_easy_recv(curl, buf, sizeof(buf), &nread);
-    }
-  }
-}
-.fi
-.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 is no socket available to use from the previous transfer, this function
-returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
-.SH "SEE ALSO"
-.BR curl_easy_getinfo (3),
-.BR curl_easy_perform (3),
-.BR curl_easy_send (3),
-.BR curl_easy_setopt (3)

docs/libcurl/curl_easy_recv.md

@@ -0,0 +1,103 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_recv
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_getinfo (3)
+  - curl_easy_perform (3)
+  - curl_easy_send (3)
+  - curl_easy_setopt (3)
+---
+
+# NAME
+
+curl_easy_recv - receives raw data on an "easy" connection
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n);
+~~~
+
+# DESCRIPTION
+
+This function receives raw data from the established connection. You may use
+it together with curl_easy_send(3) to implement custom protocols using
+libcurl. This functionality can be particularly useful if you use proxies
+and/or SSL encryption: libcurl takes care of proxy negotiation and connection
+setup.
+
+**buffer** is a pointer to your buffer memory that gets populated by the
+received data. **buflen** is the maximum amount of data you can get in that
+buffer. The variable **n** points to receives the number of received bytes.
+
+To establish the connection, set CURLOPT_CONNECT_ONLY(3) option before
+calling curl_easy_perform(3) or curl_multi_perform(3). Note that
+curl_easy_recv(3) does not work on connections that were created without
+this option.
+
+The call returns **CURLE_AGAIN** if there is no data to read - the socket is
+used in non-blocking mode internally. When **CURLE_AGAIN** is returned, use
+your operating system facilities like *select(2)* to wait for data. The
+socket may be obtained using curl_easy_getinfo(3) with
+CURLINFO_ACTIVESOCKET(3).
+
+Wait on the socket only if curl_easy_recv(3) returns **CURLE_AGAIN**.
+The reason for this is libcurl or the SSL library may internally cache some
+data, therefore you should call curl_easy_recv(3) 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,
+curl_easy_recv(3) may return **CURLE_AGAIN** if the only data that was
+read was for internal SSL processing, and no other data is available.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    CURLcode res;
+    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);
+
+    if(res == CURLE_OK) {
+      char buf[256];
+      size_t nread;
+      long sockfd;
+
+      /* Extract the socket from the curl handle - we need it for waiting. */
+      res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
+
+      /* read data */
+      res = curl_easy_recv(curl, buf, sizeof(buf), &nread);
+    }
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.18.2.
+
+# RETURN VALUE
+
+On success, returns **CURLE_OK**, stores the received data into
+**buffer**, and the number of bytes it actually read into ***n**.
+
+On failure, returns the appropriate error code.
+
+The function may return **CURLE_AGAIN**. 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 is no socket available to use from the previous transfer, this function
+returns **CURLE_UNSUPPORTED_PROTOCOL**.

docs/libcurl/curl_easy_reset.3

@@ -1,61 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_reset 3 "31 July 2004" "libcurl" "libcurl"
-.SH NAME
-curl_easy_reset - reset all options of a libcurl session handle
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-void curl_easy_reset(CURL *handle);
-.fi
-.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 EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-
-    /* ... the handle is used and options are set ... */
-    curl_easy_reset(curl);
-  }
-}
-.fi
-.SH AVAILABILITY
-This function was added in libcurl 7.12.1
-.SH RETURN VALUE
-Nothing
-.SH "SEE ALSO"
-.BR curl_easy_cleanup (3),
-.BR curl_easy_duphandle (3),
-.BR curl_easy_init (3),
-.BR curl_easy_setopt (3)

docs/libcurl/curl_easy_reset.md

@@ -0,0 +1,56 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_reset
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_cleanup (3)
+  - curl_easy_duphandle (3)
+  - curl_easy_init (3)
+  - curl_easy_setopt (3)
+---
+
+# NAME
+
+curl_easy_reset - reset all options of a libcurl session handle
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+void curl_easy_reset(CURL *handle);
+~~~
+
+# 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 curl_easy_init(3).
+
+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.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+
+    /* ... the handle is used and options are set ... */
+    curl_easy_reset(curl);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+This function was added in libcurl 7.12.1
+
+# RETURN VALUE
+
+Nothing

docs/libcurl/curl_easy_send.3

@@ -1,101 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.\"
-.TH curl_easy_send 3 "29 April 2008" "libcurl" "libcurl"
-.SH NAME
-curl_easy_send - sends raw data over an "easy" connection
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_easy_send(CURL *curl, const void *buffer,
-                        size_t buflen, size_t *n);
-.fi
-.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 takes care of proxy negotiation and
-connection setup.
-
-\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want
-sent. The variable \fBn\fP points to receives 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 does not work on connections that were created without
-this option.
-
-The call returns \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 EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    CURLcode res;
-    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);
-
-    if(res == CURLE_OK) {
-      long sockfd;
-      size_t sent;
-      /* Extract the socket from the curl handle - we need it for waiting. */
-      res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
-
-      /* send data */
-      res = curl_easy_send(curl, "hello", 5, &sent);
-    }
-  }
-}
-.fi
-.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 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 is no socket available to use from the previous transfer, this function
-returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
-.SH "SEE ALSO"
-.BR curl_easy_setopt (3),
-.BR curl_easy_perform (3),
-.BR curl_easy_getinfo (3),
-.BR curl_easy_recv (3)

docs/libcurl/curl_easy_send.md

@@ -0,0 +1,95 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_send
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_getinfo (3)
+  - curl_easy_perform (3)
+  - curl_easy_recv (3)
+  - curl_easy_setopt (3)
+---
+
+# NAME
+
+curl_easy_send - sends raw data over an "easy" connection
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_send(CURL *curl, const void *buffer,
+                        size_t buflen, size_t *n);
+~~~
+
+# DESCRIPTION
+
+This function sends arbitrary data over the established connection. You may
+use it together with curl_easy_recv(3) to implement custom protocols
+using libcurl. This functionality can be particularly useful if you use
+proxies and/or SSL encryption: libcurl takes care of proxy negotiation and
+connection setup.
+
+**buffer** is a pointer to the data of length **buflen** that you want
+sent. The variable **n** points to receives the number of sent bytes.
+
+To establish the connection, set CURLOPT_CONNECT_ONLY(3) option before
+calling curl_easy_perform(3) or curl_multi_perform(3). Note that
+curl_easy_send(3) does not work on connections that were created without
+this option.
+
+The call returns **CURLE_AGAIN** if it's not possible to send data right now
+- the socket is used in non-blocking mode internally. When **CURLE_AGAIN**
+is returned, use your operating system facilities like *select(2)* to wait
+until the socket is writable. The socket may be obtained using
+curl_easy_getinfo(3) with CURLINFO_ACTIVESOCKET(3).
+
+Furthermore if you wait on the socket and it tells you it's writable,
+curl_easy_send(3) may return **CURLE_AGAIN** if the only data that was
+sent was for internal SSL processing, and no other data could be sent.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    CURLcode res;
+    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);
+
+    if(res == CURLE_OK) {
+      long sockfd;
+      size_t sent;
+      /* Extract the socket from the curl handle - we need it for waiting. */
+      res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
+
+      /* send data */
+      res = curl_easy_send(curl, "hello", 5, &sent);
+    }
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.18.2.
+
+# RETURN VALUE
+
+On success, returns **CURLE_OK** and stores the number of bytes actually
+sent into ***n**. Note that this may be less than the amount you wanted to
+send.
+
+On failure, returns the appropriate error code.
+
+This function may return **CURLE_AGAIN**. In this case, use your operating
+system facilities to wait until the socket is writable, and retry.
+
+If there is no socket available to use from the previous transfer, this function
+returns **CURLE_UNSUPPORTED_PROTOCOL**.

docs/libcurl/curl_easy_setopt.3

@@ -1,751 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.\"
-.TH curl_easy_setopt 3 "25 Jun 2014" "libcurl" "libcurl"
-.SH NAME
-curl_easy_setopt \- set options for a curl easy handle
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
-.fi
-.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;
-the string storage associated to the pointer argument may be discarded or
-reused 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
-\fBDeprecated option\fP Callback for I/O operations.
-See \fICURLOPT_IOCTLFUNCTION(3)\fP
-.IP CURLOPT_IOCTLDATA
-\fBDeprecated option\fP 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
-\fBOBSOLETE\fP 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
-\fBOBSOLETE\fP Callback for code base conversion.
-See \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP
-.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
-\fBOBSOLETE\fP Callback for code base conversion.
-See \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP
-.IP CURLOPT_CONV_FROM_UTF8_FUNCTION
-\fBOBSOLETE\fP 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
-.IP CURLOPT_PREREQFUNCTION
-Callback to be called after a connection is established but before a request is made on that connection. See \fICURLOPT_PREREQFUNCTION(3)\fP
-.IP CURLOPT_PREREQDATA
-Data pointer to pass to the CURLOPT_PREREQFUNCTION callback. See \fICURLOPT_PREREQDATA(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
-\fBDeprecated option\fP Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP
-.IP CURLOPT_PROTOCOLS_STR
-Allowed protocols. See \fICURLOPT_PROTOCOLS_STR(3)\fP
-.IP CURLOPT_REDIR_PROTOCOLS
-\fBDeprecated option\fP Protocols to allow redirects to. See
-\fICURLOPT_REDIR_PROTOCOLS(3)\fP
-.IP CURLOPT_REDIR_PROTOCOLS_STR
-Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS_STR(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
-\fBDeprecated option\fP Socks5 GSSAPI service name.
-See \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_HAPROXY_CLIENT_IP
-Spoof the client IP in an HAProxy PROXY protocol v1 header. See \fICURLOPT_HAPROXY_CLIENT_IP(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
-\fBOBSOLETE\fP 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 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 authorization 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
-Do not 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
-\fBDeprecated option\fP 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
-\fBDeprecated option\fP 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_ALLOWFAILS
-Allow RCPT TO command to fail for some recipients. See
-\fICURLOPT_MAIL_RCPT_ALLOWFAILS(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 EPRT. 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_SERVER_RESPONSE_TIMEOUT
-Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP
-.IP CURLOPT_SERVER_RESPONSE_TIMEOUT_MS
-Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(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 a URL handle. 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_MIME_OPTIONS
-Set MIME option flags. See \fICURLOPT_MIME_OPTIONS(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 reusing this. See \fICURLOPT_FORBID_REUSE(3)\fP
-.IP CURLOPT_MAXAGE_CONN
-Limit the age (idle time) of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP
-.IP CURLOPT_MAXLIFETIME_CONN
-Limit the age (since creation) of connections for reuse. See \fICURLOPT_MAXLIFETIME_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 use. 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
-\fBOBSOLETE\fP 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_DOH_SSL_VERIFYHOST
-Verify the host name in the DoH (DNS-over-HTTPS) SSL certificate. See
-\fICURLOPT_DOH_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_DOH_SSL_VERIFYPEER
-Verify the DoH (DNS-over-HTTPS) SSL certificate. See
-\fICURLOPT_DOH_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_DOH_SSL_VERIFYSTATUS
-Verify the DoH (DNS-over-HTTPS) SSL certificate's status. See
-\fICURLOPT_DOH_SSL_VERIFYSTATUS(3)\fP
-.IP CURLOPT_CAINFO
-CA cert bundle. See \fICURLOPT_CAINFO(3)\fP
-.IP CURLOPT_CAINFO_BLOB
-CA cert bundle memory buffer. See \fICURLOPT_CAINFO_BLOB(3)\fP
-.IP CURLOPT_PROXY_CAINFO
-Proxy CA cert bundle. See \fICURLOPT_PROXY_CAINFO(3)\fP
-.IP CURLOPT_PROXY_CAINFO_BLOB
-Proxy CA cert bundle memory buffer. See \fICURLOPT_PROXY_CAINFO_BLOB(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_CA_CACHE_TIMEOUT
-Timeout for CA cache. See \fICURLOPT_CA_CACHE_TIMEOUT(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
-\fBOBSOLETE\fP Provide source for entropy random data.
-See \fICURLOPT_RANDOM_FILE(3)\fP
-.IP CURLOPT_EGDSOCKET
-\fBOBSOLETE\fP 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_HOST_PUBLIC_KEY_SHA256
-SHA256 of host's public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(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
-.IP CURLOPT_SSH_HOSTKEYFUNCTION
-Callback for checking host key handling. See \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP
-.IP CURLOPT_SSH_HOSTKEYDATA
-Custom pointer to pass to ssh host key callback. See \fICURLOPT_SSH_HOSTKEYDATA(3)\fP
-.SH WEBSOCKET
-.IP CURLOPT_WS_OPTIONS
-Set WebSocket options. See \fICURLOPT_WS_OPTIONS(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
-.IP CURLOPT_QUICK_EXIT
-To be set by toplevel tools like "curl" to skip lengthy cleanups when they are about to call exit() anyway. See \fICURLOPT_QUICK_EXIT(3)\fP
-.SH TELNET OPTIONS
-.IP CURLOPT_TELNETOPTIONS
-TELNET options. See \fICURLOPT_TELNETOPTIONS(3)\fP
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  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 AVAILABILITY
-Always
-.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.
-
-If you try to set an option that libcurl does not know about, perhaps because
-the library is too old to support it or the option was removed in a recent
-version, this function returns \fICURLE_UNKNOWN_OPTION\fP. If support for the
-option was disabled at compile-time, it returns \fICURLE_NOT_BUILT_IN\fP.
-.SH "SEE ALSO"
-.BR curl_easy_cleanup (3),
-.BR curl_easy_getinfo (3),
-.BR curl_easy_init (3),
-.BR curl_easy_option_by_id (3),
-.BR curl_easy_option_by_name (3),
-.BR curl_easy_option_next (3),
-.BR curl_easy_reset (3),
-.BR curl_multi_setopt (3)

docs/libcurl/curl_easy_setopt.md

@@ -0,0 +1,1381 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_setopt
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_cleanup (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_reset (3)
+  - curl_multi_setopt (3)
+---
+
+# NAME
+
+curl_easy_setopt - set options for a curl easy handle
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
+~~~
+
+# DESCRIPTION
+
+curl_easy_setopt(3) 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 *option* followed by a *parameter*. That parameter can
+be a **long**, a **function pointer**, an **object pointer** or a
+**curl_off_t**, 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
+curl_easy_setopt(3) calls in the setup phase.
+
+Options set with this function call are valid for all forthcoming transfers
+performed using this *handle*. 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 curl_easy_reset(3).
+
+Strings passed to libcurl as 'char *' arguments, are copied by the library;
+the string storage associated to the pointer argument may be discarded or
+reused after curl_easy_setopt(3) returns. The only exception to this rule is
+really CURLOPT_POSTFIELDS(3), but the alternative that copies the string
+CURLOPT_COPYPOSTFIELDS(3) has some usage characteristics you need to read up
+on. This function does not accept input strings longer than
+**CURL_MAX_INPUT_LENGTH** (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 *handle* is the return code from a curl_easy_init(3) or
+curl_easy_duphandle(3) call.
+
+# BEHAVIOR OPTIONS
+
+## CURLOPT_VERBOSE
+
+Display verbose information. See CURLOPT_VERBOSE(3)
+
+## CURLOPT_HEADER
+
+Include the header in the body output. See CURLOPT_HEADER(3)
+
+## CURLOPT_NOPROGRESS
+
+Shut off the progress meter. See CURLOPT_NOPROGRESS(3)
+
+## CURLOPT_NOSIGNAL
+
+Do not install signal handlers. See CURLOPT_NOSIGNAL(3)
+
+## CURLOPT_WILDCARDMATCH
+
+Transfer multiple files according to a file name pattern. See
+CURLOPT_WILDCARDMATCH(3)
+
+# CALLBACK OPTIONS
+
+## CURLOPT_WRITEFUNCTION
+
+Callback for writing data. See CURLOPT_WRITEFUNCTION(3)
+
+## CURLOPT_WRITEDATA
+
+Data pointer to pass to the write callback. See CURLOPT_WRITEDATA(3)
+
+## CURLOPT_READFUNCTION
+
+Callback for reading data. See CURLOPT_READFUNCTION(3)
+
+## CURLOPT_READDATA
+
+Data pointer to pass to the read callback. See CURLOPT_READDATA(3)
+
+## CURLOPT_IOCTLFUNCTION
+
+**Deprecated option** Callback for I/O operations.
+See CURLOPT_IOCTLFUNCTION(3)
+
+## CURLOPT_IOCTLDATA
+
+**Deprecated option** Data pointer to pass to the I/O callback.
+See CURLOPT_IOCTLDATA(3)
+
+## CURLOPT_SEEKFUNCTION
+
+Callback for seek operations. See CURLOPT_SEEKFUNCTION(3)
+
+## CURLOPT_SEEKDATA
+
+Data pointer to pass to the seek callback. See CURLOPT_SEEKDATA(3)
+
+## CURLOPT_SOCKOPTFUNCTION
+
+Callback for sockopt operations. See CURLOPT_SOCKOPTFUNCTION(3)
+
+## CURLOPT_SOCKOPTDATA
+
+Data pointer to pass to the sockopt callback. See CURLOPT_SOCKOPTDATA(3)
+
+## CURLOPT_OPENSOCKETFUNCTION
+
+Callback for socket creation. See CURLOPT_OPENSOCKETFUNCTION(3)
+
+## CURLOPT_OPENSOCKETDATA
+
+Data pointer to pass to the open socket callback. See CURLOPT_OPENSOCKETDATA(3)
+
+## CURLOPT_CLOSESOCKETFUNCTION
+
+Callback for closing socket. See CURLOPT_CLOSESOCKETFUNCTION(3)
+
+## CURLOPT_CLOSESOCKETDATA
+
+Data pointer to pass to the close socket callback. See CURLOPT_CLOSESOCKETDATA(3)
+
+## CURLOPT_PROGRESSFUNCTION
+
+**OBSOLETE** callback for progress meter.
+See CURLOPT_PROGRESSFUNCTION(3)
+
+## CURLOPT_PROGRESSDATA
+
+Data pointer to pass to the progress meter callback. See CURLOPT_PROGRESSDATA(3)
+
+## CURLOPT_XFERINFOFUNCTION
+
+Callback for progress meter. See CURLOPT_XFERINFOFUNCTION(3)
+
+## CURLOPT_XFERINFODATA
+
+Data pointer to pass to the progress meter callback. See CURLOPT_XFERINFODATA(3)
+
+## CURLOPT_HEADERFUNCTION
+
+Callback for writing received headers. See CURLOPT_HEADERFUNCTION(3)
+
+## CURLOPT_HEADERDATA
+
+Data pointer to pass to the header callback. See CURLOPT_HEADERDATA(3)
+
+## CURLOPT_DEBUGFUNCTION
+
+Callback for debug information. See CURLOPT_DEBUGFUNCTION(3)
+
+## CURLOPT_DEBUGDATA
+
+Data pointer to pass to the debug callback. See CURLOPT_DEBUGDATA(3)
+
+## CURLOPT_SSL_CTX_FUNCTION
+
+Callback for SSL context logic. See CURLOPT_SSL_CTX_FUNCTION(3)
+
+## CURLOPT_SSL_CTX_DATA
+
+Data pointer to pass to the SSL context callback. See CURLOPT_SSL_CTX_DATA(3)
+
+## CURLOPT_CONV_TO_NETWORK_FUNCTION
+
+**OBSOLETE** Callback for code base conversion.
+See CURLOPT_CONV_TO_NETWORK_FUNCTION(3)
+
+## CURLOPT_CONV_FROM_NETWORK_FUNCTION
+
+**OBSOLETE** Callback for code base conversion.
+See CURLOPT_CONV_FROM_NETWORK_FUNCTION(3)
+
+## CURLOPT_CONV_FROM_UTF8_FUNCTION
+
+**OBSOLETE** Callback for code base conversion.
+See CURLOPT_CONV_FROM_UTF8_FUNCTION(3)
+
+## CURLOPT_INTERLEAVEFUNCTION
+
+Callback for RTSP interleaved data. See CURLOPT_INTERLEAVEFUNCTION(3)
+
+## CURLOPT_INTERLEAVEDATA
+
+Data pointer to pass to the RTSP interleave callback. See CURLOPT_INTERLEAVEDATA(3)
+
+## CURLOPT_CHUNK_BGN_FUNCTION
+
+Callback for wildcard download start of chunk. See CURLOPT_CHUNK_BGN_FUNCTION(3)
+
+## CURLOPT_CHUNK_END_FUNCTION
+
+Callback for wildcard download end of chunk. See CURLOPT_CHUNK_END_FUNCTION(3)
+
+## CURLOPT_CHUNK_DATA
+
+Data pointer to pass to the chunk callbacks. See CURLOPT_CHUNK_DATA(3)
+
+## CURLOPT_FNMATCH_FUNCTION
+
+Callback for wildcard matching. See CURLOPT_FNMATCH_FUNCTION(3)
+
+## CURLOPT_FNMATCH_DATA
+
+Data pointer to pass to the wildcard matching callback. See CURLOPT_FNMATCH_DATA(3)
+
+## CURLOPT_SUPPRESS_CONNECT_HEADERS
+
+Suppress proxy CONNECT response headers from user callbacks. See
+CURLOPT_SUPPRESS_CONNECT_HEADERS(3)
+
+## CURLOPT_RESOLVER_START_FUNCTION
+
+Callback to be called before a new resolve request is started. See
+CURLOPT_RESOLVER_START_FUNCTION(3)
+
+## CURLOPT_RESOLVER_START_DATA
+
+Data pointer to pass to resolver start callback. See CURLOPT_RESOLVER_START_DATA(3)
+
+## CURLOPT_PREREQFUNCTION
+
+Callback to be called after a connection is established but before a request
+is made on that connection. See CURLOPT_PREREQFUNCTION(3)
+
+## CURLOPT_PREREQDATA
+
+Data pointer to pass to the CURLOPT_PREREQFUNCTION callback. See
+CURLOPT_PREREQDATA(3)
+
+# ERROR OPTIONS
+
+## CURLOPT_ERRORBUFFER
+
+Error message buffer. See CURLOPT_ERRORBUFFER(3)
+
+## CURLOPT_STDERR
+
+stderr replacement stream. See CURLOPT_STDERR(3)
+
+## CURLOPT_FAILONERROR
+
+Fail on HTTP 4xx errors. CURLOPT_FAILONERROR(3)
+
+## CURLOPT_KEEP_SENDING_ON_ERROR
+
+Keep sending on HTTP >= 300 errors. CURLOPT_KEEP_SENDING_ON_ERROR(3)
+
+# NETWORK OPTIONS
+
+## CURLOPT_URL
+
+URL to work on. See CURLOPT_URL(3)
+
+## CURLOPT_PATH_AS_IS
+
+Disable squashing /../ and /./ sequences in the path. See CURLOPT_PATH_AS_IS(3)
+
+## CURLOPT_PROTOCOLS
+
+**Deprecated option** Allowed protocols. See CURLOPT_PROTOCOLS(3)
+
+## CURLOPT_PROTOCOLS_STR
+
+Allowed protocols. See CURLOPT_PROTOCOLS_STR(3)
+
+## CURLOPT_REDIR_PROTOCOLS
+
+**Deprecated option** Protocols to allow redirects to. See
+CURLOPT_REDIR_PROTOCOLS(3)
+
+## CURLOPT_REDIR_PROTOCOLS_STR
+
+Protocols to allow redirects to. See CURLOPT_REDIR_PROTOCOLS_STR(3)
+
+## CURLOPT_DEFAULT_PROTOCOL
+
+Default protocol. See CURLOPT_DEFAULT_PROTOCOL(3)
+
+## CURLOPT_PROXY
+
+Proxy to use. See CURLOPT_PROXY(3)
+
+## CURLOPT_PRE_PROXY
+
+Socks proxy to use. See CURLOPT_PRE_PROXY(3)
+
+## CURLOPT_PROXYPORT
+
+Proxy port to use. See CURLOPT_PROXYPORT(3)
+
+## CURLOPT_PROXYTYPE
+
+Proxy type. See CURLOPT_PROXYTYPE(3)
+
+## CURLOPT_NOPROXY
+
+Filter out hosts from proxy use. CURLOPT_NOPROXY(3)
+
+## CURLOPT_HTTPPROXYTUNNEL
+
+Tunnel through the HTTP proxy. CURLOPT_HTTPPROXYTUNNEL(3)
+
+## CURLOPT_CONNECT_TO
+
+Connect to a specific host and port. See CURLOPT_CONNECT_TO(3)
+
+## CURLOPT_SOCKS5_AUTH
+
+Socks5 authentication methods. See CURLOPT_SOCKS5_AUTH(3)
+
+## CURLOPT_SOCKS5_GSSAPI_SERVICE
+
+**Deprecated option** Socks5 GSSAPI service name.
+See CURLOPT_SOCKS5_GSSAPI_SERVICE(3)
+
+## CURLOPT_SOCKS5_GSSAPI_NEC
+
+Socks5 GSSAPI NEC mode. See CURLOPT_SOCKS5_GSSAPI_NEC(3)
+
+## CURLOPT_PROXY_SERVICE_NAME
+
+Proxy authentication service name. CURLOPT_PROXY_SERVICE_NAME(3)
+
+## CURLOPT_HAPROXYPROTOCOL
+
+Send an HAProxy PROXY protocol v1 header. See CURLOPT_HAPROXYPROTOCOL(3)
+
+## CURLOPT_HAPROXY_CLIENT_IP
+
+Spoof the client IP in an HAProxy PROXY protocol v1 header. See
+CURLOPT_HAPROXY_CLIENT_IP(3)
+
+## CURLOPT_SERVICE_NAME
+
+Authentication service name. CURLOPT_SERVICE_NAME(3)
+
+## CURLOPT_INTERFACE
+
+Bind connection locally to this. See CURLOPT_INTERFACE(3)
+
+## CURLOPT_LOCALPORT
+
+Bind connection locally to this port. See CURLOPT_LOCALPORT(3)
+
+## CURLOPT_LOCALPORTRANGE
+
+Bind connection locally to port range. See CURLOPT_LOCALPORTRANGE(3)
+
+## CURLOPT_DNS_CACHE_TIMEOUT
+
+Timeout for DNS cache. See CURLOPT_DNS_CACHE_TIMEOUT(3)
+
+## CURLOPT_DNS_USE_GLOBAL_CACHE
+
+**OBSOLETE** Enable global DNS cache.
+See CURLOPT_DNS_USE_GLOBAL_CACHE(3)
+
+## CURLOPT_DOH_URL
+
+Use this DoH server for name resolves. See CURLOPT_DOH_URL(3)
+
+## CURLOPT_BUFFERSIZE
+
+Ask for alternate buffer size. See CURLOPT_BUFFERSIZE(3)
+
+## CURLOPT_PORT
+
+Port number to connect to. See CURLOPT_PORT(3)
+
+## CURLOPT_TCP_FASTOPEN
+
+Enable TCP Fast Open. See CURLOPT_TCP_FASTOPEN(3)
+
+## CURLOPT_TCP_NODELAY
+
+Disable the Nagle algorithm. See CURLOPT_TCP_NODELAY(3)
+
+## CURLOPT_ADDRESS_SCOPE
+
+IPv6 scope for local addresses. See CURLOPT_ADDRESS_SCOPE(3)
+
+## CURLOPT_TCP_KEEPALIVE
+
+Enable TCP keep-alive. See CURLOPT_TCP_KEEPALIVE(3)
+
+## CURLOPT_TCP_KEEPIDLE
+
+Idle time before sending keep-alive. See CURLOPT_TCP_KEEPIDLE(3)
+
+## CURLOPT_TCP_KEEPINTVL
+
+Interval between keep-alive probes. See CURLOPT_TCP_KEEPINTVL(3)
+
+## CURLOPT_UNIX_SOCKET_PATH
+
+Path to a Unix domain socket. See CURLOPT_UNIX_SOCKET_PATH(3)
+
+## CURLOPT_ABSTRACT_UNIX_SOCKET
+
+Path to an abstract Unix domain socket. See CURLOPT_ABSTRACT_UNIX_SOCKET(3)
+
+# NAMES and PASSWORDS OPTIONS (Authentication)
+
+## CURLOPT_NETRC
+
+Enable .netrc parsing. See CURLOPT_NETRC(3)
+
+## CURLOPT_NETRC_FILE
+
+&.netrc file name. See CURLOPT_NETRC_FILE(3)
+
+## CURLOPT_USERPWD
+
+User name and password. See CURLOPT_USERPWD(3)
+
+## CURLOPT_PROXYUSERPWD
+
+Proxy user name and password. See CURLOPT_PROXYUSERPWD(3)
+
+## CURLOPT_USERNAME
+
+User name. See CURLOPT_USERNAME(3)
+
+## CURLOPT_PASSWORD
+
+Password. See CURLOPT_PASSWORD(3)
+
+## CURLOPT_LOGIN_OPTIONS
+
+Login options. See CURLOPT_LOGIN_OPTIONS(3)
+
+## CURLOPT_PROXYUSERNAME
+
+Proxy user name. See CURLOPT_PROXYUSERNAME(3)
+
+## CURLOPT_PROXYPASSWORD
+
+Proxy password. See CURLOPT_PROXYPASSWORD(3)
+
+## CURLOPT_HTTPAUTH
+
+HTTP server authentication methods. See CURLOPT_HTTPAUTH(3)
+
+## CURLOPT_TLSAUTH_USERNAME
+
+TLS authentication user name. See CURLOPT_TLSAUTH_USERNAME(3)
+
+## CURLOPT_PROXY_TLSAUTH_USERNAME
+
+Proxy TLS authentication user name. See CURLOPT_PROXY_TLSAUTH_USERNAME(3)
+
+## CURLOPT_TLSAUTH_PASSWORD
+
+TLS authentication password. See CURLOPT_TLSAUTH_PASSWORD(3)
+
+## CURLOPT_PROXY_TLSAUTH_PASSWORD
+
+Proxy TLS authentication password. See CURLOPT_PROXY_TLSAUTH_PASSWORD(3)
+
+## CURLOPT_TLSAUTH_TYPE
+
+TLS authentication methods. See CURLOPT_TLSAUTH_TYPE(3)
+
+## CURLOPT_PROXY_TLSAUTH_TYPE
+
+Proxy TLS authentication methods. See CURLOPT_PROXY_TLSAUTH_TYPE(3)
+
+## CURLOPT_PROXYAUTH
+
+HTTP proxy authentication methods. See CURLOPT_PROXYAUTH(3)
+
+## CURLOPT_SASL_AUTHZID
+
+SASL authorization identity (identity to act as). See CURLOPT_SASL_AUTHZID(3)
+
+## CURLOPT_SASL_IR
+
+Enable SASL initial response. See CURLOPT_SASL_IR(3)
+
+## CURLOPT_XOAUTH2_BEARER
+
+OAuth2 bearer token. See CURLOPT_XOAUTH2_BEARER(3)
+
+## CURLOPT_DISALLOW_USERNAME_IN_URL
+
+Do not allow username in URL. See CURLOPT_DISALLOW_USERNAME_IN_URL(3)
+
+# HTTP OPTIONS
+
+## CURLOPT_AUTOREFERER
+
+Automatically set Referer: header. See CURLOPT_AUTOREFERER(3)
+
+## CURLOPT_ACCEPT_ENCODING
+
+Accept-Encoding and automatic decompressing data. See CURLOPT_ACCEPT_ENCODING(3)
+
+## CURLOPT_TRANSFER_ENCODING
+
+Request Transfer-Encoding. See CURLOPT_TRANSFER_ENCODING(3)
+
+## CURLOPT_FOLLOWLOCATION
+
+Follow HTTP redirects. See CURLOPT_FOLLOWLOCATION(3)
+
+## CURLOPT_UNRESTRICTED_AUTH
+
+Do not restrict authentication to original host. CURLOPT_UNRESTRICTED_AUTH(3)
+
+## CURLOPT_MAXREDIRS
+
+Maximum number of redirects to follow. See CURLOPT_MAXREDIRS(3)
+
+## CURLOPT_POSTREDIR
+
+How to act on redirects after POST. See CURLOPT_POSTREDIR(3)
+
+## CURLOPT_PUT
+
+**Deprecated option** Issue an HTTP PUT request. See CURLOPT_PUT(3)
+
+## CURLOPT_POST
+
+Issue an HTTP POST request. See CURLOPT_POST(3)
+
+## CURLOPT_POSTFIELDS
+
+Send a POST with this data. See CURLOPT_POSTFIELDS(3)
+
+## CURLOPT_POSTFIELDSIZE
+
+The POST data is this big. See CURLOPT_POSTFIELDSIZE(3)
+
+## CURLOPT_POSTFIELDSIZE_LARGE
+
+The POST data is this big. See CURLOPT_POSTFIELDSIZE_LARGE(3)
+
+## CURLOPT_COPYPOSTFIELDS
+
+Send a POST with this data - and copy it. See CURLOPT_COPYPOSTFIELDS(3)
+
+## CURLOPT_HTTPPOST
+
+**Deprecated option** Multipart formpost HTTP POST.
+See CURLOPT_HTTPPOST(3)
+
+## CURLOPT_REFERER
+
+Referer: header. See CURLOPT_REFERER(3)
+
+## CURLOPT_USERAGENT
+
+User-Agent: header. See CURLOPT_USERAGENT(3)
+
+## CURLOPT_HTTPHEADER
+
+Custom HTTP headers. See CURLOPT_HTTPHEADER(3)
+
+## CURLOPT_HEADEROPT
+
+Control custom headers. See CURLOPT_HEADEROPT(3)
+
+## CURLOPT_PROXYHEADER
+
+Custom HTTP headers sent to proxy. See CURLOPT_PROXYHEADER(3)
+
+## CURLOPT_HTTP200ALIASES
+
+Alternative versions of 200 OK. See CURLOPT_HTTP200ALIASES(3)
+
+## CURLOPT_COOKIE
+
+Cookie(s) to send. See CURLOPT_COOKIE(3)
+
+## CURLOPT_COOKIEFILE
+
+File to read cookies from. See CURLOPT_COOKIEFILE(3)
+
+## CURLOPT_COOKIEJAR
+
+File to write cookies to. See CURLOPT_COOKIEJAR(3)
+
+## CURLOPT_COOKIESESSION
+
+Start a new cookie session. See CURLOPT_COOKIESESSION(3)
+
+## CURLOPT_COOKIELIST
+
+Add or control cookies. See CURLOPT_COOKIELIST(3)
+
+## CURLOPT_ALTSVC
+
+Specify the Alt-Svc: cache file name. See CURLOPT_ALTSVC(3)
+
+## CURLOPT_ALTSVC_CTRL
+
+Enable and configure Alt-Svc: treatment. See CURLOPT_ALTSVC_CTRL(3)
+
+## CURLOPT_HSTS
+
+Set HSTS cache file. See CURLOPT_HSTS(3)
+
+## CURLOPT_HSTS_CTRL
+
+Enable HSTS. See CURLOPT_HSTS_CTRL(3)
+
+## CURLOPT_HSTSREADFUNCTION
+
+Set HSTS read callback. See CURLOPT_HSTSREADFUNCTION(3)
+
+## CURLOPT_HSTSREADDATA
+
+Pass pointer to the HSTS read callback. See CURLOPT_HSTSREADDATA(3)
+
+## CURLOPT_HSTSWRITEFUNCTION
+
+Set HSTS write callback. See CURLOPT_HSTSWRITEFUNCTION(3)
+
+## CURLOPT_HSTSWRITEDATA
+
+Pass pointer to the HSTS write callback. See CURLOPT_HSTSWRITEDATA(3)
+
+## CURLOPT_HTTPGET
+
+Do an HTTP GET request. See CURLOPT_HTTPGET(3)
+
+## CURLOPT_REQUEST_TARGET
+
+Set the request target. CURLOPT_REQUEST_TARGET(3)
+
+## CURLOPT_HTTP_VERSION
+
+HTTP version to use. CURLOPT_HTTP_VERSION(3)
+
+## CURLOPT_HTTP09_ALLOWED
+
+Allow HTTP/0.9 responses. CURLOPT_HTTP09_ALLOWED(3)
+
+## CURLOPT_IGNORE_CONTENT_LENGTH
+
+Ignore Content-Length. See CURLOPT_IGNORE_CONTENT_LENGTH(3)
+
+## CURLOPT_HTTP_CONTENT_DECODING
+
+Disable Content decoding. See CURLOPT_HTTP_CONTENT_DECODING(3)
+
+## CURLOPT_HTTP_TRANSFER_DECODING
+
+Disable Transfer decoding. See CURLOPT_HTTP_TRANSFER_DECODING(3)
+
+## CURLOPT_EXPECT_100_TIMEOUT_MS
+
+100-continue timeout. See CURLOPT_EXPECT_100_TIMEOUT_MS(3)
+
+## CURLOPT_TRAILERFUNCTION
+
+Set callback for sending trailing headers. See
+CURLOPT_TRAILERFUNCTION(3)
+
+## CURLOPT_TRAILERDATA
+
+Custom pointer passed to the trailing headers callback. See
+CURLOPT_TRAILERDATA(3)
+
+## CURLOPT_PIPEWAIT
+
+Wait on connection to pipeline on it. See CURLOPT_PIPEWAIT(3)
+
+## CURLOPT_STREAM_DEPENDS
+
+This HTTP/2 stream depends on another. See CURLOPT_STREAM_DEPENDS(3)
+
+## CURLOPT_STREAM_DEPENDS_E
+
+This HTTP/2 stream depends on another exclusively. See
+CURLOPT_STREAM_DEPENDS_E(3)
+
+## CURLOPT_STREAM_WEIGHT
+
+Set this HTTP/2 stream's weight. See CURLOPT_STREAM_WEIGHT(3)
+
+# SMTP OPTIONS
+
+## CURLOPT_MAIL_FROM
+
+Address of the sender. See CURLOPT_MAIL_FROM(3)
+
+## CURLOPT_MAIL_RCPT
+
+Address of the recipients. See CURLOPT_MAIL_RCPT(3)
+
+## CURLOPT_MAIL_AUTH
+
+Authentication address. See CURLOPT_MAIL_AUTH(3)
+
+## CURLOPT_MAIL_RCPT_ALLOWFAILS
+
+Allow RCPT TO command to fail for some recipients. See
+CURLOPT_MAIL_RCPT_ALLOWFAILS(3)
+
+# TFTP OPTIONS
+
+## CURLOPT_TFTP_BLKSIZE
+
+TFTP block size. See CURLOPT_TFTP_BLKSIZE(3)
+
+## CURLOPT_TFTP_NO_OPTIONS
+
+Do not send TFTP options requests. See CURLOPT_TFTP_NO_OPTIONS(3)
+
+# FTP OPTIONS
+
+## CURLOPT_FTPPORT
+
+Use active FTP. See CURLOPT_FTPPORT(3)
+
+## CURLOPT_QUOTE
+
+Commands to run before transfer. See CURLOPT_QUOTE(3)
+
+## CURLOPT_POSTQUOTE
+
+Commands to run after transfer. See CURLOPT_POSTQUOTE(3)
+
+## CURLOPT_PREQUOTE
+
+Commands to run just before transfer. See CURLOPT_PREQUOTE(3)
+
+## CURLOPT_APPEND
+
+Append to remote file. See CURLOPT_APPEND(3)
+
+## CURLOPT_FTP_USE_EPRT
+
+Use EPRT. See CURLOPT_FTP_USE_EPRT(3)
+
+## CURLOPT_FTP_USE_EPSV
+
+Use EPSV. See CURLOPT_FTP_USE_EPSV(3)
+
+## CURLOPT_FTP_USE_PRET
+
+Use PRET. See CURLOPT_FTP_USE_PRET(3)
+
+## CURLOPT_FTP_CREATE_MISSING_DIRS
+
+Create missing directories on the remote server. See CURLOPT_FTP_CREATE_MISSING_DIRS(3)
+
+## CURLOPT_SERVER_RESPONSE_TIMEOUT
+
+Timeout for server responses. See CURLOPT_SERVER_RESPONSE_TIMEOUT(3)
+
+## CURLOPT_SERVER_RESPONSE_TIMEOUT_MS
+
+Timeout for server responses. See CURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)
+
+## CURLOPT_FTP_ALTERNATIVE_TO_USER
+
+Alternative to USER. See CURLOPT_FTP_ALTERNATIVE_TO_USER(3)
+
+## CURLOPT_FTP_SKIP_PASV_IP
+
+Ignore the IP address in the PASV response. See CURLOPT_FTP_SKIP_PASV_IP(3)
+
+## CURLOPT_FTPSSLAUTH
+
+Control how to do TLS. See CURLOPT_FTPSSLAUTH(3)
+
+## CURLOPT_FTP_SSL_CCC
+
+Back to non-TLS again after authentication. See CURLOPT_FTP_SSL_CCC(3)
+
+## CURLOPT_FTP_ACCOUNT
+
+Send ACCT command. See CURLOPT_FTP_ACCOUNT(3)
+
+## CURLOPT_FTP_FILEMETHOD
+
+Specify how to reach files. See CURLOPT_FTP_FILEMETHOD(3)
+
+# RTSP OPTIONS
+
+## CURLOPT_RTSP_REQUEST
+
+RTSP request. See CURLOPT_RTSP_REQUEST(3)
+
+## CURLOPT_RTSP_SESSION_ID
+
+RTSP session-id. See CURLOPT_RTSP_SESSION_ID(3)
+
+## CURLOPT_RTSP_STREAM_URI
+
+RTSP stream URI. See CURLOPT_RTSP_STREAM_URI(3)
+
+## CURLOPT_RTSP_TRANSPORT
+
+RTSP Transport: header. See CURLOPT_RTSP_TRANSPORT(3)
+
+## CURLOPT_RTSP_CLIENT_CSEQ
+
+Client CSEQ number. See CURLOPT_RTSP_CLIENT_CSEQ(3)
+
+## CURLOPT_RTSP_SERVER_CSEQ
+
+CSEQ number for RTSP Server->Client request. See CURLOPT_RTSP_SERVER_CSEQ(3)
+
+## CURLOPT_AWS_SIGV4
+
+AWS HTTP V4 Signature. See CURLOPT_AWS_SIGV4(3)
+
+# PROTOCOL OPTIONS
+
+## CURLOPT_TRANSFERTEXT
+
+Use text transfer. See CURLOPT_TRANSFERTEXT(3)
+
+## CURLOPT_PROXY_TRANSFER_MODE
+
+Add transfer mode to URL over proxy. See CURLOPT_PROXY_TRANSFER_MODE(3)
+
+## CURLOPT_CRLF
+
+Convert newlines. See CURLOPT_CRLF(3)
+
+## CURLOPT_RANGE
+
+Range requests. See CURLOPT_RANGE(3)
+
+## CURLOPT_RESUME_FROM
+
+Resume a transfer. See CURLOPT_RESUME_FROM(3)
+
+## CURLOPT_RESUME_FROM_LARGE
+
+Resume a transfer. See CURLOPT_RESUME_FROM_LARGE(3)
+
+## CURLOPT_CURLU
+
+Set URL to work on with a URL handle. See CURLOPT_CURLU(3)
+
+## CURLOPT_CUSTOMREQUEST
+
+Custom request/method. See CURLOPT_CUSTOMREQUEST(3)
+
+## CURLOPT_FILETIME
+
+Request file modification date and time. See CURLOPT_FILETIME(3)
+
+## CURLOPT_DIRLISTONLY
+
+List only. See CURLOPT_DIRLISTONLY(3)
+
+## CURLOPT_NOBODY
+
+Do not get the body contents. See CURLOPT_NOBODY(3)
+
+## CURLOPT_INFILESIZE
+
+Size of file to send. CURLOPT_INFILESIZE(3)
+
+## CURLOPT_INFILESIZE_LARGE
+
+Size of file to send. CURLOPT_INFILESIZE_LARGE(3)
+
+## CURLOPT_UPLOAD
+
+Upload data. See CURLOPT_UPLOAD(3)
+
+## CURLOPT_UPLOAD_BUFFERSIZE
+
+Set upload buffer size. See CURLOPT_UPLOAD_BUFFERSIZE(3)
+
+## CURLOPT_MIMEPOST
+
+Post/send MIME data. See CURLOPT_MIMEPOST(3)
+
+## CURLOPT_MIME_OPTIONS
+
+Set MIME option flags. See CURLOPT_MIME_OPTIONS(3)
+
+## CURLOPT_MAXFILESIZE
+
+Maximum file size to get. See CURLOPT_MAXFILESIZE(3)
+
+## CURLOPT_MAXFILESIZE_LARGE
+
+Maximum file size to get. See CURLOPT_MAXFILESIZE_LARGE(3)
+
+## CURLOPT_TIMECONDITION
+
+Make a time conditional request. See CURLOPT_TIMECONDITION(3)
+
+## CURLOPT_TIMEVALUE
+
+Time value for the time conditional request. See CURLOPT_TIMEVALUE(3)
+
+## CURLOPT_TIMEVALUE_LARGE
+
+Time value for the time conditional request. See CURLOPT_TIMEVALUE_LARGE(3)
+
+# CONNECTION OPTIONS
+
+## CURLOPT_TIMEOUT
+
+Timeout for the entire request. See CURLOPT_TIMEOUT(3)
+
+## CURLOPT_TIMEOUT_MS
+
+Millisecond timeout for the entire request. See CURLOPT_TIMEOUT_MS(3)
+
+## CURLOPT_LOW_SPEED_LIMIT
+
+Low speed limit to abort transfer. See CURLOPT_LOW_SPEED_LIMIT(3)
+
+## CURLOPT_LOW_SPEED_TIME
+
+Time to be below the speed to trigger low speed abort. See CURLOPT_LOW_SPEED_TIME(3)
+
+## CURLOPT_MAX_SEND_SPEED_LARGE
+
+Cap the upload speed to this. See CURLOPT_MAX_SEND_SPEED_LARGE(3)
+
+## CURLOPT_MAX_RECV_SPEED_LARGE
+
+Cap the download speed to this. See CURLOPT_MAX_RECV_SPEED_LARGE(3)
+
+## CURLOPT_MAXCONNECTS
+
+Maximum number of connections in the connection pool. See CURLOPT_MAXCONNECTS(3)
+
+## CURLOPT_FRESH_CONNECT
+
+Use a new connection. CURLOPT_FRESH_CONNECT(3)
+
+## CURLOPT_FORBID_REUSE
+
+Prevent subsequent connections from reusing this. See CURLOPT_FORBID_REUSE(3)
+
+## CURLOPT_MAXAGE_CONN
+
+Limit the age (idle time) of connections for reuse. See CURLOPT_MAXAGE_CONN(3)
+
+## CURLOPT_MAXLIFETIME_CONN
+
+Limit the age (since creation) of connections for reuse. See
+CURLOPT_MAXLIFETIME_CONN(3)
+
+## CURLOPT_CONNECTTIMEOUT
+
+Timeout for the connection phase. See CURLOPT_CONNECTTIMEOUT(3)
+
+## CURLOPT_CONNECTTIMEOUT_MS
+
+Millisecond timeout for the connection phase. See CURLOPT_CONNECTTIMEOUT_MS(3)
+
+## CURLOPT_IPRESOLVE
+
+IP version to use. See CURLOPT_IPRESOLVE(3)
+
+## CURLOPT_CONNECT_ONLY
+
+Only connect, nothing else. See CURLOPT_CONNECT_ONLY(3)
+
+## CURLOPT_USE_SSL
+
+Use TLS/SSL. See CURLOPT_USE_SSL(3)
+
+## CURLOPT_RESOLVE
+
+Provide fixed/fake name resolves. See CURLOPT_RESOLVE(3)
+
+## CURLOPT_DNS_INTERFACE
+
+Bind name resolves to this interface. See CURLOPT_DNS_INTERFACE(3)
+
+## CURLOPT_DNS_LOCAL_IP4
+
+Bind name resolves to this IP4 address. See CURLOPT_DNS_LOCAL_IP4(3)
+
+## CURLOPT_DNS_LOCAL_IP6
+
+Bind name resolves to this IP6 address. See CURLOPT_DNS_LOCAL_IP6(3)
+
+## CURLOPT_DNS_SERVERS
+
+Preferred DNS servers. See CURLOPT_DNS_SERVERS(3)
+
+## CURLOPT_DNS_SHUFFLE_ADDRESSES
+
+Shuffle addresses before use. See CURLOPT_DNS_SHUFFLE_ADDRESSES(3)
+
+## CURLOPT_ACCEPTTIMEOUT_MS
+
+Timeout for waiting for the server's connect back to be accepted. See
+CURLOPT_ACCEPTTIMEOUT_MS(3)
+
+## CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS
+
+Timeout for happy eyeballs. See CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)
+
+## CURLOPT_UPKEEP_INTERVAL_MS
+
+Sets the interval at which connection upkeep are performed. See
+CURLOPT_UPKEEP_INTERVAL_MS(3)
+
+# SSL and SECURITY OPTIONS
+
+## CURLOPT_SSLCERT
+
+Client cert. See CURLOPT_SSLCERT(3)
+
+## CURLOPT_SSLCERT_BLOB
+
+Client cert memory buffer. See CURLOPT_SSLCERT_BLOB(3)
+
+## CURLOPT_PROXY_SSLCERT
+
+Proxy client cert. See CURLOPT_PROXY_SSLCERT(3)
+
+## CURLOPT_PROXY_SSLCERT_BLOB
+
+Proxy client cert memory buffer. See CURLOPT_PROXY_SSLCERT_BLOB(3)
+
+## CURLOPT_SSLCERTTYPE
+
+Client cert type. See CURLOPT_SSLCERTTYPE(3)
+
+## CURLOPT_PROXY_SSLCERTTYPE
+
+Proxy client cert type. See CURLOPT_PROXY_SSLCERTTYPE(3)
+
+## CURLOPT_SSLKEY
+
+Client key. See CURLOPT_SSLKEY(3)
+
+## CURLOPT_SSLKEY_BLOB
+
+Client key memory buffer. See CURLOPT_SSLKEY_BLOB(3)
+
+## CURLOPT_PROXY_SSLKEY
+
+Proxy client key. See CURLOPT_PROXY_SSLKEY(3)
+
+## CURLOPT_PROXY_SSLKEY_BLOB
+
+Proxy client key. See CURLOPT_PROXY_SSLKEY_BLOB(3)
+
+## CURLOPT_SSLKEYTYPE
+
+Client key type. See CURLOPT_SSLKEYTYPE(3)
+
+## CURLOPT_PROXY_SSLKEYTYPE
+
+Proxy client key type. See CURLOPT_PROXY_SSLKEYTYPE(3)
+
+## CURLOPT_KEYPASSWD
+
+Client key password. See CURLOPT_KEYPASSWD(3)
+
+## CURLOPT_PROXY_KEYPASSWD
+
+Proxy client key password. See CURLOPT_PROXY_KEYPASSWD(3)
+
+## CURLOPT_SSL_EC_CURVES
+
+Set key exchange curves. See CURLOPT_SSL_EC_CURVES(3)
+
+## CURLOPT_SSL_ENABLE_ALPN
+
+Enable use of ALPN. See CURLOPT_SSL_ENABLE_ALPN(3)
+
+## CURLOPT_SSL_ENABLE_NPN
+
+**OBSOLETE** Enable use of NPN. See CURLOPT_SSL_ENABLE_NPN(3)
+
+## CURLOPT_SSLENGINE
+
+Use identifier with SSL engine. See CURLOPT_SSLENGINE(3)
+
+## CURLOPT_SSLENGINE_DEFAULT
+
+Default SSL engine. See CURLOPT_SSLENGINE_DEFAULT(3)
+
+## CURLOPT_SSL_FALSESTART
+
+Enable TLS False Start. See CURLOPT_SSL_FALSESTART(3)
+
+## CURLOPT_SSLVERSION
+
+SSL version to use. See CURLOPT_SSLVERSION(3)
+
+## CURLOPT_PROXY_SSLVERSION
+
+Proxy SSL version to use. See CURLOPT_PROXY_SSLVERSION(3)
+
+## CURLOPT_SSL_VERIFYHOST
+
+Verify the host name in the SSL certificate. See CURLOPT_SSL_VERIFYHOST(3)
+
+## CURLOPT_DOH_SSL_VERIFYHOST
+
+Verify the host name in the DoH (DNS-over-HTTPS) SSL certificate. See
+CURLOPT_DOH_SSL_VERIFYHOST(3)
+
+## CURLOPT_PROXY_SSL_VERIFYHOST
+
+Verify the host name in the proxy SSL certificate. See
+CURLOPT_PROXY_SSL_VERIFYHOST(3)
+
+## CURLOPT_SSL_VERIFYPEER
+
+Verify the SSL certificate. See CURLOPT_SSL_VERIFYPEER(3)
+
+## CURLOPT_DOH_SSL_VERIFYPEER
+
+Verify the DoH (DNS-over-HTTPS) SSL certificate. See
+CURLOPT_DOH_SSL_VERIFYPEER(3)
+
+## CURLOPT_PROXY_SSL_VERIFYPEER
+
+Verify the proxy SSL certificate. See CURLOPT_PROXY_SSL_VERIFYPEER(3)
+
+## CURLOPT_SSL_VERIFYSTATUS
+
+Verify the SSL certificate's status. See CURLOPT_SSL_VERIFYSTATUS(3)
+
+## CURLOPT_DOH_SSL_VERIFYSTATUS
+
+Verify the DoH (DNS-over-HTTPS) SSL certificate's status. See
+CURLOPT_DOH_SSL_VERIFYSTATUS(3)
+
+## CURLOPT_CAINFO
+
+CA cert bundle. See CURLOPT_CAINFO(3)
+
+## CURLOPT_CAINFO_BLOB
+
+CA cert bundle memory buffer. See CURLOPT_CAINFO_BLOB(3)
+
+## CURLOPT_PROXY_CAINFO
+
+Proxy CA cert bundle. See CURLOPT_PROXY_CAINFO(3)
+
+## CURLOPT_PROXY_CAINFO_BLOB
+
+Proxy CA cert bundle memory buffer. See CURLOPT_PROXY_CAINFO_BLOB(3)
+
+## CURLOPT_ISSUERCERT
+
+Issuer certificate. See CURLOPT_ISSUERCERT(3)
+
+## CURLOPT_ISSUERCERT_BLOB
+
+Issuer certificate memory buffer. See CURLOPT_ISSUERCERT_BLOB(3)
+
+## CURLOPT_PROXY_ISSUERCERT
+
+Proxy issuer certificate. See CURLOPT_PROXY_ISSUERCERT(3)
+
+## CURLOPT_PROXY_ISSUERCERT_BLOB
+
+Proxy issuer certificate memory buffer. See CURLOPT_PROXY_ISSUERCERT_BLOB(3)
+
+## CURLOPT_CAPATH
+
+Path to CA cert bundle. See CURLOPT_CAPATH(3)
+
+## CURLOPT_PROXY_CAPATH
+
+Path to proxy CA cert bundle. See CURLOPT_PROXY_CAPATH(3)
+
+## CURLOPT_CRLFILE
+
+Certificate Revocation List. See CURLOPT_CRLFILE(3)
+
+## CURLOPT_PROXY_CRLFILE
+
+Proxy Certificate Revocation List. See CURLOPT_PROXY_CRLFILE(3)
+
+## CURLOPT_CA_CACHE_TIMEOUT
+
+Timeout for CA cache. See CURLOPT_CA_CACHE_TIMEOUT(3)
+
+## CURLOPT_CERTINFO
+
+Extract certificate info. See CURLOPT_CERTINFO(3)
+
+## CURLOPT_PINNEDPUBLICKEY
+
+Set pinned SSL public key . See CURLOPT_PINNEDPUBLICKEY(3)
+
+## CURLOPT_PROXY_PINNEDPUBLICKEY
+
+Set the proxy's pinned SSL public key. See
+CURLOPT_PROXY_PINNEDPUBLICKEY(3)
+
+## CURLOPT_RANDOM_FILE
+
+**OBSOLETE** Provide source for entropy random data.
+See CURLOPT_RANDOM_FILE(3)
+
+## CURLOPT_EGDSOCKET
+
+**OBSOLETE** Identify EGD socket for entropy. See CURLOPT_EGDSOCKET(3)
+
+## CURLOPT_SSL_CIPHER_LIST
+
+Ciphers to use. See CURLOPT_SSL_CIPHER_LIST(3)
+
+## CURLOPT_PROXY_SSL_CIPHER_LIST
+
+Proxy ciphers to use. See CURLOPT_PROXY_SSL_CIPHER_LIST(3)
+
+## CURLOPT_TLS13_CIPHERS
+
+TLS 1.3 cipher suites to use. See CURLOPT_TLS13_CIPHERS(3)
+
+## CURLOPT_PROXY_TLS13_CIPHERS
+
+Proxy TLS 1.3 cipher suites to use. See CURLOPT_PROXY_TLS13_CIPHERS(3)
+
+## CURLOPT_SSL_SESSIONID_CACHE
+
+Disable SSL session-id cache. See CURLOPT_SSL_SESSIONID_CACHE(3)
+
+## CURLOPT_SSL_OPTIONS
+
+Control SSL behavior. See CURLOPT_SSL_OPTIONS(3)
+
+## CURLOPT_PROXY_SSL_OPTIONS
+
+Control proxy SSL behavior. See CURLOPT_PROXY_SSL_OPTIONS(3)
+
+## CURLOPT_KRBLEVEL
+
+Kerberos security level. See CURLOPT_KRBLEVEL(3)
+
+## CURLOPT_GSSAPI_DELEGATION
+
+Disable GSS-API delegation. See CURLOPT_GSSAPI_DELEGATION(3)
+
+# SSH OPTIONS
+
+## CURLOPT_SSH_AUTH_TYPES
+
+SSH authentication types. See CURLOPT_SSH_AUTH_TYPES(3)
+
+## CURLOPT_SSH_COMPRESSION
+
+Enable SSH compression. See CURLOPT_SSH_COMPRESSION(3)
+
+## CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
+
+MD5 of host's public key. See CURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)
+
+## CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256
+
+SHA256 of host's public key. See CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)
+
+## CURLOPT_SSH_PUBLIC_KEYFILE
+
+File name of public key. See CURLOPT_SSH_PUBLIC_KEYFILE(3)
+
+## CURLOPT_SSH_PRIVATE_KEYFILE
+
+File name of private key. See CURLOPT_SSH_PRIVATE_KEYFILE(3)
+
+## CURLOPT_SSH_KNOWNHOSTS
+
+File name with known hosts. See CURLOPT_SSH_KNOWNHOSTS(3)
+
+## CURLOPT_SSH_KEYFUNCTION
+
+Callback for known hosts handling. See CURLOPT_SSH_KEYFUNCTION(3)
+
+## CURLOPT_SSH_KEYDATA
+
+Custom pointer to pass to ssh key callback. See CURLOPT_SSH_KEYDATA(3)
+
+## CURLOPT_SSH_HOSTKEYFUNCTION
+
+Callback for checking host key handling. See CURLOPT_SSH_HOSTKEYFUNCTION(3)
+
+## CURLOPT_SSH_HOSTKEYDATA
+
+Custom pointer to pass to ssh host key callback. See CURLOPT_SSH_HOSTKEYDATA(3)
+
+# WEBSOCKET
+
+## CURLOPT_WS_OPTIONS
+
+Set WebSocket options. See CURLOPT_WS_OPTIONS(3)
+
+# OTHER OPTIONS
+
+## CURLOPT_PRIVATE
+
+Private pointer to store. See CURLOPT_PRIVATE(3)
+
+## CURLOPT_SHARE
+
+Share object to use. See CURLOPT_SHARE(3)
+
+## CURLOPT_NEW_FILE_PERMS
+
+Mode for creating new remote files. See CURLOPT_NEW_FILE_PERMS(3)
+
+## CURLOPT_NEW_DIRECTORY_PERMS
+
+Mode for creating new remote directories. See CURLOPT_NEW_DIRECTORY_PERMS(3)
+
+## CURLOPT_QUICK_EXIT
+
+To be set by toplevel tools like "curl" to skip lengthy cleanups when they are
+about to call exit() anyway. See CURLOPT_QUICK_EXIT(3)
+
+# TELNET OPTIONS
+
+## CURLOPT_TELNETOPTIONS
+
+TELNET options. See CURLOPT_TELNETOPTIONS(3)
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  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);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Always
+
+# RETURN VALUE
+
+*CURLE_OK* (zero) means that the option was set properly, non-zero means an
+error occurred as *<curl/curl.h>* defines. See the libcurl-errors(3) man page
+for the full list with descriptions.
+
+Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise
+curl_easy_setopt(3) returns **CURLE_BAD_FUNCTION_ARGUMENT** (added in 7.65.0).
+
+**CURLE_BAD_FUNCTION_ARGUMENT** is returned when the argument to an option is
+invalid, like perhaps out of range.
+
+If you try to set an option that libcurl does not know about, perhaps because
+the library is too old to support it or the option was removed in a recent
+version, this function returns *CURLE_UNKNOWN_OPTION*. If support for the
+option was disabled at compile-time, it returns *CURLE_NOT_BUILT_IN*.

docs/libcurl/curl_easy_strerror.3

@@ -1,64 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_easy_strerror 3 "26 Apr 2004" "libcurl" "libcurl"
-.SH NAME
-curl_easy_strerror - return string describing error code
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-const char *curl_easy_strerror(CURLcode errornum);
-.fi
-.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 runtime.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    CURLcode res;
-    /* set options */
-    /* Perform the entire transfer */
-    res = curl_easy_perform(curl);
-    /* Check for errors */
-    if(res != CURLE_OK)
-      fprintf(stderr, "curl_easy_perform() failed: %s\\n",
-              curl_easy_strerror(res));
-  }
-}
-.fi
-.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),
-.BR curl_multi_strerror (3),
-.BR curl_share_strerror (3),
-.BR curl_url_strerror (3)

docs/libcurl/curl_easy_strerror.md

@@ -0,0 +1,59 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_strerror
+Section: 3
+Source: libcurl
+See-also:
+  - curl_multi_strerror (3)
+  - curl_share_strerror (3)
+  - curl_url_strerror (3)
+  - libcurl-errors (3)
+---
+
+# NAME
+
+curl_easy_strerror - return string describing error code
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+const char *curl_easy_strerror(CURLcode errornum);
+~~~
+
+# DESCRIPTION
+
+The curl_easy_strerror(3) function returns a string describing the
+CURLcode error code passed in the argument *errornum*.
+
+Typically applications also appreciate CURLOPT_ERRORBUFFER(3) for more
+specific error descriptions generated at runtime.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    CURLcode res;
+    /* set options */
+    /* Perform the entire transfer */
+    res = curl_easy_perform(curl);
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+  }
+}
+~~~
+
+# AVAILABILITY
+
+This function was added in libcurl 7.12.0
+
+# RETURN VALUE
+
+A pointer to a null-terminated string.

docs/libcurl/curl_easy_unescape.3

@@ -1,79 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.\"
-.TH curl_easy_unescape 3 "7 April 2006" "libcurl" "libcurl"
-.SH NAME
-curl_easy_unescape - URL decodes the given string
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-char *curl_easy_unescape(CURL *curl, const char *input,
-                         int inlength, int *outlength);
-.fi
-.SH DESCRIPTION
-This function converts the URL encoded string \fBinput\fP 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
-uses strlen() on \fBinput\fP to find out the size.
-
-If \fBoutlength\fP is non-NULL, the function writes the length of the returned
-string in the integer it points to. This allows proper handling even for
-strings containing %00. Since this is a pointer to an \fIint\fP type, it can
-only return a value up to \fIINT_MAX\fP so no longer string can be returned in
-this parameter.
-
-Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was
-per-handle character conversion support for some old operating systems such as
-TPF, but it was otherwise ignored.
-
-You must \fIcurl_free(3)\fP the returned string when you are done with it.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    int decodelen;
-    char *decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen);
-    if(decoded) {
-      /* do not assume printf() works on the decoded data! */
-      printf("Decoded: ");
-      /* ... */
-      curl_free(decoded);
-    }
-    curl_easy_cleanup(curl);
-  }
-}
-.fi
-.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),
-.BR curl_free (3)

docs/libcurl/curl_easy_unescape.md

@@ -0,0 +1,73 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_unescape
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_escape (3)
+  - curl_free (3)
+---
+
+# NAME
+
+curl_easy_unescape - URL decodes the given string
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+char *curl_easy_unescape(CURL *curl, const char *input,
+                         int inlength, int *outlength);
+~~~
+
+# DESCRIPTION
+
+This function converts the URL encoded string **input** 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 **length** argument is set to 0 (zero), curl_easy_unescape(3)
+uses strlen() on **input** to find out the size.
+
+If **outlength** is non-NULL, the function writes the length of the returned
+string in the integer it points to. This allows proper handling even for
+strings containing %00. Since this is a pointer to an *int* type, it can
+only return a value up to *INT_MAX* so no longer string can be returned in
+this parameter.
+
+Since 7.82.0, the **curl** parameter is ignored. Prior to that there was
+per-handle character conversion support for some old operating systems such as
+TPF, but it was otherwise ignored.
+
+You must curl_free(3) the returned string when you are done with it.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    int decodelen;
+    char *decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen);
+    if(decoded) {
+      /* do not assume printf() works on the decoded data! */
+      printf("Decoded: ");
+      /* ... */
+      curl_free(decoded);
+    }
+    curl_easy_cleanup(curl);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.15.4 and replaces the old curl_unescape(3) function.
+
+# RETURN VALUE
+
+A pointer to a null-terminated string or NULL if it failed.

docs/libcurl/curl_easy_upkeep.3

@@ -1,84 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.\"
-.TH curl_easy_upkeep 3 "31 Oct 2018" "libcurl" "libcurl"
-.SH NAME
-curl_easy_upkeep - Perform any connection upkeep checks.
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_easy_upkeep(CURL *handle);
-.fi
-.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 EXAMPLE
-.nf
-int main(void)
-{
-  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
-.SH AVAILABILITY
-Added in 7.62.0.
-.SH RETURN VALUE
-On success, returns \fBCURLE_OK\fP.
-
-On failure, returns the appropriate error code.
-.SH SEE ALSO
-.BR CURLOPT_TCP_KEEPALIVE "(3), "
-.BR CURLOPT_TCP_KEEPIDLE "(3), "

docs/libcurl/curl_easy_upkeep.md

@@ -0,0 +1,77 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_easy_upkeep
+Section: 3
+Source: libcurl
+See-also:
+  - CURLOPT_TCP_KEEPALIVE (3)
+  - CURLOPT_TCP_KEEPIDLE (3)
+---
+
+# NAME
+
+curl_easy_upkeep - Perform any connection upkeep checks.
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_upkeep(CURL *handle);
+~~~
+
+# 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 curl_easy_upkeep(3)
+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
+CURLOPT_UPKEEP_INTERVAL_MS(3).
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  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);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.62.0.
+
+# RETURN VALUE
+
+On success, returns **CURLE_OK**.
+
+On failure, returns the appropriate error code.

docs/libcurl/curl_escape.3

@@ -1,63 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_escape 3 "6 March 2002" "libcurl" "libcurl"
-.SH NAME
-curl_escape - URL encodes the given string
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-char *curl_escape(const char *string, int length);
-.fi
-.SH DESCRIPTION
-Obsolete function. Use \fIcurl_easy_escape(3)\fP instead!
-
-This function converts the given input \fBstring\fP to a URL encoded string
-and return that as a new allocated string. All input characters that are not
-a-z, A-Z or 0-9 are converted to their "URL escaped" version (\fB%NN\fP where
-\fBNN\fP is a two-digit hexadecimal number).
-
-If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP uses strlen()
-on \fBstring\fP to find out the size.
-
-You must \fIcurl_free(3)\fP the returned string when you are done with it.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  char *output = curl_escape("data to convert", 15);
-  if(output) {
-    printf("Encoded: %s\\n", output);
-    curl_free(output);
-  }
-}
-.fi
-.SH AVAILABILITY
-Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function might 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),
-.BR curl_free (3)

docs/libcurl/curl_escape.md

@@ -0,0 +1,58 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_escape
+Section: 3
+Source: libcurl
+See-also:
+  - curl_free (3)
+  - curl_unescape (3)
+---
+
+# NAME
+
+curl_escape - URL encodes the given string
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+char *curl_escape(const char *string, int length);
+~~~
+
+# DESCRIPTION
+
+Obsolete function. Use curl_easy_escape(3) instead!
+
+This function converts the given input **string** to a URL encoded string
+and return that as a new allocated string. All input characters that are not
+a-z, A-Z or 0-9 are 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(3) uses strlen()
+on **string** to find out the size.
+
+You must curl_free(3) the returned string when you are done with it.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  char *output = curl_escape("data to convert", 15);
+  if(output) {
+    printf("Encoded: %s\n", output);
+    curl_free(output);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Since 7.15.4, curl_easy_escape(3) should be used. This function might be
+removed in a future release.
+
+# RETURN VALUE
+
+A pointer to a null-terminated string or NULL if it failed.

docs/libcurl/curl_formadd.3

@@ -1,285 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_formadd 3 "24 June 2002" "libcurl" "libcurl"
-.SH NAME
-curl_formadd - add a section to a multipart form POST
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLFORMcode curl_formadd(struct curl_httppost **firstitem,
-                          struct curl_httppost **lastitem, ...);
-.fi
-.SH DESCRIPTION
-\fBThis function is deprecated.\fP Use \fIcurl_mime_init(3)\fP instead.
-
-curl_formadd() is used to append sections when building a multipart form
-post. Append one section at a time until you have 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 is 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 form
-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 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 does not need to keep it around after
-this function call. If the name is not null-terminated, you must set its
-length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to
-contain zero-valued bytes. The copied data is freed by \fIcurl_formfree(3)\fP.
-.IP CURLFORM_PTRNAME
-followed by a string which provides the \fIname\fP of this part. libcurl uses
-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 is not null-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 does not need to
-keep it around after this function call. If the data is not null terminated,
-or if you would like it to contain zero bytes, you must set the length of the
-name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied data is 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 uses 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 is
-not null-terminated, or if you would 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 calls 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 calls 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 \fICURLformoption\fP 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 have passed the \fIstruct curl_httppost\fP pointer to
-\fIcurl_easy_setopt(3)\fP (using the \fICURLOPT_HTTPPOST(3)\fP option), you
-must not free the list until after you have called \fIcurl_easy_cleanup(3)\fP
-for the curl handle.
-
-See example below.
-.SH EXAMPLE
-.nf
-#include <string.h> /* for strlen */
-
-static const char record[]="data in a buffer";
-
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    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, sizeof(record),
-                 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);
-
-    curl_easy_perform(curl);
-
-    curl_easy_cleanup(curl);
-
-    curl_formfree(post);
-  }
-}
-.fi
-.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 "SEE ALSO"
-.BR curl_easy_setopt (3),
-.BR curl_formfree (3),
-.BR curl_mime_init (3)

docs/libcurl/curl_formadd.md

@@ -0,0 +1,313 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_formadd
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_setopt (3)
+  - curl_formfree (3)
+  - curl_mime_init (3)
+---
+
+# NAME
+
+curl_formadd - add a section to a multipart form POST
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLFORMcode curl_formadd(struct curl_httppost **firstitem,
+                          struct curl_httppost **lastitem, ...);
+~~~
+
+# DESCRIPTION
+
+**This function is deprecated.** Use curl_mime_init(3) instead.
+
+curl_formadd() is used to append sections when building a multipart form
+post. Append one section at a time until you have added all the sections you
+want included and then you pass the *firstitem* pointer as parameter to
+CURLOPT_HTTPPOST(3). *lastitem* is set after each curl_formadd(3) 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 *lastitem* pointer follow the real arguments.
+
+The pointers *firstitem* and *lastitem* should both be pointing to
+NULL in the first call to this function. All list-data is allocated by the
+function itself. You must call curl_formfree(3) on the *firstitem*
+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 CURLOPT_HTTPHEADER(3) as usual.
+
+First, there are some basics you need to understand about multipart form
+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 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
+*CURLFORM_FILE* through *CURLFORM_BUFFERLENGTH* are for file upload
+parts.
+
+# OPTIONS
+
+## CURLFORM_COPYNAME
+
+followed by a string which provides the *name* of this part. libcurl
+copies the string so your application does not need to keep it around after
+this function call. If the name is not null-terminated, you must set its
+length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to
+contain zero-valued bytes. The copied data is freed by curl_formfree(3).
+
+## CURLFORM_PTRNAME
+
+followed by a string which provides the *name* of this part. libcurl uses 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 is not null-terminated, you
+must set its length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to
+contain zero-valued bytes.
+
+## 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 does not need to
+keep it around after this function call. If the data is not null terminated,
+or if you would like it to contain zero bytes, you must set the length of the
+name with **CURLFORM_CONTENTSLENGTH**. The copied data is freed by
+curl_formfree(3).
+
+## CURLFORM_PTRCONTENTS
+
+followed by a pointer to the contents of this part, the actual data to send
+away. libcurl uses 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 is
+not null-terminated, or if you would like it to contain zero bytes, you must
+set its length with **CURLFORM_CONTENTSLENGTH**.
+
+## CURLFORM_CONTENTLEN
+
+followed by a curl_off_t value giving the length of the contents. Note that
+for *CURLFORM_STREAM* contents, this option is mandatory.
+
+If you pass a 0 (zero) for this option, libcurl calls 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)
+
+## CURLFORM_CONTENTSLENGTH
+
+(This option is deprecated. Use *CURLFORM_CONTENTLEN* instead!)
+
+followed by a long giving the length of the contents. Note that for
+*CURLFORM_STREAM* contents, this option is mandatory.
+
+If you pass a 0 (zero) for this option, libcurl calls 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.
+
+## CURLFORM_FILECONTENT
+
+followed by a filename, causes that file to be read and its contents used
+as data in this part. This part does *not* 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.
+
+## CURLFORM_FILE
+
+followed by a filename, makes this part a file upload part. It sets the
+*filename* 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
+**CURLFORM_FILE** the user may send one or more files in one part by
+providing multiple **CURLFORM_FILE** arguments each followed by the filename
+(and each *CURLFORM_FILE* is allowed to have a
+*CURLFORM_CONTENTTYPE*).
+
+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.
+
+## CURLFORM_CONTENTTYPE
+
+is used in combination with *CURLFORM_FILE*. Followed by a pointer to a
+string which provides the content-type for this part, possibly instead of an
+internally chosen one.
+
+## CURLFORM_FILENAME
+
+is used in combination with *CURLFORM_FILE*. Followed by a pointer to a
+string, it tells libcurl to use the given string as the *filename* in the
+file upload part instead of the actual file name.
+
+## CURLFORM_BUFFER
+
+is used for custom file upload parts without use of *CURLFORM_FILE*. It
+tells libcurl that the file contents are already present in a buffer. The
+parameter is a string which provides the *filename* field in the content
+header.
+
+## CURLFORM_BUFFERPTR
+
+is used in combination with *CURLFORM_BUFFER*. The parameter is a pointer
+to the buffer to be uploaded. This buffer must not be freed until after
+curl_easy_cleanup(3) is called. You must also use
+*CURLFORM_BUFFERLENGTH* to set the number of bytes in the buffer.
+
+## CURLFORM_BUFFERLENGTH
+
+is used in combination with *CURLFORM_BUFFER*. The parameter is a
+long which gives the length of the buffer.
+
+## CURLFORM_STREAM
+
+Tells libcurl to use the CURLOPT_READFUNCTION(3) callback to get
+data. The parameter you pass to *CURLFORM_STREAM* 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 *CURLFORM_FILENAME* parameter as well. Note that
+when using *CURLFORM_STREAM*, *CURLFORM_CONTENTSLENGTH* 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)
+
+## CURLFORM_ARRAY
+
+Another possibility to send options to curl_formadd() is the
+**CURLFORM_ARRAY** 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 **CURLFORM_END**.
+
+## CURLFORM_CONTENTHEADER
+
+specifies extra headers for the form POST section. This takes a curl_slist
+prepared in the usual way using **curl_slist_append** 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 have passed the *struct curl_httppost* pointer to
+curl_easy_setopt(3) (using the CURLOPT_HTTPPOST(3) option), you
+must not free the list until after you have called curl_easy_cleanup(3)
+for the curl handle.
+
+See example below.
+
+# EXAMPLE
+
+~~~c
+#include <string.h> /* for strlen */
+
+static const char record[]="data in a buffer";
+
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    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, sizeof(record),
+                 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);
+
+    curl_easy_perform(curl);
+
+    curl_easy_cleanup(curl);
+
+    curl_formfree(post);
+  }
+}
+~~~
+
+# 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.
+
+# RETURN VALUE
+
+0 means everything was OK, non-zero means an error occurred corresponding
+to a CURL_FORMADD_* constant defined in
+*<curl/curl.h>*

docs/libcurl/curl_formfree.3

@@ -1,81 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_formfree 3 "6 April 2001" "libcurl" "libcurl"
-.SH NAME
-curl_formfree - free a previously build multipart form post chain
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-void curl_formfree(struct curl_httppost *form);
-.fi
-.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 makes this function return immediately
-with no action.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    struct curl_httppost *formpost;
-    struct curl_httppost *lastptr;
-
-    /* Fill in a file upload field */
-    curl_formadd(&formpost,
-                 &lastptr,
-                 CURLFORM_COPYNAME, "file",
-                 CURLFORM_FILE, "nice-image.jpg",
-                 CURLFORM_END);
-
-    curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);
-
-    curl_easy_perform(curl);
-
-    /* then cleanup the formpost chain */
-    curl_formfree(formpost);
-  }
-}
-.fi
-.SH AVAILABILITY
-Deprecated in 7.56.0.
-.SH RETURN VALUE
-None
-.SH "SEE ALSO"
-.BR curl_formadd (3),
-.BR curl_mime_init (3),
-.BR curl_mime_free (3)

docs/libcurl/curl_formfree.md

@@ -0,0 +1,76 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_formfree
+Section: 3
+Source: libcurl
+See-also:
+  - curl_formadd (3)
+  - curl_mime_free (3)
+  - curl_mime_init (3)
+---
+
+# NAME
+
+curl_formfree - free a previously build multipart form post chain
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+void curl_formfree(struct curl_httppost *form);
+~~~
+
+# DESCRIPTION
+
+This function is deprecated. Do not use. See curl_mime_init(3) instead!
+
+curl_formfree() is used to clean up data previously built/appended with
+curl_formadd(3). This must be called when the data has been used, which
+typically means after curl_easy_perform(3) has been called.
+
+The pointer to free is the same pointer you passed to the
+CURLOPT_HTTPPOST(3) option, which is the *firstitem* pointer from
+the curl_formadd(3) invoke(s).
+
+**form** is the pointer as returned from a previous call to
+curl_formadd(3) and may be NULL.
+
+Passing in a NULL pointer in *form* makes this function return immediately
+with no action.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    struct curl_httppost *formpost;
+    struct curl_httppost *lastptr;
+
+    /* Fill in a file upload field */
+    curl_formadd(&formpost,
+                 &lastptr,
+                 CURLFORM_COPYNAME, "file",
+                 CURLFORM_FILE, "nice-image.jpg",
+                 CURLFORM_END);
+
+    curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);
+
+    curl_easy_perform(curl);
+
+    /* then cleanup the formpost chain */
+    curl_formfree(formpost);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Deprecated in 7.56.0.
+
+# RETURN VALUE
+
+None

docs/libcurl/curl_formget.3

@@ -1,77 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_formget 3 "20 June 2006" "libcurl" "libcurl"
-.SH NAME
-curl_formget - serialize a previously built multipart form POST chain
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-int curl_formget(struct curl_httppost * form, void *userp,
-                 curl_formget_callback append);
-.fi
-.SH DESCRIPTION
-curl_formget() serializes data previously built with \fIcurl_formadd(3)\fP. It
-accepts a void pointer as second argument named \fIuserp\fP which is passed as
-the first argument to the curl_formget_callback function.
-
-.nf
- typedef size_t (*curl_formget_callback)(void *userp, const char *buf,
-                                         size_t len);"
-.fi
-
-The curl_formget_callback is invoked 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 prevents
-\fIcurl_formget(3)\fP from working until you have performed the actual HTTP
-request. This, because first then does libcurl known which actual read
-callback to use!
-.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;
-}
-.fi
-.SH AVAILABILITY
-This function was added in libcurl 7.15.5. The form API is deprecated in
-libcurl 7.56.0.
-.SH RETURN VALUE
-0 means everything was OK, non-zero means an error occurred
-.SH "SEE ALSO"
-.BR curl_formadd (3),
-.BR curl_mime_init (3)

docs/libcurl/curl_formget.md

@@ -0,0 +1,72 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_formget
+Section: 3
+Source: libcurl
+See-also:
+  - curl_formadd (3)
+  - curl_mime_init (3)
+---
+
+# NAME
+
+curl_formget - serialize a previously built multipart form POST chain
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+int curl_formget(struct curl_httppost * form, void *userp,
+                 curl_formget_callback append);
+~~~
+
+# DESCRIPTION
+
+curl_formget() serializes data previously built with curl_formadd(3). It
+accepts a void pointer as second argument named *userp* which is passed as
+the first argument to the curl_formget_callback function.
+
+~~~c
+ typedef size_t (*curl_formget_callback)(void *userp, const char *buf,
+                                         size_t len);"
+~~~
+
+The curl_formget_callback is invoked 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 **CURLFORM_STREAM** option is used in the formpost, it prevents
+curl_formget(3) from working until you have performed the actual HTTP
+request. This, because first then does libcurl known which actual read
+callback to use!
+
+# EXAMPLE
+
+~~~c
+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;
+}
+~~~
+
+# AVAILABILITY
+
+This function was added in libcurl 7.15.5. The form API is deprecated in
+libcurl 7.56.0.
+
+# RETURN VALUE
+
+0 means everything was OK, non-zero means an error occurred

docs/libcurl/curl_free.3

@@ -1,57 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_free 3 "12 Aug 2003" "libcurl" "libcurl"
-.SH NAME
-curl_free - reclaim memory that has been obtained through a libcurl call
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-void curl_free(void *ptr);
-.fi
-.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 makes this function return immediately
-with no action.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  char *width = curl_getenv("COLUMNS");
-  if(width) {
-    /* it was set! */
-    curl_free(width);
-  }
-}
-.fi
-.SH AVAILABILITY
-Always
-.SH RETURN VALUE
-None
-.SH "SEE ALSO"
-.BR curl_easy_escape (3),
-.BR curl_easy_unescape (3)

docs/libcurl/curl_free.md

@@ -0,0 +1,52 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_free
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_escape (3)
+  - curl_easy_unescape (3)
+---
+
+# NAME
+
+curl_free - reclaim memory that has been obtained through a libcurl call
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+void curl_free(void *ptr);
+~~~
+
+# DESCRIPTION
+
+curl_free reclaims memory that has been obtained through a libcurl call. Use
+curl_free(3) 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 *ptr* makes this function return immediately
+with no action.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  char *width = curl_getenv("COLUMNS");
+  if(width) {
+    /* it was set! */
+    curl_free(width);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Always
+
+# RETURN VALUE
+
+None

docs/libcurl/curl_getdate.3

@@ -1,120 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_getdate 3 "12 Aug 2005" "libcurl" "libcurl"
-.SH NAME
-curl_getdate - Convert a date string to number of seconds
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-time_t curl_getdate(const char *datestring, const time_t *now);
-.fi
-.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.
-
-This function works with valid dates and does not always detect and reject
-wrong dates, such as February 30.
-
-.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:
-.IP "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.
-.IP "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. If there is no time given in a provided date
-string, 00:00:00 is assumed. Example: 18:19:21.
-.IP "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.
-.IP "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.
-.IP "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.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  time_t t;
-  t = curl_getdate("Sun, 06 Nov 1994 08:49:37 GMT", NULL);
-  t = curl_getdate("Sunday, 06-Nov-94 08:49:37 GMT", NULL);
-  t = curl_getdate("Sun Nov  6 08:49:37 1994", NULL);
-  t = curl_getdate("06 Nov 1994 08:49:37 GMT", NULL);
-  t = curl_getdate("06-Nov-94 08:49:37 GMT", NULL);
-  t = curl_getdate("Nov  6 08:49:37 1994", NULL);
-  t = curl_getdate("06 Nov 1994 08:49:37", NULL);
-  t = curl_getdate("06-Nov-94 08:49:37", NULL);
-  t = curl_getdate("1994 Nov 6 08:49:37", NULL);
-  t = curl_getdate("GMT 08:49:37 06-Nov-94 Sunday", NULL);
-  t = curl_getdate("94 6 Nov 08:49:37", NULL);
-  t = curl_getdate("1994 Nov 6", NULL);
-  t = curl_getdate("06-Nov-94", NULL);
-  t = curl_getdate("Sun Nov 6 94", NULL);
-  t = curl_getdate("1994.Nov.6", NULL);
-  t = curl_getdate("Sun/Nov/6/94/GMT", NULL);
-  t = curl_getdate("Sun, 06 Nov 1994 08:49:37 CET", NULL);
-  t = curl_getdate("06 Nov 1994 08:49:37 EST", NULL);
-  t = curl_getdate("Sun, 12 Sep 2004 15:05:58 -0700", NULL);
-  t = curl_getdate("Sat, 11 Sep 2004 21:32:11 +0200", NULL);
-  t = curl_getdate("20040912 15:05:58 -0700", NULL);
-  t = curl_getdate("20040911 +0200", NULL);
-}
-.fi
-.SH STANDARDS
-This parser handles 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 \fIasctime()\fP format.
-
-These formats are the only ones RFC 7231 says HTTP applications may use.
-.SH AVAILABILITY
-Always
-.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 returns -1.
-
-On systems with an unsigned 32 bit time_t: if the year is larger than 2106 or
-less than 1970, this function returns -1.
-
-On systems with 64 bit time_t: if the year is less than 1583, this function
-returns -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),
-.BR curl_easy_unescape (3),
-.BR CURLOPT_TIMECONDITION (3),
-.BR CURLOPT_TIMEVALUE (3)

docs/libcurl/curl_getdate.md

@@ -0,0 +1,128 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_getdate
+Section: 3
+Source: libcurl
+See-also:
+  - CURLOPT_TIMECONDITION (3)
+  - CURLOPT_TIMEVALUE (3)
+  - curl_easy_escape (3)
+  - curl_easy_unescape (3)
+---
+
+# NAME
+
+curl_getdate - Convert a date string to number of seconds
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+time_t curl_getdate(const char *datestring, const time_t *now);
+~~~
+
+# DESCRIPTION
+
+curl_getdate(3) 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
+*datestring* parameter specifies. The *now* parameter is not used,
+pass a NULL there.
+
+This function works with valid dates and does not always detect and reject
+wrong dates, such as February 30.
+
+# 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:
+
+## 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.
+
+## 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. If there is no time given in a provided date
+string, 00:00:00 is assumed. Example: 18:19:21.
+
+## 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.
+
+## 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.
+
+## 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.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  time_t t;
+  t = curl_getdate("Sun, 06 Nov 1994 08:49:37 GMT", NULL);
+  t = curl_getdate("Sunday, 06-Nov-94 08:49:37 GMT", NULL);
+  t = curl_getdate("Sun Nov  6 08:49:37 1994", NULL);
+  t = curl_getdate("06 Nov 1994 08:49:37 GMT", NULL);
+  t = curl_getdate("06-Nov-94 08:49:37 GMT", NULL);
+  t = curl_getdate("Nov  6 08:49:37 1994", NULL);
+  t = curl_getdate("06 Nov 1994 08:49:37", NULL);
+  t = curl_getdate("06-Nov-94 08:49:37", NULL);
+  t = curl_getdate("1994 Nov 6 08:49:37", NULL);
+  t = curl_getdate("GMT 08:49:37 06-Nov-94 Sunday", NULL);
+  t = curl_getdate("94 6 Nov 08:49:37", NULL);
+  t = curl_getdate("1994 Nov 6", NULL);
+  t = curl_getdate("06-Nov-94", NULL);
+  t = curl_getdate("Sun Nov 6 94", NULL);
+  t = curl_getdate("1994.Nov.6", NULL);
+  t = curl_getdate("Sun/Nov/6/94/GMT", NULL);
+  t = curl_getdate("Sun, 06 Nov 1994 08:49:37 CET", NULL);
+  t = curl_getdate("06 Nov 1994 08:49:37 EST", NULL);
+  t = curl_getdate("Sun, 12 Sep 2004 15:05:58 -0700", NULL);
+  t = curl_getdate("Sat, 11 Sep 2004 21:32:11 +0200", NULL);
+  t = curl_getdate("20040912 15:05:58 -0700", NULL);
+  t = curl_getdate("20040911 +0200", NULL);
+}
+~~~
+
+# STANDARDS
+
+This parser handles 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.
+
+# AVAILABILITY
+
+Always
+
+# 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 returns -1.
+
+On systems with an unsigned 32 bit time_t: if the year is larger than 2106 or
+less than 1970, this function returns -1.
+
+On systems with 64 bit time_t: if the year is less than 1583, this function
+returns -1. (The Gregorian calendar was first introduced 1582 so no "real"
+dates in this way of doing dates existed before then.)

docs/libcurl/curl_getenv.3

@@ -1,60 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_getenv 3 "30 April 2004" "libcurl" "libcurl"
-.SH NAME
-curl_getenv - return value for environment name
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-char *curl_getenv(const char *name);
-.fi
-.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 are done with it.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  char *width = curl_getenv("COLUMNS");
-  if(width) {
-    /* it was set! */
-    curl_free(width);
-  }
-}
-.fi
-.SH AVAILABILITY
-Always
-.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 is no point in returning an allocated
-memory, although other systems does not work properly if this is not done. The
-unix implementation thus suffers slightly from the drawbacks of other systems.
-.SH "SEE ALSO"
-.BR getenv (3C)

docs/libcurl/curl_getenv.md

@@ -0,0 +1,57 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_getenv
+Section: 3
+Source: libcurl
+See-also:
+  - getenv (3C)
+---
+
+# NAME
+
+curl_getenv - return value for environment name
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+char *curl_getenv(const char *name);
+~~~
+
+# 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 curl_free(3) the returned string when you are done with it.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  char *width = curl_getenv("COLUMNS");
+  if(width) {
+    /* it was set! */
+    curl_free(width);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+Always
+
+# RETURN VALUE
+
+A pointer to a null-terminated string or NULL if it failed to find the
+specified name.
+
+# NOTE
+
+Under unix operating systems, there is no point in returning an allocated
+memory, although other systems does not work properly if this is not done. The
+unix implementation thus suffers slightly from the drawbacks of other systems.

docs/libcurl/curl_global_cleanup.3

@@ -1,77 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_global_cleanup 3 "17 Feb 2006" "libcurl" "libcurl"
-.SH NAME
-curl_global_cleanup - global libcurl cleanup
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-void curl_global_cleanup(void);
-.fi
-.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.
-
-This function is thread-safe since libcurl 7.84.0 if
-\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
-(most platforms).
-
-If this is not thread-safe, you must not call this function when any other
-thread in the program (i.e. a thread sharing the same memory) is running.
-This does not 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 EXAMPLE
-.nf
-int main(void)
-{
-  curl_global_init(CURL_GLOBAL_DEFAULT);
-
-  /* use libcurl, then before exiting... */
-
-  curl_global_cleanup();
-}
-.fi
-.SH AVAILABILITY
-Added in 7.8
-.SH RETURN VALUE
-None
-.SH "SEE ALSO"
-.BR curl_global_init (3),
-.BR libcurl (3),
-.BR libcurl-thread (3)

docs/libcurl/curl_global_cleanup.md

@@ -0,0 +1,74 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_global_cleanup
+Section: 3
+Source: libcurl
+See-also:
+  - curl_global_init (3)
+  - libcurl (3)
+  - libcurl-thread (3)
+---
+
+# NAME
+
+curl_global_cleanup - global libcurl cleanup
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+void curl_global_cleanup(void);
+~~~
+
+# DESCRIPTION
+
+This function releases resources acquired by curl_global_init(3).
+
+You should call curl_global_cleanup(3) once for each call you make to
+curl_global_init(3), after you are done using libcurl.
+
+This function is thread-safe since libcurl 7.84.0 if
+curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set
+(most platforms).
+
+If this is not thread-safe, you must not call this function when any other
+thread in the program (i.e. a thread sharing the same memory) is running.
+This does not just mean no other thread that is using libcurl. Because
+curl_global_cleanup(3) 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 libcurl(3) of global environment requirements for
+details of how to use this function.
+
+# CAUTION
+
+curl_global_cleanup(3) 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.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  curl_global_init(CURL_GLOBAL_DEFAULT);
+
+  /* use libcurl, then before exiting... */
+
+  curl_global_cleanup();
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.8
+
+# RETURN VALUE
+
+None

docs/libcurl/curl_global_init.3

@@ -1,124 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_global_init 3 "11 May 2004" "libcurl" "libcurl"
-.SH NAME
-curl_global_init - Global libcurl initialization
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_global_init(long flags);
-.fi
-.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. Do not use any other
-value unless you are familiar with it and mean to control internal operations
-of libcurl.
-
-This function is thread-safe since libcurl 7.84.0 if
-\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
-(most platforms).
-
-If this is not thread-safe, you must not call this function when any other
-thread in the program (i.e. a thread sharing the same memory) is running.
-This does not 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 \fIDllMain\fP 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 is no need for libcurl to do it again.
-.IP CURL_GLOBAL_NOTHING
-Initialize nothing extra. This sets no bit.
-.IP CURL_GLOBAL_DEFAULT
-A sensible default. It initializes 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 acknowledges EINTR condition when
-connecting or when waiting for data. Otherwise, curl waits until full timeout
-elapses. (Added in 7.30.0)
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  curl_global_init(CURL_GLOBAL_DEFAULT);
-
-  /* use libcurl, then before exiting... */
-
-  curl_global_cleanup();
-}
-.fi
-.SH AVAILABILITY
-Added in 7.8
-.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_easy_init (3),
-.BR curl_global_cleanup (3),
-.BR curl_global_init_mem (3),
-.BR curl_global_sslset (3),
-.BR curl_global_trace (3),
-.BR libcurl (3)

docs/libcurl/curl_global_init.md

@@ -0,0 +1,131 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_global_init
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_init (3)
+  - curl_global_cleanup (3)
+  - curl_global_init_mem (3)
+  - curl_global_sslset (3)
+  - curl_global_trace (3)
+  - libcurl (3)
+---
+
+# NAME
+
+curl_global_init - Global libcurl initialization
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_global_init(long flags);
+~~~
+
+# 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. Do not use any other
+value unless you are familiar with it and mean to control internal operations
+of libcurl.
+
+This function is thread-safe since libcurl 7.84.0 if
+curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set
+(most platforms).
+
+If this is not thread-safe, you must not call this function when any other
+thread in the program (i.e. a thread sharing the same memory) is running.
+This does not just mean no other thread that is using libcurl. Because
+curl_global_init(3) 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 libcurl(3) of global environment requirements for
+details of how to use this function.
+
+# FLAGS
+
+## CURL_GLOBAL_ALL
+
+Initialize everything possible. This sets all known bits except
+**CURL_GLOBAL_ACK_EINTR**.
+
+## 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.
+
+## 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 is no need for libcurl to do it again.
+
+## CURL_GLOBAL_NOTHING
+
+Initialize nothing extra. This sets no bit.
+
+## CURL_GLOBAL_DEFAULT
+
+A sensible default. It initializes both SSL and Win32. Right now, this equals
+the functionality of the **CURL_GLOBAL_ALL** mask.
+
+## 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 acknowledges EINTR condition when
+connecting or when waiting for data. Otherwise, curl waits until full timeout
+elapses. (Added in 7.30.0)
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  curl_global_init(CURL_GLOBAL_DEFAULT);
+
+  /* use libcurl, then before exiting... */
+
+  curl_global_cleanup();
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.8
+
+# RETURN VALUE
+
+If this function returns non-zero, something went wrong and you cannot use the
+other curl functions.

docs/libcurl/curl_global_init_mem.3

@@ -1,88 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_global_init_mem 3 "10 May 2004" "libcurl" "libcurl"
-.SH NAME
-curl_global_init_mem - Global libcurl initialization with memory callbacks
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_global_init_mem(long flags,
-                              curl_malloc_callback m,
-                              curl_free_callback f,
-                              curl_realloc_callback r,
-                              curl_strdup_callback s,
-                              curl_calloc_callback c);
-.fi
-.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()
-
-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 EXAMPLE
-.nf
-extern void *malloc_cb(size_t);
-extern void free_cb(void *);
-extern void *realloc_cb(void *, size_t);
-extern char *strdup_cb(const char *);
-extern void *calloc_cb(size_t, size_t);
-
-int main(void)
-{
-  curl_global_init_mem(CURL_GLOBAL_DEFAULT, malloc_cb,
-                       free_cb, realloc_cb,
-                       strdup_cb, calloc_cb);
-}
-.fi
-.SH AVAILABILITY
-Added in 7.12.0
-.SH RETURN VALUE
-CURLE_OK (0) means everything was OK, non-zero means an error occurred as
-\fI<curl/curl.h>\fP defines - see \fIlibcurl-errors(3)\fP.
-.SH "SEE ALSO"
-.BR curl_global_init (3),
-.BR curl_global_cleanup (3)

docs/libcurl/curl_global_init_mem.md

@@ -0,0 +1,95 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_global_init_mem
+Section: 3
+Source: libcurl
+See-also:
+  - curl_global_cleanup (3)
+  - curl_global_init (3)
+---
+
+# NAME
+
+curl_global_init_mem - Global libcurl initialization with memory callbacks
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_global_init_mem(long flags,
+                              curl_malloc_callback m,
+                              curl_free_callback f,
+                              curl_realloc_callback r,
+                              curl_strdup_callback s,
+                              curl_calloc_callback c);
+~~~
+
+# DESCRIPTION
+
+This function works exactly as curl_global_init(3) 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:
+
+## void *malloc_callback(size_t size);
+
+To replace malloc()
+
+## void free_callback(void *ptr);
+
+To replace free()
+
+## void *realloc_callback(void *ptr, size_t size);
+
+To replace realloc()
+
+## char *strdup_callback(const char *str);
+
+To replace strdup()
+
+## void *calloc_callback(size_t nmemb, size_t size);
+
+To replace calloc()
+
+This function is otherwise the same as curl_global_init(3), please refer
+to that man page for documentation.
+
+# CAUTION
+
+Manipulating these gives considerable powers to the application to severely
+screw things up for libcurl. Take care!
+
+# EXAMPLE
+
+~~~c
+extern void *malloc_cb(size_t);
+extern void free_cb(void *);
+extern void *realloc_cb(void *, size_t);
+extern char *strdup_cb(const char *);
+extern void *calloc_cb(size_t, size_t);
+
+int main(void)
+{
+  curl_global_init_mem(CURL_GLOBAL_DEFAULT, malloc_cb,
+                       free_cb, realloc_cb,
+                       strdup_cb, calloc_cb);
+}
+~~~
+
+# AVAILABILITY
+
+Added in 7.12.0
+
+# RETURN VALUE
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred as
+*<curl/curl.h>* defines - see libcurl-errors(3).

docs/libcurl/curl_global_sslset.3

@@ -1,139 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_global_sslset 3 "15 July 2017" "libcurl" "libcurl"
-.SH NAME
-curl_global_sslset - Select SSL backend to use with libcurl
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLsslset curl_global_sslset(curl_sslbackend id,
-                              const char *name,
-                              const 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
-\fBCURLSSLBACKEND_NONE\fP as \fIid\fP). If both \fIid\fP and \fIname\fP are
-specified, the \fIname\fP is ignored.
-
-If neither \fIid\fP nor \fPname\fP are specified, the function fails with
-\fBCURLSSLSET_UNKNOWN_BACKEND\fP 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 is always set to the list of
-alternatives if non-NULL.
-
-Upon success, the function returns \fBCURLSSLSET_OK\fP.
-
-If the specified SSL backend is not available, the function returns
-\fBCURLSSLSET_UNKNOWN_BACKEND\fP 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 results in a \fBCURLSSLSET_TOO_LATE\fP getting returned.
-
-This function is thread-safe since libcurl 7.84.0 if
-\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
-(most platforms).
-
-If this is not thread-safe, you must not call this function when any other
-thread in the program (i.e. a thread sharing the same memory) is running.
-This does not just mean no other thread that is using libcurl.
-.SH OpenSSL
-The name "OpenSSL" is used for all versions of OpenSSL and its associated
-forks/flavors in this function. OpenSSL, BoringSSL, libressl, quictls and
-AmiSSL are all supported by libcurl, but in the eyes of
-\fIcurl_global_sslset(3)\fP they are all just "OpenSSL". They all mostly
-provide the same API.
-
-\fIcurl_version_info(3)\fP can return more specific info about the exact
-OpenSSL flavor and version number is use.
-.SH struct
-.nf
-typedef struct {
-  curl_sslbackend id;
-  const char *name;
-} curl_ssl_backend;
-
-typedef enum {
-  CURLSSLBACKEND_NONE = 0,
-  CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */
-  CURLSSLBACKEND_GNUTLS = 2,
-  CURLSSLBACKEND_NSS = 3,
-  CURLSSLBACKEND_GSKIT = 5, /* deprecated */
-  CURLSSLBACKEND_POLARSSL = 6, /* deprecated */
-  CURLSSLBACKEND_WOLFSSL = 7,
-  CURLSSLBACKEND_SCHANNEL = 8,
-  CURLSSLBACKEND_SECURETRANSPORT = 9,
-  CURLSSLBACKEND_AXTLS = 10, /* deprecated */
-  CURLSSLBACKEND_MBEDTLS = 11,
-  CURLSSLBACKEND_MESALINK = 12, /* deprecated */
-  CURLSSLBACKEND_BEARSSL = 13,
-  CURLSSLBACKEND_RUSTLS = 14
-} curl_sslbackend;
-.fi
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  int i;
-  /* choose a specific backend */
-  curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL);
-
-  /* list the available ones */
-  const curl_ssl_backend **list;
-  curl_global_sslset(CURLSSLBACKEND_NONE, NULL, &list);
-
-  for(i = 0; list[i]; i++)
-    printf("SSL backend #%d: '%s' (ID: %d)\\n",
-           i, list[i]->name, list[i]->id);
-}
-.fi
-.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 \fICURLSSLSET_OK\fP, 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)

docs/libcurl/curl_global_sslset.md

@@ -0,0 +1,138 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_global_sslset
+Section: 3
+Source: libcurl
+See-also:
+  - curl_global_init (3)
+  - libcurl (3)
+---
+
+# NAME
+
+curl_global_sslset - Select SSL backend to use with libcurl
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLsslset curl_global_sslset(curl_sslbackend id,
+                              const char *name,
+                              const curl_ssl_backend ***avail);
+~~~
+
+# 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 **before** curl_global_init(3).
+
+The backend can be identified by the *id*
+(e.g. **CURLSSLBACKEND_OPENSSL**). The backend can also be specified via the
+*name* parameter for a case insensitive match (passing
+**CURLSSLBACKEND_NONE** as *id*). If both *id* and *name* are
+specified, the *name* is ignored.
+
+If neither *id* nor *name* are specified, the function fails with
+**CURLSSLSET_UNKNOWN_BACKEND** and set the *avail* 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 *avail* pointer is always 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 *avail* 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 results in a **CURLSSLSET_TOO_LATE** getting returned.
+
+This function is thread-safe since libcurl 7.84.0 if
+curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set
+(most platforms).
+
+If this is not thread-safe, you must not call this function when any other
+thread in the program (i.e. a thread sharing the same memory) is running.
+This does not just mean no other thread that is using libcurl.
+
+# OpenSSL
+
+The name "OpenSSL" is used for all versions of OpenSSL and its associated
+forks/flavors in this function. OpenSSL, BoringSSL, libressl, quictls and
+AmiSSL are all supported by libcurl, but in the eyes of
+curl_global_sslset(3) they are all just "OpenSSL". They all mostly
+provide the same API.
+
+curl_version_info(3) can return more specific info about the exact
+OpenSSL flavor and version number is use.
+
+# struct
+
+~~~c
+typedef struct {
+  curl_sslbackend id;
+  const char *name;
+} curl_ssl_backend;
+
+typedef enum {
+  CURLSSLBACKEND_NONE = 0,
+  CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */
+  CURLSSLBACKEND_GNUTLS = 2,
+  CURLSSLBACKEND_NSS = 3,
+  CURLSSLBACKEND_GSKIT = 5, /* deprecated */
+  CURLSSLBACKEND_POLARSSL = 6, /* deprecated */
+  CURLSSLBACKEND_WOLFSSL = 7,
+  CURLSSLBACKEND_SCHANNEL = 8,
+  CURLSSLBACKEND_SECURETRANSPORT = 9,
+  CURLSSLBACKEND_AXTLS = 10, /* deprecated */
+  CURLSSLBACKEND_MBEDTLS = 11,
+  CURLSSLBACKEND_MESALINK = 12, /* deprecated */
+  CURLSSLBACKEND_BEARSSL = 13,
+  CURLSSLBACKEND_RUSTLS = 14
+} curl_sslbackend;
+~~~
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  int i;
+  /* choose a specific backend */
+  curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL);
+
+  /* list the available ones */
+  const curl_ssl_backend **list;
+  curl_global_sslset(CURLSSLBACKEND_NONE, NULL, &list);
+
+  for(i = 0; list[i]; i++)
+    printf("SSL backend #%d: '%s' (ID: %d)\n",
+           i, list[i]->name, list[i]->id);
+}
+~~~
+
+# AVAILABILITY
+
+This function was added in libcurl 7.56.0. Before this version, there was no
+support for choosing SSL backends at runtime.
+
+# 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
+*CURLSSLSET_UNKNOWN_BACKEND*.
+
+If the backend had been configured previously, or if curl_global_init(3)
+has already been called, the function returns *CURLSSLSET_TOO_LATE*.
+
+If this libcurl was built completely without SSL support, with no backends at
+all, this function returns *CURLSSLSET_NO_BACKENDS*.

docs/libcurl/curl_global_trace.3

@@ -1,121 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_global_trace 3 "01 August 2023" "libcurl" "libcurl"
-.SH NAME
-curl_global_trace - Global libcurl logging configuration
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_global_trace(const char *config);
-.fi
-.SH DESCRIPTION
-This function configures the logging behavior, allowing to make some
-parts of curl more verbose or silent than others.
-
-This function may be called during the initialization phase of a program. It
-does not have to be. It can be called several times even, possibly overwriting
-settings of previous calls.
-
-Calling this function after transfers have been started is undefined. On
-some platforms/architectures it might take effect, on others not.
-
-This function is thread-safe since libcurl 8.3.0 if
-\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
-(most platforms).
-
-If this is not thread-safe, you must not call this function when any other
-thread in the program (i.e. a thread sharing the same memory) is running.
-This does not just mean no other thread that is using libcurl. Because
-\fIcurl_global_init(3)\fP may call 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 \fIDllMain\fP or a static initializer because Windows holds the loader
-lock during that time and it could cause a deadlock.
-
-The \fIconfig\fP string is a list of comma-separated component names. Names
-are case-insensitive and unknown names are ignored. The special name "all"
-applies to all components. Names may be prefixed with '+' or '-' to enable
-or disable detailed logging for a component.
-
-The list of component names is not part of curl's public API. Names may be
-added or disappear in future versions of libcurl. Since unknown names are
-silently ignored, outdated log configurations does not cause errors when
-upgrading libcurl. Given that, some names can be expected to be fairly stable
-and are listed below for easy reference.
-
-Note that log configuration applies only to transfers where debug logging
-is enabled. See \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP
-on how to control that.
-
-.SH TRACE COMPONENTS
-.IP tcp
-Tracing of TCP socket handling: connect, reads, writes.
-.IP ssl
-Tracing of SSL/TLS operations, whichever SSL backend is used in your build.
-.IP http/2
-Details about HTTP/2 handling: frames, events, I/O, etc.
-.IP http/3
-Details about HTTP/3 handling: connect, frames, events, I/O etc.
-.IP http-proxy
-Involved when transfers are tunneled through a HTTP proxy. "h1-proxy" or
-"h2-proxy" are also involved, depending on the HTTP version negotiated with
-the proxy.
-
-In order to find out all components involved in a transfer, run it with "all"
-configured. You can then see all names involved in your libcurl version in the
-trace.
-
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  /* log details of HTTP/2 and SSL handling */
-  curl_global_trace("http/2,ssl");
-
-  /* log all details, except SSL handling */
-  curl_global_trace("all,-ssl");
-}
-.fi
-
-Below is a trace sample where "http/2" was configured. The trace output
-of an enabled component appears at the beginning in brackets.
-.nf
-* [HTTP/2] [h2sid=1] cf_send(len=96) submit https://example.com/
-\&...
-* [HTTP/2] [h2sid=1] FRAME[HEADERS]
-* [HTTP/2] [h2sid=1] 249 header bytes
-\&...
-.fi
-
-.SH AVAILABILITY
-Added in 8.3
-.SH RETURN VALUE
-If this function returns non-zero, something went wrong and the configuration
-may not have any effects or may only been applied partially.
-.SH "SEE ALSO"
-.BR curl_global_init (3),
-.BR libcurl (3)

docs/libcurl/curl_global_trace.md

@@ -0,0 +1,124 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_global_trace
+Section: 3
+Source: libcurl
+See-also:
+  - curl_global_init (3)
+  - libcurl (3)
+---
+
+# NAME
+
+curl_global_trace - Global libcurl logging configuration
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_global_trace(const char *config);
+~~~
+
+# DESCRIPTION
+
+This function configures the logging behavior, allowing to make some
+parts of curl more verbose or silent than others.
+
+This function may be called during the initialization phase of a program. It
+does not have to be. It can be called several times even, possibly overwriting
+settings of previous calls.
+
+Calling this function after transfers have been started is undefined. On
+some platforms/architectures it might take effect, on others not.
+
+This function is thread-safe since libcurl 8.3.0 if
+curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set
+(most platforms).
+
+If this is not thread-safe, you must not call this function when any other
+thread in the program (i.e. a thread sharing the same memory) is running.
+This does not just mean no other thread that is using libcurl. Because
+curl_global_init(3) may call 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.
+
+The *config* string is a list of comma-separated component names. Names
+are case-insensitive and unknown names are ignored. The special name "all"
+applies to all components. Names may be prefixed with '+' or '-' to enable
+or disable detailed logging for a component.
+
+The list of component names is not part of curl's public API. Names may be
+added or disappear in future versions of libcurl. Since unknown names are
+silently ignored, outdated log configurations does not cause errors when
+upgrading libcurl. Given that, some names can be expected to be fairly stable
+and are listed below for easy reference.
+
+Note that log configuration applies only to transfers where debug logging
+is enabled. See CURLOPT_VERBOSE(3) or CURLOPT_DEBUGFUNCTION(3)
+on how to control that.
+
+# TRACE COMPONENTS
+
+## tcp
+
+Tracing of TCP socket handling: connect, reads, writes.
+
+## ssl
+
+Tracing of SSL/TLS operations, whichever SSL backend is used in your build.
+
+## http/2
+
+Details about HTTP/2 handling: frames, events, I/O, etc.
+
+## http/3
+
+Details about HTTP/3 handling: connect, frames, events, I/O etc.
+
+## http-proxy
+
+Involved when transfers are tunneled through a HTTP proxy. "h1-proxy" or
+"h2-proxy" are also involved, depending on the HTTP version negotiated with
+the proxy.
+
+In order to find out all components involved in a transfer, run it with "all"
+configured. You can then see all names involved in your libcurl version in the
+trace.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  /* log details of HTTP/2 and SSL handling */
+  curl_global_trace("http/2,ssl");
+
+  /* log all details, except SSL handling */
+  curl_global_trace("all,-ssl");
+}
+~~~
+
+Below is a trace sample where "http/2" was configured. The trace output
+of an enabled component appears at the beginning in brackets.
+~~~
+* [HTTP/2] [h2sid=1] cf_send(len=96) submit https://example.com/
+...
+* [HTTP/2] [h2sid=1] FRAME[HEADERS]
+* [HTTP/2] [h2sid=1] 249 header bytes
+...
+~~~
+
+# AVAILABILITY
+
+Added in 8.3
+
+# RETURN VALUE
+
+If this function returns non-zero, something went wrong and the configuration
+may not have any effects or may only been applied partially.

docs/libcurl/curl_mime_addpart.3

@@ -1,75 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_addpart 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_addpart - append a new empty part to a mime structure
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-curl_mimepart *curl_mime_addpart(curl_mime *mime);
-.fi
-.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 EXAMPLE
-.nf
-int main(void)
-{
-  curl_mime *mime;
-  curl_mimepart *part;
-
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    /* create a mime handle */
-    mime = curl_mime_init(curl);
-
-    /* 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 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 "SEE ALSO"
-.BR curl_mime_data (3),
-.BR curl_mime_data_cb (3),
-.BR curl_mime_encoder (3),
-.BR curl_mime_filedata (3),
-.BR curl_mime_filename (3),
-.BR curl_mime_headers (3),
-.BR curl_mime_init (3),
-.BR curl_mime_name (3),
-.BR curl_mime_subparts (3),
-.BR curl_mime_type (3)

docs/libcurl/curl_mime_addpart.md

@@ -0,0 +1,70 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_addpart
+Section: 3
+Source: libcurl
+See-also:
+  - curl_mime_data (3)
+  - curl_mime_data_cb (3)
+  - curl_mime_encoder (3)
+  - curl_mime_filedata (3)
+  - curl_mime_filename (3)
+  - curl_mime_headers (3)
+  - curl_mime_init (3)
+  - curl_mime_name (3)
+  - curl_mime_subparts (3)
+  - curl_mime_type (3)
+---
+
+# NAME
+
+curl_mime_addpart - append a new empty part to a mime structure
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+curl_mimepart *curl_mime_addpart(curl_mime *mime);
+~~~
+
+# DESCRIPTION
+
+curl_mime_addpart(3) 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.
+
+*mime* is the handle of the mime structure in which the new part must be
+appended.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  curl_mime *mime;
+  curl_mimepart *part;
+
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    /* create a mime handle */
+    mime = curl_mime_init(curl);
+
+    /* 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");
+  }
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# RETURN VALUE
+
+A mime part structure handle, or NULL upon failure.

docs/libcurl/curl_mime_data.3

@@ -1,81 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_data 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_data - set a mime part's body data from memory
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_mime_data(curl_mimepart *part, const char *data,
-                        size_t datasize);
-.fi
-.SH DESCRIPTION
-\fIcurl_mime_data(3)\fP sets a mime part's body content from memory data.
-
-\fIpart\fP is the mime part to assign contents to, created with
-\fIcurl_mime_addpart(3)\fP.
-
-\fIdata\fP points to the data that gets copied by this function. The storage
-may safely be reused after the call.
-
-\fIdatasize\fP is the number of bytes \fIdata\fP points to. It can be set to
-\fICURL_ZERO_TERMINATED\fP to indicate \fIdata\fP is a null-terminated
-character string.
-
-Setting a part's contents multiple times 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 large data is memory consuming: one might consider using
-\fIcurl_mime_data_cb(3)\fP in such a case.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  curl_mime *mime;
-  curl_mimepart *part;
-
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    /* create a mime handle */
-    mime = curl_mime_init(curl);
-
-    /* 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 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 "SEE ALSO"
-.BR curl_mime_addpart (3),
-.BR curl_mime_data_cb (3),
-.BR curl_mime_name (3),
-.BR curl_mime_type (3)

docs/libcurl/curl_mime_data.md

@@ -0,0 +1,76 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_data
+Section: 3
+Source: libcurl
+See-also:
+  - curl_mime_addpart (3)
+  - curl_mime_data_cb (3)
+  - curl_mime_name (3)
+  - curl_mime_type (3)
+---
+
+# NAME
+
+curl_mime_data - set a mime part's body data from memory
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_mime_data(curl_mimepart *part, const char *data,
+                        size_t datasize);
+~~~
+
+# DESCRIPTION
+
+curl_mime_data(3) sets a mime part's body content from memory data.
+
+*part* is the mime part to assign contents to, created with
+curl_mime_addpart(3).
+
+*data* points to the data that gets copied by this function. The storage
+may safely be reused after the call.
+
+*datasize* is the number of bytes *data* points to. It can be set to
+*CURL_ZERO_TERMINATED* to indicate *data* is a null-terminated
+character string.
+
+Setting a part's contents multiple times is valid: only the value set by the
+last call is retained. It is possible to unassign part's contents by setting
+*data* to NULL.
+
+Setting large data is memory consuming: one might consider using
+curl_mime_data_cb(3) in such a case.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  curl_mime *mime;
+  curl_mimepart *part;
+
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    /* create a mime handle */
+    mime = curl_mime_init(curl);
+
+    /* add a part */
+    part = curl_mime_addpart(mime);
+
+    /* add data to the part  */
+    curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# RETURN VALUE
+
+CURLE_OK or a CURL error code upon failure.

docs/libcurl/curl_mime_data_cb.3

@@ -1,173 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_data_cb 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_data_cb - set a callback-based data source for a mime part's body
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
-
-int seekfunc(void *arg, curl_off_t offset, int origin);
-
-void freefunc(void *arg);
-
-CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize,
-                           curl_read_callback readfunc,
-                           curl_seek_callback seekfunc,
-                           curl_free_callback freefunc, void *arg);
-.fi
-.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 is used when resending data (i.e.:
-after a redirect); this pointer may be set to NULL, in which case a resend
-might not be 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 is 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 \fInitems\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 signals 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 have said you intend to upload N bytes
-and yet you upload less than N bytes), you may experience that the server
-"hangs" waiting for the rest of the data that does not 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 then gets called twice with the same argument.
-.SH EXAMPLE
-Sending a huge data string causes 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
-#include <string.h> /* for memcpy */
-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;
-}
-
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    curl_mime *mime = curl_mime_init(curl);
-    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);
-  }
-}
-.fi
-.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 "SEE ALSO"
-.BR curl_easy_duphandle (3),
-.BR curl_mime_addpart (3),
-.BR curl_mime_data (3),
-.BR curl_mime_name (3)

docs/libcurl/curl_mime_data_cb.md

@@ -0,0 +1,168 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_data_cb
+Section: 3
+Source: libcurl
+See-also:
+  - curl_easy_duphandle (3)
+  - curl_mime_addpart (3)
+  - curl_mime_data (3)
+  - curl_mime_name (3)
+---
+
+# NAME
+
+curl_mime_data_cb - set a callback-based data source for a mime part's body
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
+
+int seekfunc(void *arg, curl_off_t offset, int origin);
+
+void freefunc(void *arg);
+
+CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize,
+                           curl_read_callback readfunc,
+                           curl_seek_callback seekfunc,
+                           curl_free_callback freefunc, void *arg);
+~~~
+
+# DESCRIPTION
+
+curl_mime_data_cb(3) sets the data source of a mime part's body content
+from a data read callback function.
+
+*part* is the part's to assign contents to.
+
+*readfunc* 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.
+
+*seekfunc* is a pointer to a seek callback function, with a signature as
+shown by the above prototype. This function is used when resending data (i.e.:
+after a redirect); this pointer may be set to NULL, in which case a resend
+might not be not possible.
+
+*freefunc* 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 is called upon mime structure
+freeing.
+
+*arg* 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 *buffer*
+should be filled up with at most *size* multiplied with *nitems* 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 signals 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 have said you intend to upload N bytes
+and yet you upload less than N bytes), you may experience that the server
+"hangs" waiting for the rest of the data that does not come.
+
+The read callback may return *CURL_READFUNC_ABORT* to stop the current
+operation immediately, resulting in a *CURLE_ABORTED_BY_CALLBACK* error
+code from the transfer.
+
+The callback can return *CURL_READFUNC_PAUSE* to cause reading from this
+connection to pause. See curl_easy_pause(3) 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 *origin*,
+although libcurl currently only passes SEEK_SET.
+
+The callback function must return *CURL_SEEKFUNC_OK* on success,
+*CURL_SEEKFUNC_FAIL* to cause the upload operation to fail or
+*CURL_SEEKFUNC_CANTSEEK* to indicate that while the seek failed, libcurl
+is free to work around the problem if possible. The latter can sometimes be
+done by instead reading from the input or similar.
+
+Care must be taken if the part is bound to a curl easy handle that is later
+duplicated: the *arg* 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 *freefunc* procedure
+code since it then gets called twice with the same argument.
+
+# EXAMPLE
+
+Sending a huge data string causes 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.
+~~~c
+#include <string.h> /* for memcpy */
+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;
+}
+
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    curl_mime *mime = curl_mime_init(curl);
+    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);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# RETURN VALUE
+
+CURLE_OK or a CURL error code upon failure.

docs/libcurl/curl_mime_encoder.3

@@ -1,105 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_encoder 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_encoder - set a mime part's encoder and content transfer encoding
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_mime_encoder(curl_mimepart *part, const char *encoding);
-.fi
-.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 multiple times 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 \fI"Content-Transfer-Encoding"\fP header
-is added to the part.
-
-Supported encoding schemes are:
-
-"\fIbinary\fP": the data is left unchanged, the header is added.
-
-"\fI8bit\fP": header added, no data change.
-
-"\fI7bit\fP": the data is unchanged, but is each byte is checked
-to be a 7-bit value; if not, a read error occurs.
-
-"\fIbase64\fP": Data is converted to base64 encoding, then split in
-CRLF-terminated lines of at most 76 characters.
-
-"\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(3)\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(3)\fP is strongly
-discouraged.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  curl_mime *mime;
-  curl_mimepart *part;
-
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    /* create a mime handle */
-    mime = curl_mime_init(curl);
-
-    /* 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 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 "SEE ALSO"
-.BR curl_mime_addpart (3),
-.BR curl_mime_headers (3),
-.BR curl_mime_subparts (3)

docs/libcurl/curl_mime_encoder.md

@@ -0,0 +1,100 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_encoder
+Section: 3
+Source: libcurl
+See-also:
+  - curl_mime_addpart (3)
+  - curl_mime_headers (3)
+  - curl_mime_subparts (3)
+---
+
+# NAME
+
+curl_mime_encoder - set a mime part's encoder and content transfer encoding
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_mime_encoder(curl_mimepart *part, const char *encoding);
+~~~
+
+# DESCRIPTION
+
+curl_mime_encoder() requests a mime part's content to be encoded before being
+transmitted.
+
+*part* is the part's handle to assign an encoder.
+*encoding* 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 multiple times 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 *"Content-Transfer-Encoding"* header
+is added to the part.
+
+Supported encoding schemes are:
+
+"*binary*": the data is left unchanged, the header is added.
+
+"*8bit*": header added, no data change.
+
+"*7bit*": the data is unchanged, but is each byte is checked
+to be a 7-bit value; if not, a read error occurs.
+
+"*base64*": Data is converted to base64 encoding, then split in
+CRLF-terminated lines of at most 76 characters.
+
+"*quoted-printable*": 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
+*Content-Transfer-Encoding* header should be added with
+curl_mime_headers(3) 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 curl_mime_subparts(3) is strongly
+discouraged.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  curl_mime *mime;
+  curl_mimepart *part;
+
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    /* create a mime handle */
+    mime = curl_mime_init(curl);
+
+    /* 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");
+  }
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# RETURN VALUE
+
+CURLE_OK or a CURL error code upon failure.

docs/libcurl/curl_mime_filedata.3

@@ -1,93 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_filedata 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_filedata - set a mime part's body data from a file contents
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_mime_filedata(curl_mimepart *part,
-                            const char *filename);
-.fi
-.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 character device or named pipe), the whole mime structure containing the
-part is transferred using chunks by HTTP but is rejected by IMAP.
-
-Setting a part's contents multiple times is valid: only the value set by the
-last call is retained.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  curl_mime *mime;
-  curl_mimepart *part;
-
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    /* create a mime handle */
-    mime = curl_mime_init(curl);
-
-    /* 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 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 "SEE ALSO"
-.BR curl_mime_addpart (3),
-.BR curl_mime_data (3),
-.BR curl_mime_filename (3),
-.BR curl_mime_name (3)

docs/libcurl/curl_mime_filedata.md

@@ -0,0 +1,88 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_filedata
+Section: 3
+Source: libcurl
+See-also:
+  - curl_mime_addpart (3)
+  - curl_mime_data (3)
+  - curl_mime_filename (3)
+  - curl_mime_name (3)
+---
+
+# NAME
+
+curl_mime_filedata - set a mime part's body data from a file contents
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_mime_filedata(curl_mimepart *part,
+                            const char *filename);
+~~~
+
+# DESCRIPTION
+
+curl_mime_filedata(3) sets a mime part's body content from the named
+file's contents. This is an alternative to curl_mime_data(3) for setting
+data to a mime part.
+
+*part* is the part's to assign contents to.
+
+*filename* 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 *filename* if it is a valid named file. This can be undone or
+overridden by a subsequent call to curl_mime_filename(3).
+
+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 character device or named pipe), the whole mime structure containing the
+part is transferred using chunks by HTTP but is rejected by IMAP.
+
+Setting a part's contents multiple times is valid: only the value set by the
+last call is retained.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  curl_mime *mime;
+  curl_mimepart *part;
+
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    /* create a mime handle */
+    mime = curl_mime_init(curl);
+
+    /* 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");
+  }
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# 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.

docs/libcurl/curl_mime_filename.3

@@ -1,84 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_filename 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_filename - set a mime part's remote file name
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_mime_filename(curl_mimepart *part,
-                            const char *filename);
-.fi
-.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 multiple times is valid: only the value set by the last call is retained.
-.SH EXAMPLE
-.nf
-
-static char imagebuf[]="imagedata";
-
-int main(void)
-{
-  curl_mime *mime;
-  curl_mimepart *part;
-
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    /* create a mime handle */
-    mime = curl_mime_init(curl);
-
-    /* add a part */
-    part = curl_mime_addpart(mime);
-
-    /* send image data from memory */
-    curl_mime_data(part, imagebuf, sizeof(imagebuf));
-
-    /* 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 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 "SEE ALSO"
-.BR curl_mime_addpart (3),
-.BR curl_mime_data (3),
-.BR curl_mime_filedata (3)

docs/libcurl/curl_mime_filename.md

@@ -0,0 +1,79 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_filename
+Section: 3
+Source: libcurl
+See-also:
+  - curl_mime_addpart (3)
+  - curl_mime_data (3)
+  - curl_mime_filedata (3)
+---
+
+# NAME
+
+curl_mime_filename - set a mime part's remote file name
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_mime_filename(curl_mimepart *part,
+                            const char *filename);
+~~~
+
+# DESCRIPTION
+
+curl_mime_filename(3) 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.
+
+*part* is the part's handle to assign the remote file name to.
+
+*filename* 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 multiple times is valid: only the value set by the last call is retained.
+
+# EXAMPLE
+
+~~~c
+
+static char imagebuf[]="imagedata";
+
+int main(void)
+{
+  curl_mime *mime;
+  curl_mimepart *part;
+
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    /* create a mime handle */
+    mime = curl_mime_init(curl);
+
+    /* add a part */
+    part = curl_mime_addpart(mime);
+
+    /* send image data from memory */
+    curl_mime_data(part, imagebuf, sizeof(imagebuf));
+
+    /* 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");
+  }
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# RETURN VALUE
+
+CURLE_OK or a CURL error code upon failure.

docs/libcurl/curl_mime_free.3

@@ -1,70 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_free 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_free - free a previously built mime structure
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-void curl_mime_free(curl_mime *mime);
-.fi
-.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 sub part 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 makes this function return immediately
-with no action.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    /* Build the mime message. */
-    curl_mime *mime = curl_mime_init(curl);
-
-    /* send off the transfer */
-
-    /* Free multipart message. */
-    curl_mime_free(mime);
-  }
-}
-.fi
-.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_free (3),
-.BR curl_mime_init (3)

docs/libcurl/curl_mime_free.md

@@ -0,0 +1,65 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_free
+Section: 3
+Source: libcurl
+See-also:
+  - curl_free (3)
+  - curl_mime_init (3)
+---
+
+# NAME
+
+curl_mime_free - free a previously built mime structure
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+void curl_mime_free(curl_mime *mime);
+~~~
+
+# DESCRIPTION
+
+curl_mime_free(3) is used to clean up data previously built/appended
+with curl_mime_addpart(3) and other mime-handling functions. This must
+be called when the data has been used, which typically means after
+curl_easy_perform(3) has been called.
+
+The handle to free is the one you passed to the CURLOPT_MIMEPOST(3)
+option: attached sub part mime structures must not be explicitly freed as they
+are by the top structure freeing.
+
+**mime** is the handle as returned from a previous call to
+curl_mime_init(3) and may be NULL.
+
+Passing in a NULL pointer in *mime* makes this function return immediately
+with no action.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    /* Build the mime message. */
+    curl_mime *mime = curl_mime_init(curl);
+
+    /* send off the transfer */
+
+    /* Free multipart message. */
+    curl_mime_free(mime);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# RETURN VALUE
+
+None

docs/libcurl/curl_mime_headers.3

@@ -1,83 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_headers 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_headers - set a mime part's custom headers
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_mime_headers(curl_mimepart *part,
-                           struct curl_slist *headers, int take_ownership);
-.fi
-.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 multiple times is valid: only the value
-set by the last call is retained.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  struct curl_slist *headers = NULL;
-  CURL *easy = curl_easy_init();
-  curl_mime *mime;
-  curl_mimepart *part;
-
-  headers = curl_slist_append(headers, "Custom-Header: mooo");
-
-  mime = curl_mime_init(easy);
-  part = curl_mime_addpart(mime);
-
-  /* use these headers in the part, takes ownership */
-  curl_mime_headers(part, headers, 1);
-
-  /* pass on this data */
-  curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED);
-
-  /* set name */
-  curl_mime_name(part, "numbers");
-
-  /* Post and send it. */
-  curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime);
-  curl_easy_setopt(easy, CURLOPT_URL, "https://example.com");
-  curl_easy_perform(easy);
-}
-.fi
-.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 "SEE ALSO"
-.BR curl_mime_addpart (3),
-.BR curl_mime_name (3)

docs/libcurl/curl_mime_headers.md

@@ -0,0 +1,78 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_headers
+Section: 3
+Source: libcurl
+See-also:
+  - curl_mime_addpart (3)
+  - curl_mime_name (3)
+---
+
+# NAME
+
+curl_mime_headers - set a mime part's custom headers
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_mime_headers(curl_mimepart *part,
+                           struct curl_slist *headers, int take_ownership);
+~~~
+
+# DESCRIPTION
+
+curl_mime_headers(3) sets a mime part's custom headers.
+
+*part* is the part's handle to assign the custom headers list to.
+
+*headers* is the head of a list of custom headers; it may be set to NULL
+to remove a previously attached custom header list.
+
+*take_ownership*: 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 multiple times is valid: only the value
+set by the last call is retained.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  struct curl_slist *headers = NULL;
+  CURL *easy = curl_easy_init();
+  curl_mime *mime;
+  curl_mimepart *part;
+
+  headers = curl_slist_append(headers, "Custom-Header: mooo");
+
+  mime = curl_mime_init(easy);
+  part = curl_mime_addpart(mime);
+
+  /* use these headers in the part, takes ownership */
+  curl_mime_headers(part, headers, 1);
+
+  /* pass on this data */
+  curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED);
+
+  /* set name */
+  curl_mime_name(part, "numbers");
+
+  /* Post and send it. */
+  curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime);
+  curl_easy_setopt(easy, CURLOPT_URL, "https://example.com");
+  curl_easy_perform(easy);
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# RETURN VALUE
+
+CURLE_OK or a CURL error code upon failure.

docs/libcurl/curl_mime_init.3

@@ -1,77 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_init 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_init - create a mime handle
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-curl_mime *curl_mime_init(CURL *easy_handle);
-.fi
-.SH DESCRIPTION
-\fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure.
-This mime structure can be subsequently filled using the mime API, then
-attached to some easy handle using option \fICURLOPT_MIMEPOST(3)\fP within
-a \fIcurl_easy_setopt(3)\fP call or added as a multipart in another mime
-handle's part using \fIcurl_mime_subparts(3)\fP.
-
-\fIeasy_handle\fP is used for part separator randomization and error
-reporting. Since 7.87.0, it does not need to be the final target handle.
-
-Using a mime handle is the recommended way to post an HTTP form, format and
-send a multi-part email with SMTP or upload such an email to an IMAP server.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  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);
-}
-.fi
-.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 "SEE ALSO"
-.BR curl_mime_addpart (3),
-.BR curl_mime_free (3),
-.BR curl_mime_subparts (3),
-.BR CURLOPT_MIMEPOST (3)

docs/libcurl/curl_mime_init.md

@@ -0,0 +1,72 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_init
+Section: 3
+Source: libcurl
+See-also:
+  - CURLOPT_MIMEPOST (3)
+  - curl_mime_addpart (3)
+  - curl_mime_free (3)
+  - curl_mime_subparts (3)
+---
+
+# NAME
+
+curl_mime_init - create a mime handle
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+curl_mime *curl_mime_init(CURL *easy_handle);
+~~~
+
+# DESCRIPTION
+
+curl_mime_init(3) creates a handle to a new empty mime structure.
+This mime structure can be subsequently filled using the mime API, then
+attached to some easy handle using option CURLOPT_MIMEPOST(3) within
+a curl_easy_setopt(3) call or added as a multipart in another mime
+handle's part using curl_mime_subparts(3).
+
+*easy_handle* is used for part separator randomization and error
+reporting. Since 7.87.0, it does not need to be the final target handle.
+
+Using a mime handle is the recommended way to post an HTTP form, format and
+send a multi-part email with SMTP or upload such an email to an IMAP server.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  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);
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# RETURN VALUE
+
+A mime struct handle, or NULL upon failure.

docs/libcurl/curl_mime_name.3

@@ -1,72 +0,0 @@
-.\" **************************************************************************
-.\" *                                  _   _ ____  _
-.\" *  Project                     ___| | | |  _ \| |
-.\" *                             / __| | | | |_) | |
-.\" *                            | (__| |_| |  _ <| |___
-.\" *                             \___|\___/|_| \_\_____|
-.\" *
-.\" * Copyright (C) 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.
-.\" *
-.\" * SPDX-License-Identifier: curl
-.\" *
-.\" **************************************************************************
-.TH curl_mime_name 3 "22 August 2017" "libcurl" "libcurl"
-.SH NAME
-curl_mime_name - set a mime part's name
-.SH SYNOPSIS
-.nf
-#include <curl/curl.h>
-
-CURLcode curl_mime_name(curl_mimepart *part, const char *name);
-.fi
-.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 multiple times
-is valid: only the value set by the last call is retained. It is possible to
-reset the name of a part by setting \fIname\fP to NULL.
-.SH EXAMPLE
-.nf
-int main(void)
-{
-  curl_mime *mime;
-  curl_mimepart *part;
-
-  CURL *curl = curl_easy_init();
-  if(curl) {
-    /* create a mime handle */
-    mime = curl_mime_init(curl);
-
-    /* add a part */
-    part = curl_mime_addpart(mime);
-
-    /* give the part a name */
-    curl_mime_name(part, "shoe_size");
-  }
-}
-.fi
-.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 "SEE ALSO"
-.BR curl_mime_addpart (3),
-.BR curl_mime_data (3),
-.BR curl_mime_type (3)

docs/libcurl/curl_mime_name.md

@@ -0,0 +1,67 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: curl_mime_name
+Section: 3
+Source: libcurl
+See-also:
+  - curl_mime_addpart (3)
+  - curl_mime_data (3)
+  - curl_mime_type (3)
+---
+
+# NAME
+
+curl_mime_name - set a mime part's name
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_mime_name(curl_mimepart *part, const char *name);
+~~~
+
+# DESCRIPTION
+
+curl_mime_name(3) sets a mime part's name. This is the way HTTP form
+fields are named.
+
+*part* is the part's handle to assign a name to.
+
+*name* 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 multiple times
+is valid: only the value set by the last call is retained. It is possible to
+reset the name of a part by setting *name* to NULL.
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  curl_mime *mime;
+  curl_mimepart *part;
+
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    /* create a mime handle */
+    mime = curl_mime_init(curl);
+
+    /* add a part */
+    part = curl_mime_addpart(mime);
+
+    /* give the part a name */
+    curl_mime_name(part, "shoe_size");
+  }
+}
+~~~
+
+# AVAILABILITY
+
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+
+# RETURN VALUE
+
+CURLE_OK or a CURL error code upon failure.