Rim/iw3sp-mod
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

[Global]: loading init

Browse Source
This commit is contained in:
JerryALT
2024-03-12 22:41:56 +03:00
commit f6f27d419a
7509 changed files with 1423218 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
deps/curl/docs/libcurl/.gitignore vendored Normal file
View File

@ -0,0 +1,5 @@
# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
#
# SPDX-License-Identifier: curl
libcurl-symbols.md

68
deps/curl/docs/libcurl/ABI.md vendored Normal file
View File

@ -0,0 +1,68 @@
<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
-->
ABI - Application Binary Interface
==================================
"ABI" describes the low-level interface between an application program and a
library. Calling conventions, function arguments, return values, struct
sizes/defines and more.
[Wikipedia has a longer description](https://en.wikipedia.org/wiki/Application_binary_interface)
## Upgrades
A libcurl upgrade does not break the ABI or change established and documented
behavior. Your application can remain using libcurl just as before, only with
fewer bugs and possibly with added new features.
## Version Numbers
In libcurl land, you cannot tell by the libcurl version number if that
libcurl is binary compatible or not with another libcurl version. As a rule,
we do not break the ABI so you can *always* upgrade to a later version without
any loss or change in functionality.
## SONAME Bumps
Whenever there are changes done to the library that will cause an ABI
breakage, that may require your application to get attention or possibly be
changed to adhere to new things, we will bump the SONAME. Then the library
will get a different output name and thus can in fact be installed in
parallel with an older installed lib (on most systems). Thus, old
applications built against the previous ABI version will remain working and
using the older lib, while newer applications build and use the newer one.
During the first seven years of libcurl releases, there have only been four
ABI breakages.
We are determined to bump the SONAME as rarely as possible. Ideally, we never
do it again.
## Downgrades
Going to an older libcurl version from one you are currently using can be a
tricky thing. Mostly we add features and options to newer libcurls as that
will not break ABI or hamper existing applications. This has the implication
that going backwards may get you in a situation where you pick a libcurl that
does not support the options your application needs. Or possibly you even
downgrade so far so you cross an ABI break border and thus a different
SONAME, and then your application may need to adapt to the modified ABI.
## History
The previous major library SONAME number bumps (breaking backwards
compatibility) happened the following times:
0 - libcurl 7.1, August 2000
1 - libcurl 7.5 December 2000
2 - libcurl 7.7 March 2001
3 - libcurl 7.12.0 June 2004
4 - libcurl 7.16.0 October 2006

72
deps/curl/docs/libcurl/CMakeLists.txt vendored Normal file
View File

@ -0,0 +1,72 @@
#***************************************************************************
# _ _ ____ _
# 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
#
###########################################################################
# Load man_MANS from shared file
transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
function(add_manual_pages _listname)
unset(_rofffiles)
unset(_mdfiles)
foreach(_file IN LISTS ${_listname})
list(APPEND _rofffiles "${CMAKE_CURRENT_BINARY_DIR}/${_file}")
if(_file STREQUAL "libcurl-symbols.3")
# Special case, an auto-generated file.
string(REPLACE ".3" ".md" _mdfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}")
else()
string(REPLACE ".3" ".md" _mdfile "${_file}")
endif()
list(APPEND _mdfiles "${_mdfile}")
endforeach()
add_custom_command(OUTPUT ${_rofffiles}
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
COMMAND ${PROJECT_SOURCE_DIR}/scripts/cd2nroff -k -d "${CMAKE_CURRENT_BINARY_DIR}" ${_mdfiles}
DEPENDS ${_mdfiles}
VERBATIM
)
endfunction()
add_custom_command(OUTPUT libcurl-symbols.md
COMMAND
"${PERL_EXECUTABLE}"
"${CMAKE_CURRENT_SOURCE_DIR}/mksymbolsmanpage.pl" <
"${CMAKE_CURRENT_SOURCE_DIR}/symbols-in-versions" > libcurl-symbols.md
DEPENDS
"${CMAKE_CURRENT_SOURCE_DIR}/symbols-in-versions"
"${CMAKE_CURRENT_SOURCE_DIR}/mksymbolsmanpage.pl"
VERBATIM
)
add_manual_pages(man_MANS)
add_custom_target(man ALL DEPENDS ${man_MANS})
if(NOT CURL_DISABLE_INSTALL)
unset(_src)
foreach(_f ${man_MANS})
list(APPEND _src "${CMAKE_CURRENT_BINARY_DIR}/${_f}")
endforeach()
install(FILES ${_src} DESTINATION ${CMAKE_INSTALL_MANDIR}/man3)
endif()
add_subdirectory(opts)

59
deps/curl/docs/libcurl/Makefile.am vendored Normal file
View File

@ -0,0 +1,59 @@
#***************************************************************************
# _ _ ____ _
# 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
#
###########################################################################
AUTOMAKE_OPTIONS = foreign no-dependencies
SUBDIRS = opts
if BUILD_DOCS
include Makefile.inc
CURLPAGES = $(man_MANS:.3=.md)
endif
m4macrodir = $(datadir)/aclocal
dist_m4macro_DATA = libcurl.m4
CLEANFILES = $(man_MANS) libcurl-symbols.md
EXTRA_DIST = $(CURLPAGES) ABI.md symbols-in-versions symbols.pl \
mksymbolsmanpage.pl CMakeLists.txt
if BUILD_DOCS
CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@
CD2 = $(CD2_$(V))
CD2_0 = @echo " RENDER " $@;
CD2_1 =
CD2_ = $(CD2_0)
SUFFIXES = .3 .md
libcurl-symbols.md: $(srcdir)/symbols-in-versions $(srcdir)/mksymbolsmanpage.pl
$(CD2)perl $(srcdir)/mksymbolsmanpage.pl < $(srcdir)/symbols-in-versions > $@
.md.3:
$(CD2)$(CD2NROFF)
endif

124
deps/curl/docs/libcurl/Makefile.inc vendored Normal file
View File

@ -0,0 +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
#
###########################################################################
# Shared between Makefile.am and CMakeLists.txt
man_MANS = \
curl_easy_cleanup.3 \
curl_easy_duphandle.3 \
curl_easy_escape.3 \
curl_easy_getinfo.3 \
curl_easy_header.3 \
curl_easy_init.3 \
curl_easy_nextheader.3 \
curl_easy_option_by_id.3 \
curl_easy_option_by_name.3 \
curl_easy_option_next.3 \
curl_easy_pause.3 \
curl_easy_perform.3 \
curl_easy_recv.3 \
curl_easy_reset.3 \
curl_easy_send.3 \
curl_easy_setopt.3 \
curl_easy_strerror.3 \
curl_easy_unescape.3 \
curl_easy_upkeep.3 \
curl_escape.3 \
curl_formadd.3 \
curl_formfree.3 \
curl_formget.3 \
curl_free.3 \
curl_getdate.3 \
curl_getenv.3 \
curl_global_cleanup.3 \
curl_global_init.3 \
curl_global_init_mem.3 \
curl_global_trace.3 \
curl_global_sslset.3 \
curl_mime_addpart.3 \
curl_mime_data.3 \
curl_mime_data_cb.3 \
curl_mime_encoder.3 \
curl_mime_filedata.3 \
curl_mime_filename.3 \
curl_mime_free.3 \
curl_mime_headers.3 \
curl_mime_init.3 \
curl_mime_name.3 \
curl_mime_subparts.3 \
curl_mime_type.3 \
curl_mprintf.3 \
curl_multi_add_handle.3 \
curl_multi_assign.3 \
curl_multi_cleanup.3 \
curl_multi_fdset.3 \
curl_multi_get_handles.3 \
curl_multi_info_read.3 \
curl_multi_init.3 \
curl_multi_perform.3 \
curl_multi_poll.3 \
curl_multi_remove_handle.3 \
curl_multi_setopt.3 \
curl_multi_socket.3 \
curl_multi_socket_action.3 \
curl_multi_socket_all.3 \
curl_multi_strerror.3 \
curl_multi_timeout.3 \
curl_multi_wakeup.3 \
curl_multi_wait.3 \
curl_pushheader_bynum.3 \
curl_pushheader_byname.3 \
curl_share_cleanup.3 \
curl_share_init.3 \
curl_share_setopt.3 \
curl_share_strerror.3 \
curl_slist_append.3 \
curl_slist_free_all.3 \
curl_strequal.3 \
curl_strnequal.3 \
curl_unescape.3 \
curl_url.3 \
curl_url_cleanup.3 \
curl_url_dup.3 \
curl_url_get.3 \
curl_url_set.3 \
curl_url_strerror.3 \
curl_version.3 \
curl_version_info.3 \
curl_ws_meta.3 \
curl_ws_recv.3 \
curl_ws_send.3 \
libcurl-easy.3 \
libcurl-env.3 \
libcurl-env-dbg.3 \
libcurl-errors.3 \
libcurl-multi.3 \
libcurl-security.3 \
libcurl-share.3 \
libcurl-symbols.3 \
libcurl-thread.3 \
libcurl-tutorial.3 \
libcurl-url.3 \
libcurl-ws.3 \
libcurl.3

76
deps/curl/docs/libcurl/curl_easy_cleanup.md vendored Normal file
View 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

72
deps/curl/docs/libcurl/curl_easy_duphandle.md vendored Normal file
View 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 filename 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.

75
deps/curl/docs/libcurl/curl_easy_escape.md vendored Normal file
View 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.

485
deps/curl/docs/libcurl/curl_easy_getinfo.md vendored Normal file
View File

@ -0,0 +1,485 @@
---
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_USED_PROXY
Whether the proxy was used (Added in 8.7.0). See CURLINFO_USED_PROXY(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
|--|--NAMELOOKUP
|--|--|--CONNECT
|--|--|--|--APPCONNECT
|--|--|--|--|--PRETRANSFER
|--|--|--|--|--|--STARTTRANSFER
|--|--|--|--|--|--|--TOTAL
|--|--|--|--|--|--|--REDIRECT
## CURLINFO_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)
## CURLINFO_NAMELOOKUP_TIME
CURLINFO_NAMELOOKUP_TIME(3) and CURLINFO_NAMELOOKUP_TIME_T(3). The time it
took from the start until the name resolving was completed.
## CURLINFO_CONNECT_TIME
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.
## CURLINFO_APPCONNECT_TIME
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)
## CURLINFO_PRETRANSFER_TIME
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.
## CURLINFO_STARTTRANSFER_TIME
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.
## CURLINFO_TOTAL_TIME
CURLINFO_TOTAL_TIME(3) and CURLINFO_TOTAL_TIME_T(3). Total time
of the previous request.
## CURLINFO_REDIRECT_TIME
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.

160
deps/curl/docs/libcurl/curl_easy_header.md vendored Normal file
View File

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

73
deps/curl/docs/libcurl/curl_easy_init.md vendored Normal file
View 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.

100
deps/curl/docs/libcurl/curl_easy_nextheader.md vendored Normal file
View 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.

54
deps/curl/docs/libcurl/curl_easy_option_by_id.md vendored Normal file
View 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.

53
deps/curl/docs/libcurl/curl_easy_option_by_name.md vendored Normal file
View 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.

89
deps/curl/docs/libcurl/curl_easy_option_next.md vendored Normal file
View 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.

140
deps/curl/docs/libcurl/curl_easy_pause.md vendored Normal file
View File

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

83
deps/curl/docs/libcurl/curl_easy_perform.md vendored Normal file
View 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 CURLOPT_ERRORBUFFER(3)
was set with curl_easy_setopt(3) there is an error message stored in the error
buffer when non-zero is returned.

103
deps/curl/docs/libcurl/curl_easy_recv.md vendored Normal file
View 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**.

56
deps/curl/docs/libcurl/curl_easy_reset.md vendored Normal file
View 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

95
deps/curl/docs/libcurl/curl_easy_send.md vendored Normal file
View 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 is 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 is 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**.

1381
deps/curl/docs/libcurl/curl_easy_setopt.md vendored Normal file
View File

File diff suppressed because it is too large Load Diff

59
deps/curl/docs/libcurl/curl_easy_strerror.md vendored Normal file
View 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.

73
deps/curl/docs/libcurl/curl_easy_unescape.md vendored Normal file
View 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.

77
deps/curl/docs/libcurl/curl_easy_upkeep.md vendored Normal file
View 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.

58
deps/curl/docs/libcurl/curl_escape.md vendored Normal file
View 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.

312
deps/curl/docs/libcurl/curl_formadd.md vendored Normal file
View File

@ -0,0 +1,312 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_formadd
Section: 3
Source: libcurl
See-also:
- curl_easy_setopt (3)
- curl_formfree (3)
- curl_mime_init (3)
---
# NAME
curl_formadd - add a section to a multipart form POST
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLFORMcode curl_formadd(struct curl_httppost **firstitem,
struct curl_httppost **lastitem, ...);
~~~
# DESCRIPTION
**This function is deprecated.** Use curl_mime_init(3) instead.
curl_formadd() is used to append sections when building a multipart form
post. Append one section at a time until you have added all the sections you
want included and then you pass the *firstitem* pointer as parameter to
CURLOPT_HTTPPOST(3). *lastitem* is set after each curl_formadd(3) call and
on repeated invokes it should be left as set to allow repeated invokes to find
the end of the list faster.
After the *lastitem* pointer follow the real arguments.
The pointers *firstitem* and *lastitem* should both be pointing to
NULL in the first call to this function. All list-data is allocated by the
function itself. You must call curl_formfree(3) on the *firstitem*
after the form post has been done to free the resources.
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with CURLOPT_HTTPHEADER(3) as usual.
First, there are some basics you need to understand about multipart form
posts. Each part consists of at least a NAME and a CONTENTS part. If the part
is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
Below, we discuss what options you use to set these properties in the parts
you want to add to your post.
The options listed first are for making normal parts. The options from
*CURLFORM_FILE* through *CURLFORM_BUFFERLENGTH* are for file upload
parts.
# OPTIONS
## CURLFORM_COPYNAME
followed by a string which provides the *name* of this part. libcurl
copies the string so your application does not need to keep it around after
this function call. If the name is not null-terminated, you must set its
length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to
contain zero-valued bytes. The copied data is freed by curl_formfree(3).
## CURLFORM_PTRNAME
followed by a string which provides the *name* of this part. libcurl uses the
pointer and refer to the data in your application, so you must make sure it
remains until curl no longer needs it. If the name is not null-terminated, you
must set its length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to
contain zero-valued bytes.
## CURLFORM_COPYCONTENTS
followed by a pointer to the contents of this part, the actual data to send
away. libcurl copies the provided data, so your application does not need to
keep it around after this function call. If the data is not null terminated,
or if you would like it to contain zero bytes, you must set the length of the
name with **CURLFORM_CONTENTSLENGTH**. The copied data is freed by
curl_formfree(3).
## CURLFORM_PTRCONTENTS
followed by a pointer to the contents of this part, the actual data to send
away. libcurl uses the pointer and refer to the data in your application, so
you must make sure it remains until curl no longer needs it. If the data is
not null-terminated, or if you would like it to contain zero bytes, you must
set its length with **CURLFORM_CONTENTSLENGTH**.
## CURLFORM_CONTENTLEN
followed by a curl_off_t value giving the length of the contents. Note that
for *CURLFORM_STREAM* contents, this option is mandatory.
If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents
to figure out the size. If you really want to send a zero byte content then
you must make sure strlen() on the data pointer returns zero.
(Option added in 7.46.0)
## CURLFORM_CONTENTSLENGTH
(This option is deprecated. Use *CURLFORM_CONTENTLEN* instead!)
followed by a long giving the length of the contents. Note that for
*CURLFORM_STREAM* contents, this option is mandatory.
If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents
to figure out the size. If you really want to send a zero byte content then
you must make sure strlen() on the data pointer returns zero.
## CURLFORM_FILECONTENT
followed by a filename, causes that file to be read and its contents used
as data in this part. This part does *not* automatically become a file
upload part simply because its data was read from a file.
The specified file needs to kept around until the associated transfer is done.
## CURLFORM_FILE
followed by a filename, makes this part a file upload part. It sets the
*filename* field to the basename of the provided filename, it reads the
contents of the file and passes them as data and sets the content-type if the
given file match one of the internally known file extensions. For
**CURLFORM_FILE** the user may send one or more files in one part by
providing multiple **CURLFORM_FILE** arguments each followed by the filename
(and each *CURLFORM_FILE* is allowed to have a
*CURLFORM_CONTENTTYPE*).
The given upload file has to exist in its full in the file system already when
the upload starts, as libcurl needs to read the correct file size beforehand.
The specified file needs to kept around until the associated transfer is done.
## CURLFORM_CONTENTTYPE
is used in combination with *CURLFORM_FILE*. Followed by a pointer to a
string which provides the content-type for this part, possibly instead of an
internally chosen one.
## CURLFORM_FILENAME
is used in combination with *CURLFORM_FILE*. Followed by a pointer to a
string, it tells libcurl to use the given string as the *filename* in the file
upload part instead of the actual filename.
## CURLFORM_BUFFER
is used for custom file upload parts without use of *CURLFORM_FILE*. It
tells libcurl that the file contents are already present in a buffer. The
parameter is a string which provides the *filename* field in the content
header.
## CURLFORM_BUFFERPTR
is used in combination with *CURLFORM_BUFFER*. The parameter is a pointer
to the buffer to be uploaded. This buffer must not be freed until after
curl_easy_cleanup(3) is called. You must also use
*CURLFORM_BUFFERLENGTH* to set the number of bytes in the buffer.
## CURLFORM_BUFFERLENGTH
is used in combination with *CURLFORM_BUFFER*. The parameter is a
long which gives the length of the buffer.
## CURLFORM_STREAM
Tells libcurl to use the CURLOPT_READFUNCTION(3) callback to get
data. The parameter you pass to *CURLFORM_STREAM* is the pointer passed on
to the read callback's fourth argument. If you want the part to look like a
file upload one, set the *CURLFORM_FILENAME* parameter as well. Note that
when using *CURLFORM_STREAM*, *CURLFORM_CONTENTSLENGTH* must also be
set with the total expected length of the part unless the formpost is sent
chunked encoded. (Option added in libcurl 7.18.2)
## CURLFORM_ARRAY
Another possibility to send options to curl_formadd() is the
**CURLFORM_ARRAY** option, that passes a struct curl_forms array pointer as
its value. Each curl_forms structure element has a *CURLformoption* and a
char pointer. The final element in the array must be a CURLFORM_END. All
available options can be used in an array, except the CURLFORM_ARRAY option
itself. The last argument in such an array must always be **CURLFORM_END**.
## CURLFORM_CONTENTHEADER
specifies extra headers for the form POST section. This takes a curl_slist
prepared in the usual way using **curl_slist_append** and appends the list
of headers to those libcurl automatically generates. The list must exist while
the POST occurs, if you free it before the post completes you may experience
problems.
When you have passed the *struct curl_httppost* pointer to
curl_easy_setopt(3) (using the CURLOPT_HTTPPOST(3) option), you
must not free the list until after you have called curl_easy_cleanup(3)
for the curl handle.
See example below.
# EXAMPLE
~~~c
#include <string.h> /* for strlen */
static const char record[]="data in a buffer";
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
struct curl_httppost *post = NULL;
struct curl_httppost *last = NULL;
char namebuffer[] = "name buffer";
long namelength = strlen(namebuffer);
char buffer[] = "test buffer";
char htmlbuffer[] = "<HTML>test buffer</HTML>";
long htmlbufferlength = strlen(htmlbuffer);
struct curl_forms forms[3];
char file1[] = "my-face.jpg";
char file2[] = "your-face.jpg";
/* add null character into htmlbuffer, to demonstrate that
transfers of buffers containing null characters actually work
*/
htmlbuffer[8] = '\0';
/* Add simple name/content section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
/* Add simple name/content/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
CURLFORM_COPYCONTENTS, "<HTML></HTML>",
CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
/* Add name/ptrcontent section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
/* Add ptrname/ptrcontent section */
curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
namelength, CURLFORM_END);
/* Add name/ptrcontent/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
CURLFORM_PTRCONTENTS, htmlbuffer,
CURLFORM_CONTENTSLENGTH, htmlbufferlength,
CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
/* Add simple file section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
/* Add file/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
CURLFORM_FILE, "my-face.jpg",
CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
/* Add two file section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
CURLFORM_FILE, "my-face.jpg",
CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
/* Add two file section using CURLFORM_ARRAY */
forms[0].option = CURLFORM_FILE;
forms[0].value = file1;
forms[1].option = CURLFORM_FILE;
forms[1].value = file2;
forms[2].option = CURLFORM_END;
/* Add a buffer to upload */
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "name",
CURLFORM_BUFFER, "data",
CURLFORM_BUFFERPTR, record,
CURLFORM_BUFFERLENGTH, sizeof(record),
CURLFORM_END);
/* no option needed for the end marker */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
CURLFORM_ARRAY, forms, CURLFORM_END);
/* Add the content of a file as a normal post text value */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
/* Set the form info */
curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
curl_easy_perform(curl);
curl_easy_cleanup(curl);
curl_formfree(post);
}
}
~~~
# AVAILABILITY
Deprecated in 7.56.0. Before this release, field names were allowed to contain
zero-valued bytes. The pseudo-filename "-" to read stdin is discouraged
although still supported, but data is not read before being actually sent: the
effective data size can then not be automatically determined, resulting in a
chunked encoding transfer. Backslashes and double quotes in field and
filenames are now escaped before transmission.
# RETURN VALUE
0 means everything was OK, non-zero means an error occurred corresponding to a
CURL_FORMADD_* constant defined in *\<curl/curl.h\>*.

76
deps/curl/docs/libcurl/curl_formfree.md vendored Normal file
View 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

72
deps/curl/docs/libcurl/curl_formget.md vendored Normal file
View 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

52
deps/curl/docs/libcurl/curl_free.md vendored Normal file
View 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

128
deps/curl/docs/libcurl/curl_getdate.md vendored Normal file
View File

@ -0,0 +1,128 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_getdate
Section: 3
Source: libcurl
See-also:
- CURLOPT_TIMECONDITION (3)
- CURLOPT_TIMEVALUE (3)
- curl_easy_escape (3)
- curl_easy_unescape (3)
---
# NAME
curl_getdate - Convert a date string to number of seconds
# SYNOPSIS
~~~c
#include <curl/curl.h>
time_t curl_getdate(const char *datestring, const time_t *now);
~~~
# DESCRIPTION
curl_getdate(3) returns the number of seconds since the Epoch, January
1st 1970 00:00:00 in the UTC time zone, for the date and time that the
*datestring* parameter specifies. The *now* parameter is not used,
pass a NULL there.
This function works with valid dates and does not always detect and reject
wrong dates, such as February 30.
# PARSING DATES AND TIMES
A "date" is a string containing several items separated by whitespace. The
order of the items is immaterial. A date string may contain many flavors of
items:
## calendar date items
Can be specified several ways. Month names can only be three-letter English
abbreviations, numbers can be zero-prefixed and the year may use 2 or 4
digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6.
## time of the day items
This string specifies the time on a given day. You must specify it with 6
digits with two colons: HH:MM:SS. If there is no time given in a provided date
string, 00:00:00 is assumed. Example: 18:19:21.
## time zone items
Specifies international time zone. There are a few acronyms supported, but in
general you should instead use the specific relative time compared to
UTC. Supported formats include: -1200, MST, +0100.
## day of the week items
Specifies a day of the week. Days of the week may be spelled out in full
(using English): `Sunday', `Monday', etc or they may be abbreviated to their
first three letters. This is usually not info that adds anything.
## pure numbers
If a decimal number of the form YYYYMMDD appears, then YYYY is read as the
year, MM as the month number and DD as the day of the month, for the specified
calendar date.
# EXAMPLE
~~~c
int main(void)
{
time_t t;
t = curl_getdate("Sun, 06 Nov 1994 08:49:37 GMT", NULL);
t = curl_getdate("Sunday, 06-Nov-94 08:49:37 GMT", NULL);
t = curl_getdate("Sun Nov 6 08:49:37 1994", NULL);
t = curl_getdate("06 Nov 1994 08:49:37 GMT", NULL);
t = curl_getdate("06-Nov-94 08:49:37 GMT", NULL);
t = curl_getdate("Nov 6 08:49:37 1994", NULL);
t = curl_getdate("06 Nov 1994 08:49:37", NULL);
t = curl_getdate("06-Nov-94 08:49:37", NULL);
t = curl_getdate("1994 Nov 6 08:49:37", NULL);
t = curl_getdate("GMT 08:49:37 06-Nov-94 Sunday", NULL);
t = curl_getdate("94 6 Nov 08:49:37", NULL);
t = curl_getdate("1994 Nov 6", NULL);
t = curl_getdate("06-Nov-94", NULL);
t = curl_getdate("Sun Nov 6 94", NULL);
t = curl_getdate("1994.Nov.6", NULL);
t = curl_getdate("Sun/Nov/6/94/GMT", NULL);
t = curl_getdate("Sun, 06 Nov 1994 08:49:37 CET", NULL);
t = curl_getdate("06 Nov 1994 08:49:37 EST", NULL);
t = curl_getdate("Sun, 12 Sep 2004 15:05:58 -0700", NULL);
t = curl_getdate("Sat, 11 Sep 2004 21:32:11 +0200", NULL);
t = curl_getdate("20040912 15:05:58 -0700", NULL);
t = curl_getdate("20040911 +0200", NULL);
}
~~~
# STANDARDS
This parser handles date formats specified in RFC 822 (including the update in
RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by
RFC 1036) and ANSI C's *asctime()* format.
These formats are the only ones RFC 7231 says HTTP applications may use.
# AVAILABILITY
Always
# RETURN VALUE
This function returns -1 when it fails to parse the date string. Otherwise it
returns the number of seconds as described.
On systems with a signed 32 bit time_t: if the year is larger than 2037 or
less than 1903, this function returns -1.
On systems with an unsigned 32 bit time_t: if the year is larger than 2106 or
less than 1970, this function returns -1.
On systems with 64 bit time_t: if the year is less than 1583, this function
returns -1. (The Gregorian calendar was first introduced 1582 so no "real"
dates in this way of doing dates existed before then.)

57
deps/curl/docs/libcurl/curl_getenv.md vendored Normal file
View 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.

74
deps/curl/docs/libcurl/curl_global_cleanup.md vendored Normal file
View 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

131
deps/curl/docs/libcurl/curl_global_init.md vendored Normal file
View File

@ -0,0 +1,131 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_global_init
Section: 3
Source: libcurl
See-also:
- curl_easy_init (3)
- curl_global_cleanup (3)
- curl_global_init_mem (3)
- curl_global_sslset (3)
- curl_global_trace (3)
- libcurl (3)
---
# NAME
curl_global_init - Global libcurl initialization
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLcode curl_global_init(long flags);
~~~
# DESCRIPTION
This function sets up the program environment that libcurl needs. Think of it
as an extension of the library loader.
This function must be called at least once within a program (a program is all
the code that shares a memory space) before the program calls any other
function in libcurl. The environment it sets up is constant for the life of
the program and is the same for every program, so multiple calls have the same
effect as one call.
The flags option is a bit pattern that tells libcurl exactly what features to
init, as described below. Set the desired bits by ORing the values together.
In normal operation, you must specify CURL_GLOBAL_ALL. Do not use any other
value unless you are familiar with it and mean to control internal operations
of libcurl.
This function is thread-safe since libcurl 7.84.0 if
curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set
(most platforms).
If this is not thread-safe, you must not call this function when any other
thread in the program (i.e. a thread sharing the same memory) is running.
This does not just mean no other thread that is using libcurl. Because
curl_global_init(3) calls functions of other libraries that are
similarly thread unsafe, it could conflict with any other thread that uses
these other libraries.
If you are initializing libcurl from a Windows DLL you should not initialize
it from *DllMain* or a static initializer because Windows holds the loader
lock during that time and it could cause a deadlock.
See the description in libcurl(3) of global environment requirements for
details of how to use this function.
# FLAGS
## CURL_GLOBAL_ALL
Initialize everything possible. This sets all known bits except
**CURL_GLOBAL_ACK_EINTR**.
## CURL_GLOBAL_SSL
(This flag's presence or absence serves no meaning since 7.57.0. The
description below is for older libcurl versions.)
Initialize SSL.
The implication here is that if this bit is not set, the initialization of the
SSL layer needs to be done by the application or at least outside of
libcurl. The exact procedure how to do SSL initialization depends on the TLS
backend libcurl uses.
Doing TLS based transfers without having the TLS layer initialized may lead to
unexpected behaviors.
## CURL_GLOBAL_WIN32
Initialize the Win32 socket libraries.
The implication here is that if this bit is not set, the initialization of
winsock has to be done by the application or you risk getting undefined
behaviors. This option exists for when the initialization is handled outside
of libcurl so there is no need for libcurl to do it again.
## CURL_GLOBAL_NOTHING
Initialize nothing extra. This sets no bit.
## CURL_GLOBAL_DEFAULT
A sensible default. It initializes both SSL and Win32. Right now, this equals
the functionality of the **CURL_GLOBAL_ALL** mask.
## CURL_GLOBAL_ACK_EINTR
This bit has no point since 7.69.0 but its behavior is instead the default.
Before 7.69.0: when this flag is set, curl acknowledges EINTR condition when
connecting or when waiting for data. Otherwise, curl waits until full timeout
elapses. (Added in 7.30.0)
# EXAMPLE
~~~c
int main(void)
{
curl_global_init(CURL_GLOBAL_DEFAULT);
/* use libcurl, then before exiting... */
curl_global_cleanup();
}
~~~
# AVAILABILITY
Added in 7.8
# RETURN VALUE
If this function returns non-zero, something went wrong and you cannot use the
other curl functions.

95
deps/curl/docs/libcurl/curl_global_init_mem.md vendored Normal file
View 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).

138
deps/curl/docs/libcurl/curl_global_sslset.md vendored Normal file
View 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*.

128
deps/curl/docs/libcurl/curl_global_trace.md vendored Normal file
View File

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

70
deps/curl/docs/libcurl/curl_mime_addpart.md vendored Normal file
View 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.

76
deps/curl/docs/libcurl/curl_mime_data.md vendored Normal file
View 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.

168
deps/curl/docs/libcurl/curl_mime_data_cb.md vendored Normal file
View File

@ -0,0 +1,168 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_mime_data_cb
Section: 3
Source: libcurl
See-also:
- curl_easy_duphandle (3)
- curl_mime_addpart (3)
- curl_mime_data (3)
- curl_mime_name (3)
---
# NAME
curl_mime_data_cb - set a callback-based data source for a mime part's body
# SYNOPSIS
~~~c
#include <curl/curl.h>
size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
int seekfunc(void *arg, curl_off_t offset, int origin);
void freefunc(void *arg);
CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize,
curl_read_callback readfunc,
curl_seek_callback seekfunc,
curl_free_callback freefunc, void *arg);
~~~
# DESCRIPTION
curl_mime_data_cb(3) sets the data source of a mime part's body content
from a data read callback function.
*part* is the part's to assign contents to.
*readfunc* is a pointer to a data read callback function, with a signature
as shown by the above prototype. It may not be set to NULL.
*seekfunc* is a pointer to a seek callback function, with a signature as
shown by the above prototype. This function is used when resending data (i.e.:
after a redirect); this pointer may be set to NULL, in which case a resend
might not be not possible.
*freefunc* is a pointer to a user resource freeing callback function, with
a signature as shown by the above prototype. If no resource is to be freed, it
may safely be set to NULL. This function is called upon mime structure
freeing.
*arg* is a user defined argument to callback functions.
The read callback function gets called by libcurl as soon as it needs to
read data in order to send it to the peer - like if you ask it to upload or
post data to the server. The data area pointed at by the pointer *buffer*
should be filled up with at most *size* multiplied with *nitems* number
of bytes by your function.
Your read function must then return the actual number of bytes that it stored
in that memory area. Returning 0 signals end-of-file to the library and cause
it to stop the current transfer.
If you stop the current transfer by returning 0 "pre-maturely" (i.e. before
the server expected it, like when you have said you intend to upload N bytes
and yet you upload less than N bytes), you may experience that the server
"hangs" waiting for the rest of the data that does not come.
The read callback may return *CURL_READFUNC_ABORT* to stop the current
operation immediately, resulting in a *CURLE_ABORTED_BY_CALLBACK* error
code from the transfer.
The callback can return *CURL_READFUNC_PAUSE* to cause reading from this
connection to pause. See curl_easy_pause(3) for further details.
The seek function gets called by libcurl to rewind input stream data or to
seek to a certain position. The function shall work like fseek(3) or lseek(3)
and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for *origin*,
although libcurl currently only passes SEEK_SET.
The callback function must return *CURL_SEEKFUNC_OK* on success,
*CURL_SEEKFUNC_FAIL* to cause the upload operation to fail or
*CURL_SEEKFUNC_CANTSEEK* to indicate that while the seek failed, libcurl
is free to work around the problem if possible. The latter can sometimes be
done by instead reading from the input or similar.
Care must be taken if the part is bound to a curl easy handle that is later
duplicated: the *arg* pointer argument is also duplicated, resulting in
the pointed item to be shared between the original and the copied handle. In
particular, special attention should be given to the *freefunc* procedure
code since it then gets called twice with the same argument.
# EXAMPLE
Sending a huge data string causes the same amount of memory to be allocated:
to avoid overhead resources consumption, one might want to use a callback
source to avoid data duplication. In this case, original data must be retained
until after the transfer terminates.
~~~c
#include <string.h> /* for memcpy */
char hugedata[512000];
struct ctl {
char *buffer;
curl_off_t size;
curl_off_t position;
};
size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
{
struct ctl *p = (struct ctl *) arg;
curl_off_t sz = p->size - p->position;
nitems *= size;
if(sz > nitems)
sz = nitems;
if(sz)
memcpy(buffer, p->buffer + p->position, sz);
p->position += sz;
return sz;
}
int seek_callback(void *arg, curl_off_t offset, int origin)
{
struct ctl *p = (struct ctl *) arg;
switch(origin) {
case SEEK_END:
offset += p->size;
break;
case SEEK_CUR:
offset += p->position;
break;
}
if(offset < 0)
return CURL_SEEKFUNC_FAIL;
p->position = offset;
return CURL_SEEKFUNC_OK;
}
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
curl_mime *mime = curl_mime_init(curl);
curl_mimepart *part = curl_mime_addpart(mime);
struct ctl hugectl;
hugectl.buffer = hugedata;
hugectl.size = sizeof(hugedata);
hugectl.position = 0;
curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
&hugectl);
}
}
~~~
# AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
# RETURN VALUE
CURLE_OK or a CURL error code upon failure.

100
deps/curl/docs/libcurl/curl_mime_encoder.md vendored Normal file
View 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.

88
deps/curl/docs/libcurl/curl_mime_filedata.md vendored Normal file
View 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 filename 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.

79
deps/curl/docs/libcurl/curl_mime_filename.md vendored Normal file
View 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 filename
# 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 filename. When remote
filename is set, content data is processed as a file, whatever is the part's
content source. A part's remote filename is transmitted to the server in the
associated Content-Disposition generated header.
*part* is the part's handle to assign the remote filename to.
*filename* points to the null-terminated filename string; it may be set
to NULL to remove a previously attached remote filename.
The remote filename 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.

65
deps/curl/docs/libcurl/curl_mime_free.md vendored Normal file
View 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

78
deps/curl/docs/libcurl/curl_mime_headers.md vendored Normal file
View 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.

72
deps/curl/docs/libcurl/curl_mime_init.md vendored Normal file
View 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.

67
deps/curl/docs/libcurl/curl_mime_name.md vendored Normal file
View 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.

83
deps/curl/docs/libcurl/curl_mime_subparts.md vendored Normal file
View 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.

86
deps/curl/docs/libcurl/curl_mime_type.md vendored Normal file
View 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 filename is set, the mime type is taken from the filename
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.

288
deps/curl/docs/libcurl/curl_mprintf.md vendored Normal file
View File

@ -0,0 +1,288 @@
---
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
# SYNOPSIS
~~~c
#include <curl/mprintf.h>
int curl_mprintf(const char *format, ...);
int curl_mfprintf(FILE *fd, const char *format, ...);
int curl_msprintf(char *buffer, const char *format, ...);
int curl_msnprintf(char *buffer, size_t maxlength, const char *format, ...);
int curl_mvprintf(const char *format, va_list args);
int curl_mvfprintf(FILE *fd, const char *format, va_list args);
int curl_mvsprintf(char *buffer, const char *format, va_list args);
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);
~~~
# 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.
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 **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 **curl_msnprintf()** and **curl_mvsnprintf()** write at most
*maxlength* bytes (including the terminating null byte ('0')) to
*buffer*.
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 **curl_maprintf()** and **curl_mvaprintf()** return the
output string as pointer to a newly allocated memory area. The returned string
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.
# 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 *flags*, an optional minimum *field width*, an optional
*precision* and an optional *length modifier*.
# 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
argument (and it is an error if insufficiently many arguments are given). One
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,
~~~c
curl_mprintf("%*d", width, num);
~~~
and
~~~c
curl_mprintf("%2$*1$d", width, num);
~~~
are equivalent. The second style allows repeated references to the same
argument.
If the style using '$' is used, it must be used throughout for all conversions
taking an argument and all width and precision arguments, but it may be mixed
with "%%" formats, which do not consume an argument. There may be no gaps in
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.
# Flag characters
The character % is followed by zero or more of the following flags:
## #
The value should be converted to its "alternate form".
## 0
The value should be zero padded.
## -
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.
# 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 *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.
# 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 *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 **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
## 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.
## q
A synonym for **ll**.
## L
A following a, A, e, E, f, F, g, or G conversion corresponds to a long double
argument.
## z
A following integer conversion corresponds to a *size_t* or *ssize_t*
argument.
# Conversion specifiers
A character that specifies the type of conversion to be applied. The
conversion specifiers and their meanings are:
## 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.
## o, u, x, X
The unsigned int argument is converted to unsigned octal (o), unsigned decimal
(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.
## 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
**"[-]ddd.ddd"**.
## g, G
The double argument is converted in style f or e.
## c
The int argument is converted to an unsigned char, and the resulting character
is written.
## 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.
## 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.
## %
A '%' symbol is written. No argument is converted.
# 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);
}
~~~
# AVAILABILITY
These functions might be removed from the public libcurl API in the future. Do
not use them in new programs or projects.
# 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.

88
deps/curl/docs/libcurl/curl_multi_add_handle.md vendored Normal file
View 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.

81
deps/curl/docs/libcurl/curl_multi_assign.md vendored Normal file
View File

@ -0,0 +1,81 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_assign
Section: 3
Source: libcurl
See-also:
- curl_multi_setopt (3)
- curl_multi_socket_action (3)
---
# NAME
curl_multi_assign - set data to associate with an internal socket
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,
void *sockptr);
~~~
# 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
curl_multi_socket_action(3) uses.
When set, the *sockptr* pointer is passed to all future socket callbacks
for the specific *sockfd* socket.
If the given *sockfd* 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.
# EXAMPLE
~~~c
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));
}
~~~
# AVAILABILITY
Added in 7.15.5
# RETURN VALUE
The standard CURLMcode for multi interface error codes.
# 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 curl_multi_socket_action(3) approach.
When our socket-callback gets called by libcurl and we get to know about yet
another socket to wait for, we can use curl_multi_assign(3) 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.

65
deps/curl/docs/libcurl/curl_multi_cleanup.md vendored Normal file
View File

@ -0,0 +1,65 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_cleanup
Section: 3
Source: libcurl
See-also:
- curl_easy_cleanup (3)
- curl_easy_init (3)
- curl_multi_get_handles (3)
- curl_multi_init (3)
---
# NAME
curl_multi_cleanup - close down a multi session
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_cleanup(CURLM *multi_handle);
~~~
# DESCRIPTION
Cleans up and removes a whole multi stack. It does not free or touch any
individual easy handles in any way - they still need to be closed
individually, using the usual curl_easy_cleanup(3) way. The order of
cleaning up should be:
1 - curl_multi_remove_handle(3) before any easy handles are cleaned up
2 - curl_easy_cleanup(3) can now be called independently since the easy
handle is no longer connected to the multi handle
3 - curl_multi_cleanup(3) should be called when all easy handles are
removed
Passing in a NULL pointer in *multi_handle* makes this function return
CURLM_BAD_HANDLE immediately with no other action.
# EXAMPLE
~~~c
int main(void)
{
CURLM *multi = curl_multi_init();
/* when the multi transfer is done ... */
/* remove all easy handles, then: */
curl_multi_cleanup(multi);
}
~~~
# AVAILABILITY
Added in 7.9.6
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code. On success,
CURLM_OK is returned.

119
deps/curl/docs/libcurl/curl_multi_fdset.md vendored Normal file
View File

@ -0,0 +1,119 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_fdset
Section: 3
Source: libcurl
See-also:
- curl_multi_cleanup (3)
- curl_multi_init (3)
- curl_multi_perform (3)
- curl_multi_timeout (3)
- curl_multi_wait (3)
- select (2)
---
# NAME
curl_multi_fdset - extracts file descriptor information from a multi handle
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_fdset(CURLM *multi_handle,
fd_set *read_fd_set,
fd_set *write_fd_set,
fd_set *exc_fd_set,
int *max_fd);
~~~
# DESCRIPTION
This function extracts file descriptor information from a given multi_handle.
libcurl returns its *fd_set* sets. The application can use these to
select() on, but be sure to *FD_ZERO* them before calling this function as
curl_multi_fdset(3) only adds its own descriptors, it does not zero or
otherwise remove any others. The curl_multi_perform(3) function should
be called as soon as one of them is ready to be read from or written to.
The *read_fd_set* argument should point to an object of type **fd_set**
that on returns specifies the file descriptors to be checked for being ready
to read.
The *write_fd_set* argument should point to an object of type **fd_set**
that on return specifies the file descriptors to be checked for being ready to
write.
The *exc_fd_set* argument should point to an object of type **fd_set**
that on return specifies the file descriptors to be checked for error
conditions.
If no file descriptors are set by libcurl, *max_fd* contain -1 when this
function returns. Otherwise it contains the highest descriptor number libcurl
set. When libcurl returns -1 in *max_fd*, it is because libcurl currently
does something that is not possible for your application to monitor with a
socket and unfortunately you can then not know exactly when the current action
is completed using select(). You then need to wait a while before you proceed
and call curl_multi_perform(3) anyway. How long to wait? Unless
curl_multi_timeout(3) gives you a lower number, we suggest 100
milliseconds or so, but you may want to test it out in your own particular
conditions to find a suitable value.
When doing select(), you should use curl_multi_timeout(3) to figure out
how long to wait for action. Call curl_multi_perform(3) even if no
activity has been seen on the **fd_sets** after the timeout expires as
otherwise internal retries and timeouts may not work as you would think and
want.
If one of the sockets used by libcurl happens to be larger than what can be
set in an **fd_set**, which on POSIX systems means that the file descriptor
is larger than **FD_SETSIZE**, then libcurl tries to not set it. Setting a
too large file descriptor in an **fd_set** implies an out of bounds write
which can cause crashes, or worse. The effect of NOT storing it might possibly
save you from the crash, but makes your program NOT wait for sockets it should
wait for...
# EXAMPLE
~~~c
int main(void)
{
fd_set fdread;
fd_set fdwrite;
fd_set fdexcep;
int maxfd;
int rc;
CURLMcode mc;
struct timeval timeout = {1, 0};
CURLM *multi = curl_multi_init();
do {
/* call curl_multi_perform() */
/* get file descriptors from the transfers */
mc = curl_multi_fdset(multi, &fdread, &fdwrite, &fdexcep, &maxfd);
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi_fdset() failed, code %d.\n", mc);
break;
}
/* wait for activity on one of the sockets */
rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout);
} while(!mc);
}
~~~
# AVAILABILITY
Added in 7.9.6
# RETURN VALUE
**CURLMcode** type, general libcurl multi interface error code. See
libcurl-errors(3)

77
deps/curl/docs/libcurl/curl_multi_get_handles.md vendored Normal file
View File

@ -0,0 +1,77 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_get_handles
Section: 3
Source: libcurl
See-also:
- curl_multi_add_handle (3)
- curl_multi_cleanup (3)
- curl_multi_init (3)
- curl_multi_remove_handle (3)
---
# NAME
curl_multi_get_handles - returns all added easy handles
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURL **curl_multi_get_handles(CURLM *multi_handle);
~~~
# DESCRIPTION
Returns an array with pointers to all added easy handles. The end of the list
is marked with a NULL pointer.
Even if there is not a single easy handle added, this still returns an array
but with only a single NULL pointer entry.
The returned array contains all the handles that are present at the time of
the call. As soon as a handle has been removed from or a handle has been added
to the multi handle after the handle array was returned, the two data points
are out of sync.
The order of the easy handles within the array is not guaranteed.
The returned array must be freed with a call to curl_free(3) after use.
# EXAMPLE
~~~c
int main(void)
{
/* init a multi stack */
CURLM *multi = curl_multi_init();
CURL *curl = curl_easy_init();
if(curl) {
/* add the transfer */
curl_multi_add_handle(multi, curl);
/* extract all added handles */
CURL **list = curl_multi_get_handles(multi);
if(list) {
int i;
/* remove all added handles */
for(i = 0; list[i]; i++) {
curl_multi_remove_handle(multi, list[i]);
}
curl_free(list);
}
}
}
~~~
# AVAILABILITY
Added in 8.4.0
# RETURN VALUE
Returns NULL on failure. Otherwise it returns a pointer to an allocated array.

102
deps/curl/docs/libcurl/curl_multi_info_read.md vendored Normal file
View File

@ -0,0 +1,102 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_info_read
Section: 3
Source: libcurl
See-also:
- curl_multi_cleanup (3)
- curl_multi_init (3)
- curl_multi_perform (3)
---
# NAME
curl_multi_info_read - read multi stack information
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue);
~~~
# DESCRIPTION
Ask the multi handle if there are any messages from the individual
transfers. Messages may include information such as an error code from the
transfer or just the fact that a transfer is completed. More details on these
should be written down as well.
Repeated calls to this function returns a new struct each time, until a NULL
is returned as a signal that there is no more to get at this point. The
integer pointed to with *msgs_in_queue* contains the number of remaining
messages after this function was called.
When you fetch a message using this function, it is removed from the internal
queue so calling this function again does not return the same message
again. It instead returns new messages at each new invoke until the queue is
emptied.
**WARNING:** The data the returned pointer points to does not survive
calling curl_multi_cleanup(3), curl_multi_remove_handle(3) or
curl_easy_cleanup(3).
The *CURLMsg* struct is simple and only contains basic information. If
more involved information is wanted, the particular "easy handle" is present
in that struct and can be used in subsequent regular
curl_easy_getinfo(3) calls (or similar):
~~~c
struct CURLMsg {
CURLMSG msg; /* what this message means */
CURL *easy_handle; /* the handle it concerns */
union {
void *whatever; /* message-specific data */
CURLcode result; /* return code for transfer */
} data;
};
~~~
When **msg** is *CURLMSG_DONE*, the message identifies a transfer that
is done, and then **result** contains the return code for the easy handle
that just completed.
At this point, there are no other **msg** types defined.
# EXAMPLE
~~~c
int main(void)
{
CURLM *multi = curl_multi_init();
CURL *curl = curl_easy_init();
if(curl) {
struct CURLMsg *m;
/* call curl_multi_perform or curl_multi_socket_action first, then loop
through and check if there are any transfers that have completed */
do {
int msgq = 0;
m = curl_multi_info_read(multi, &msgq);
if(m && (m->msg == CURLMSG_DONE)) {
CURL *e = m->easy_handle;
/* m->data.result holds the error code for the transfer */
curl_multi_remove_handle(multi, e);
curl_easy_cleanup(e);
}
} while(m);
}
}
~~~
# AVAILABILITY
Added in 7.9.6
# RETURN VALUE
A pointer to a filled-in struct, or NULL if it failed or ran out of
structs. It also writes the number of messages left in the queue (after this
read) in the integer the second argument points to.

57
deps/curl/docs/libcurl/curl_multi_init.md vendored Normal file
View File

@ -0,0 +1,57 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_init
Section: 3
Source: libcurl
See-also:
- curl_easy_init (3)
- curl_global_init (3)
- curl_multi_add_handle (3)
- curl_multi_cleanup (3)
- curl_multi_get_handles (3)
---
# NAME
curl_multi_init - create a multi handle
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLM *curl_multi_init();
~~~
# DESCRIPTION
This function returns a pointer to a *CURLM* handle to be used as input to
all the other multi-functions, sometimes referred to as a multi handle in some
places in the documentation. This init call MUST have a corresponding call to
curl_multi_cleanup(3) when the operation is complete.
# EXAMPLE
~~~c
int main(void)
{
/* init a multi stack */
CURLM *multi = curl_multi_init();
CURL *curl = curl_easy_init();
CURL *curl2 = curl_easy_init();
/* add individual transfers */
curl_multi_add_handle(multi, curl);
curl_multi_add_handle(multi, curl2);
}
~~~
# AVAILABILITY
Added in 7.9.6
# RETURN VALUE
If this function returns NULL, something went wrong and you cannot use the
other curl functions.

107
deps/curl/docs/libcurl/curl_multi_perform.md vendored Normal file
View File

@ -0,0 +1,107 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_perform
Section: 3
Source: libcurl
See-also:
- curl_multi_add_handle (3)
- curl_multi_cleanup (3)
- curl_multi_fdset (3)
- curl_multi_info_read (3)
- curl_multi_init (3)
- curl_multi_wait (3)
- libcurl-errors (3)
---
# NAME
curl_multi_perform - reads/writes available data from easy handles
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles);
~~~
# DESCRIPTION
This function performs transfers on all the added handles that need attention
in a non-blocking fashion. The easy handles have previously been added to the
multi handle with curl_multi_add_handle(3).
When an application has found out there is data available for the multi_handle
or a timeout has elapsed, the application should call this function to
read/write whatever there is to read or write right now etc.
curl_multi_perform(3) returns as soon as the reads/writes are done. This
function does not require that there actually is any data available for
reading or that data can be written, it can be called just in case. It stores
the number of handles that still transfer data in the second argument's
integer-pointer.
If the amount of *running_handles* is changed from the previous call (or
is less than the amount of easy handles you have added to the multi handle),
you know that there is one or more transfers less "running". You can then call
curl_multi_info_read(3) to get information about each individual
completed transfer, and that returned info includes CURLcode and more. If an
added handle fails quickly, it may never be counted as a running_handle. You
could use curl_multi_info_read(3) to track actual status of the added
handles in that case.
When *running_handles* is set to zero (0) on the return of this function,
there is no longer any transfers in progress.
When this function returns error, the state of all transfers are uncertain and
they cannot be continued. curl_multi_perform(3) should not be called
again on the same multi handle after an error has been returned, unless first
removing all the handles and adding new ones.
# EXAMPLE
~~~c
int main(void)
{
int still_running;
CURL *multi = curl_multi_init();
CURL *curl = curl_easy_init();
if(curl) {
curl_multi_add_handle(multi, curl);
do {
CURLMcode mc = curl_multi_perform(multi, &still_running);
if(!mc && still_running)
/* wait for activity, timeout or "nothing" */
mc = curl_multi_poll(multi, NULL, 0, 1000, NULL);
if(mc) {
fprintf(stderr, "curl_multi_poll() failed, code %d.\n", (int)mc);
break;
}
/* if there are still transfers, loop! */
} while(still_running);
}
}
~~~
# AVAILABILITY
Added in 7.9.6
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code.
This function returns errors regarding the whole multi stack. Problems on
individual transfers may have occurred even when this function returns
*CURLM_OK*. Use curl_multi_info_read(3) to figure out how individual
transfers did.
# TYPICAL USAGE
Most applications use curl_multi_poll(3) to make libcurl wait for
activity on any of the ongoing transfers. As soon as one or more file
descriptor has activity or the function times out, the application calls
curl_multi_perform(3).

128
deps/curl/docs/libcurl/curl_multi_poll.md vendored Normal file
View File

@ -0,0 +1,128 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_poll
Section: 3
Source: libcurl
See-also:
- curl_multi_fdset (3)
- curl_multi_perform (3)
- curl_multi_wait (3)
- curl_multi_wakeup (3)
---
# NAME
curl_multi_poll - polls on all easy handles in a multi handle
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_poll(CURLM *multi_handle,
struct curl_waitfd extra_fds[],
unsigned int extra_nfds,
int timeout_ms,
int *numfds);
~~~
# DESCRIPTION
curl_multi_poll(3) polls all file descriptors used by the curl easy
handles contained in the given multi handle set. It blocks until activity is
detected on at least one of the handles or *timeout_ms* has passed.
Alternatively, if the multi handle has a pending internal timeout that has a
shorter expiry time than *timeout_ms*, that shorter time is used instead
to make sure timeout accuracy is reasonably kept.
The calling application may pass additional curl_waitfd structures which are
similar to *poll(2)*'s *pollfd* structure to be waited on in the same
call.
On completion, if *numfds* is non-NULL, it gets populated with the total
number of file descriptors on which interesting events occurred. This number
can include both libcurl internal descriptors as well as descriptors provided
in *extra_fds*.
The curl_multi_wakeup(3) function can be used from another thread to
wake up this function and return faster. This is one of the details
that makes this function different than curl_multi_wait(3) which cannot
be woken up this way.
If no extra file descriptors are provided and libcurl has no file descriptor
to offer to wait for, this function instead waits during *timeout_ms*
milliseconds (or shorter if an internal timer indicates so). This is the other
detail that makes this function different than curl_multi_wait(3).
This function is encouraged to be used instead of select(3) when using the
multi interface to allow applications to easier circumvent the common problem
with 1024 maximum file descriptors.
# curl_waitfd
~~~c
struct curl_waitfd {
curl_socket_t fd;
short events;
short revents;
};
~~~
## CURL_WAIT_POLLIN
Bit flag to curl_waitfd.events indicating the socket should poll on read
events such as new data received.
## CURL_WAIT_POLLPRI
Bit flag to curl_waitfd.events indicating the socket should poll on high
priority read events such as out of band data.
## CURL_WAIT_POLLOUT
Bit flag to curl_waitfd.events indicating the socket should poll on write
events such as the socket being clear to write without blocking.
# EXAMPLE
~~~c
int main(void)
{
CURL *easy_handle;
CURLM *multi_handle;
int still_running = 0;
/* add the individual easy handle */
curl_multi_add_handle(multi_handle, easy_handle);
do {
CURLMcode mc;
int numfds;
mc = curl_multi_perform(multi_handle, &still_running);
if(mc == CURLM_OK) {
/* wait for activity or timeout */
mc = curl_multi_poll(multi_handle, NULL, 0, 1000, &numfds);
}
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi failed, code %d.\n", mc);
break;
}
} while(still_running);
curl_multi_remove_handle(multi_handle, easy_handle);
}
~~~
# AVAILABILITY
Added in 7.66.0.
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code. See
libcurl-errors(3)

73
deps/curl/docs/libcurl/curl_multi_remove_handle.md vendored Normal file
View File

@ -0,0 +1,73 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_remove_handle
Section: 3
Source: libcurl
See-also:
- curl_multi_add_handle (3)
- curl_multi_cleanup (3)
- curl_multi_init (3)
---
# NAME
curl_multi_remove_handle - remove an easy handle from a multi session
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle);
~~~
# DESCRIPTION
Removes a given *easy_handle* from the *multi_handle*. This makes the
specified easy handle be removed from this multi handle's control.
When the easy handle has been removed from a multi stack, it is again
perfectly legal to invoke curl_easy_perform(3) on this easy handle.
Removing an easy handle while being in use is perfectly legal and effectively
halts the transfer in progress involving that easy handle. All other easy
handles and transfers remain unaffected.
It is fine to remove a handle at any time during a transfer, just not from
within any libcurl callback function.
Removing an easy handle from the multi handle before the corresponding
transfer is complete might cause libcurl to close the connection - if the
state of it and the internal protocol handler deem it necessary. Otherwise
libcurl keeps the connection alive in the connection pool associated with the
multi handle, ready to get reused for a future transfer using this multi
handle.
# EXAMPLE
~~~c
int main(void)
{
CURLM *multi = curl_multi_init();
int queued = 0;
/* when an easy handle has completed, remove it */
CURLMsg *msg = curl_multi_info_read(multi, &queued);
if(msg) {
if(msg->msg == CURLMSG_DONE) {
/* a transfer ended */
fprintf(stderr, "Transfer completed\n");
curl_multi_remove_handle(multi, msg->easy_handle);
}
}
}
~~~
# AVAILABILITY
Added in 7.9.6
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code.

125
deps/curl/docs/libcurl/curl_multi_setopt.md vendored Normal file
View File

@ -0,0 +1,125 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_setopt
Section: 3
Source: libcurl
See-also:
- curl_multi_cleanup (3)
- curl_multi_info_read (3)
- curl_multi_init (3)
- curl_multi_socket (3)
---
# NAME
curl_multi_setopt - set options for a curl multi handle
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *multi_handle, CURLMoption option, parameter);
~~~
# DESCRIPTION
curl_multi_setopt(3) is used to tell a libcurl multi handle how to
behave. By using the appropriate options to curl_multi_setopt(3), you
can change libcurl's behavior when using that multi handle. All options are
set with the *option* followed by the *parameter*. That parameter can
be a **long**, a **function pointer**, an **object pointer** or a
**curl_off_t** type, depending on what the specific option expects. Read
this manual carefully as bad input values may cause libcurl to behave
badly. You can only set one option in each function call.
# OPTIONS
## CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE
See CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)
## CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE
See CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)
## CURLMOPT_MAX_HOST_CONNECTIONS
See CURLMOPT_MAX_HOST_CONNECTIONS(3)
## CURLMOPT_MAX_PIPELINE_LENGTH
See CURLMOPT_MAX_PIPELINE_LENGTH(3)
## CURLMOPT_MAX_TOTAL_CONNECTIONS
See CURLMOPT_MAX_TOTAL_CONNECTIONS(3)
## CURLMOPT_MAXCONNECTS
See CURLMOPT_MAXCONNECTS(3)
## CURLMOPT_PIPELINING
See CURLMOPT_PIPELINING(3)
## CURLMOPT_PIPELINING_SITE_BL
See CURLMOPT_PIPELINING_SITE_BL(3)
## CURLMOPT_PIPELINING_SERVER_BL
See CURLMOPT_PIPELINING_SERVER_BL(3)
## CURLMOPT_PUSHFUNCTION
See CURLMOPT_PUSHFUNCTION(3)
## CURLMOPT_PUSHDATA
See CURLMOPT_PUSHDATA(3)
## CURLMOPT_SOCKETFUNCTION
See CURLMOPT_SOCKETFUNCTION(3)
## CURLMOPT_SOCKETDATA
See CURLMOPT_SOCKETDATA(3)
## CURLMOPT_TIMERFUNCTION
See CURLMOPT_TIMERFUNCTION(3)
## CURLMOPT_TIMERDATA
See CURLMOPT_TIMERDATA(3)
## CURLMOPT_MAX_CONCURRENT_STREAMS
See CURLMOPT_MAX_CONCURRENT_STREAMS(3)
# EXAMPLE
~~~c
#define MAX_PARALLEL 45
int main(void)
{
CURLM *multi;
/* Limit the amount of simultaneous connections curl should allow: */
curl_multi_setopt(multi, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL);
}
~~~
# AVAILABILITY
Added in 7.15.4
# RETURN VALUE
The standard CURLMcode for multi interface error codes. Note that it returns a
CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl
does not know of.

95
deps/curl/docs/libcurl/curl_multi_socket.md vendored Normal file
View File

@ -0,0 +1,95 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_socket
Section: 3
Source: libcurl
See-also:
- curl_multi_cleanup (3)
- curl_multi_fdset (3)
- curl_multi_info_read (3)
- curl_multi_init (3)
- the hiperfifo.c example
---
# NAME
curl_multi_socket - reads/writes available data
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd,
int *running_handles);
CURLMcode curl_multi_socket_all(CURLM *multi_handle,
int *running_handles);
~~~
# DESCRIPTION
These functions are deprecated. Do not use. See
curl_multi_socket_action(3) instead.
At return, the integer **running_handles** points to contains the number of
still running easy handles within the multi handle. When this number reaches
zero, all transfers are complete/done. Note that when you call
curl_multi_socket_action(3) on a specific socket and the counter
decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
is the one that completed. Use curl_multi_info_read(3) to figure out
which easy handle that completed.
The curl_multi_socket_action(3) functions inform the application about
updates in the socket (file descriptor) status by doing none, one, or multiple
calls to the socket callback function set with the
CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They
update the status with changes since the previous time the callback was
called.
Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option
with curl_multi_setopt(3). Your application then gets called with
information on how long to wait for socket actions at most before doing the
timeout action: call the curl_multi_socket_action(3) function with the
**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the
curl_multi_timeout(3) function to poll the value at any given time, but
for an event-based system using the callback is far better than relying on
polling the timeout value.
Usage of curl_multi_socket(3) is deprecated, whereas the function is
equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to
0.
Force libcurl to (re-)check all its internal sockets and transfers instead of
just a single one by calling curl_multi_socket_all(3). Note that there
should not be any reason to use this function.
# EXAMPLE
~~~c
int main(void)
{
/* the event-library gets told when there activity on the socket 'fd',
which we translate to a call to curl_multi_socket_action() */
int running;
int rc;
int fd;
CURLM *multi;
rc = curl_multi_socket(multi, fd, &running);
}
~~~
# AVAILABILITY
This function was added in libcurl 7.15.4, and is deemed stable since
7.16.0.
curl_multi_socket(3) is deprecated, use
curl_multi_socket_action(3) instead!
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code.
The return code is for the whole multi stack. Problems still might have
occurred on individual transfers even when one of these functions return OK.

120
deps/curl/docs/libcurl/curl_multi_socket_action.md vendored Normal file
View File

@ -0,0 +1,120 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_socket_action
Section: 3
Source: libcurl
See-also:
- curl_multi_cleanup (3)
- curl_multi_fdset (3)
- curl_multi_info_read (3)
- curl_multi_init (3)
- the hiperfifo.c example
---
# NAME
curl_multi_socket_action - reads/writes available data given an action
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_socket_action(CURLM *multi_handle,
curl_socket_t sockfd,
int ev_bitmask,
int *running_handles);
~~~
# DESCRIPTION
When the application has detected action on a socket handled by libcurl, it
should call curl_multi_socket_action(3) with the **sockfd** argument
set to the socket with the action. When the events on a socket are known, they
can be passed as an events bitmask **ev_bitmask** by first setting
**ev_bitmask** to 0, and then adding using bitwise OR (|) any combination of
events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
libcurl tests the descriptor internally. It is also permissible to pass
CURL_SOCKET_TIMEOUT to the **sockfd** parameter in order to initiate the
whole process or when a timeout occurs.
At return, **running_handles** points to the number of running easy handles
within the multi handle. When this number reaches zero, all transfers are
complete/done. When you call curl_multi_socket_action(3) on a specific
socket and the counter decreases by one, it DOES NOT necessarily mean that
this exact socket/transfer is the one that completed. Use
curl_multi_info_read(3) to figure out which easy handle that completed.
The curl_multi_socket_action(3) function informs the application about
updates in the socket (file descriptor) status by doing none, one, or multiple
calls to the socket callback function set with the
CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They
update the status with changes since the previous time the callback was
called.
Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option
with curl_multi_setopt(3). Your application then gets called with
information on how long to wait for socket actions at most before doing the
timeout action: call the curl_multi_socket_action(3) function with the
**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the
curl_multi_timeout(3) function to poll the value at any given time, but
for an event-based system using the callback is far better than relying on
polling the timeout value.
When this function returns error, the state of all transfers are uncertain and
they cannot be continued. curl_multi_socket_action(3) should not be
called again on the same multi handle after an error has been returned, unless
first removing all the handles and adding new ones.
# TYPICAL USAGE
1. Create a multi handle
2. Set the socket callback with CURLMOPT_SOCKETFUNCTION(3)
3. Set the timeout callback with CURLMOPT_TIMERFUNCTION(3), to get to
know what timeout value to use when waiting for socket activities.
4. Add easy handles with curl_multi_add_handle()
5. Provide some means to manage the sockets libcurl is using, so you can check
them for activity. This can be done through your application code, or by way
of an external library such as libevent or glib.
6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...)
to kickstart everything. To get one or more callbacks called.
7. Wait for activity on any of libcurl's sockets, use the timeout value your
callback has been told.
8, When activity is detected, call curl_multi_socket_action() for the
socket(s) that got action. If no activity is detected and the timeout expires,
call curl_multi_socket_action(3) with *CURL_SOCKET_TIMEOUT*.
# EXAMPLE
~~~c
int main(void)
{
/* the event-library gets told when there activity on the socket 'fd',
which we translate to a call to curl_multi_socket_action() */
int running;
CURLM *multi; /* the stack we work with */
int fd; /* the descriptor that had action */
int bitmask; /* what activity that happened */
CURLMcode mc = curl_multi_socket_action(multi, fd, bitmask, &running);
if(mc)
printf("error: %s\n", curl_multi_strerror(mc));
}
~~~
# AVAILABILITY
This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code. See
libcurl-errors(3)

95
deps/curl/docs/libcurl/curl_multi_socket_all.md vendored Normal file
View File

@ -0,0 +1,95 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_socket
Section: 3
Source: libcurl
See-also:
- curl_multi_cleanup (3)
- curl_multi_fdset (3)
- curl_multi_info_read (3)
- curl_multi_init (3)
- the hiperfifo.c example
---
# NAME
curl_multi_socket - reads/writes available data
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd,
int *running_handles);
CURLMcode curl_multi_socket_all(CURLM *multi_handle,
int *running_handles);
~~~
# DESCRIPTION
These functions are deprecated. Do not use. See
curl_multi_socket_action(3) instead.
At return, the integer **running_handles** points to contains the number of
still running easy handles within the multi handle. When this number reaches
zero, all transfers are complete/done. Note that when you call
curl_multi_socket_action(3) on a specific socket and the counter
decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
is the one that completed. Use curl_multi_info_read(3) to figure out
which easy handle that completed.
The curl_multi_socket_action(3) functions inform the application about
updates in the socket (file descriptor) status by doing none, one, or multiple
calls to the socket callback function set with the
CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They
update the status with changes since the previous time the callback was
called.
Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option
with curl_multi_setopt(3). Your application then gets called with
information on how long to wait for socket actions at most before doing the
timeout action: call the curl_multi_socket_action(3) function with the
**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the
curl_multi_timeout(3) function to poll the value at any given time, but
for an event-based system using the callback is far better than relying on
polling the timeout value.
Usage of curl_multi_socket(3) is deprecated, whereas the function is
equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to
0.
Force libcurl to (re-)check all its internal sockets and transfers instead of
just a single one by calling curl_multi_socket_all(3). Note that there
should not be any reason to use this function.
# EXAMPLE
~~~c
int main(void)
{
/* the event-library gets told when there activity on the socket 'fd',
which we translate to a call to curl_multi_socket_action() */
int running;
int rc;
int fd;
CURLM *multi;
rc = curl_multi_socket(multi, fd, &running);
}
~~~
# AVAILABILITY
This function was added in libcurl 7.15.4, and is deemed stable since
7.16.0.
curl_multi_socket(3) is deprecated, use
curl_multi_socket_action(3) instead!
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code.
The return code is for the whole multi stack. Problems still might have
occurred on individual transfers even when one of these functions return OK.

51
deps/curl/docs/libcurl/curl_multi_strerror.md vendored Normal file
View File

@ -0,0 +1,51 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_strerror
Section: 3
Source: libcurl
See-also:
- curl_easy_strerror (3)
- curl_share_strerror (3)
- curl_url_strerror (3)
- libcurl-errors (3)
---
# NAME
curl_multi_strerror - return string describing error code
# SYNOPSIS
~~~c
#include <curl/curl.h>
const char *curl_multi_strerror(CURLMcode errornum);
~~~
# DESCRIPTION
This function returns a string describing the *CURLMcode* error code
passed in the argument *errornum*.
# EXAMPLE
~~~c
int main(void)
{
int still_running;
CURLM *multi = curl_multi_init();
CURLMcode mc = curl_multi_perform(multi, &still_running);
if(mc)
printf("error: %s\n", curl_multi_strerror(mc));
}
~~~
# AVAILABILITY
This function was added in libcurl 7.12.0
# RETURN VALUE
A pointer to a null-terminated string.

89
deps/curl/docs/libcurl/curl_multi_timeout.md vendored Normal file
View File

@ -0,0 +1,89 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_timeout
Section: 3
Source: libcurl
See-also:
- curl_multi_fdset (3)
- curl_multi_info_read (3)
- curl_multi_setopt (3)
- curl_multi_socket (3)
---
# NAME
curl_multi_timeout - how long to wait for action before proceeding
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout);
~~~
# DESCRIPTION
An application using the libcurl multi interface should call
curl_multi_timeout(3) to figure out how long it should wait for socket
actions - at most - before proceeding.
Proceeding means either doing the socket-style timeout action: call the
curl_multi_socket_action(3) function with the **sockfd** argument set
to CURL_SOCKET_TIMEOUT, or call curl_multi_perform(3) if you are using
the simpler and older multi interface approach.
The timeout value returned in the long **timeout** points to, is in number
of milliseconds at this moment. If 0, it means you should proceed immediately
without waiting for anything. If it returns -1, there is no timeout at all set.
An application that uses the *multi_socket* API should not use this function.
It should instead use the CURLMOPT_TIMERFUNCTION(3) option for proper and
desired behavior.
Note: if libcurl returns a -1 timeout here, it just means that libcurl
currently has no stored timeout value. You must not wait too long (more than a
few seconds perhaps) before you call curl_multi_perform(3) again.
# EXAMPLE
~~~c
int main(void)
{
struct timeval timeout;
long timeo;
fd_set fdread;
fd_set fdwrite;
fd_set fdexcep;
int maxfd;
CURLM *multi = curl_multi_init();
curl_multi_timeout(multi, &timeo);
if(timeo < 0)
/* no set timeout, use a default */
timeo = 980;
timeout.tv_sec = timeo / 1000;
timeout.tv_usec = (timeo % 1000) * 1000;
/* wait for activities no longer than the set timeout */
select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout);
}
~~~
# TYPICAL USAGE
Call curl_multi_timeout(3), then wait for action on the sockets. Figure
out which sockets to wait for by calling curl_multi_fdset(3).
When there is activity or timeout, call curl_multi_perform(3) and then
loop - until all transfers are complete.
# AVAILABILITY
This function was added in libcurl 7.15.4.
# RETURN VALUE
The standard CURLMcode for multi interface error codes.

121
deps/curl/docs/libcurl/curl_multi_wait.md vendored Normal file
View File

@ -0,0 +1,121 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_wait
Section: 3
Source: libcurl
See-also:
- curl_multi_fdset (3)
- curl_multi_perform (3)
- curl_multi_poll (3)
---
# NAME
curl_multi_wait - polls on all easy handles in a multi handle
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_wait(CURLM *multi_handle,
struct curl_waitfd extra_fds[],
unsigned int extra_nfds,
int timeout_ms,
int *numfds);
~~~
# DESCRIPTION
curl_multi_wait(3) polls all file descriptors used by the curl easy
handles contained in the given multi handle set. It blocks until activity is
detected on at least one of the handles or *timeout_ms* has passed.
Alternatively, if the multi handle has a pending internal timeout that has a
shorter expiry time than *timeout_ms*, that shorter time is be used
instead to make sure timeout accuracy is reasonably kept.
The calling application may pass additional *curl_waitfd* structures which
are similar to *poll(2)*'s *pollfd* structure to be waited on in the
same call.
On completion, if *numfds* is non-NULL, it gets populated with the total
number of file descriptors on which interesting events occurred. This number
can include both libcurl internal descriptors as well as descriptors provided
in *extra_fds*.
If no extra file descriptors are provided and libcurl has no file descriptor
to offer to wait for, this function returns immediately. (Consider using
curl_multi_poll(3) to avoid this behavior.)
This function is encouraged to be used instead of select(3) when using the
multi interface to allow applications to easier circumvent the common problem
with 1024 maximum file descriptors.
# curl_waitfd
~~~c
struct curl_waitfd {
curl_socket_t fd;
short events;
short revents;
};
~~~
## CURL_WAIT_POLLIN
Bit flag to *curl_waitfd.events* indicating the socket should poll on read
events such as new data received.
## CURL_WAIT_POLLPRI
Bit flag to *curl_waitfd.events* indicating the socket should poll on high
priority read events such as out of band data.
## CURL_WAIT_POLLOUT
Bit flag to *curl_waitfd.events* indicating the socket should poll on
write events such as the socket being clear to write without blocking.
# EXAMPLE
~~~c
int main(void)
{
CURL *easy;
CURLM *multi = curl_multi_init();
int still_running;
/* add the individual easy handle */
curl_multi_add_handle(multi, easy);
do {
CURLMcode mc;
int numfds;
mc = curl_multi_perform(multi, &still_running);
if(mc == CURLM_OK) {
/* wait for activity, timeout or "nothing" */
mc = curl_multi_wait(multi, NULL, 0, 1000, &numfds);
}
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi failed, code %d.\n", mc);
break;
}
} while(still_running);
curl_multi_remove_handle(multi, easy);
}
~~~
# AVAILABILITY
This function was added in libcurl 7.28.0.
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code. See
libcurl-errors(3)

91
deps/curl/docs/libcurl/curl_multi_wakeup.md vendored Normal file
View File

@ -0,0 +1,91 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_multi_wakeup
Section: 3
Source: libcurl
See-also:
- curl_multi_poll (3)
- curl_multi_wait (3)
---
# NAME
curl_multi_wakeup - wakes up a sleeping curl_multi_poll call
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLMcode curl_multi_wakeup(CURLM *multi_handle);
~~~
# DESCRIPTION
This function can be called from any thread and it wakes up a sleeping
curl_multi_poll(3) call that is currently (or is about to be) waiting
for activity or a timeout.
If the function is called when there is no curl_multi_poll(3) call, it
causes the next call to return immediately.
Calling this function only guarantees to wake up the current (or the next if
there is no current) curl_multi_poll(3) call, which means it is possible
that multiple calls to this function wake up the same waiting operation.
This function has no effect on curl_multi_wait(3) calls.
# EXAMPLE
~~~c
extern int time_to_die(void);
extern int set_something_to_signal_thread_1_to_exit(void);
extern int decide_to_stop_thread1();
int main(void)
{
CURL *easy;
CURLM *multi;
int still_running;
/* add the individual easy handle */
curl_multi_add_handle(multi, easy);
/* this is thread 1 */
do {
CURLMcode mc;
int numfds;
mc = curl_multi_perform(multi, &still_running);
if(mc == CURLM_OK) {
/* wait for activity, timeout or wakeup */
mc = curl_multi_poll(multi, NULL, 0, 10000, &numfds);
}
if(time_to_die())
return 1;
} while(still_running);
curl_multi_remove_handle(multi, easy);
/* this is thread 2 */
if(decide_to_stop_thread1()) {
set_something_to_signal_thread_1_to_exit();
curl_multi_wakeup(multi);
}
}
~~~
# AVAILABILITY
Added in 7.68.0
# RETURN VALUE
CURLMcode type, general libcurl multi interface error code.

82
deps/curl/docs/libcurl/curl_pushheader_byname.md vendored Normal file
View File

@ -0,0 +1,82 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_pushheader_byname
Section: 3
Source: libcurl
See-also:
- CURLMOPT_PUSHFUNCTION (3)
- curl_pushheader_bynum (3)
---
# NAME
curl_pushheader_byname - get a push header by name
# SYNOPSIS
~~~c
#include <curl/curl.h>
char *curl_pushheader_byname(struct curl_pushheaders *h, const char *name);
~~~
# DESCRIPTION
This is a function that is only functional within a
CURLMOPT_PUSHFUNCTION(3) callback. It makes no sense to try to use it
elsewhere and it has no function then.
It returns the value for the given header field name (or NULL) for the
incoming server push request. This is a shortcut so that the application does
not have to loop through all headers to find the one it is interested in. The
data this function points to is freed when this callback returns. If more than
one header field use the same name, this returns only the first one.
# EXAMPLE
~~~c
#include <string.h> /* for strncmp */
static int push_cb(CURL *parent,
CURL *easy,
size_t num_headers,
struct curl_pushheaders *headers,
void *clientp)
{
char *headp;
int *transfers = (int *)clientp;
FILE *out;
headp = curl_pushheader_byname(headers, ":path");
if(headp && !strncmp(headp, "/push-", 6)) {
fprintf(stderr, "The PATH is %s\n", headp);
/* save the push here */
out = fopen("pushed-stream", "wb");
/* write to this file */
curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
(*transfers)++; /* one more */
return CURL_PUSH_OK;
}
return CURL_PUSH_DENY;
}
int main(void)
{
int counter;
CURLM *multi = curl_multi_init();
curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb);
curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
}
~~~
# AVAILABILITY
Added in 7.44.0
# RETURN VALUE
Returns a pointer to the header field content or NULL.

69
deps/curl/docs/libcurl/curl_pushheader_bynum.md vendored Normal file
View File

@ -0,0 +1,69 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_pushheader_bynum
Section: 3
Source: libcurl
See-also:
- CURLMOPT_PUSHFUNCTION (3)
- curl_pushheader_byname (3)
---
# NAME
curl_pushheader_bynum - get a push header by index
# SYNOPSIS
~~~c
#include <curl/curl.h>
char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num);
~~~
# DESCRIPTION
This is a function that is only functional within a
CURLMOPT_PUSHFUNCTION(3) callback. It makes no sense to try to use it
elsewhere and it has no function then.
It returns the value for the header field at the given index **num**, for
the incoming server push request or NULL. The data pointed to is freed by
libcurl when this callback returns. The returned pointer points to a
"name:value" string that gets freed when this callback returns.
# EXAMPLE
~~~c
/* output all the incoming push request headers */
static int push_cb(CURL *parent,
CURL *easy,
size_t num_headers,
struct curl_pushheaders *headers,
void *clientp)
{
int i = 0;
char *field;
do {
field = curl_pushheader_bynum(headers, i);
if(field)
fprintf(stderr, "Push header: %s\n", field);
i++;
} while(field);
return CURL_PUSH_OK; /* permission granted */
}
int main(void)
{
CURLM *multi = curl_multi_init();
curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb);
}
~~~
# AVAILABILITY
Added in 7.44.0
# RETURN VALUE
Returns a pointer to the header field content or NULL.

54
deps/curl/docs/libcurl/curl_share_cleanup.md vendored Normal file
View File

@ -0,0 +1,54 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_share_cleanup
Section: 3
Source: libcurl
See-also:
- curl_share_init (3)
- curl_share_setopt (3)
---
# NAME
curl_share_cleanup - Clean up a shared object
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLSHcode curl_share_cleanup(CURLSH *share_handle);
~~~
# DESCRIPTION
This function deletes a shared object. The share handle cannot be used anymore
when this function has been called.
Passing in a NULL pointer in *share_handle* makes this function return
immediately with no action.
# EXAMPLE
~~~c
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
/* use the share, then ... */
curl_share_cleanup(share);
}
~~~
# AVAILABILITY
Added in 7.10
# RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred as *\<curl/curl.h\>* defines. See the libcurl-errors(3) man
page for the full list with descriptions. If an error occurs, then the share
object is not deleted.

56
deps/curl/docs/libcurl/curl_share_init.md vendored Normal file
View File

@ -0,0 +1,56 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_share_init
Section: 3
Source: libcurl
See-also:
- curl_share_cleanup (3)
- curl_share_setopt (3)
---
# NAME
curl_share_init - Create a shared object
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLSH *curl_share_init();
~~~
# DESCRIPTION
This function returns a pointer to a *CURLSH* handle to be used as input
to all the other share-functions, sometimes referred to as a share handle in
some places in the documentation. This init call MUST have a corresponding
call to curl_share_cleanup(3) when all operations using the share are
complete.
This *share handle* is what you pass to curl using the
CURLOPT_SHARE(3) option with curl_easy_setopt(3), to make that
specific curl handle use the data in this share.
# EXAMPLE
~~~c
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
if(sh)
printf("Error: %s\n", curl_share_strerror(sh));
}
~~~
# AVAILABILITY
Added in 7.10
# RETURN VALUE
If this function returns NULL, something went wrong (out of memory, etc.)
and therefore the share object was not created.

71
deps/curl/docs/libcurl/curl_share_setopt.md vendored Normal file
View File

@ -0,0 +1,71 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_share_setopt
Section: 3
Source: libcurl
See-also:
- curl_share_cleanup (3)
- curl_share_init (3)
---
# NAME
curl_share_setopt - Set options for a shared object
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter);
~~~
# DESCRIPTION
Set the *option* to *parameter* for the given *share*.
# OPTIONS
## CURLSHOPT_LOCKFUNC
See CURLSHOPT_LOCKFUNC(3).
## CURLSHOPT_UNLOCKFUNC
See CURLSHOPT_UNLOCKFUNC(3).
## CURLSHOPT_SHARE
See CURLSHOPT_SHARE(3).
## CURLSHOPT_UNSHARE
See CURLSHOPT_UNSHARE(3).
## CURLSHOPT_USERDATA
See CURLSHOPT_USERDATA(3).
# EXAMPLE
~~~c
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
if(sh)
printf("Error: %s\n", curl_share_strerror(sh));
}
~~~
# AVAILABILITY
Added in 7.10
# RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred as *\<curl/curl.h\>* defines. See the libcurl-errors(3) man
page for the full list with descriptions.

50
deps/curl/docs/libcurl/curl_share_strerror.md vendored Normal file
View File

@ -0,0 +1,50 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_share_strerror
Section: 3
Source: libcurl
See-also:
- curl_easy_strerror (3)
- curl_multi_strerror (3)
- curl_url_strerror (3)
- libcurl-errors (3)
---
# NAME
curl_share_strerror - return string describing error code
# SYNOPSIS
~~~c
#include <curl/curl.h>
const char *curl_share_strerror(CURLSHcode errornum);
~~~
# DESCRIPTION
The curl_share_strerror(3) function returns a string describing the
*CURLSHcode* error code passed in the argument *errornum*.
# EXAMPLE
~~~c
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
if(sh)
printf("Error: %s\n", curl_share_strerror(sh));
}
~~~
# AVAILABILITY
This function was added in libcurl 7.12.0
# RETURN VALUE
A pointer to a null-terminated string.

75
deps/curl/docs/libcurl/curl_slist_append.md vendored Normal file
View File

@ -0,0 +1,75 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_slist_append
Section: 3
Source: libcurl
See-also:
- curl_slist_free_all (3)
---
# NAME
curl_slist_append - add a string to an slist
# SYNOPSIS
~~~c
#include <curl/curl.h>
struct curl_slist *curl_slist_append(struct curl_slist *list,
const char *string);
~~~
# DESCRIPTION
curl_slist_append(3) appends a string to a linked list of strings. The
existing **list** should be passed as the first argument and the new list is
returned from this function. Pass in NULL in the **list** argument to create
a new list. The specified **string** has been appended when this function
returns. curl_slist_append(3) copies the string.
The list should be freed again (after usage) with
curl_slist_free_all(3).
# EXAMPLE
~~~c
int main(void)
{
CURL *handle;
struct curl_slist *slist = NULL;
struct curl_slist *temp = NULL;
slist = curl_slist_append(slist, "pragma:");
if(!slist)
return -1;
temp = curl_slist_append(slist, "Accept:");
if(!temp) {
curl_slist_free_all(slist);
return -1;
}
slist = temp;
curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist);
curl_easy_perform(handle);
curl_slist_free_all(slist); /* free the list again */
}
~~~
# AVAILABILITY
Always
# RETURN VALUE
A null pointer is returned if anything went wrong, otherwise the new list
pointer is returned. To avoid overwriting an existing non-empty list on
failure, the new list should be returned to a temporary variable which can
be tested for NULL before updating the original list pointer.

58
deps/curl/docs/libcurl/curl_slist_free_all.md vendored Normal file
View File

@ -0,0 +1,58 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_slist_free_all
Section: 3
Source: libcurl
See-also:
- curl_slist_append (3)
---
# NAME
curl_slist_free_all - free an entire curl_slist list
# SYNOPSIS
~~~c
#include <curl/curl.h>
void curl_slist_free_all(struct curl_slist *list);
~~~
# DESCRIPTION
curl_slist_free_all() removes all traces of a previously built curl_slist
linked list.
Passing in a NULL pointer in *list* makes this function return immediately
with no action.
# EXAMPLE
~~~c
int main(void)
{
CURL *handle;
struct curl_slist *slist = NULL;
slist = curl_slist_append(slist, "X-libcurl: coolness");
if(!slist)
return -1;
curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist);
curl_easy_perform(handle);
curl_slist_free_all(slist); /* free the list again */
}
~~~
# AVAILABILITY
Always
# RETURN VALUE
Nothing.

57
deps/curl/docs/libcurl/curl_strequal.md vendored Normal file
View File

@ -0,0 +1,57 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_strequal
Section: 3
Source: libcurl
See-also:
- strcasecmp (3)
- strcmp (3)
---
# NAME
curl_strequal, curl_strnequal - case insensitive string comparisons
# SYNOPSIS
~~~c
#include <curl/curl.h>
int curl_strequal(const char *str1, const char *str2);
int curl_strnequal(const char *str1, const char *str2, size_t length);
~~~
# DESCRIPTION
The curl_strequal(3) function compares the two strings *str1* and
*str2*, ignoring the case of the characters. It returns a non-zero (TRUE)
integer if the strings are identical.
The **curl_strnequal()** function is similar, except it only compares the
first *length* characters of *str1*.
These functions are provided by libcurl to enable applications to compare
strings in a truly portable manner. There are no standard portable case
insensitive string comparison functions. These two work on all platforms.
# EXAMPLE
~~~c
int main(int argc, char **argv)
{
const char *name = "compare";
if(curl_strequal(name, argv[1]))
printf("Name and input matches\n");
if(curl_strnequal(name, argv[1], 5))
printf("Name and input matches in the 5 first bytes\n");
}
~~~
# AVAILABILITY
Always
# RETURN VALUE
Non-zero if the strings are identical. Zero if they are not.

57
deps/curl/docs/libcurl/curl_strnequal.md vendored Normal file
View File

@ -0,0 +1,57 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_strequal
Section: 3
Source: libcurl
See-also:
- strcasecmp (3)
- strcmp (3)
---
# NAME
curl_strequal, curl_strnequal - case insensitive string comparisons
# SYNOPSIS
~~~c
#include <curl/curl.h>
int curl_strequal(const char *str1, const char *str2);
int curl_strnequal(const char *str1, const char *str2, size_t length);
~~~
# DESCRIPTION
The curl_strequal(3) function compares the two strings *str1* and
*str2*, ignoring the case of the characters. It returns a non-zero (TRUE)
integer if the strings are identical.
The **curl_strnequal()** function is similar, except it only compares the
first *length* characters of *str1*.
These functions are provided by libcurl to enable applications to compare
strings in a truly portable manner. There are no standard portable case
insensitive string comparison functions. These two work on all platforms.
# EXAMPLE
~~~c
int main(int argc, char **argv)
{
const char *name = "compare";
if(curl_strequal(name, argv[1]))
printf("Name and input matches\n");
if(curl_strnequal(name, argv[1], 5))
printf("Name and input matches in the 5 first bytes\n");
}
~~~
# AVAILABILITY
Always
# RETURN VALUE
Non-zero if the strings are identical. Zero if they are not.

65
deps/curl/docs/libcurl/curl_unescape.md vendored Normal file
View File

@ -0,0 +1,65 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_unescape
Section: 3
Source: libcurl
See-also:
- RFC 2396
- curl_easy_escape (3)
- curl_easy_unescape (3)
- curl_free (3)
---
# NAME
curl_unescape - URL decodes the given string
# SYNOPSIS
~~~c
#include <curl/curl.h>
char *curl_unescape(const char *input, int length);
~~~
# DESCRIPTION
Obsolete function. Use curl_easy_unescape(3) instead.
This function converts the URL encoded string **input** to a "plain string"
and return that as a new allocated string. All input characters that are URL
encoded (%XX where XX is a two-digit hexadecimal number) are converted to
their plain text versions.
If the **length** argument is set to 0, curl_unescape(3) calls
strlen() on **input** to find out the size.
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) {
char *decoded = curl_unescape("%63%75%72%6c", 12);
if(decoded) {
/* do not assume printf() works on the decoded data */
printf("Decoded: ");
/* ... */
curl_free(decoded);
}
}
}
~~~
# AVAILABILITY
Since 7.15.4, curl_easy_unescape(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.

64
deps/curl/docs/libcurl/curl_url.md vendored Normal file
View File

@ -0,0 +1,64 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_url
Section: 3
Source: libcurl
See-also:
- CURLOPT_CURLU (3)
- curl_url_cleanup (3)
- curl_url_dup (3)
- curl_url_get (3)
- curl_url_set (3)
- curl_url_strerror (3)
---
# NAME
curl_url - returns a new URL handle
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLU *curl_url();
~~~
# DESCRIPTION
This function allocates a URL object and returns a *CURLU* handle for it,
to be used as input to all other URL API functions.
This is a handle to a URL object that holds or can hold URL components for a
single URL. When the object is first created, there is of course no components
stored. They are then set in the object with the curl_url_set(3)
function.
# EXAMPLE
~~~c
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
char *scheme;
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
if(!rc) {
printf("the scheme is %s\n", scheme);
curl_free(scheme);
}
curl_url_cleanup(url);
}
}
~~~
# AVAILABILITY
Added in 7.62.0
# RETURN VALUE
Returns a **CURLU *** if successful, or NULL if out of memory.

51
deps/curl/docs/libcurl/curl_url_cleanup.md vendored Normal file
View File

@ -0,0 +1,51 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_url_cleanup
Section: 3
Source: libcurl
See-also:
- CURLOPT_CURLU (3)
- curl_url (3)
- curl_url_dup (3)
- curl_url_get (3)
- curl_url_set (3)
---
# NAME
curl_url_cleanup - free the URL handle
# SYNOPSIS
~~~c
#include <curl/curl.h>
void curl_url_cleanup(CURLU *handle);
~~~
# DESCRIPTION
Frees all the resources associated with the given *CURLU* handle!
Passing in a NULL pointer in *handle* makes this function return
immediately with no action.
# EXAMPLE
~~~c
int main(void)
{
CURLU *url = curl_url();
curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
curl_url_cleanup(url);
}
~~~
# AVAILABILITY
Added in 7.62.0
# RETURN VALUE
none

56
deps/curl/docs/libcurl/curl_url_dup.md vendored Normal file
View File

@ -0,0 +1,56 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_url_dup
Section: 3
Source: libcurl
See-also:
- CURLOPT_CURLU (3)
- curl_url (3)
- curl_url_cleanup (3)
- curl_url_get (3)
- curl_url_set (3)
---
# NAME
curl_url_dup - duplicate a URL handle
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLU *curl_url_dup(const CURLU *inhandle);
~~~
# DESCRIPTION
Duplicates the URL object the input *CURLU* *inhandle* identifies and
returns a pointer to the copy as a new *CURLU* handle. The new handle also
needs to be freed with curl_url_cleanup(3).
# EXAMPLE
~~~c
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
CURLU *url2;
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
url2 = curl_url_dup(url); /* clone it! */
curl_url_cleanup(url2);
}
curl_url_cleanup(url);
}
~~~
# AVAILABILITY
Added in 7.62.0
# RETURN VALUE
Returns a new handle or NULL if out of memory.

210
deps/curl/docs/libcurl/curl_url_get.md vendored Normal file
View File

@ -0,0 +1,210 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_url_get
Section: 3
Source: libcurl
See-also:
- CURLOPT_CURLU (3)
- curl_url (3)
- curl_url_cleanup (3)
- curl_url_dup (3)
- curl_url_set (3)
- curl_url_strerror (3)
---
# NAME
curl_url_get - extract a part from a URL
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLUcode curl_url_get(const CURLU *url,
CURLUPart part,
char **content,
unsigned int flags);
~~~
# DESCRIPTION
Given a *url* handle of a URL object, this function extracts an individual
piece or the full URL from it.
The *part* argument specifies which part to extract (see list below) and
*content* points to a 'char *' to get updated to point to a newly
allocated string with the contents.
The *flags* argument is a bitmask with individual features.
The returned content pointer must be freed with curl_free(3) after use.
# FLAGS
The flags argument is zero, one or more bits set in a bitmask.
## CURLU_DEFAULT_PORT
If the handle has no port stored, this option makes curl_url_get(3)
return the default port for the used scheme.
## CURLU_DEFAULT_SCHEME
If the handle has no scheme stored, this option makes curl_url_get(3)
return the default scheme instead of error.
## CURLU_NO_DEFAULT_PORT
Instructs curl_url_get(3) to not return a port number if it matches the
default port for the scheme.
## CURLU_URLDECODE
Asks curl_url_get(3) to URL decode the contents before returning it. It
does not decode the scheme, the port number or the full URL.
The query component also gets plus-to-space conversion as a bonus when this
bit is set.
Note that this URL decoding is charset unaware and you get a zero terminated
string back with data that could be intended for a particular encoding.
If there are byte values lower than 32 in the decoded string, the get
operation returns an error instead.
## CURLU_URLENCODE
If set, curl_url_get(3) URL encodes the hostname part when a full URL is
retrieved. If not set (default), libcurl returns the URL with the hostname raw
to support IDN names to appear as-is. IDN hostnames are typically using
non-ASCII bytes that otherwise gets percent-encoded.
Note that even when not asking for URL encoding, the '%' (byte 37) is URL
encoded to make sure the hostname remains valid.
## CURLU_PUNYCODE
If set and *CURLU_URLENCODE* is not set, and asked to retrieve the
**CURLUPART_HOST** or **CURLUPART_URL** parts, libcurl returns the host
name in its punycode version if it contains any non-ASCII octets (and is an
IDN name).
If libcurl is built without IDN capabilities, using this bit makes
curl_url_get(3) return *CURLUE_LACKS_IDN* if the hostname contains
anything outside the ASCII range.
(Added in curl 7.88.0)
## CURLU_PUNY2IDN
If set and asked to retrieve the **CURLUPART_HOST** or **CURLUPART_URL**
parts, libcurl returns the hostname in its IDN (International Domain Name)
UTF-8 version if it otherwise is a punycode version. If the punycode name
cannot be converted to IDN correctly, libcurl returns
*CURLUE_BAD_HOSTNAME*.
If libcurl is built without IDN capabilities, using this bit makes
curl_url_get(3) return *CURLUE_LACKS_IDN* if the hostname is using
punycode.
(Added in curl 8.3.0)
# PARTS
## CURLUPART_URL
When asked to return the full URL, curl_url_get(3) returns a normalized
and possibly cleaned up version using all available URL parts.
We advise using the *CURLU_PUNYCODE* option to get the URL as "normalized"
as possible since IDN allows hostnames to be written in many different ways
that still end up the same punycode version.
## CURLUPART_SCHEME
Scheme cannot be URL decoded on get.
## CURLUPART_USER
## CURLUPART_PASSWORD
## CURLUPART_OPTIONS
The options field is an optional field that might follow the password in the
userinfo part. It is only recognized/used when parsing URLs for the following
schemes: pop3, smtp and imap. The URL API still allows users to set and get
this field independently of scheme when not parsing full URLs.
## CURLUPART_HOST
The hostname. If it is an IPv6 numeric address, the zone id is not part of it
but is provided separately in *CURLUPART_ZONEID*. IPv6 numerical addresses
are returned within brackets ([]).
IPv6 names are normalized when set, which should make them as short as
possible while maintaining correct syntax.
## CURLUPART_ZONEID
If the hostname is a numeric IPv6 address, this field might also be set.
## CURLUPART_PORT
A port cannot be URL decoded on get. This number is returned in a string just
like all other parts. That string is guaranteed to hold a valid port number in
ASCII using base 10.
## CURLUPART_PATH
The *part* is always at least a slash ('/') even if no path was supplied
in the URL. A URL path always starts with a slash.
## CURLUPART_QUERY
The initial question mark that denotes the beginning of the query part is a
delimiter only. It is not part of the query contents.
A not-present query returns *part* set to NULL.
A zero-length query returns *part* as a zero-length string.
The query part gets pluses converted to space when asked to URL decode on get
with the CURLU_URLDECODE bit.
## CURLUPART_FRAGMENT
The initial hash sign that denotes the beginning of the fragment is a
delimiter only. It is not part of the fragment contents.
# EXAMPLE
~~~c
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
char *scheme;
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
if(!rc) {
printf("the scheme is %s\n", scheme);
curl_free(scheme);
}
curl_url_cleanup(url);
}
}
~~~
# AVAILABILITY
Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
# RETURN VALUE
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
fine. See the libcurl-errors(3) man page for the full list with
descriptions.
If this function returns an error, no URL part is returned.

247
deps/curl/docs/libcurl/curl_url_set.md vendored Normal file
View File

@ -0,0 +1,247 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_url_set
Section: 3
Source: libcurl
See-also:
- CURLOPT_CURLU (3)
- curl_url (3)
- curl_url_cleanup (3)
- curl_url_dup (3)
- curl_url_get (3)
- curl_url_strerror (3)
---
# NAME
curl_url_set - set a URL part
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLUcode curl_url_set(CURLU *url,
CURLUPart part,
const char *content,
unsigned int flags);
~~~
# DESCRIPTION
The *url* handle to work on, passed in as the first argument, must be a
handle previously created by curl_url(3) or curl_url_dup(3).
This function sets or updates individual URL components, or parts, held by the
URL object the handle identifies.
The *part* argument should identify the particular URL part (see list
below) to set or change, with *content* pointing to a null-terminated
string with the new contents for that URL part. The contents should be in the
form and encoding they would use in a URL: URL encoded.
When setting part in the URL object that was previously already set, it
replaces the data that was previously stored for that part with the new
*content*.
The caller does not have to keep *content* around after a successful call
as this function copies the content.
Setting a part to a NULL pointer removes that part's contents from the
*CURLU* handle.
By default, this API only accepts URLs using schemes for protocols that are
supported built-in. To make libcurl parse URLs generically even for schemes it
does not know about, the **CURLU_NON_SUPPORT_SCHEME** flags bit must be
set. Otherwise, this function returns *CURLUE_UNSUPPORTED_SCHEME* for URL
schemes it does not recognize.
This function has an 8 MB maximum length limit for all provided input strings.
In the real world, excessively long fields in URLs cause problems even if this
API accepts them.
When setting or updating contents of individual URL parts, this API might
accept data that would not be otherwise possible to set in the string when it
gets populated as a result of a full URL parse. Beware. If done so, extracting
a full URL later on from such components might render an invalid URL.
The *flags* argument is a bitmask with independent features.
# PARTS
## CURLUPART_URL
Allows the full URL of the handle to be replaced. If the handle already is
populated with a URL, the new URL can be relative to the previous.
When successfully setting a new URL, relative or absolute, the handle contents
is replaced with the components of the newly set URL.
Pass a pointer to a null-terminated string to the *url* parameter. The
string must point to a correctly formatted "RFC 3986+" URL or be a NULL
pointer.
Unless *CURLU_NO_AUTHORITY* is set, a blank hostname is not allowed in
the URL.
## CURLUPART_SCHEME
Scheme cannot be URL decoded on set. libcurl only accepts setting schemes up
to 40 bytes long.
## CURLUPART_USER
## CURLUPART_PASSWORD
## CURLUPART_OPTIONS
The options field is an optional field that might follow the password in the
userinfo part. It is only recognized/used when parsing URLs for the following
schemes: pop3, smtp and imap. This function however allows users to
independently set this field.
## CURLUPART_HOST
The hostname. If it is International Domain Name (IDN) the string must then be
encoded as your locale says or UTF-8 (when WinIDN is used). If it is a
bracketed IPv6 numeric address it may contain a zone id (or you can use
*CURLUPART_ZONEID*).
Unless *CURLU_NO_AUTHORITY* is set, a blank hostname is not allowed to set.
## CURLUPART_ZONEID
If the hostname is a numeric IPv6 address, this field can also be set.
## CURLUPART_PORT
The port number cannot be URL encoded on set. The given port number is
provided as a string and the decimal number in it must be between 0 and
65535. Anything else returns an error.
## CURLUPART_PATH
If a path is set in the URL without a leading slash, a slash is prepended
automatically.
## CURLUPART_QUERY
The query part gets spaces converted to pluses when asked to URL encode on set
with the *CURLU_URLENCODE* bit.
If used together with the *CURLU_APPENDQUERY* bit, the provided part is
appended on the end of the existing query.
The question mark in the URL is not part of the actual query contents.
## CURLUPART_FRAGMENT
The hash sign in the URL is not part of the actual fragment contents.
# FLAGS
The flags argument is zero, one or more bits set in a bitmask.
## CURLU_APPENDQUERY
Can be used when setting the *CURLUPART_QUERY* component. The provided new
part is then appended at the end of the existing query - and if the previous
part did not end with an ampersand (&), an ampersand gets inserted before the
new appended part.
When *CURLU_APPENDQUERY* is used together with *CURLU_URLENCODE*, the
first '=' symbol is not URL encoded.
## CURLU_NON_SUPPORT_SCHEME
If set, allows curl_url_set(3) to set a non-supported scheme.
## CURLU_URLENCODE
When set, curl_url_set(3) URL encodes the part on entry, except for
scheme, port and URL.
When setting the path component with URL encoding enabled, the slash character
is be skipped.
The query part gets space-to-plus conversion before the URL conversion.
This URL encoding is charset unaware and converts the input in a byte-by-byte
manner.
## CURLU_DEFAULT_SCHEME
If set, allows the URL to be set without a scheme and then sets that to the
default scheme: HTTPS. Overrides the *CURLU_GUESS_SCHEME* option if both
are set.
## CURLU_GUESS_SCHEME
If set, allows the URL to be set without a scheme and it instead "guesses"
which scheme that was intended based on the hostname. If the outermost
subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme is
used, otherwise it picks HTTP. Conflicts with the *CURLU_DEFAULT_SCHEME*
option which takes precedence if both are set.
## CURLU_NO_AUTHORITY
If set, skips authority checks. The RFC allows individual schemes to omit the
host part (normally the only mandatory part of the authority), but libcurl
cannot know whether this is permitted for custom schemes. Specifying the flag
permits empty authority sections, similar to how file scheme is handled.
## CURLU_PATH_AS_IS
When set for **CURLUPART_URL**, this skips the normalization of the
path. That is the procedure where libcurl otherwise removes sequences of
dot-slash and dot-dot etc. The same option used for transfers is called
CURLOPT_PATH_AS_IS(3).
## CURLU_ALLOW_SPACE
If set, the URL parser allows space (ASCII 32) where possible. The URL syntax
does normally not allow spaces anywhere, but they should be encoded as %20
or '+'. When spaces are allowed, they are still not allowed in the scheme.
When space is used and allowed in a URL, it is stored as-is unless
*CURLU_URLENCODE* is also set, which then makes libcurl URL encode the
space before stored. This affects how the URL is constructed when
curl_url_get(3) is subsequently used to extract the full URL or
individual parts. (Added in 7.78.0)
## CURLU_DISALLOW_USER
If set, the URL parser does not accept embedded credentials for the
**CURLUPART_URL**, and instead returns **CURLUE_USER_NOT_ALLOWED** for
such URLs.
# EXAMPLE
~~~c
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
/* change it to an FTP URL */
rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
}
curl_url_cleanup(url);
}
~~~
# AVAILABILITY
Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
# RETURN VALUE
Returns a *CURLUcode* error value, which is CURLUE_OK (0) if everything
went fine. See the libcurl-errors(3) man page for the full list with
descriptions.
The input string passed to curl_url_set(3) must be shorter than eight
million bytes. Otherwise this function returns **CURLUE_MALFORMED_INPUT**.
If this function returns an error, no URL part is set.

53
deps/curl/docs/libcurl/curl_url_strerror.md vendored Normal file
View File

@ -0,0 +1,53 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_url_strerror
Section: 3
Source: libcurl
See-also:
- curl_easy_strerror (3)
- curl_multi_strerror (3)
- curl_share_strerror (3)
- curl_url_get (3)
- curl_url_set (3)
- libcurl-errors (3)
---
# NAME
curl_url_strerror - return string describing error code
# SYNOPSIS
~~~c
#include <curl/curl.h>
const char *curl_url_strerror(CURLUcode errornum);
~~~
# DESCRIPTION
This function returns a string describing the CURLUcode error code passed in
the argument *errornum*.
# EXAMPLE
~~~c
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(rc)
printf("URL error: %s\n", curl_url_strerror(rc));
curl_url_cleanup(url);
}
~~~
# AVAILABILITY
Added in 7.80.0
# RETURN VALUE
A pointer to a null-terminated string.

46
deps/curl/docs/libcurl/curl_version.md vendored Normal file
View File

@ -0,0 +1,46 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_version
Section: 3
Source: libcurl
See-also:
- curl_version_info (3)
---
# NAME
curl_version - returns the libcurl version string
# SYNOPSIS
~~~c
#include <curl/curl.h>
char *curl_version();
~~~
# DESCRIPTION
Returns a human readable string with the version number of libcurl and some of
its important components (like OpenSSL version).
We recommend using curl_version_info(3) instead!
# EXAMPLE
~~~c
int main(void)
{
printf("libcurl version %s\n", curl_version());
}
~~~
# AVAILABILITY
Always
# RETURN VALUE
A pointer to a null-terminated string. The string resides in a statically
allocated buffer and must not be freed by the caller.

381
deps/curl/docs/libcurl/curl_version_info.md vendored Normal file
View File

@ -0,0 +1,381 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_version_info
Section: 3
Source: libcurl
See-also:
- curl_version (3)
---
# NAME
curl_version_info - returns runtime libcurl version info
# SYNOPSIS
~~~c
#include <curl/curl.h>
curl_version_info_data *curl_version_info(CURLversion age);
~~~
# DESCRIPTION
Returns a pointer to a filled in static struct with information about various
features in the running version of libcurl. *age* should be set to the
version of this functionality by the time you write your program. This way,
libcurl always returns a proper struct that your program understands, while
programs in the future might get a different struct. **CURLVERSION_NOW** is
the most recent one for the library you have installed:
~~~c
data = curl_version_info(CURLVERSION_NOW);
~~~
Applications should use this information to judge if things are possible to do
or not, instead of using compile-time checks, as dynamic/DLL libraries can be
changed independent of applications.
This function can alter the returned static data as long as
curl_global_init(3) has not been called. It is therefore not thread-safe
before libcurl initialization occurs.
The curl_version_info_data struct looks like this
~~~c
typedef struct {
CURLversion age; /* see description below */
const char *version; /* human readable string */
unsigned int version_num; /* numeric representation */
const char *host; /* human readable string */
int features; /* bitmask, see below */
char *ssl_version; /* human readable string */
long ssl_version_num; /* not used, always zero */
const char *libz_version; /* human readable string */
const char *const *protocols; /* protocols */
/* when 'age' is CURLVERSION_SECOND or higher, the members below exist */
const char *ares; /* human readable string */
int ares_num; /* number */
/* when 'age' is CURLVERSION_THIRD or higher, the members below exist */
const char *libidn; /* human readable string */
/* when 'age' is CURLVERSION_FOURTH or higher (>= 7.16.1), the members
below exist */
int iconv_ver_num; /* '_libiconv_version' if iconv support enabled */
const char *libssh_version; /* human readable string */
/* when 'age' is CURLVERSION_FIFTH or higher (>= 7.57.0), the members
below exist */
unsigned int brotli_ver_num; /* Numeric Brotli version
(MAJOR << 24) | (MINOR << 12) | PATCH */
const char *brotli_version; /* human readable string. */
/* when 'age' is CURLVERSION_SIXTH or higher (>= 7.66.0), the members
below exist */
unsigned int nghttp2_ver_num; /* Numeric nghttp2 version
(MAJOR << 16) | (MINOR << 8) | PATCH */
const char *nghttp2_version; /* human readable string. */
const char *quic_version; /* human readable quic (+ HTTP/3) library +
version or NULL */
/* when 'age' is CURLVERSION_SEVENTH or higher (>= 7.70.0), the members
below exist */
const char *cainfo; /* the built-in default CURLOPT_CAINFO, might
be NULL */
const char *capath; /* the built-in default CURLOPT_CAPATH, might
be NULL */
/* when 'age' is CURLVERSION_EIGHTH or higher (>= 7.71.0), the members
below exist */
unsigned int zstd_ver_num; /* Numeric Zstd version
(MAJOR << 24) | (MINOR << 12) | PATCH */
const char *zstd_version; /* human readable string. */
/* when 'age' is CURLVERSION_NINTH or higher (>= 7.75.0), the members
below exist */
const char *hyper_version; /* human readable string. */
/* when 'age' is CURLVERSION_TENTH or higher (>= 7.77.0), the members
below exist */
const char *gsasl_version; /* human readable string. */
/* when 'age' is CURLVERSION_ELEVENTH or higher (>= 7.87.0), the members
below exist */
const char *const *feature_names; /* Feature names. */
} curl_version_info_data;
~~~
*age* describes what the age of this struct is. The number depends on how
new the libcurl you are using is. You are however guaranteed to get a struct
that you have a matching struct for in the header, as you tell libcurl your
"age" with the input argument.
*version* is just an ascii string for the libcurl version.
*version_num* is a 24 bit number created like this: \<8 bits major number\> |
\<8 bits minor number\> | \<8 bits patch number\>. Version 7.9.8 is therefore
returned as 0x070908.
*host* is an ascii string showing what host information that this libcurl
was built for. As discovered by a configure script or set by the build
environment.
*features* is a bit mask representing available features. It can have none,
one or more bits set. The use of this field is deprecated: use
*feature_names* instead. The feature names description below lists the
associated bits.
*feature_names* is a pointer to an array of string pointers, containing the
names of the features that libcurl supports. The array is terminated by a NULL
entry. See the list of features names below.
*ssl_version* is an ASCII string for the TLS library name + version used. If
libcurl has no SSL support, this is NULL. For example "Schannel", "Secure
Transport" or "OpenSSL/1.1.0g".
*ssl_version_num* is always 0.
*libz_version* is an ASCII string (there is no numerical version). If
libcurl has no libz support, this is NULL.
*protocols* is a pointer to an array of char * pointers, containing the
names protocols that libcurl supports (using lowercase letters). The protocol
names are the same as would be used in URLs. The array is terminated by a NULL
entry.
# FEATURES
## alt-svc
*features* mask bit: CURL_VERSION_ALTSVC
HTTP Alt-Svc parsing and the associated options (Added in 7.64.1)
## AsynchDNS
*features* mask bit: CURL_VERSION_ASYNCHDNS
libcurl was built with support for asynchronous name lookups, which allows
more exact timeouts (even on Windows) and less blocking when using the multi
interface. (added in 7.10.7)
## brotli
*features* mask bit: CURL_VERSION_BROTLI
supports HTTP Brotli content encoding using libbrotlidec (Added in 7.57.0)
## Debug
*features* mask bit: CURL_VERSION_DEBUG
libcurl was built with debug capabilities (added in 7.10.6)
## gsasl
*features* mask bit: CURL_VERSION_GSASL
libcurl was built with libgsasl and thus with some extra SCRAM-SHA
authentication methods. (added in 7.76.0)
## GSS-API
*features* mask bit: CURL_VERSION_GSSAPI
libcurl was built with support for GSS-API. This makes libcurl use provided
functions for Kerberos and SPNEGO authentication. It also allows libcurl
to use the current user credentials without the app having to pass them on.
(Added in 7.38.0)
## HSTS
*features* mask bit: CURL_VERSION_HSTS
libcurl was built with support for HSTS (HTTP Strict Transport Security)
(Added in 7.74.0)
## HTTP2
*features* mask bit: CURL_VERSION_HTTP2
libcurl was built with support for HTTP2.
(Added in 7.33.0)
## HTTP3
*features* mask bit: CURL_VERSION_HTTP3
HTTP/3 and QUIC support are built-in (Added in 7.66.0)
## HTTPS-proxy
*features* mask bit: CURL_VERSION_HTTPS_PROXY
libcurl was built with support for HTTPS-proxy.
(Added in 7.52.0)
## IDN
*features* mask bit: CURL_VERSION_IDN
libcurl was built with support for IDNA, domain names with international
letters. (Added in 7.12.0)
## IPv6
*features* mask bit: CURL_VERSION_IPV6
supports IPv6
## Kerberos
*features* mask bit: CURL_VERSION_KERBEROS5
supports Kerberos V5 authentication for FTP, IMAP, LDAP, POP3, SMTP and
SOCKSv5 proxy. (Added in 7.40.0)
## Largefile
*features* mask bit: CURL_VERSION_LARGEFILE
libcurl was built with support for large files. (Added in 7.11.1)
## libz
*features* mask bit: CURL_VERSION_LIBZ
supports HTTP deflate using libz (Added in 7.10)
## MultiSSL
*features* mask bit: CURL_VERSION_MULTI_SSL
libcurl was built with multiple SSL backends. For details, see
curl_global_sslset(3).
(Added in 7.56.0)
## NTLM
*features* mask bit: CURL_VERSION_NTLM
supports HTTP NTLM (added in 7.10.6)
## NTLM_WB
*features* mask bit: CURL_VERSION_NTLM_WB
libcurl was built with support for NTLM delegation to a winbind helper.
(Added in 7.22.0)
## PSL
*features* mask bit: CURL_VERSION_PSL
libcurl was built with support for Mozilla's Public Suffix List. This makes
libcurl ignore cookies with a domain that is on the list.
(Added in 7.47.0)
## SPNEGO
*features* mask bit: CURL_VERSION_SPNEGO
libcurl was built with support for SPNEGO authentication (Simple and Protected
GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8)
## SSL
*features* mask bit: CURL_VERSION_SSL
supports SSL (HTTPS/FTPS) (Added in 7.10)
## SSPI
*features* mask bit: CURL_VERSION_SSPI
libcurl was built with support for SSPI. This is only available on Windows and
makes libcurl use Windows-provided functions for Kerberos, NTLM, SPNEGO and
Digest authentication. It also allows libcurl to use the current user
credentials without the app having to pass them on. (Added in 7.13.2)
## threadsafe
*features* mask bit: CURL_VERSION_THREADSAFE
libcurl was built with thread-safety support (Atomic or SRWLOCK) to protect
curl initialization. (Added in 7.84.0) See libcurl-thread(3)
## TLS-SRP
*features* mask bit: CURL_VERSION_TLSAUTH_SRP
libcurl was built with support for TLS-SRP (in one or more of the built-in TLS
backends). (Added in 7.21.4)
## TrackMemory
*features* mask bit: CURL_VERSION_CURLDEBUG
libcurl was built with memory tracking debug capabilities. This is mainly of
interest for libcurl hackers. (added in 7.19.6)
## Unicode
*features* mask bit: CURL_VERSION_UNICODE
libcurl was built with Unicode support on Windows. This makes non-ASCII
characters work in filenames and options passed to libcurl. (Added in 7.72.0)
## UnixSockets
*features* mask bit: CURL_VERSION_UNIX_SOCKETS
libcurl was built with support for Unix domain sockets.
(Added in 7.40.0)
## zstd
*features* mask bit: CURL_VERSION_ZSTD
supports HTTP zstd content encoding using zstd library (Added in 7.72.0)
## no name
*features* mask bit: CURL_VERSION_CONV
libcurl was built with support for character conversions, as provided by the
CURLOPT_CONV_* callbacks. Always 0 since 7.82.0. (Added in 7.15.4,
deprecated.)
## no name
*features* mask bit: CURL_VERSION_GSSNEGOTIATE
supports HTTP GSS-Negotiate (added in 7.10.6, deprecated in 7.38.0)
## no name
*features* mask bit: CURL_VERSION_KERBEROS4
supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0.
# EXAMPLE
~~~c
int main(void)
{
curl_version_info_data *ver = curl_version_info(CURLVERSION_NOW);
printf("libcurl version %u.%u.%u\n",
(ver->version_num >> 16) & 0xff,
(ver->version_num >> 8) & 0xff,
ver->version_num & 0xff);
}
~~~
# AVAILABILITY
Added in 7.10
# RETURN VALUE
A pointer to a curl_version_info_data struct.
curl_version(3)

142
deps/curl/docs/libcurl/curl_ws_meta.md vendored Normal file
View File

@ -0,0 +1,142 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_ws_meta
Section: 3
Source: libcurl
See-also:
- curl_easy_getinfo (3)
- curl_easy_setopt (3)
- curl_ws_recv (3)
- curl_ws_send (3)
- libcurl-ws (3)
---
# NAME
curl_ws_meta - meta data WebSocket information
# SYNOPSIS
~~~c
#include <curl/curl.h>
const struct curl_ws_frame *curl_ws_meta(CURL *curl);
~~~
# DESCRIPTION
This function call is EXPERIMENTAL.
When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on
received WebSocket traffic, curl_ws_meta(3) can be called from within
the callback to provide additional information about the current frame.
This function only works from within the callback, and only when receiving
WebSocket data.
This function requires an easy handle as input argument for libcurl to know
what transfer the question is about, but as there is no such pointer provided
to the callback by libcurl itself, applications that want to use
curl_ws_meta(3) need to pass it on to the callback on its own.
# struct curl_ws_frame
~~~c
struct curl_ws_frame {
int age;
int flags;
curl_off_t offset;
curl_off_t bytesleft;
};
~~~
## `age`
This field specify the age of this struct. It is always zero for now.
## `flags`
This is a bitmask with individual bits set that describes the WebSocket data.
See the list below.
## `offset`
When this frame is a continuation of fragment data already delivered, this is
the offset into the final fragment where this piece belongs.
## `bytesleft`
If this is not a complete fragment, the *bytesleft* field informs about how
many additional bytes are expected to arrive before this fragment is complete.
# FLAGS
## CURLWS_TEXT
The buffer contains text data. Note that this makes a difference to WebSocket
but libcurl itself does not make any verification of the content or
precautions that you actually receive valid UTF-8 content.
## CURLWS_BINARY
This is binary data.
## CURLWS_CONT
This is not the final fragment of the message, it implies that there is
another fragment coming as part of the same message.
## CURLWS_CLOSE
This transfer is now closed.
## CURLWS_PING
This as an incoming ping message, that expects a pong response.
# EXAMPLE
~~~c
/* we pass a pointer to this struct to the callback */
struct customdata {
CURL *easy;
void *ptr;
};
static size_t writecb(unsigned char *buffer,
size_t size, size_t nitems, void *p)
{
struct customdata *c = (struct customdata *)p;
const struct curl_ws_frame *m = curl_ws_meta(c->easy);
printf("flags: %x\n", m->flags);
}
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
struct customdata custom;
custom.easy = curl;
custom.ptr = NULL;
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom);
curl_easy_perform(curl);
}
}
~~~
# AVAILABILITY
Added in 7.86.0.
# RETURN VALUE
This function returns a pointer to a *curl_ws_frame* struct with read-only
information that is valid for this specific callback invocation. If it cannot
return this information, or if the function is called in the wrong context, it
returns NULL.

73
deps/curl/docs/libcurl/curl_ws_recv.md vendored Normal file
View File

@ -0,0 +1,73 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_ws_recv
Section: 3
Source: libcurl
See-also:
- curl_easy_getinfo (3)
- curl_easy_perform (3)
- curl_easy_setopt (3)
- curl_ws_send (3)
- libcurl-ws (3)
---
# NAME
curl_ws_recv - receive WebSocket data
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen,
size_t *recv, const struct curl_ws_frame **meta);
~~~
# DESCRIPTION
This function call is EXPERIMENTAL.
Retrieves as much as possible of a received WebSocket data fragment into the
**buffer**, but not more than **buflen** bytes. *recv* is set to the
number of bytes actually stored.
If there is more fragment data to deliver than what fits in the provided
*buffer*, libcurl returns a full buffer and the application needs to call
this function again to continue draining the buffer.
The *meta* pointer gets set to point to a *const struct curl_ws_frame*
that contains information about the received data. See the
curl_ws_meta(3) for details on that struct.
# EXAMPLE
~~~c
int main(void)
{
size_t rlen;
const struct curl_ws_frame *meta;
char buffer[256];
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res = curl_ws_recv(curl, buffer, sizeof(buffer), &rlen, &meta);
if(res)
printf("error: %s\n", curl_easy_strerror(res));
}
}
~~~
# AVAILABILITY
Added in 7.86.0.
# RETURN VALUE
Returns **CURLE_OK** if everything is okay, and a non-zero number for
errors. Returns **CURLE_GOT_NOTHING** if the associated connection is
closed.
Instead of blocking, the function returns **CURLE_AGAIN**. The correct
behavior is then to wait for the socket to signal readability before calling
this function again.

120
deps/curl/docs/libcurl/curl_ws_send.md vendored Normal file
View File

@ -0,0 +1,120 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: curl_ws_send
Section: 3
Source: libcurl
See-also:
- curl_easy_getinfo (3)
- curl_easy_perform (3)
- curl_easy_setopt (3)
- curl_ws_recv (3)
- libcurl-ws (3)
---
# NAME
curl_ws_send - send WebSocket data
# SYNOPSIS
~~~c
#include <curl/curl.h>
CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen,
size_t *sent, curl_off_t fragsize,
unsigned int flags);
~~~
# DESCRIPTION
This function call is EXPERIMENTAL.
Send the specific message fragment over an established WebSocket
connection. The *buffer* holds the data to send and it is *buflen*
number of payload bytes in that memory area.
*sent* is returned as the number of payload bytes actually sent.
To send a (huge) fragment using multiple calls with partial content per
invoke, set the *CURLWS_OFFSET* bit and the *fragsize* argument as the
total expected size for the first part, then set the *CURLWS_OFFSET* with
a zero *fragsize* for the following parts.
If not sending a partial fragment or if this is raw mode, *fragsize*
should be set to zero.
If **CURLWS_RAW_MODE** is enabled in CURLOPT_WS_OPTIONS(3), the
**flags** argument should be set to 0.
To send a message consisting of multiple frames, set the *CURLWS_CONT* bit
in all frames except the final one.
# FLAGS
## CURLWS_TEXT
The buffer contains text data. Note that this makes a difference to WebSocket
but libcurl itself does not make any verification of the content or
precautions that you actually send valid UTF-8 content.
## CURLWS_BINARY
This is binary data.
## CURLWS_CONT
This is not the final fragment of the message, which implies that there is
another fragment coming as part of the same message where this bit is not set.
## CURLWS_CLOSE
Close this transfer.
## CURLWS_PING
This is a ping.
## CURLWS_PONG
This is a pong.
## CURLWS_OFFSET
The provided data is only a partial fragment and there is more coming in a
following call to *curl_ws_send()*. When sending only a piece of the
fragment like this, the *fragsize* must be provided with the total
expected fragment size in the first call and it needs to be zero in subsequent
calls.
# EXAMPLE
~~~c
#include <string.h> /* for strlen */
const char *send_payload = "magic";
int main(void)
{
size_t sent;
CURLcode res;
CURL *curl = curl_easy_init();
curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/");
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L);
curl_easy_perform(curl);
res = curl_ws_send(curl, send_payload, strlen(send_payload), &sent, 0,
CURLWS_PING);
curl_easy_cleanup(curl);
return (int)res;
}
~~~
# AVAILABILITY
Added in 7.86.0.
# RETURN VALUE
*CURLE_OK* (zero) means that the data was sent properly, non-zero means an
error occurred as *\<curl/curl.h\>* defines. See the libcurl-errors(3) man
page for the full list with descriptions.

52
deps/curl/docs/libcurl/libcurl-easy.md vendored Normal file
View File

@ -0,0 +1,52 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: libcurl
Section: 3
Source: libcurl
See-also:
- curl_easy_cleanup (3)
- curl_easy_init (3)
- curl_easy_setopt (3)
- libcurl (3)
- libcurl-errors (3)
- libcurl-multi (3)
---
# NAME
libcurl-easy - easy interface overview
# DESCRIPTION
When using libcurl's "easy" interface you init your session and get a handle
(often referred to as an "easy handle"), which you use as input to the easy
interface functions you use. Use curl_easy_init(3) to get the handle.
You continue by setting all the options you want in the upcoming transfer, the
most important among them is the URL itself (you cannot transfer anything
without a specified URL as you may have figured out yourself). You might want
to set some callbacks as well that are called from the library when data is
available etc. curl_easy_setopt(3) is used for all this.
CURLOPT_URL(3) is the only option you really must set, as otherwise
there can be no transfer. Another commonly used option is
CURLOPT_VERBOSE(3) that helps you see what libcurl is doing under the
hood, which is useful when debugging for example. The
curl_easy_setopt(3) man page has a full index of the almost 300
available options.
If you at any point would like to blank all previously set options for a
single easy handle, you can call curl_easy_reset(3) and you can also
make a clone of an easy handle (with all its set options) using
curl_easy_duphandle(3).
When all is setup, you tell libcurl to perform the transfer using
curl_easy_perform(3). It performs the entire transfer operation and does
not return until it is done (successfully or not).
After the transfer has been made, you can set new options and make another
transfer, or if you are done, cleanup the session by calling
curl_easy_cleanup(3). If you want persistent connections, you do not
cleanup immediately, but instead run ahead and perform other transfers using
the same easy handle.

123
deps/curl/docs/libcurl/libcurl-env-dbg.md vendored Normal file
View File

@ -0,0 +1,123 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: libcurl-env-dbg
Section: 3
Source: libcurl
See-also:
- libcurl-env (3)
---
# NAME
libcurl-env-dbg - environment variables libcurl DEBUGBUILD understands
# DESCRIPTION
This is a set of variables only recognized and used if libcurl was built
"debug enabled", which should never be true for a library used in production.
These variables are intended for internal use only, subject to change and have
many effects on the behavior of libcurl. Refer to the source code to determine
how exactly they are being used.
## CURL_ALTSVC_HTTP
Bypass the AltSvc HTTPS protocol restriction if this variable exists.
## CURL_DBG_SOCK_RBLOCK
The percentage of recv() calls that should be answered with a EAGAIN at random.
For TCP/UNIX sockets.
## CURL_DBG_SOCK_RMAX
The maximum data that shall be received from the network in one recv() call.
For TCP/UNIX sockets. This is applied to every recv.
Example: **CURL_DBG_SOCK_RMAX=400** means recv buffer size is limited to a
maximum of 400 bytes.
## CURL_DBG_SOCK_WBLOCK
The percentage of send() calls that should be answered with a EAGAIN at random.
For TCP/UNIX sockets.
## CURL_DBG_SOCK_WPARTIAL
The percentage of data that shall be written to the network. For TCP/UNIX
sockets. This is applied to every send.
Example: **CURL_DBG_SOCK_WPARTIAL=80** means a send with 1000 bytes would
only send 800.
## CURL_DBG_QUIC_WBLOCK
The percentage of send() calls that should be answered with EAGAIN at random.
QUIC only.
## CURL_DEBUG
Trace logging behavior as an alternative to calling curl_global_trace(3).
Example: **CURL_DEBUG=http/2** means trace details about HTTP/2 handling.
## CURL_DEBUG_SIZE
Fake the size returned by CURLINFO_HEADER_SIZE and CURLINFO_REQUEST_SIZE.
## CURL_GETHOSTNAME
Fake the local machine's unqualified hostname for NTLM and SMTP.
## CURL_HSTS_HTTP
Bypass the HSTS HTTPS protocol restriction if this variable exists.
## CURL_FORCETIME
A time of 0 is used for AWS signatures and NTLM if this variable exists.
## CURL_ENTROPY
A fixed faked value to use instead of a proper random number so that functions
in libcurl that are otherwise getting random outputs can be tested for what
they generate.
## CURL_SMALLREQSEND
An alternative size of HTTP data to be sent at a time only if smaller than the
current.
## CURL_SMALLSENDS
An alternative size of socket data to be sent at a time only if smaller than
the current.
## CURL_TIME
Fake unix timestamp to use for AltSvc, HSTS and CURLINFO variables that are
time related.
This variable can also be used to fake the data returned by some CURLINFO
variables that are not time-related (such as CURLINFO_LOCAL_PORT), and in that
case the value is not a timestamp.
## CURL_TRACE
LDAP tracing is enabled if this variable exists and its value is 1 or greater.
OpenLDAP tracing is separate. Refer to CURL_OPENLDAP_TRACE.
## CURL_NTLM_WB_FILE
Debug-version of the *ntlm-wb* executable.
## CURL_OPENLDAP_TRACE
OpenLDAP tracing is enabled if this variable exists and its value is 1 or
greater. There is a number of debug levels, refer to *openldap.c* comments.
## CURL_WS_CHUNK_SIZE
Used to influence the buffer chunk size used for WebSocket encoding and
decoding.

99
deps/curl/docs/libcurl/libcurl-env.md vendored Normal file
View File

@ -0,0 +1,99 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: libcurl-env
Section: 3
Source: libcurl
See-also:
- libcurl-env-dbg (3)
---
# NAME
libcurl-env - environment variables libcurl understands
# DESCRIPTION
libcurl reads and understands a set of environment variables that if set
controls and changes behaviors. This is the full list of variables to set and
description of what they do. Also note that curl, the command line tool,
supports a set of additional environment variables independently of this.
## `[scheme]_proxy`
When libcurl is given a URL to use in a transfer, it first extracts the scheme
part from the URL and checks if there is a given proxy set for that in its
corresponding environment variable. A URL like https://example.com makes
libcurl use the **http_proxy** variable, while a URL like ftp://example.com
uses the **ftp_proxy** variable.
These proxy variables are also checked for in their uppercase versions, except
the **http_proxy** one which is only used lowercase. Note also that some
systems actually have a case insensitive handling of environment variables and
then of course **HTTP_PROXY** still works.
An exception exists for the WebSocket **ws** and **wss** URL schemes,
where libcurl first checks **ws_proxy** or **wss_proxy** but if they are
not set, it will fall back and try the http and https versions instead if set.
## `ALL_PROXY`
This is a setting to set proxy for all URLs, independently of what scheme is
being used. Note that the scheme specific variables overrides this one if set.
## `CURL_SSL_BACKEND`
When libcurl is built to support multiple SSL backends, it selects a specific
backend at first use. If no selection is done by the program using libcurl,
this variable's selection is used. Setting a name that is not a built-in
alternative makes libcurl stay with the default.
SSL backend names (case-insensitive): BearSSL, GnuTLS, mbedTLS,
nss, OpenSSL, rustls, Schannel, Secure-Transport, wolfSSL
## `HOME`
When the netrc feature is used (CURLOPT_NETRC(3)), this variable is
checked as the primary way to find the "current" home directory in which
the .netrc file is likely to exist.
## `USERPROFILE`
When the netrc feature is used (CURLOPT_NETRC(3)), this variable is
checked as the secondary way to find the "current" home directory (on Windows
only) in which the .netrc file is likely to exist.
## `LOGNAME`
Username to use when invoking the *ntlm-wb* tool, if *NTLMUSER* was
not set.
## `NO_PROXY`
This has the same functionality as the CURLOPT_NOPROXY(3) option: it
gives libcurl a comma-separated list of hostname patterns for which libcurl
should not use a proxy.
## `NTLMUSER`
Username to use when invoking the *ntlm-wb* tool.
## `SSLKEYLOGFILE`
When set and libcurl runs with a SSL backend that supports this feature,
libcurl saves SSL secrets into the given filename. Using those SSL secrets,
other tools (such as Wireshark) can decrypt the SSL communication and
analyze/view the traffic.
These secrets and this file might be sensitive. Users are advised to take
precautions so that they are not stolen or otherwise inadvertently revealed.
## `USER`
Username to use when invoking the *ntlm-wb* tool, if *NTLMUSER* and *LOGNAME*
were not set.
# Debug Variables
Debug variables are intended for internal use and are documented in
libcurl-env-dbg(3).

757
deps/curl/docs/libcurl/libcurl-errors.md vendored Normal file
View File

@ -0,0 +1,757 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: libcurl-errors
Section: 3
Source: libcurl
See-also:
- CURLOPT_DEBUGFUNCTION (3)
- CURLOPT_ERRORBUFFER (3)
- CURLOPT_VERBOSE (3)
- curl_easy_strerror (3)
- curl_multi_strerror (3)
- curl_share_strerror (3)
- curl_url_strerror (3)
---
# NAME
libcurl-errors - error codes in libcurl
# DESCRIPTION
This man page includes most, if not all, available error codes in libcurl.
Why they occur and possibly what you can do to fix the problem are also included.
# CURLcode
Almost all "easy" interface functions return a CURLcode error code. No matter
what, using the curl_easy_setopt(3) option CURLOPT_ERRORBUFFER(3)
is a good idea as it gives you a human readable error string that may offer
more details about the cause of the error than just the error code.
curl_easy_strerror(3) can be called to get an error string from a given
CURLcode number.
CURLcode is one of the following:
## CURLE_OK (0)
All fine. Proceed as usual.
## CURLE_UNSUPPORTED_PROTOCOL (1)
The URL you passed to libcurl used a protocol that this libcurl does not
support. The support might be a compile-time option that you did not use, it
can be a misspelled protocol string or just a protocol libcurl has no code
for.
## CURLE_FAILED_INIT (2)
Early initialization code failed. This is likely to be an internal error or
problem, or a resource problem where something fundamental could not get done
at init time.
## CURLE_URL_MALFORMAT (3)
The URL was not properly formatted.
## CURLE_NOT_BUILT_IN (4)
A requested feature, protocol or option was not found built-in in this libcurl
due to a build-time decision. This means that a feature or option was not
enabled or explicitly disabled when libcurl was built and in order to get it
to function you have to get a rebuilt libcurl.
## CURLE_COULDNT_RESOLVE_PROXY (5)
Could not resolve proxy. The given proxy host could not be resolved.
## CURLE_COULDNT_RESOLVE_HOST (6)
Could not resolve host. The given remote host was not resolved.
## CURLE_COULDNT_CONNECT (7)
Failed to connect() to host or proxy.
## CURLE_WEIRD_SERVER_REPLY (8)
The server sent data libcurl could not parse. This error code was known as
*CURLE_FTP_WEIRD_SERVER_REPLY* before 7.51.0.
## CURLE_REMOTE_ACCESS_DENIED (9)
We were denied access to the resource given in the URL. For FTP, this occurs
while trying to change to the remote directory.
## CURLE_FTP_ACCEPT_FAILED (10)
While waiting for the server to connect back when an active FTP session is
used, an error code was sent over the control connection or similar.
## CURLE_FTP_WEIRD_PASS_REPLY (11)
After having sent the FTP password to the server, libcurl expects a proper
reply. This error code indicates that an unexpected code was returned.
## CURLE_FTP_ACCEPT_TIMEOUT (12)
During an active FTP session while waiting for the server to connect, the
CURLOPT_ACCEPTTIMEOUT_MS(3) (or the internal default) timeout expired.
## CURLE_FTP_WEIRD_PASV_REPLY (13)
libcurl failed to get a sensible result back from the server as a response to
either a PASV or a EPSV command. The server is flawed.
## CURLE_FTP_WEIRD_227_FORMAT (14)
FTP servers return a 227-line as a response to a PASV command. If libcurl
fails to parse that line, this return code is passed back.
## CURLE_FTP_CANT_GET_HOST (15)
An internal failure to lookup the host used for the new connection.
## CURLE_HTTP2 (16)
A problem was detected in the HTTP2 framing layer. This is somewhat generic
and can be one out of several problems, see the error buffer for details.
## CURLE_FTP_COULDNT_SET_TYPE (17)
Received an error when trying to set the transfer mode to binary or ASCII.
## CURLE_PARTIAL_FILE (18)
A file transfer was shorter or larger than expected. This happens when the
server first reports an expected transfer size, and then delivers data that
does not match the previously given size.
## CURLE_FTP_COULDNT_RETR_FILE (19)
This was either a weird reply to a 'RETR' command or a zero byte transfer
complete.
## Obsolete error (20)
Not used in modern versions.
## CURLE_QUOTE_ERROR (21)
When sending custom "QUOTE" commands to the remote server, one of the commands
returned an error code that was 400 or higher (for FTP) or otherwise
indicated unsuccessful completion of the command.
## CURLE_HTTP_RETURNED_ERROR (22)
This is returned if CURLOPT_FAILONERROR(3) is set TRUE and the HTTP server
returns an error code that is \>= 400.
## CURLE_WRITE_ERROR (23)
An error occurred when writing received data to a local file, or an error was
returned to libcurl from a write callback.
## Obsolete error (24)
Not used in modern versions.
## CURLE_UPLOAD_FAILED (25)
Failed starting the upload. For FTP, the server typically denied the STOR
command. The error buffer usually contains the server's explanation for this.
## CURLE_READ_ERROR (26)
There was a problem reading a local file or an error returned by the read
callback.
## CURLE_OUT_OF_MEMORY (27)
A memory allocation request failed. This is serious badness and
things are severely screwed up if this ever occurs.
## CURLE_OPERATION_TIMEDOUT (28)
Operation timeout. The specified time-out period was reached according to the
conditions.
## Obsolete error (29)
Not used in modern versions.
## CURLE_FTP_PORT_FAILED (30)
The FTP PORT command returned error. This mostly happens when you have not
specified a good enough address for libcurl to use. See
CURLOPT_FTPPORT(3).
## CURLE_FTP_COULDNT_USE_REST (31)
The FTP REST command returned error. This should never happen if the server is
sane.
## Obsolete error (32)
Not used in modern versions.
## CURLE_RANGE_ERROR (33)
The server does not support or accept range requests.
## CURLE_HTTP_POST_ERROR (34)
This is an odd error that mainly occurs due to internal confusion.
## CURLE_SSL_CONNECT_ERROR (35)
A problem occurred somewhere in the SSL/TLS handshake. You really want the
error buffer and read the message there as it pinpoints the problem slightly
more. Could be certificates (file formats, paths, permissions), passwords, and
others.
## CURLE_BAD_DOWNLOAD_RESUME (36)
The download could not be resumed because the specified offset was out of the
file boundary.
## CURLE_FILE_COULDNT_READ_FILE (37)
A file given with FILE:// could not be opened. Most likely because the file
path does not identify an existing file. Did you check file permissions?
## CURLE_LDAP_CANNOT_BIND (38)
LDAP cannot bind. LDAP bind operation failed.
## CURLE_LDAP_SEARCH_FAILED (39)
LDAP search failed.
## Obsolete error (40)
Not used in modern versions.
## CURLE_FUNCTION_NOT_FOUND (41)
Function not found. A required zlib function was not found.
## CURLE_ABORTED_BY_CALLBACK (42)
Aborted by callback. A callback returned "abort" to libcurl.
## CURLE_BAD_FUNCTION_ARGUMENT (43)
A function was called with a bad parameter.
## Obsolete error (44)
Not used in modern versions.
## CURLE_INTERFACE_FAILED (45)
Interface error. A specified outgoing interface could not be used. Set which
interface to use for outgoing connections' source IP address with
CURLOPT_INTERFACE(3).
## Obsolete error (46)
Not used in modern versions.
## CURLE_TOO_MANY_REDIRECTS (47)
Too many redirects. When following redirects, libcurl hit the maximum amount.
Set your limit with CURLOPT_MAXREDIRS(3).
## CURLE_UNKNOWN_OPTION (48)
An option passed to libcurl is not recognized/known. Refer to the appropriate
documentation. This is most likely a problem in the program that uses
libcurl. The error buffer might contain more specific information about which
exact option it concerns.
## CURLE_SETOPT_OPTION_SYNTAX (49)
An option passed in to a setopt was wrongly formatted. See error message for
details about what option.
## Obsolete errors (50-51)
Not used in modern versions.
## CURLE_GOT_NOTHING (52)
Nothing was returned from the server, and under the circumstances, getting
nothing is considered an error.
## CURLE_SSL_ENGINE_NOTFOUND (53)
The specified crypto engine was not found.
## CURLE_SSL_ENGINE_SETFAILED (54)
Failed setting the selected SSL crypto engine as default.
## CURLE_SEND_ERROR (55)
Failed sending network data.
## CURLE_RECV_ERROR (56)
Failure with receiving network data.
## Obsolete error (57)
Not used in modern versions.
## CURLE_SSL_CERTPROBLEM (58)
problem with the local client certificate.
## CURLE_SSL_CIPHER (59)
Could not use specified cipher.
## CURLE_PEER_FAILED_VERIFICATION (60)
The remote server's SSL certificate or SSH fingerprint was deemed not OK.
This error code has been unified with CURLE_SSL_CACERT since 7.62.0. Its
previous value was 51.
## CURLE_BAD_CONTENT_ENCODING (61)
Unrecognized transfer encoding.
## Obsolete error (62)
Not used in modern versions.
## CURLE_FILESIZE_EXCEEDED (63)
Maximum file size exceeded.
## CURLE_USE_SSL_FAILED (64)
Requested FTP SSL level failed.
## CURLE_SEND_FAIL_REWIND (65)
When doing a send operation curl had to rewind the data to retransmit, but the
rewinding operation failed.
## CURLE_SSL_ENGINE_INITFAILED (66)
Initiating the SSL Engine failed.
## CURLE_LOGIN_DENIED (67)
The remote server denied curl to login (Added in 7.13.1)
## CURLE_TFTP_NOTFOUND (68)
File not found on TFTP server.
## CURLE_TFTP_PERM (69)
Permission problem on TFTP server.
## CURLE_REMOTE_DISK_FULL (70)
Out of disk space on the server.
## CURLE_TFTP_ILLEGAL (71)
Illegal TFTP operation.
## CURLE_TFTP_UNKNOWNID (72)
Unknown TFTP transfer ID.
## CURLE_REMOTE_FILE_EXISTS (73)
File already exists and is not overwritten.
## CURLE_TFTP_NOSUCHUSER (74)
This error should never be returned by a properly functioning TFTP server.
## Obsolete error (75-76)
Not used in modern versions.
## CURLE_SSL_CACERT_BADFILE (77)
Problem with reading the SSL CA cert (path? access rights?)
## CURLE_REMOTE_FILE_NOT_FOUND (78)
The resource referenced in the URL does not exist.
## CURLE_SSH (79)
An unspecified error occurred during the SSH session.
## CURLE_SSL_SHUTDOWN_FAILED (80)
Failed to shut down the SSL connection.
## CURLE_AGAIN (81)
Socket is not ready for send/recv. Wait until it is ready and try again. This
return code is only returned from curl_easy_recv(3) and curl_easy_send(3)
(Added in 7.18.2)
## CURLE_SSL_CRL_BADFILE (82)
Failed to load CRL file (Added in 7.19.0)
## CURLE_SSL_ISSUER_ERROR (83)
Issuer check failed (Added in 7.19.0)
## CURLE_FTP_PRET_FAILED (84)
The FTP server does not understand the PRET command at all or does not support
the given argument. Be careful when using CURLOPT_CUSTOMREQUEST(3), a
custom LIST command is sent with the PRET command before PASV as well. (Added
in 7.20.0)
## CURLE_RTSP_CSEQ_ERROR (85)
Mismatch of RTSP CSeq numbers.
## CURLE_RTSP_SESSION_ERROR (86)
Mismatch of RTSP Session Identifiers.
## CURLE_FTP_BAD_FILE_LIST (87)
Unable to parse FTP file list (during FTP wildcard downloading).
## CURLE_CHUNK_FAILED (88)
Chunk callback reported error.
## CURLE_NO_CONNECTION_AVAILABLE (89)
(For internal use only, is never returned by libcurl) No connection available,
the session is queued. (added in 7.30.0)
## CURLE_SSL_PINNEDPUBKEYNOTMATCH (90)
Failed to match the pinned key specified with CURLOPT_PINNEDPUBLICKEY(3).
## CURLE_SSL_INVALIDCERTSTATUS (91)
Status returned failure when asked with CURLOPT_SSL_VERIFYSTATUS(3).
## CURLE_HTTP2_STREAM (92)
Stream error in the HTTP/2 framing layer.
## CURLE_RECURSIVE_API_CALL (93)
An API function was called from inside a callback.
## CURLE_AUTH_ERROR (94)
An authentication function returned an error.
## CURLE_HTTP3 (95)
A problem was detected in the HTTP/3 layer. This is somewhat generic and can
be one out of several problems, see the error buffer for details.
## CURLE_QUIC_CONNECT_ERROR (96)
QUIC connection error. This error may be caused by an SSL library error. QUIC
is the protocol used for HTTP/3 transfers.
## CURLE_PROXY (97)
Proxy handshake error. CURLINFO_PROXY_ERROR(3) provides extra details on
the specific problem.
## CURLE_SSL_CLIENTCERT (98)
SSL Client Certificate required.
## CURLE_UNRECOVERABLE_POLL (99)
An internal call to poll() or select() returned error that is not recoverable.
## CURLE_TOO_LARGE (100)
A value or data field grew larger than allowed.
# CURLMcode
This is the generic return code used by functions in the libcurl multi
interface. Also consider curl_multi_strerror(3).
## CURLM_CALL_MULTI_PERFORM (-1)
This is not really an error. It means you should call
curl_multi_perform(3) again without doing select() or similar in
between. Before version 7.20.0 (released on February 9 2010) this could be returned by
curl_multi_perform(3), but in later versions this return code is never
used.
## CURLM_OK (0)
Things are fine.
## CURLM_BAD_HANDLE (1)
The passed-in handle is not a valid *CURLM* handle.
## CURLM_BAD_EASY_HANDLE (2)
An easy handle was not good/valid. It could mean that it is not an easy handle
at all, or possibly that the handle already is in use by this or another multi
handle.
## CURLM_OUT_OF_MEMORY (3)
You are doomed.
## CURLM_INTERNAL_ERROR (4)
This can only be returned if libcurl bugs. Please report it to us!
## CURLM_BAD_SOCKET (5)
The passed-in socket is not a valid one that libcurl already knows about.
(Added in 7.15.4)
## CURLM_UNKNOWN_OPTION (6)
curl_multi_setopt() with unsupported option
(Added in 7.15.4)
## CURLM_ADDED_ALREADY (7)
An easy handle already added to a multi handle was attempted to get added a
second time. (Added in 7.32.1)
## CURLM_RECURSIVE_API_CALL (8)
An API function was called from inside a callback.
## CURLM_WAKEUP_FAILURE (9)
Wake up is unavailable or failed.
## CURLM_BAD_FUNCTION_ARGUMENT (10)
A function was called with a bad parameter.
## CURLM_ABORTED_BY_CALLBACK (11)
A multi handle callback returned error.
## CURLM_UNRECOVERABLE_POLL (12)
An internal call to poll() or select() returned error that is not recoverable.
# CURLSHcode
The "share" interface returns a **CURLSHcode** to indicate when an error has
occurred. Also consider curl_share_strerror(3).
## CURLSHE_OK (0)
All fine. Proceed as usual.
## CURLSHE_BAD_OPTION (1)
An invalid option was passed to the function.
## CURLSHE_IN_USE (2)
The share object is currently in use.
## CURLSHE_INVALID (3)
An invalid share object was passed to the function.
## CURLSHE_NOMEM (4)
Not enough memory was available.
(Added in 7.12.0)
## CURLSHE_NOT_BUILT_IN (5)
The requested sharing could not be done because the library you use do not have
that particular feature enabled. (Added in 7.23.0)
# CURLUcode
The URL interface returns a *CURLUcode* to indicate when an error has
occurred. Also consider curl_url_strerror(3).
## CURLUE_OK (0)
All fine. Proceed as usual.
## CURLUE_BAD_HANDLE (1)
An invalid URL handle was passed as argument.
## CURLUE_BAD_PARTPOINTER (2)
An invalid 'part' argument was passed as argument.
## CURLUE_MALFORMED_INPUT (3)
A malformed input was passed to a URL API function.
## CURLUE_BAD_PORT_NUMBER (4)
The port number was not a decimal number between 0 and 65535.
## CURLUE_UNSUPPORTED_SCHEME (5)
This libcurl build does not support the given URL scheme.
## CURLUE_URLDECODE (6)
URL decode error, most likely because of rubbish in the input.
## CURLUE_OUT_OF_MEMORY (7)
A memory function failed.
## CURLUE_USER_NOT_ALLOWED (8)
Credentials was passed in the URL when prohibited.
## CURLUE_UNKNOWN_PART (9)
An unknown part ID was passed to a URL API function.
## CURLUE_NO_SCHEME (10)
There is no scheme part in the URL.
## CURLUE_NO_USER (11)
There is no user part in the URL.
## CURLUE_NO_PASSWORD (12)
There is no password part in the URL.
## CURLUE_NO_OPTIONS (13)
There is no options part in the URL.
## CURLUE_NO_HOST (14)
There is no host part in the URL.
## CURLUE_NO_PORT (15)
There is no port part in the URL.
## CURLUE_NO_QUERY (16)
There is no query part in the URL.
## CURLUE_NO_FRAGMENT (17)
There is no fragment part in the URL.
## CURLUE_NO_ZONEID (18)
There is no zone id set in the URL.
## CURLUE_BAD_FILE_URL (19)
The file:// URL is invalid.
## CURLUE_BAD_FRAGMENT (20)
The fragment part of the URL contained bad or invalid characters.
## CURLUE_BAD_HOSTNAME (21)
The hostname contained bad or invalid characters.
## CURLUE_BAD_IPV6 (22)
The IPv6 address hostname contained bad or invalid characters.
## CURLUE_BAD_LOGIN (23)
The login part of the URL contained bad or invalid characters.
## CURLUE_BAD_PASSWORD (24)
The password part of the URL contained bad or invalid characters.
## CURLUE_BAD_PATH (25)
The path part of the URL contained bad or invalid characters.
## CURLUE_BAD_QUERY (26)
The query part of the URL contained bad or invalid characters.
## CURLUE_BAD_SCHEME (27)
The scheme part of the URL contained bad or invalid characters.
## CURLUE_BAD_SLASHES (28)
The URL contained an invalid number of slashes.
## CURLUE_BAD_USER (29)
The user part of the URL contained bad or invalid characters.
## CURLUE_LACKS_IDN (30)
libcurl lacks IDN support.
## CURLUE_TOO_LARGE (31)
A value or data field is larger than allowed.
# CURLHcode
The header interface returns a *CURLHcode* to indicate when an error has
occurred.
## CURLHE_OK (0)
All fine. Proceed as usual.
## CURLHE_BADINDEX (1)
There is no header with the requested index.
## CURLHE_MISSING (2)
No such header exists.
## CURLHE_NOHEADERS (3)
No headers at all have been recorded.
## CURLHE_NOREQUEST (4)
There was no such request number.
## CURLHE_OUT_OF_MEMORY (5)
Out of resources
## CURLHE_BAD_ARGUMENT (6)
One or more of the given arguments are bad.
## CURLHE_NOT_BUILT_IN (7)
HTTP support or the header API has been disabled in the build.

178
deps/curl/docs/libcurl/libcurl-multi.md vendored Normal file
View File

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

493
deps/curl/docs/libcurl/libcurl-security.md vendored Normal file
View File

@ -0,0 +1,493 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: libcurl-security
Section: 3
Source: libcurl
See-also:
- libcurl-thread (3)
---
<!-- markdown-link-check-disable -->
# NAME
libcurl-security - security considerations when using libcurl
# Security
The libcurl project takes security seriously. The library is written with
caution and precautions are taken to mitigate many kinds of risks encountered
while operating with potentially malicious servers on the Internet. It is a
powerful library, however, which allows application writers to make trade-offs
between ease of writing and exposure to potential risky operations. If used
the right way, you can use libcurl to transfer data pretty safely.
Many applications are used in closed networks where users and servers can
(possibly) be trusted, but many others are used on arbitrary servers and are
fed input from potentially untrusted users. Following is a discussion about
some risks in the ways in which applications commonly use libcurl and
potential mitigations of those risks. It is not comprehensive, but shows
classes of attacks that robust applications should consider. The Common
Weakness Enumeration project at https://cwe.mitre.org/ is a good reference for
many of these and similar types of weaknesses of which application writers
should be aware.
# Command Lines
If you use a command line tool (such as curl) that uses libcurl, and you give
options to the tool on the command line those options can get read by other
users of your system when they use *ps* or other tools to list currently
running processes.
To avoid these problems, never feed sensitive things to programs using command
line options. Write them to a protected file and use the -K option to avoid
this.
# .netrc
.netrc is a pretty handy file/feature that allows you to login quickly and
automatically to frequently visited sites. The file contains passwords in
clear text and is a real security risk. In some cases, your .netrc is also
stored in a home directory that is NFS mounted or used on another network
based file system, so the clear text password flies through your network every
time anyone reads that file.
For applications that enable .netrc use, a user who manage to set the right
URL might then be possible to pass on passwords.
To avoid these problems, do not use .netrc files and never store passwords in
plain text anywhere.
# Clear Text Passwords
Many of the protocols libcurl supports send name and password unencrypted as
clear text (HTTP Basic authentication, FTP, TELNET etc). It is easy for anyone
on your network or a network nearby yours to just fire up a network analyzer
tool and eavesdrop on your passwords. Do not let the fact that HTTP Basic uses
base64 encoded passwords fool you. They may not look readable at a first
glance, but they are easily "deciphered" by anyone within seconds.
To avoid this problem, use an authentication mechanism or other protocol that
does not let snoopers see your password: Digest, CRAM-MD5, Kerberos, SPNEGO or
NTLM authentication. Or even better: use authenticated protocols that protect
the entire connection and everything sent over it.
# Unauthenticated Connections
Protocols that do not have any form of cryptographic authentication cannot
with any certainty know that they communicate with the right remote server.
If your application is using a fixed scheme or fixed hostname, it is not safe
as long as the connection is unauthenticated. There can be a man-in-the-middle
or in fact the whole server might have been replaced by an evil actor.
Unauthenticated protocols are unsafe. The data that comes back to curl may
have been injected by an attacker. The data that curl sends might be modified
before it reaches the intended server. If it even reaches the intended server
at all.
Remedies:
## Restrict operations to authenticated transfers
Use authenticated protocols protected with HTTPS or SSH.
## Make sure the server's certificate etc is verified
Never ever switch off certificate verification.
# Redirects
The CURLOPT_FOLLOWLOCATION(3) option automatically follows HTTP
redirects sent by a remote server. These redirects can refer to any kind of
URL, not just HTTP. libcurl restricts the protocols allowed to be used in
redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are
enabled by default. Applications may opt to restrict that set further.
A redirect to a file: URL would cause the libcurl to read (or write) arbitrary
files from the local filesystem. If the application returns the data back to
the user (as would happen in some kinds of CGI scripts), an attacker could
leverage this to read otherwise forbidden data (e.g.
**file://localhost/etc/passwd**).
If authentication credentials are stored in the ~/.netrc file, or Kerberos is
in use, any other URL type (not just file:) that requires authentication is
also at risk. A redirect such as **ftp://some-internal-server/private-file** would
then return data even when the server is password protected.
In the same way, if an unencrypted SSH private key has been configured for the
user running the libcurl application, SCP: or SFTP: URLs could access password
or private-key protected resources,
e.g. **sftp://user@some-internal-server/etc/passwd**
The CURLOPT_REDIR_PROTOCOLS(3) and CURLOPT_NETRC(3) options can be
used to mitigate against this kind of attack.
A redirect can also specify a location available only on the machine running
libcurl, including servers hidden behind a firewall from the attacker.
E.g. **http://127.0.0.1/** or **http://intranet/delete-stuff.cgi?delete=all** or
**tftp://bootp-server/pc-config-data**
Applications can mitigate against this by disabling
CURLOPT_FOLLOWLOCATION(3) and handling redirects itself, sanitizing URLs
as necessary. Alternately, an app could leave CURLOPT_FOLLOWLOCATION(3)
enabled but set CURLOPT_REDIR_PROTOCOLS(3) and install a
CURLOPT_OPENSOCKETFUNCTION(3) or CURLOPT_PREREQFUNCTION(3) callback
function in which addresses are sanitized before use.
# CRLF in Headers
For all options in libcurl which specify headers, including but not limited to
CURLOPT_HTTPHEADER(3), CURLOPT_PROXYHEADER(3),
CURLOPT_COOKIE(3), CURLOPT_USERAGENT(3), CURLOPT_REFERER(3)
and CURLOPT_RANGE(3), libcurl sends the headers as-is and does not apply
any special sanitation or normalization to them.
If you allow untrusted user input into these options without sanitizing CRLF
sequences in them, someone malicious may be able to modify the request in a
way you did not intend such as injecting new headers.
# Local Resources
A user who can control the DNS server of a domain being passed in within a URL
can change the address of the host to a local, private address which a
server-side libcurl-using application could then use. E.g. the innocuous URL
**http://fuzzybunnies.example.com/** could actually resolve to the IP
address of a server behind a firewall, such as 127.0.0.1 or
10.1.2.3. Applications can mitigate against this by setting a
CURLOPT_OPENSOCKETFUNCTION(3) or CURLOPT_PREREQFUNCTION(3) and
checking the address before a connection.
All the malicious scenarios regarding redirected URLs apply just as well to
non-redirected URLs, if the user is allowed to specify an arbitrary URL that
could point to a private resource. For example, a web app providing a
translation service might happily translate **file://localhost/etc/passwd**
and display the result. Applications can mitigate against this with the
CURLOPT_PROTOCOLS(3) option as well as by similar mitigation techniques
for redirections.
A malicious FTP server could in response to the PASV command return an IP
address and port number for a server local to the app running libcurl but
behind a firewall. Applications can mitigate against this by using the
CURLOPT_FTP_SKIP_PASV_IP(3) option or CURLOPT_FTPPORT(3).
Local servers sometimes assume local access comes from friends and trusted
users. An application that expects https://example.com/file_to_read that and
instead gets http://192.168.0.1/my_router_config might print a file that would
otherwise be protected by the firewall.
Allowing your application to connect to local hosts, be it the same machine
that runs the application or a machine on the same local network, might be
possible to exploit by an attacker who then perhaps can "port-scan" the
particular hosts - depending on how the application and servers acts.
# IPv4 Addresses
Some users might be tempted to filter access to local resources or similar
based on numerical IPv4 addresses used in URLs. This is a bad and error-prone
idea because of the many different ways a numerical IPv4 address can be
specified and libcurl accepts: one to four dot-separated fields using one of
or a mix of decimal, octal or hexadecimal encoding.
# IPv6 Addresses
libcurl handles IPv6 addresses transparently and just as easily as IPv4
addresses. That means that a sanitizing function that filters out addresses
like 127.0.0.1 is not sufficient - the equivalent IPv6 addresses **::1**,
**::**, **0:00::0:1**, **::127.0.0.1** and **::ffff:7f00:1** supplied
somehow by an attacker would all bypass a naive filter and could allow access
to undesired local resources. IPv6 also has special address blocks like
link-local and site-local that generally should not be accessed by a
server-side libcurl-using application. A poorly configured firewall installed
in a data center, organization or server may also be configured to limit IPv4
connections but leave IPv6 connections wide open. In some cases, setting
CURLOPT_IPRESOLVE(3) to CURL_IPRESOLVE_V4 can be used to limit resolved
addresses to IPv4 only and bypass these issues.
# Uploads
When uploading, a redirect can cause a local (or remote) file to be
overwritten. Applications must not allow any unsanitized URL to be passed in
for uploads. Also, CURLOPT_FOLLOWLOCATION(3) should not be used on
uploads. Instead, the applications should consider handling redirects itself,
sanitizing each URL first.
# Authentication
Use of CURLOPT_UNRESTRICTED_AUTH(3) could cause authentication
information to be sent to an unknown second server. Applications can mitigate
against this by disabling CURLOPT_FOLLOWLOCATION(3) and handling
redirects itself, sanitizing where necessary.
Use of the CURLAUTH_ANY option to CURLOPT_HTTPAUTH(3) could result in username
and password being sent in clear text to an HTTP server. Instead, use
CURLAUTH_ANYSAFE which ensures that the password is encrypted over the
network, or else fail the request.
Use of the CURLUSESSL_TRY option to CURLOPT_USE_SSL(3) could result in
username and password being sent in clear text to an FTP server. Instead, use
CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else fail
the request.
# Cookies
If cookies are enabled and cached, then a user could craft a URL which
performs some malicious action to a site whose authentication is already
stored in a cookie. E.g.
**http://mail.example.com/delete-stuff.cgi?delete=all** Applications can
mitigate against this by disabling cookies or clearing them between requests.
# Dangerous SCP URLs
SCP URLs can contain raw commands within the scp: URL, which is a side effect
of how the SCP protocol is designed. E.g.
~~~
scp://user:pass@host/a;date >/tmp/test;
~~~
Applications must not allow unsanitized SCP: URLs to be passed in for
downloads.
# file://
By default curl and libcurl support file:// URLs. Such a URL is always an
access, or attempted access, to a local resource. If your application wants to
avoid that, keep control of what URLs to use and/or prevent curl/libcurl from
using the protocol.
By default, libcurl prohibits redirects to file:// URLs.
# Warning: file:// on Windows
The Windows operating system tries automatically, and without any way for
applications to disable it, to establish a connection to another host over the
network and access it (over SMB or other protocols), if only the correct file
path is accessed.
When first realizing this, the curl team tried to filter out such attempts in
order to protect applications for inadvertent probes of for example internal
networks etc. This resulted in CVE-2019-15601 and the associated security fix.
However, we have since been made aware of the fact that the previous fix was far
from adequate as there are several other ways to accomplish more or less the
same thing: accessing a remote host over the network instead of the local file
system.
The conclusion we have come to is that this is a weakness or feature in the
Windows operating system itself, that we as an application cannot safely
protect users against. It would just be a whack-a-mole race we do not want to
participate in. There are too many ways to do it and there is no knob we can
use to turn off the practice.
If you use curl or libcurl on Windows (any version), disable the use of the
FILE protocol in curl or be prepared that accesses to a range of "magic paths"
potentially make your system access other hosts on your network. curl cannot
protect you against this.
# What if the user can set the URL
Applications may find it tempting to let users set the URL that it can work
on. That is probably fine, but opens up for mischief and trickery that you as
an application author may want to address or take precautions against.
If your curl-using script allow a custom URL do you also, perhaps
unintentionally, allow the user to pass other options to the curl command line
if creative use of special characters are applied?
If the user can set the URL, the user can also specify the scheme part to
other protocols that you did not intend for users to use and perhaps did not
consider. curl supports over 20 different URL schemes. "http://" might be what
you thought, "ftp://" or "imap://" might be what the user gives your
application. Also, cross-protocol operations might be done by using a
particular scheme in the URL but point to a server doing a different protocol
on a non-standard port.
Remedies:
## Use --proto
curl command lines can use *--proto* to limit what URL schemes it accepts
## Use CURLOPT_PROTOCOLS
libcurl programs can use CURLOPT_PROTOCOLS(3) to limit what URL schemes it accepts
## consider not allowing the user to set the full URL
Maybe just let the user provide data for parts of it? Or maybe filter input to
only allow specific choices?
# RFC 3986 vs WHATWG URL
curl supports URLs mostly according to how they are defined in RFC 3986, and
has done so since the beginning.
Web browsers mostly adhere to the WHATWG URL Specification.
This deviance makes some URLs copied between browsers (or returned over HTTP
for redirection) and curl not work the same way. It can also cause problems if
an application parses URLs differently from libcurl and makes different
assumptions about a link. This can mislead users into getting the wrong thing,
connecting to the wrong host or otherwise not working identically.
Within an application, this can be mitigated by always using the
curl_url(3) API to parse URLs, ensuring that they are parsed the same way
as within libcurl itself.
# FTP uses two connections
When performing an FTP transfer, two TCP connections are used: one for setting
up the transfer and one for the actual data.
FTP is not only unauthenticated, but the setting up of the second transfer is
also a weak spot. The second connection to use for data, is either setup with
the PORT/EPRT command that makes the server connect back to the client on the
given IP+PORT, or with PASV/EPSV that makes the server setup a port to listen
to and tells the client to connect to a given IP+PORT.
Again, unauthenticated means that the connection might be meddled with by a
man-in-the-middle or that there is a malicious server pretending to be the
right one.
A malicious FTP server can respond to PASV commands with the IP+PORT of a
totally different machine. Perhaps even a third party host, and when there are
many clients trying to connect to that third party, it could create a
Distributed Denial-Of-Service attack out of it. If the client makes an upload
operation, it can make the client send the data to another site. If the
attacker can affect what data the client uploads, it can be made to work as a
HTTP request and then the client could be made to issue HTTP requests to third
party hosts.
An attacker that manages to control curl's command line options can tell curl
to send an FTP PORT command to ask the server to connect to a third party host
instead of back to curl.
The fact that FTP uses two connections makes it vulnerable in a way that is
hard to avoid.
# Active FTP passes on the local IP address
If you use curl/libcurl to do *active* FTP transfers, curl will pass on the
address of your local IP to the remote server - even when for example using a
SOCKS or HTTP proxy in between curl and the target server.
# Denial of Service
A malicious server could cause libcurl to effectively hang by sending data
slowly, or even no data at all but just keeping the TCP connection open. This
could effectively result in a denial-of-service attack. The
CURLOPT_TIMEOUT(3) and/or CURLOPT_LOW_SPEED_LIMIT(3) options can
be used to mitigate against this.
A malicious server could cause libcurl to download an infinite amount of data,
potentially causing all of memory or disk to be filled. Setting the
CURLOPT_MAXFILESIZE_LARGE(3) option is not sufficient to guard against
this. Instead, applications should monitor the amount of data received within
the write or progress callback and abort once the limit is reached.
A malicious HTTP server could cause an infinite redirection loop, causing a
denial-of-service. This can be mitigated by using the
CURLOPT_MAXREDIRS(3) option.
# Arbitrary Headers
User-supplied data must be sanitized when used in options like
CURLOPT_USERAGENT(3), CURLOPT_HTTPHEADER(3),
CURLOPT_POSTFIELDS(3) and others that are used to generate structured
data. Characters like embedded carriage returns or ampersands could allow the
user to create additional headers or fields that could cause malicious
transactions.
# Server-supplied Names
A server can supply data which the application may, in some cases, use as a
filename. The curl command-line tool does this with *--remote-header-name*,
using the Content-disposition: header to generate a filename. An application
could also use CURLINFO_EFFECTIVE_URL(3) to generate a filename from a
server-supplied redirect URL. Special care must be taken to sanitize such
names to avoid the possibility of a malicious server supplying one like
**"/etc/passwd"**, **"autoexec.bat"**, **"prn:"** or even **".bashrc"**.
# Server Certificates
A secure application should never use the CURLOPT_SSL_VERIFYPEER(3)
option to disable certificate validation. There are numerous attacks that are
enabled by applications that fail to properly validate server TLS/SSL
certificates, thus enabling a malicious server to spoof a legitimate
one. HTTPS without validated certificates is potentially as insecure as a
plain HTTP connection.
# Showing What You Do
Relatedly, be aware that in situations when you have problems with libcurl and
ask someone for help, everything you reveal in order to get best possible help
might also impose certain security related risks. Hostnames, usernames, paths,
operating system specifics, etc. (not to mention passwords of course) may in
fact be used by intruders to gain additional information of a potential
target.
Be sure to limit access to application logs if they could hold private or
security-related data. Besides the obvious candidates like usernames and
passwords, things like URLs, cookies or even filenames could also hold
sensitive data.
To avoid this problem, you must of course use your common sense. Often, you
can just edit out the sensitive data or just search/replace your true
information with faked data.
# setuid applications using libcurl
libcurl-using applications that set the 'setuid' bit to run with elevated or
modified rights also implicitly give that extra power to libcurl and this
should only be done after careful considerations.
Giving setuid powers to the application means that libcurl can save files using
those new rights (if for example the `SSLKEYLOGFILE` environment variable is
set). Also: if the application wants these powers to read or manage secrets
that the user is otherwise not able to view (like credentials for a login
etc), it should be noted that libcurl still might understand proxy environment
variables that allow the user to redirect libcurl operations to use a proxy
controlled by the user.
# File descriptors, fork and NTLM
An application that uses libcurl and invokes *fork()* gets all file
descriptors duplicated in the child process, including the ones libcurl
created.
libcurl itself uses *fork()* and *execl()* if told to use the
**CURLAUTH_NTLM_WB** authentication method which then invokes the helper
command in a child process with file descriptors duplicated. Make sure that
only the trusted and reliable helper program is invoked!
# Secrets in memory
When applications pass usernames, passwords or other sensitive data to
libcurl to be used for upcoming transfers, those secrets are kept around as-is
in memory. In many cases they are stored in the heap for as long as the handle
itself for which the options are set.
If an attacker can access the heap, like maybe by reading swap space or via a
core dump file, such data might be accessible.
Further, when eventually closing a handle and the secrets are no longer
needed, libcurl does not explicitly clear memory before freeing it, so
credentials may be left in freed data.
# Saving files
libcurl cannot protect against attacks where an attacker has write access to
the same directory where libcurl is directed to save files.
# Cookies
If libcurl is built with PSL (**Public Suffix List**) support, it detects and
discards cookies that are specified for such suffix domains that should not be
allowed to have cookies.
if libcurl is *not* built with PSL support, it has no ability to stop super
cookies.
# Report Security Problems
Should you detect or just suspect a security problem in libcurl or curl,
contact the project curl security team immediately. See
https://curl.se/dev/secprocess.html for details.

62
deps/curl/docs/libcurl/libcurl-share.md vendored Normal file
View File

@ -0,0 +1,62 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: libcurl-share
Section: 3
Source: libcurl
See-also:
- curl_share_cleanup (3)
- curl_share_init (3)
- curl_share_setopt (3)
- libcurl-easy (3)
- libcurl-errors (3)
- libcurl-multi (3)
---
# NAME
libcurl-share - how to use the share interface
# DESCRIPTION
This is an overview on how to use the libcurl share interface in your C
programs. There are specific man pages for each function mentioned in
here.
All functions in the share interface are prefixed with curl_share.
# OBJECTIVES
The share interface was added to enable sharing of data between curl handles.
# ONE SET OF DATA - MANY TRANSFERS
You can have multiple easy handles share data between them. Have them update
and use the **same** cookie database, DNS cache, TLS session cache and/or
connection cache! This way, each single transfer takes advantage from data
updates made by the other transfer(s).
# SHARE OBJECT
You create a shared object with curl_share_init(3). It returns a handle
for a newly created one.
You tell the shared object what data you want it to share by using
curl_share_setopt(3).
Since you can use this share from multiple threads, and libcurl has no
internal thread synchronization, you must provide mutex callbacks if you are
using this multi-threaded. You set lock and unlock functions with
curl_share_setopt(3) too.
Then, you make an easy handle to use this share, you set the
CURLOPT_SHARE(3) option with curl_easy_setopt(3), and pass in
share handle. You can make any number of easy handles share the same share
handle.
To make an easy handle stop using that particular share, you set
CURLOPT_SHARE(3) to NULL for that easy handle. To make a handle stop
sharing a particular data, you can CURLSHOPT_UNSHARE(3) it.
When you are done using the share, make sure that no easy handle is still using
it, and call curl_share_cleanup(3) on the handle.

99
deps/curl/docs/libcurl/libcurl-thread.md vendored Normal file
View File

@ -0,0 +1,99 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: libcurl-thread
Section: 3
Source: libcurl
See-also:
- libcurl-security (3)
---
# NAME
libcurl-thread - libcurl thread safety
# Multi-threading with libcurl
libcurl is thread safe but has no internal thread synchronization. You may have
to provide your own locking should you meet any of the thread safety exceptions
below.
# Handles
You must **never** share the same handle in multiple threads. You can pass the
handles around among threads, but you must never use a single handle from more
than one thread at any given time.
# Shared objects
You can share certain data between multiple handles by using the share
interface but you must provide your own locking and set
curl_share_setopt(3) CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.
Note that some items are specifically documented as not thread-safe in the
share API (the connection pool and HSTS cache for example).
# TLS
All current TLS libraries libcurl supports are thread-safe. OpenSSL 1.1.0+ can
be safely used in multi-threaded applications provided that support for the
underlying OS threading API is built-in. For older versions of OpenSSL, the
user must set mutex callbacks.
# Signals
Signals are used for timing out name resolves (during DNS lookup) - when built
without using either the c-ares or threaded resolver backends. On systems that
have a signal concept.
When using multiple threads you should set the CURLOPT_NOSIGNAL(3)
option to 1L for all handles. Everything works fine except that timeouts
cannot be honored during DNS lookups - which you can work around by building
libcurl with c-ares or threaded-resolver support. c-ares is a library that
provides asynchronous name resolves. On some platforms, libcurl simply cannot
function properly multi-threaded unless the CURLOPT_NOSIGNAL(3) option
is set.
When CURLOPT_NOSIGNAL(3) is set to 1L, your application needs to deal
with the risk of a SIGPIPE (that at least the OpenSSL backend can
trigger). Note that setting CURLOPT_NOSIGNAL(3) to 0L does not work in a
threaded situation as there is a race condition where libcurl risks restoring
the former signal handler while another thread should still ignore it.
# Name resolving
The **gethostbyname** or **getaddrinfo** and other name resolving system
calls used by libcurl are provided by your operating system and must be thread
safe. It is important that libcurl can find and use thread safe versions of
these and other system calls, as otherwise it cannot function fully thread
safe. Some operating systems are known to have faulty thread
implementations. We have previously received problem reports on *BSD (at least
in the past, they may be working fine these days). Some operating systems that
are known to have solid and working thread support are Linux, Solaris and
Windows.
# curl_global_* functions
These functions are thread-safe since libcurl 7.84.0 if
curl_version_info(3) has the **CURL_VERSION_THREADSAFE** feature bit
set (most platforms).
If these functions are not thread-safe and you are using libcurl with multiple
threads it is especially important that before use you call
curl_global_init(3) or curl_global_init_mem(3) to explicitly
initialize the library and its dependents, rather than rely on the "lazy"
fail-safe initialization that takes place the first time
curl_easy_init(3) is called. For an in-depth explanation refer to
libcurl(3) section **GLOBAL CONSTANTS**.
# Memory functions
These functions, provided either by your operating system or your own
replacements, must be thread safe. You can use curl_global_init_mem(3)
to set your own replacement memory functions.
# Non-safe functions
CURLOPT_DNS_USE_GLOBAL_CACHE(3) is not thread-safe.
curl_version_info(3) is not thread-safe before libcurl initialization.

1455
deps/curl/docs/libcurl/libcurl-tutorial.md vendored Normal file
View File

File diff suppressed because it is too large Load Diff

162
deps/curl/docs/libcurl/libcurl-url.md vendored Normal file
View File

@ -0,0 +1,162 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: libcurl
Section: 3
Source: libcurl
See-also:
- CURLOPT_URL (3)
- curl_url (3)
- curl_url_cleanup (3)
- curl_url_dup (3)
- curl_url_get (3)
- curl_url_set (3)
- curl_url_strerror (3)
---
# NAME
libcurl-url - URL interface overview
# DESCRIPTION
The URL interface provides functions for parsing and generating URLs.
# INCLUDE
You still only include \<curl/curl.h\> in your code.
# CREATE
Create a handle that holds URL info and resources with curl_url(3):
~~~c
CURLU *h = curl_url();
~~~
# CLEANUP
When done with it, clean it up with curl_url_cleanup(3)
~~~c
curl_url_cleanup(h);
~~~
# DUPLICATE
When you need a copy of a handle, just duplicate it with curl_url_dup(3):
~~~c
CURLU *nh = curl_url_dup(h);
~~~
# PARSING
By setting a URL to the handle with curl_url_set(3), the URL is parsed
and stored in the handle. If the URL is not syntactically correct it returns
an error instead.
~~~c
rc = curl_url_set(h, CURLUPART_URL,
"https://example.com:449/foo/bar?name=moo", 0);
~~~
The zero in the fourth argument is a bitmask for changing specific features.
If successful, this stores the URL in its individual parts within the handle.
# REDIRECT
When a handle already contains info about a URL, setting a relative URL makes
it "redirect" to that.
~~~c
rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
~~~
# GET URL
The **CURLU** handle represents a URL and you can easily extract that with
curl_url_get(3):
~~~c
char *url;
rc = curl_url_get(h, CURLUPART_URL, &url, 0);
curl_free(url);
~~~
The zero in the fourth argument is a bitmask for changing specific features.
# GET PARTS
When a URL has been parsed or parts have been set, you can extract those
pieces from the handle at any time.
~~~c
rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);
rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);
rc = curl_url_get(h, CURLUPART_USER, &user, 0);
rc = curl_url_get(h, CURLUPART_ZONEID, &zoneid, 0);
~~~
Extracted parts are not URL decoded unless the user also asks for it with the
*CURLU_URLDECODE* flag set in the fourth bitmask argument.
Remember to free the returned string with curl_free(3) when you are done
with it!
# SET PARTS
A user set individual URL parts, either after having parsed a full URL or
instead of parsing such.
~~~c
rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
rc = curl_url_set(urlp, CURLUPART_ZONEID, "eth0", 0);
~~~
Set parts are not URL encoded unless the user asks for it with the
*CURLU_URLENCODE* flag.
# CURLU_APPENDQUERY
An application can append a string to the right end of the query part with the
*CURLU_APPENDQUERY* flag to curl_url_set(3).
Imagine a handle that holds the URL "https://example.com/?shoes=2". An
application can then add the string "hat=1" to the query part like this:
~~~c
rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
~~~
It notices the lack of an ampersand (&) separator and injects one, and the
handle's full URL then equals "https://example.com/?shoes=2&hat=1".
The appended string can of course also get URL encoded on add, and if asked to
URL encode, the encoding process skips the '=' character. For example, append
"candy=N&N" to what we already have, and URL encode it to deal with the
ampersand in the data:
~~~c
rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
CURLU_APPENDQUERY | CURLU_URLENCODE);
~~~
Now the URL looks like
~~~c
https://example.com/?shoes=2&hat=1&candy=N%26N
~~~
# AVAILABILITY
The URL API was introduced in libcurl 7.62.0.
A URL with a literal IPv6 address can be parsed even when IPv6 support is not
enabled.

123
deps/curl/docs/libcurl/libcurl-ws.md vendored Normal file
View File

@ -0,0 +1,123 @@
---
c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
SPDX-License-Identifier: curl
Title: libcurl
Section: 3
Source: libcurl
See-also:
- CURLOPT_CONNECT_ONLY (3)
- CURLOPT_WRITEFUNCTION (3)
- CURLOPT_WS_OPTIONS (3)
- curl_easy_init (3)
- curl_ws_meta (3)
- curl_ws_recv (3)
- curl_ws_send (3)
---
# NAME
libcurl-ws - WebSocket interface overview
# DESCRIPTION
The WebSocket interface provides functions for receiving and sending WebSocket
data.
# INCLUDE
You still only include \<curl/curl.h\> in your code.
# SETUP
WebSocket is also often known as *WebSockets*, in plural. It is done by
upgrading a regular HTTP(S) GET request to a WebSocket connection.
WebSocket is a TCP-like message-based communication protocol done over HTTP,
specified in RFC 6455.
To initiate a WebSocket session with libcurl, setup an easy handle to use a
URL with a "WS://" or "WSS://" scheme. "WS" is for cleartext communication
over HTTP and "WSS" is for doing WebSocket securely over HTTPS.
A WebSocket request is done as an HTTP/1 GET request with an "Upgrade
WebSocket" request header field. When the upgrade is accepted by the server,
it responds with a 101 Switching and then the client can speak WebSocket with
the server. The communication can happen in both directions at the same time.
# MESSAGES
WebSocket communication is message based. That means that both ends send and
receive entire messages, not streams like TCP. A WebSocket message is sent
over the wire in one or more frames. Each frame in a message can have a size
up to 2^63 bytes.
libcurl delivers WebSocket data as frame fragments. It might send a whole
frame, but it might also deliver them in pieces depending on size and network
patterns. It makes sure to provide the API user about the exact specifics
about the fragment: type, offset, size and how much data there is pending to
arrive for the same frame.
A message has an unknown size until the last frame header for the message has
been received since only frames have set sizes.
# Raw mode
libcurl can be told to speak WebSocket in "raw mode" by setting the
**CURLWS_RAW_MODE** bit to the CURLOPT_WS_OPTIONS(3) option.
Raw WebSocket means that libcurl passes on the data from the network without
parsing it leaving that entirely to the application. This mode assumes that
the user of this knows WebSocket and can parse and figure out the data all by
itself.
This mode is intended for applications that already have a WebSocket
parser/engine that want to switch over to use libcurl for enabling WebSocket,
and keep parts of the existing software architecture.
# PING
WebSocket is designed to allow long-lived sessions and in order to keep the
connections alive, both ends can send PING messages for the other end to
respond with a PONG.
libcurl automatically responds to server PING messages with a PONG. It does
not send any PING messages automatically.
# MODELS
Because of the many different ways WebSocket can be used, which is much more
flexible than limited to plain downloads or uploads, libcurl offers two
different API models to use it:
1. Using a write callback with CURLOPT_WRITEFUNCTION(3) much like other
downloads for when the traffic is download oriented.
2. Using CURLOPT_CONNECT_ONLY(3) and use the WebSocket recv/send
functions.
# Callback model
When a write callback is set and a WebSocket transfer is performed, the
callback is called to deliver all WebSocket data that arrives.
The callback can then call curl_ws_meta(3) to learn about the details of
the incoming data fragment.
# CONNECT_ONLY model
By setting CURLOPT_CONNECT_ONLY(3) to **2L**, the transfer only
establishes and setups the WebSocket communication and then returns control
back to the application.
Once such a setup has been successfully performed, the application can proceed
and use curl_ws_recv(3) and curl_ws_send(3) freely to exchange
WebSocket messages with the server.
# AVAILABILITY
The WebSocket API was introduced as experimental in 7.86.0 and is still
experimental today.
It is only built-in if explicitly opted in at build time. We discourage use of
the WebSocket API in production because of its experimental state. We might
change API, ABI and behavior before this "goes live".

Some files were not shown because too many files have changed in this diff Show More