Unity-Technologies
/
curl
зеркало из https://github.com/Unity-Technologies/curl.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

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
This commit is contained in:
Daniel Stenberg 2024-01-17 11:32:44 +01:00
Родитель 02f91d5b64
Коммит eefcc1bda4
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 5CC908FDB71E12C2
960 изменённых файлов: 41083 добавлений и 39724 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

1
.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 $_;
}

15
.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
IPFS
IPNS
ipld
trustless
IPCXN
IPFS
ipld
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

10
.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;

3
.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

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

6
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

16
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

6
docs/.gitignore поставляемый
Просмотреть файл

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

2
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

125
docs/CURLDOWN.md Normal file
Просмотреть файл

@ -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)`.

2
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.

2
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

44
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 $< >$@
SUFFIXES = .1 .html .pdf
CD2 = $(CD2_$(V))
CD2_0 = @echo " RENDER " $@;
CD2_1 =
CD2_ = $(CD2_0)
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
.md.1:
$(CD2)$(CD2NROFF)
pdf: $(PDFPAGES)
cd libcurl && $(MAKE) pdf
.1.html:
$(MAN2HTML)
.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)

8
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

139
docs/curl-config.1 → docs/curl-config.md
Просмотреть файл

@ -1,105 +1,124 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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
---
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.
.SH OPTIONS
.IP "--ca"
# OPTIONS
## --ca
Displays the built-in path to the CA cert bundle this libcurl uses.
.IP "--cc"
## --cc
Displays the compiler used to build libcurl.
.IP "--cflags"
## --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]"
## --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"
## --configure
Displays the arguments given to configure when building curl.
.IP "--feature"
## --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"
## --help
Displays the available options.
.IP "--libs"
## --libs
Shows the complete set of libs and other linker options you will need in order
to link your application with libcurl.
.IP "--prefix"
## --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"
## --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"
## --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"
## --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"
## --version
Outputs version information about the installed libcurl.
.IP "--vernum"
## --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"
# 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)
~~~
$ `curl-config --cc --cflags` -o example source.c `curl-config --libs`
~~~

8
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

54
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
CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@
CD2 = $(CD2_$(V))
CD2_0 = @echo " RENDER " $@;
CD2_1 =
CD2_ = $(CD2_0)
libcurl-symbols.3: $(srcdir)/symbols-in-versions $(srcdir)/mksymbolsmanpage.pl
perl $(srcdir)/mksymbolsmanpage.pl < $(srcdir)/symbols-in-versions > $@
SUFFIXES = .3 .md
html: $(HTMLPAGES)
cd opts && $(MAKE) html
libcurl-symbols.md: $(srcdir)/symbols-in-versions $(srcdir)/mksymbolsmanpage.pl
$(CD2)perl $(srcdir)/mksymbolsmanpage.pl < $(srcdir)/symbols-in-versions > $@
.3.html:
$(MAN2HTML)
pdf: $(PDFPAGES)
cd opts && $(MAKE) pdf
.3.pdf:
@(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \
groff -Tps -man $< >$$foo.ps; \
ps2pdf $$foo.ps $@; \
rm $$foo.ps; \
echo "converted $< to $@")
# Make sure each option man page is referenced in the main man page
TESTS = check-easy check-multi
LOG_COMPILER = $(PERL)
# The test fails if the log file contains any text
AM_LOG_FLAGS = -p -e 'die "$$_" if ($$_);'
check-easy: $(srcdir)/curl_easy_setopt.3 $(srcdir)/opts/CURLOPT*.3
OPTS="$$(ls $(srcdir)/opts/CURLOPT*.3 | $(SED) -e 's,^.*/,,' -e 's,\.3$$,,')" && \
for opt in $$OPTS; do grep "^\.IP $$opt$$" $(srcdir)/curl_easy_setopt.3 >/dev/null || echo Missing $$opt; done > $@
check-multi: $(srcdir)/curl_multi_setopt.3 $(srcdir)/opts/CURLMOPT*.3
OPTS="$$(ls $(srcdir)/opts/CURLMOPT*.3 | $(SED) -e 's,^.*/,,' -e 's,\.3$$,,')" && \
for opt in $$OPTS; do grep "^\.IP $$opt$$" $(srcdir)/curl_multi_setopt.3 >/dev/null || echo Missing $$opt; done > $@
.md.3:
$(CD2)$(CD2NROFF)

82
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)

76
docs/libcurl/curl_easy_cleanup.md Normal file
Просмотреть файл

@ -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

78
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)

72
docs/libcurl/curl_easy_duphandle.md Normal file
Просмотреть файл

@ -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.

79
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)

75
docs/libcurl/curl_easy_escape.md Normal file
Просмотреть файл

@ -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.

336
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)

483
docs/libcurl/curl_easy_getinfo.md Normal file
Просмотреть файл

@ -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.

150
docs/libcurl/curl_easy_header.3 → docs/libcurl/curl_easy_header.md
Просмотреть файл

@ -1,31 +1,24 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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
---
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
.SH SYNOPSIS
.nf
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLHcode curl_easy_header(CURL *easy,
@ -34,24 +27,26 @@ CURLHcode curl_easy_header(CURL *easy,
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.
# DESCRIPTION
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.
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.
The \fIrequest\fP argument tells libcurl from which request you want headers
*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
@ -66,10 +61,10 @@ 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
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 \fIcurl_easy_cleanup(3)\fP of the easy handle.
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
@ -78,8 +73,10 @@ 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
# The header struct
~~~c
struct curl_header {
char *name;
char *value;
@ -88,45 +85,58 @@ struct curl_header {
unsigned int origin;
void *anchor;
};
.fi
~~~
The data \fBname\fP field points to, is the same as the requested name, but
The data **name** 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
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.
\fBamount\fP is how many headers using this name that exist, within the origin
**amount** 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
**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 \fBamount\fP.
than 0 but is always less than **amount**.
The \fBorigin\fP field in the "curl_header" struct has one of the origin bits
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.
\fBanchor\fP is a private handle used by libcurl internals. Do not modify.
.SH ORIGINS
.IP CURLH_HEADER
**anchor** is a private handle used by libcurl internals. Do not modify.
# ORIGINS
## CURLH_HEADER
The header arrived as a header from the server.
.IP CURLH_TRAILER
## CURLH_TRAILER
The header arrived as a trailer. A header that arrives after the body.
.IP CURLH_CONNECT
## 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
## 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
## CURLH_PSEUDO
The header is an HTTP/2 or HTTP/3 pseudo header
.SH EXAMPLE
.nf
# EXAMPLE
~~~c
int main(void)
{
struct curl_header *type;
@ -139,14 +149,12 @@ int main(void)
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
~~~
# AVAILABILITY
Added in 7.83.0. Officially supported since 7.84.0.
.SH RETURN VALUE
# 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)

82
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)

73
docs/libcurl/curl_easy_init.md Normal file
Просмотреть файл

@ -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.

106
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)

100
docs/libcurl/curl_easy_nextheader.md Normal file
Просмотреть файл

@ -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.

59
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)

54
docs/libcurl/curl_easy_option_by_id.md Normal file
Просмотреть файл

@ -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.

58
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)

53
docs/libcurl/curl_easy_option_by_name.md Normal file
Просмотреть файл

@ -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.

92
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)

89
docs/libcurl/curl_easy_option_next.md Normal file
Просмотреть файл

@ -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.

119
docs/libcurl/curl_easy_pause.3 → docs/libcurl/curl_easy_pause.md
Просмотреть файл

@ -1,84 +1,88 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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
---
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
.SH SYNOPSIS
.nf
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLcode curl_easy_pause(CURL *handle, int bitmask );
.fi
.SH DESCRIPTION
~~~
# 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
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
(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback
(*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 (\fICURLOPT_PROGRESSFUNCTION(3)\fP).
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
\fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP etc.
CURLOPT_MAX_RECV_SPEED_LARGE(3) etc.
The \fBhandle\fP argument identifies the transfer you want to pause or
The **handle** 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
CURLOPT_LOW_SPEED_LIMIT(3) 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
The **bitmask** argument is a set of bits that sets the new state of the
connection. The following bits can be used:
.IP CURLPAUSE_RECV
## 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
(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
(\fICURLOPT_READFUNCTION(3)\fP) is not called.
.IP CURLPAUSE_ALL
(CURLOPT_READFUNCTION(3)) is not called.
## CURLPAUSE_ALL
Convenience define that pauses both directions.
.IP CURLPAUSE_CONT
## CURLPAUSE_CONT
Convenience define that unpauses both directions.
.SH LIMITATIONS
# 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
# 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
@ -90,8 +94,10 @@ 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
# EXAMPLE
~~~c
int main(void)
{
CURL *curl = curl_easy_init();
@ -101,8 +107,10 @@ int main(void)
}
}
.fi
.SH "MEMORY USE"
~~~
# 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
@ -113,19 +121,20 @@ 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
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
# AVAILABILITY
Added in 7.18.0.
.SH RETURN VALUE
# 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)
libcurl-errors(3) man page for the full list with descriptions.

90
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)

83
docs/libcurl/curl_easy_perform.md Normal file
Просмотреть файл

@ -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.

109
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)

103
docs/libcurl/curl_easy_recv.md Normal file
Просмотреть файл

@ -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**.

61
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)

56
docs/libcurl/curl_easy_reset.md Normal file
Просмотреть файл

@ -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

101
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)

95
docs/libcurl/curl_easy_send.md Normal file
Просмотреть файл

@ -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**.

751
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)

1381
docs/libcurl/curl_easy_setopt.md Normal file
Просмотреть файл

Разница между файлами не показана из-за своего большого размера Загрузить разницу

64
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)

59
docs/libcurl/curl_easy_strerror.md Normal file
Просмотреть файл

@ -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.

79
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)

73
docs/libcurl/curl_easy_unescape.md Normal file
Просмотреть файл

@ -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.

84
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), "

77
docs/libcurl/curl_easy_upkeep.md Normal file
Просмотреть файл

@ -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.

63
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)

58
docs/libcurl/curl_escape.md Normal file
Просмотреть файл

@ -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.

244
docs/libcurl/curl_formadd.3 → docs/libcurl/curl_formadd.md
Просмотреть файл

@ -1,55 +1,48 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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
---
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
.SH SYNOPSIS
.nf
# SYNOPSIS
~~~c
#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.
~~~
# 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 \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.
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 \fIlastitem\fP pointer follow the real arguments.
After the *lastitem* pointer follow the real arguments.
The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
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 \fIcurl_formfree(3)\fP on the \fIfirstitem\fP
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 \fICURLOPT_HTTPHEADER(3)\fP as usual.
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
@ -58,123 +51,158 @@ 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
*CURLFORM_FILE* through *CURLFORM_BUFFERLENGTH* are for file upload
parts.
.SH OPTIONS
.IP CURLFORM_COPYNAME
followed by a string which provides the \fIname\fP of this part. libcurl
# 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 \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
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 \fBCURLFORM_CONTENTSLENGTH\fP. The copied data is freed by
\fIcurl_formfree(3)\fP.
.IP CURLFORM_PTRCONTENTS
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
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
set its length with **CURLFORM_CONTENTSLENGTH**.
## 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.
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)
.IP CURLFORM_CONTENTSLENGTH
(This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!)
## CURLFORM_CONTENTSLENGTH
(This option is deprecated. Use *CURLFORM_CONTENTLEN* instead!)
followed by a long giving the length of the contents. Note that for
\fICURLFORM_STREAM\fP contents, this option is mandatory.
*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.
.IP CURLFORM_FILECONTENT
## 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
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.
.IP CURLFORM_FILE
## 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
*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
\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).
**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.
.IP CURLFORM_CONTENTTYPE
is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
## 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.
.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
## 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.
.IP CURLFORM_BUFFER
is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
## 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 \fIfilename\fP field in the content
parameter is a string which provides the *filename* field in the content
header.
.IP CURLFORM_BUFFERPTR
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
## 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
\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
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.
.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
## 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 \fICURLFORM_FILENAME\fP parameter as well. Note that
when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
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)
.IP CURLFORM_ARRAY
## 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
**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 \fBCURLFORM_END\fP.
.IP CURLFORM_CONTENTHEADER
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 \fBcurl_slist_append\fP and appends the list
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 \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
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.
.SH EXAMPLE
.nf
# EXAMPLE
~~~c
#include <string.h> /* for strlen */
static const char record[]="data in a buffer";
@ -196,7 +224,7 @@ int main(void)
/* add null character into htmlbuffer, to demonstrate that
transfers of buffers containing null characters actually work
*/
htmlbuffer[8] = '\\0';
htmlbuffer[8] = '\0';
/* Add simple name/content section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
@ -267,19 +295,19 @@ int main(void)
curl_formfree(post);
}
}
.fi
.SH AVAILABILITY
~~~
# 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
# 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)
*<curl/curl.h>*

81
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)

76
docs/libcurl/curl_formfree.md Normal file
Просмотреть файл

@ -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

77
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)

72
docs/libcurl/curl_formget.md Normal file
Просмотреть файл

@ -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

57
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)

52
docs/libcurl/curl_free.md Normal file
Просмотреть файл

@ -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

108
docs/libcurl/curl_getdate.3 → docs/libcurl/curl_getdate.md
Просмотреть файл

@ -1,70 +1,77 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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
---
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
.SH SYNOPSIS
.nf
# SYNOPSIS
~~~c
#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
~~~
# 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
\fIdatestring\fP parameter specifies. The \fInow\fP parameter is not used,
*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.
.SH PARSING DATES AND TIMES
# 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"
## 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"
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.
.IP "time zone items"
## 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"
## 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"
## 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
# EXAMPLE
~~~c
int main(void)
{
time_t t;
@ -91,16 +98,22 @@ int main(void)
t = curl_getdate("20040912 15:05:58 -0700", NULL);
t = curl_getdate("20040911 +0200", NULL);
}
.fi
.SH STANDARDS
~~~
# 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.
RFC 1036) and ANSI C's *asctime()* format.
These formats are the only ones RFC 7231 says HTTP applications may use.
.SH AVAILABILITY
# AVAILABILITY
Always
.SH RETURN VALUE
# RETURN VALUE
This function returns -1 when it fails to parse the date string. Otherwise it
returns the number of seconds as described.
@ -113,8 +126,3 @@ 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)

60
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)

57
docs/libcurl/curl_getenv.md Normal file
Просмотреть файл

@ -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.

77
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)

74
docs/libcurl/curl_global_cleanup.md Normal file
Просмотреть файл

@ -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

117
docs/libcurl/curl_global_init.3 → docs/libcurl/curl_global_init.md
Просмотреть файл

@ -1,36 +1,32 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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
---
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
.SH SYNOPSIS
.nf
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLcode curl_global_init(long flags);
.fi
.SH DESCRIPTION
~~~
# DESCRIPTION
This function sets up the program environment that libcurl needs. Think of it
as an extension of the library loader.
@ -47,28 +43,32 @@ 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
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
\fIcurl_global_init(3)\fP calls functions of other libraries that are
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 \fIDllMain\fP or a static initializer because Windows holds the loader
it from *DllMain* or a static initializer because Windows holds the loader
lock during that time and it could cause a deadlock.
See the description in \fIlibcurl(3)\fP of global environment requirements for
See the description in libcurl(3) 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
# 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.)
@ -81,26 +81,36 @@ backend libcurl uses.
Doing TLS based transfers without having the TLS layer initialized may lead to
unexpected behaviors.
.IP CURL_GLOBAL_WIN32
## 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
## CURL_GLOBAL_NOTHING
Initialize nothing extra. This sets no bit.
.IP CURL_GLOBAL_DEFAULT
## 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
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)
.SH EXAMPLE
.nf
# EXAMPLE
~~~c
int main(void)
{
curl_global_init(CURL_GLOBAL_DEFAULT);
@ -109,16 +119,13 @@ int main(void)
curl_global_cleanup();
}
.fi
.SH AVAILABILITY
~~~
# AVAILABILITY
Added in 7.8
.SH RETURN VALUE
# 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)

88
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)

95
docs/libcurl/curl_global_init_mem.md Normal file
Просмотреть файл

@ -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).

139
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)

138
docs/libcurl/curl_global_sslset.md Normal file
Просмотреть файл

@ -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*.

107
docs/libcurl/curl_global_trace.3 → docs/libcurl/curl_global_trace.md
Просмотреть файл

@ -1,36 +1,28 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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
---
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
.SH SYNOPSIS
.nf
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLcode curl_global_trace(const char *config);
.fi
.SH DESCRIPTION
~~~
# DESCRIPTION
This function configures the logging behavior, allowing to make some
parts of curl more verbose or silent than others.
@ -42,21 +34,21 @@ 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
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
\fIcurl_global_init(3)\fP may call functions of other libraries that are
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 \fIDllMain\fP or a static initializer because Windows holds the loader
it from *DllMain* 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
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.
@ -68,19 +60,29 @@ 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
is enabled. See CURLOPT_VERBOSE(3) or CURLOPT_DEBUGFUNCTION(3)
on how to control that.
.SH TRACE COMPONENTS
.IP tcp
# TRACE COMPONENTS
## tcp
Tracing of TCP socket handling: connect, reads, writes.
.IP ssl
## ssl
Tracing of SSL/TLS operations, whichever SSL backend is used in your build.
.IP http/2
## http/2
Details about HTTP/2 handling: frames, events, I/O, etc.
.IP http/3
## http/3
Details about HTTP/3 handling: connect, frames, events, I/O etc.
.IP http-proxy
## 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.
@ -89,8 +91,9 @@ 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
# EXAMPLE
~~~c
int main(void)
{
/* log details of HTTP/2 and SSL handling */
@ -99,23 +102,23 @@ int main(void)
/* 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
...
~~~
# AVAILABILITY
.SH AVAILABILITY
Added in 8.3
.SH RETURN VALUE
# 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)

75
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)

70
docs/libcurl/curl_mime_addpart.md Normal file
Просмотреть файл

@ -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.

81
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)

76
docs/libcurl/curl_mime_data.md Normal file
Просмотреть файл

@ -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.

109
docs/libcurl/curl_mime_data_cb.3 → docs/libcurl/curl_mime_data_cb.md
Просмотреть файл

@ -1,31 +1,23 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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
---
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
.SH SYNOPSIS
.nf
# SYNOPSIS
~~~c
#include <curl/curl.h>
size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
@ -38,32 +30,34 @@ 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
~~~
# DESCRIPTION
curl_mime_data_cb(3) 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.
*part* is the part's to assign contents to.
\fIreadfunc\fP is a pointer to a data read callback function, with a signature
*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.
\fIseekfunc\fP is a pointer to a seek callback function, with a signature as
*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.
\fIfreefunc\fP is a pointer to a user resource freeing callback function, with
*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.
\fIarg\fP is a user defined argument to callback functions.
*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 \fIbuffer\fP
should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number
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
@ -75,35 +69,37 @@ 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
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 \fICURL_READFUNC_PAUSE\fP to cause reading from this
connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
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 \fIorigin\fP,
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 \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
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 \fIarg\fP pointer argument is also duplicated, resulting in
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 \fIfreefunc\fP procedure
particular, special attention should be given to the *freefunc* procedure
code since it then gets called twice with the same argument.
.SH EXAMPLE
# 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
~~~c
#include <string.h> /* for memcpy */
char hugedata[512000];
@ -161,13 +157,12 @@ int main(void)
&hugectl);
}
}
.fi
.SH AVAILABILITY
~~~
# AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
# 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)

105
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)

100
docs/libcurl/curl_mime_encoder.md Normal file
Просмотреть файл

@ -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.

93
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)

88
docs/libcurl/curl_mime_filedata.md Normal file
Просмотреть файл

@ -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.

84
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)

79
docs/libcurl/curl_mime_filename.md Normal file
Просмотреть файл

@ -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.

70
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)

65
docs/libcurl/curl_mime_free.md Normal file
Просмотреть файл

@ -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

83
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)

78
docs/libcurl/curl_mime_headers.md Normal file
Просмотреть файл

@ -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.

77
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)

72
docs/libcurl/curl_mime_init.md Normal file
Просмотреть файл

@ -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.

72
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)

67
docs/libcurl/curl_mime_name.md Normal file
Просмотреть файл

@ -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.

88
docs/libcurl/curl_mime_subparts.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_mime_subparts 3 "22 August 2017" "libcurl" "libcurl"
.SH NAME
curl_mime_subparts - set sub-parts of a multipart mime part
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_subparts(curl_mimepart *part, curl_mime *subparts);
.fi
.SH DESCRIPTION
\fIcurl_mime_subparts(3)\fP sets a multipart mime part's content from a mime
structure.
\fIpart\fP is a handle to the multipart part.
\fIsubparts\fP is a mime structure handle holding the sub-parts. After
\fIcurl_mime_subparts(3)\fP succeeds, the mime structure handle belongs to the
multipart part and must not be freed explicitly. It may however be updated by
subsequent calls to mime API functions.
Setting a part's contents multiple times is valid: only the value set by the
last call is retained. It is possible to unassign previous part's contents by
setting \fIsubparts\fP to NULL.
.SH EXAMPLE
.nf
static char *inline_html = "<title>example</title>";
static char *inline_text = "once upon the time";
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
struct curl_slist *slist;
/* The inline part is an alternative proposing the html and the text
versions of the email. */
curl_mime *alt = curl_mime_init(curl);
curl_mimepart *part;
/* HTML message. */
part = curl_mime_addpart(alt);
curl_mime_data(part, inline_html, CURL_ZERO_TERMINATED);
curl_mime_type(part, "text/html");
/* Text message. */
part = curl_mime_addpart(alt);
curl_mime_data(part, inline_text, CURL_ZERO_TERMINATED);
/* Create the inline part. */
part = curl_mime_addpart(alt);
curl_mime_subparts(part, alt);
curl_mime_type(part, "multipart/alternative");
slist = curl_slist_append(NULL, "Content-Disposition: inline");
curl_mime_headers(part, slist, 1);
}
}
.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_init (3)

83
docs/libcurl/curl_mime_subparts.md Normal file
Просмотреть файл

@ -0,0 +1,83 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_mime_subparts
Section: 3
Source: libcurl
See-also:
- curl_mime_addpart (3)
- curl_mime_init (3)
---
# NAME
curl_mime_subparts - set sub-parts of a multipart mime part
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLcode curl_mime_subparts(curl_mimepart *part, curl_mime *subparts);
~~~
# DESCRIPTION
curl_mime_subparts(3) sets a multipart mime part's content from a mime
structure.
*part* is a handle to the multipart part.
*subparts* is a mime structure handle holding the sub-parts. After
curl_mime_subparts(3) succeeds, the mime structure handle belongs to the
multipart part and must not be freed explicitly. It may however be updated by
subsequent calls to mime API functions.
Setting a part's contents multiple times is valid: only the value set by the
last call is retained. It is possible to unassign previous part's contents by
setting *subparts* to NULL.
# EXAMPLE
~~~c
static char *inline_html = "<title>example</title>";
static char *inline_text = "once upon the time";
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
struct curl_slist *slist;
/* The inline part is an alternative proposing the html and the text
versions of the email. */
curl_mime *alt = curl_mime_init(curl);
curl_mimepart *part;
/* HTML message. */
part = curl_mime_addpart(alt);
curl_mime_data(part, inline_html, CURL_ZERO_TERMINATED);
curl_mime_type(part, "text/html");
/* Text message. */
part = curl_mime_addpart(alt);
curl_mime_data(part, inline_text, CURL_ZERO_TERMINATED);
/* Create the inline part. */
part = curl_mime_addpart(alt);
curl_mime_subparts(part, alt);
curl_mime_type(part, "multipart/alternative");
slist = curl_slist_append(NULL, "Content-Disposition: inline");
curl_mime_headers(part, slist, 1);
}
}
~~~
# 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.

91
docs/libcurl/curl_mime_type.3
Просмотреть файл

@ -1,91 +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_type 3 "22 August 2017" "libcurl" "libcurl"
.SH NAME
curl_mime_type - set a mime part's content type
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_type(curl_mimepart *part, const char *mimetype);
.fi
.SH DESCRIPTION
\fIcurl_mime_type(3)\fP sets a mime part's content type.
\fIpart\fP is the part's handle to assign the content type to.
\fImimetype\fP points to the null-terminated file mime type string; it may be
set to NULL to remove a previously attached mime type.
The mime type string is copied into the part, thus the associated storage may
safely be released or reused after call. Setting a part's type multiple times
is valid: only the value set by the last call is retained.
In the absence of a mime type and if needed by the protocol specifications,
a default mime type is determined by the context:
- If set as a custom header, use this value.
- application/form-data for an HTTP form post.
- If a remote file name is set, the mime type is taken from the file name
extension, or application/octet-stream by default.
- For a multipart part, multipart/mixed.
- text/plain in other cases.
.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);
/* get data from this file */
curl_mime_filedata(part, "image.png");
/* content-type for this part */
curl_mime_type(part, "image/png");
/* set name */
curl_mime_name(part, "image");
}
}
.fi
.SH 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_name (3)

86
docs/libcurl/curl_mime_type.md Normal file
Просмотреть файл

@ -0,0 +1,86 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_mime_type
Section: 3
Source: libcurl
See-also:
- curl_mime_addpart (3)
- curl_mime_data (3)
- curl_mime_name (3)
---
# NAME
curl_mime_type - set a mime part's content type
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLcode curl_mime_type(curl_mimepart *part, const char *mimetype);
~~~
# DESCRIPTION
curl_mime_type(3) sets a mime part's content type.
*part* is the part's handle to assign the content type to.
*mimetype* points to the null-terminated file mime type string; it may be
set to NULL to remove a previously attached mime type.
The mime type string is copied into the part, thus the associated storage may
safely be released or reused after call. Setting a part's type multiple times
is valid: only the value set by the last call is retained.
In the absence of a mime type and if needed by the protocol specifications,
a default mime type is determined by the context:
- If set as a custom header, use this value.
- application/form-data for an HTTP form post.
- If a remote file name is set, the mime type is taken from the file name
extension, or application/octet-stream by default.
- For a multipart part, multipart/mixed.
- text/plain in other cases.
# 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);
/* get data from this file */
curl_mime_filedata(part, "image.png");
/* content-type for this part */
curl_mime_type(part, "image/png");
/* set name */
curl_mime_name(part, "image");
}
}
~~~
# 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.

287
docs/libcurl/curl_mprintf.3 → docs/libcurl/curl_mprintf.md
Просмотреть файл

@ -1,33 +1,25 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * 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_printf 3 "30 April 2004" "libcurl" "libcurl"
.SH NAME
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_printf
Section: 3
Source: libcurl
See-also:
- fprintf (3)
- printf (3)
- sprintf (3)
- vprintf (3)
---
# NAME
curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf
curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf,
curl_mvsprintf - formatted output conversion
.SH SYNOPSIS
.nf
# SYNOPSIS
~~~c
#include <curl/mprintf.h>
int curl_mprintf(const char *format, ...);
@ -41,8 +33,10 @@ int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format,
va_list args);
char *curl_maprintf(const char *format , ...);
char *curl_mvaprintf(const char *format, va_list args);
.fi
.SH DESCRIPTION
~~~
# DESCRIPTION
These functions produce output according to the format string and given
arguments. They are mostly clones of the well-known C-style functions but
there are slight differences in behavior.
@ -50,41 +44,43 @@ there are slight differences in behavior.
We discourage users from using any of these functions in new applications.
Functions in the curl_mprintf() family produce output according to a format as
described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP
write output to stdout, the standard output stream; \fBcurl_mfprintf()\fP and
\fBcurl_mvfprintf()\fP write output to the given output stream;
\fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, \fBcurl_mvsprintf()\fP, and
\fBcurl_mvsnprintf()\fP write to the character string \fBbuffer\fP.
described below. The functions **curl_mprintf()** and **curl_mvprintf()**
write output to stdout, the standard output stream; **curl_mfprintf()** and
**curl_mvfprintf()** write output to the given output stream;
**curl_msprintf()**, **curl_msnprintf()**, **curl_mvsprintf()**, and
**curl_mvsnprintf()** write to the character string **buffer**.
The functions \fBcurl_msnprintf()\fP and \fBcurl_mvsnprintf()\fP write at most
\fImaxlength\fP bytes (including the terminating null byte ('\\0')) to
\fIbuffer\fP.
The functions **curl_msnprintf()** and **curl_mvsnprintf()** write at most
*maxlength* bytes (including the terminating null byte ('0')) to
*buffer*.
The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP,
\fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the
functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP,
\fBcurl_msnprintf()\fP, respectively, except that they are called with a
\fIva_list\fP instead of a variable number of arguments. These functions do
not call the \fIva_end\fP macro. Because they invoke the \fIva_arg\fP macro,
the value of \fIap\fP is undefined after the call.
The functions **curl_mvprintf()**, **curl_mvfprintf()**,
**curl_mvsprintf()**, **curl_mvsnprintf()** are equivalent to the
functions **curl_mprintf()**, **curl_mfprintf()**, **curl_msprintf()**,
**curl_msnprintf()**, respectively, except that they are called with a
*va_list* instead of a variable number of arguments. These functions do
not call the *va_end* macro. Because they invoke the *va_arg* macro,
the value of *ap* is undefined after the call.
The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the
The functions **curl_maprintf()** and **curl_mvaprintf()** return the
output string as pointer to a newly allocated memory area. The returned string
must be \fIcurl_free(3)\fPed by the receiver.
must be curl_free(3)ed by the receiver.
All of these functions write the output under the control of a format string
that specifies how subsequent arguments are converted for output.
.SH FORMAT STRING
# FORMAT STRING
The format string is composed of zero or more directives: ordinary characters
(not %), which are copied unchanged to the output stream; and conversion
specifications, each of which results in fetching zero or more subsequent
arguments. Each conversion specification is introduced by the character %, and
ends with a conversion specifier. In between there may be (in this order) zero
or more \fIflags\fP, an optional minimum \fIfield width\fP, an optional
\fIprecision\fP and an optional \fIlength modifier\fP.
or more *flags*, an optional minimum *field width*, an optional
*precision* and an optional *length modifier*.
# The $ modifier
.SH "The $ modifier"
The arguments must correspond properly with the conversion specifier. By
default, the arguments are used in the order given, where each '*' (see Field
width and Precision below) and each conversion specifier asks for the next
@ -93,13 +89,13 @@ can also specify explicitly which argument is taken, at each place where an
argument is required, by writing "%m$" instead of '%' and "*m$" instead
of '*', where the decimal integer m denotes the position in the argument list
of the desired argument, indexed starting from 1. Thus,
.nf
~~~c
curl_mprintf("%*d", width, num);
.fi
~~~
and
.nf
~~~c
curl_mprintf("%2$*1$d", width, num);
.fi
~~~
are equivalent. The second style allows repeated references to the same
argument.
@ -110,130 +106,183 @@ the numbers of arguments specified using '$'; for example, if arguments 1 and
3 are specified, argument 2 must also be specified somewhere in the format
string.
.SH "Flag characters"
# Flag characters
The character % is followed by zero or more of the following flags:
.IP #
## #
The value should be converted to its "alternate form".
.IP 0
## 0
The value should be zero padded.
.IP -
The converted value is to be left adjusted on the field boundary. (The
default is right justification.) The converted value is padded on the right
with blanks, rather than on the left with blanks or zeros. A '-' overrides a
\&'0' if both are given.
.IP ' '
(a space) A blank should be left before a positive number (or empty string)
produced by a signed conversion.
.IP +
## -
The converted value is to be left adjusted on the field boundary. (The default
is right justification.) The converted value is padded on the right with
blanks, rather than on the left with blanks or zeros. A '-' overrides a &'0'
if both are given.
## (space)
(a space: ' ') A blank should be left before a positive number (or empty
string) produced by a signed conversion.
## +
A sign (+ or -) should always be placed before a number produced by a signed
conversion. By default, a sign is used only for negative numbers. A '+'
overrides a space if both are used.
.SH "Field width"
# Field width
An optional decimal digit string (with nonzero first digit) specifying a
minimum field width. If the converted value has fewer characters than the
field width, it gets padded with spaces on the left (or right, if the
left-adjustment flag has been given). Instead of a decimal digit string one
may write "*" or "*m$" (for some decimal integer m) to specify that the field
width is given in the next argument, or in the \fIm-th\fP argument,
width is given in the next argument, or in the *m-th* argument,
respectively, which must be of type int. A negative field width is taken as
a '-' flag followed by a positive field width. In no case does a nonexistent
or small field width cause truncation of a field; if the result of a
conversion is wider than the field width, the field is expanded to contain the
conversion result.
.SH "Precision"
# Precision
An optional precision in the form of a period ('.') followed by an optional
decimal digit string. Instead of a decimal digit string one may write "*" or
"*m$" (for some decimal integer m) to specify that the precision is given in
the next argument, or in the \fIm-th\fP argument, respectively, which must be of
the next argument, or in the *m-th* argument, respectively, which must be of
type int. If the precision is given as just '.', the precision is taken to be
zero. A negative precision is taken as if the precision were omitted. This
gives the minimum number of digits to appear for \fBd\fP, \fBi\fP, \fBo\fP,
\fBu\fP, \fBx\fP, and \fBX\fP conversions, the number of digits to appear
after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and
\fBF\fP conversions, the maximum number of significant digits for \fBg\fP and
\fBG\fP conversions, or the maximum number of characters to be printed from a
string for \fBs\fP and \fBS\fP conversions.
.SH "Length modifier"
.IP h
A following integer conversion corresponds to a \fIshort\fP or \fIunsigned
short\fP argument.
.IP l
(ell) A following integer conversion corresponds to a \fIlong\fP or
\fIunsigned long\fP argument, or a following n conversion corresponds to a
gives the minimum number of digits to appear for **d**, **i**, **o**,
**u**, **x**, and **X** conversions, the number of digits to appear
after the radix character for **a**, **A**, **e**, **E**, **f**, and
**F** conversions, the maximum number of significant digits for **g** and
**G** conversions, or the maximum number of characters to be printed from a
string for **s** and **S** conversions.
# Length modifier
## h
A following integer conversion corresponds to a *short* or *unsigned short*
argument.
## l
(ell) A following integer conversion corresponds to a *long* or
*unsigned long* argument, or a following n conversion corresponds to a
pointer to a long argument
.IP ll
(ell-ell). A following integer conversion corresponds to a \fIlong long\fP or
\fIunsigned long long\fP argument, or a following n conversion corresponds to
## ll
(ell-ell). A following integer conversion corresponds to a *long long* or
*unsigned long long* argument, or a following n conversion corresponds to
a pointer to a long long argument.
.IP q
A synonym for \fBll\fP.
.IP L
## q
A synonym for **ll**.
## L
A following a, A, e, E, f, F, g, or G conversion corresponds to a long double
argument.
.IP z
A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP
## z
A following integer conversion corresponds to a *size_t* or *ssize_t*
argument.
.SH "Conversion specifiers"
# Conversion specifiers
A character that specifies the type of conversion to be applied. The
conversion specifiers and their meanings are:
.IP "d, i"
## d, i
The int argument is converted to signed decimal notation. The precision, if
any, gives the minimum number of digits that must appear; if the converted
value requires fewer digits, it is padded on the left with zeros. The default
precision is 1. When 0 is printed with an explicit precision 0, the output is
empty.
.IP "o, u, x, X"
## o, u, x, X
The unsigned int argument is converted to unsigned octal (o), unsigned decimal
(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters
\fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are
used for \fBX\fP conversions. The precision, if any, gives the minimum number
(u), or unsigned hexadecimal (**x** and **X**) notation. The letters
*abcdef* are used for **x** conversions; the letters *ABCDEF* are
used for **X** conversions. The precision, if any, gives the minimum number
of digits that must appear; if the converted value requires fewer digits, it
is padded on the left with zeros. The default precision is 1. When 0 is
printed with an explicit precision 0, the output is empty.
.IP "e, E"
The double argument is rounded and output in the style \fB"[-]d.ddde±dd"\fP
.IP "f, F"
## e, E
The double argument is rounded and output in the style **"[-]d.ddde±dd"**
## f, F
The double argument is rounded and output to decimal notation in the style
\fB"[-]ddd.ddd"\fP.
.IP "g, G"
**"[-]ddd.ddd"**.
## g, G
The double argument is converted in style f or e.
.IP "c"
## c
The int argument is converted to an unsigned char, and the resulting character
is written.
.IP "s"
The \fIconst char *\fP argument is expected to be a pointer to an array of
## s
The *const char ** argument is expected to be a pointer to an array of
character type (pointer to a string). Characters from the array are written up
to (but not including) a terminating null byte. If a precision is specified,
no more than the number specified are written. If a precision is given, no
null byte need be present; if the precision is not specified, or is greater
than the size of the array, the array must contain a terminating null byte.
.IP "p"
The \fIvoid *\fP pointer argument is printed in hexadecimal.
.IP "n"
## p
The *void ** pointer argument is printed in hexadecimal.
## n
The number of characters written so far is stored into the integer pointed to
by the corresponding argument.
.IP "%"
## %
A '%' symbol is written. No argument is converted.
.SH EXAMPLE
.nf
# EXAMPLE
~~~c
const char *name = "John";
int main(void)
{
curl_mprintf("My name is %s\\n", name);
curl_mprintf("Pi is almost %f\\n", (double)25.0/8);
curl_mprintf("My name is %s\n", name);
curl_mprintf("Pi is almost %f\n", (double)25.0/8);
}
.fi
.SH AVAILABILITY
~~~
# AVAILABILITY
These functions might be removed from the public libcurl API in the future. Do
not use them in new programs or projects.
.SH RETURN VALUE
The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to
# RETURN VALUE
The **curl_maprintf** and **curl_mvaprintf** functions return a pointer to
a newly allocated string, or NULL if it failed.
All other functions return the number of characters actually printed
(excluding the null byte used to end output to strings). Note that this
sometimes differ from how the POSIX versions of these functions work.
.SH "SEE ALSO"
.BR printf "(3), " sprintf "(3), " fprintf "(3), " vprintf "(3) "

93
docs/libcurl/curl_multi_add_handle.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_multi_add_handle 3 "4 March 2002" "libcurl" "libcurl"
.SH NAME
curl_multi_add_handle - add an easy handle to a multi session
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle);
.fi
.SH DESCRIPTION
Adds the \fIeasy handle\fP to the \fImulti_handle\fP.
While an easy handle is added to a multi stack, you cannot and you must not
use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy
handle from the multi stack again, it is perfectly fine to use it with the
easy interface again.
If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) cache,
it is made to use a DNS cache that is shared between all easy handles within
the multi handle when \fIcurl_multi_add_handle(3)\fP is called.
When an easy interface is added to a multi handle, it is set to use a shared
connection cache owned by the multi handle. Removing and adding new easy
handles does not affect the pool of connections or the ability to do
connection reuse.
If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (as you
should if you are working event-based with \fIcurl_multi_socket_action(3)\fP
and friends), that callback is called from within this function to ask for an
updated timer so that your main event loop gets the activity on this handle to
get started.
The easy handle remains added to the multi handle until you remove it again
with \fIcurl_multi_remove_handle(3)\fP - even when a transfer with that
specific easy handle is completed.
You should remove the easy handle from the multi stack before you terminate
first the easy handle and then the multi handle:
1 - \fIcurl_multi_remove_handle(3)\fP
2 - \fIcurl_easy_cleanup(3)\fP
3 - \fIcurl_multi_cleanup(3)\fP
.SH EXAMPLE
.nf
int main(void)
{
/* init a multi stack */
CURLM *multi = curl_multi_init();
/* create two easy handles */
CURL *http_handle = curl_easy_init();
CURL *http_handle2 = curl_easy_init();
/* add individual transfers */
curl_multi_add_handle(multi, http_handle);
curl_multi_add_handle(multi, http_handle2);
}
.fi
.SH AVAILABILITY
Added in 7.9.6
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code.
.SH "SEE ALSO"
.BR curl_multi_cleanup (3),
.BR curl_multi_get_handles (3),
.BR curl_multi_init (3),
.BR curl_multi_setopt (3),
.BR curl_multi_socket_action (3)

88
docs/libcurl/curl_multi_add_handle.md Normal file
Просмотреть файл

@ -0,0 +1,88 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_add_handle
Section: 3
Source: libcurl
See-also:
- curl_multi_cleanup (3)
- curl_multi_get_handles (3)
- curl_multi_init (3)
- curl_multi_setopt (3)
- curl_multi_socket_action (3)
---
# NAME
curl_multi_add_handle - add an easy handle to a multi session
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle);
~~~
# DESCRIPTION
Adds the *easy handle* to the *multi_handle*.
While an easy handle is added to a multi stack, you cannot and you must not
use curl_easy_perform(3) on that handle. After having removed the easy
handle from the multi stack again, it is perfectly fine to use it with the
easy interface again.
If the easy handle is not set to use a shared (CURLOPT_SHARE(3)) cache,
it is made to use a DNS cache that is shared between all easy handles within
the multi handle when curl_multi_add_handle(3) is called.
When an easy interface is added to a multi handle, it is set to use a shared
connection cache owned by the multi handle. Removing and adding new easy
handles does not affect the pool of connections or the ability to do
connection reuse.
If you have CURLMOPT_TIMERFUNCTION(3) set in the multi handle (as you
should if you are working event-based with curl_multi_socket_action(3)
and friends), that callback is called from within this function to ask for an
updated timer so that your main event loop gets the activity on this handle to
get started.
The easy handle remains added to the multi handle until you remove it again
with curl_multi_remove_handle(3) - even when a transfer with that
specific easy handle is completed.
You should remove the easy handle from the multi stack before you terminate
first the easy handle and then the multi handle:
1 - curl_multi_remove_handle(3)
2 - curl_easy_cleanup(3)
3 - curl_multi_cleanup(3)
# EXAMPLE
~~~c
int main(void)
{
/* init a multi stack */
CURLM *multi = curl_multi_init();
/* create two easy handles */
CURL *http_handle = curl_easy_init();
CURL *http_handle2 = curl_easy_init();
/* add individual transfers */
curl_multi_add_handle(multi, http_handle);
curl_multi_add_handle(multi, http_handle2);
}
~~~
# AVAILABILITY
Added in 7.9.6
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code.

84
docs/libcurl/curl_multi_assign.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_multi_assign 3 "9 Jul 2006" "libcurl" "libcurl"
.SH NAME
curl_multi_assign \- set data to associate with an internal socket
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,
void *sockptr);
.fi
.SH DESCRIPTION
This function creates an association in the multi handle between the given
socket and a private pointer of the application. This is designed for
\fIcurl_multi_socket_action(3)\fP uses.
When set, the \fIsockptr\fP pointer is passed to all future socket callbacks
for the specific \fIsockfd\fP socket.
If the given \fIsockfd\fP is not already in use by libcurl, this function
returns an error.
libcurl only keeps one single pointer associated with a socket, so calling
this function several times for the same socket makes the last set pointer get
used.
The idea here being that this association (socket to private pointer) is
something that just about every application that uses this API needs and then
libcurl can just as well do it since it already has the necessary
functionality.
It is acceptable to call this function from your multi callback functions.
.SH EXAMPLE
.nf
int main(void)
{
CURLM *multi = curl_multi_init();
void *ourstructp; /* pointer to our data */
curl_socket_t fd; /* file descriptor to associate our data with */
/* make our struct pointer associated with socket fd */
CURLMcode mc = curl_multi_assign(multi, fd, ourstructp);
if(mc)
printf("error: %s\\n", curl_multi_strerror(mc));
}
.fi
.SH AVAILABILITY
Added in 7.15.5
.SH RETURN VALUE
The standard CURLMcode for multi interface error codes.
.SH TYPICAL USAGE
In a typical application you allocate a struct or at least use some kind of
semi-dynamic data for each socket that we must wait for action on when using
the \fIcurl_multi_socket_action(3)\fP approach.
When our socket-callback gets called by libcurl and we get to know about yet
another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out
the particular data so that when we get updates about this same socket again,
we do not have to find the struct associated with this socket by ourselves.
.SH "SEE ALSO"
.BR curl_multi_setopt (3),
.BR curl_multi_socket_action (3)

Некоторые файлы не были показаны из-за слишком большого количества измененных файлов Показать больше