romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-05-30 06:17:28 +03:00
Code Issues Projects Releases Packages Wiki Activity

tidy-up: miscellaneous

Browse source 
- tool_bname: scope an include.
- `endif` comments.
- Markdown fixes.
- comment tidy-ups.
- whitespace, newlines, indent.

Closes #20309
This commit is contained in:
Viktor Szakats 2026-01-02 01:34:05 +01:00
parent 62ba3604dc
commit ac6264366f
No known key found for this signature in database
GPG key ID: B5ABD165E2AEF201
98 changed files with 829 additions and 863 deletions
Download patch file Download diff file Expand all files Collapse all files

31
docs/CONTRIBUTE.md
View file

@ -224,9 +224,9 @@ How to write git commit messages in the curl project.
The first line is a succinct description of the change and should ideally work
as a single line in the RELEASE NOTES.
- use the imperative, present tense: **change** not "changed" nor "changes"
- do not capitalize the first letter
- no period (.) at the end
- use the imperative, present tense: **change** not "changed" nor "changes"
- do not capitalize the first letter
- no period (.) at the end
The `[area]` in the first line can be `http2`, `cookies`, `openssl` or
similar. There is no fixed list to select from but using the same "area" as
@ -238,36 +238,36 @@ Use the following ways to improve the message and provide pointers to related
work.
- `Follow-up to {shorthash}` - if this fixes or continues a previous commit;
add a `Ref:` that commit's PR or issue if it is not a small, obvious fix;
followed by an empty line
add a `Ref:` that commit's PR or issue if it is not a small, obvious fix;
followed by an empty line
- `Bug: URL` to the source of the report or more related discussion; use
`Fixes` for GitHub issues instead when that is appropriate.
`Fixes` for GitHub issues instead when that is appropriate.
- `Approved-by: John Doe` - credit someone who approved the PR.
- `Authored-by: John Doe` - credit the original author of the code; only use
this if you cannot use `git commit --author=...`.
this if you cannot use `git commit --author=...`.
- `Signed-off-by: John Doe` - we do not use this, but do not bother removing
it.
- `whatever-else-by:` credit all helpers, finders, doers; try to use one of
the following keywords if at all possible, for consistency: `Acked-by:`,
`Assisted-by:`, `Co-authored-by:`, `Found-by:`, `Reported-by:`,
`Reviewed-by:`, `Suggested-by:`, `Tested-by:`.
the following keywords if at all possible, for consistency: `Acked-by:`,
`Assisted-by:`, `Co-authored-by:`, `Found-by:`, `Reported-by:`,
`Reviewed-by:`, `Suggested-by:`, `Tested-by:`.
- `Ref: #1234` - if this is related to a GitHub issue or PR, possibly one that
has already been closed.
has already been closed.
- `Ref: URL` to more information about the commit; use `Bug:` instead for a
reference to a bug on another bug tracker]
reference to a bug on another bug tracker]
- `Fixes #1234` - if this fixes a GitHub issue; GitHub closes the issue once
this commit is merged.
this commit is merged.
- `Closes #1234` - if this merges a GitHub PR; GitHub closes the PR once this
commit is merged.
commit is merged.
Do not forget to use commit with `--author` if you commit someone else's work,
and make sure that you have your own user and email setup correctly in git
@ -289,7 +289,8 @@ Just ask if this is what you would want. You are required to have posted
several high quality patches first, before you can be granted push access.
## Useful resources
- [Webinar on getting code into curl](https://youtu.be/QmZ3W1d6LQI)
- [Webinar on getting code into curl](https://youtu.be/QmZ3W1d6LQI)
# Update copyright and license information

12
docs/HELP-US.md
View file

@ -33,12 +33,12 @@ If you are looking for a smaller or simpler task in the project to help out
with as an entry-point into the project, perhaps because you are a newcomer or
even maybe not a terribly experienced developer, here's our advice:
- Read through this document to get a grasp on a general approach to use
- Consider adding a test case for something not currently tested (correctly)
- Consider updating or adding documentation
- One way to get started gently in the project, is to participate in an
existing issue/PR and help out by reproducing the issue, review the code in
the PR etc.
- Read through this document to get a grasp on a general approach to use
- Consider adding a test case for something not currently tested (correctly)
- Consider updating or adding documentation
- One way to get started gently in the project, is to participate in an
existing issue/PR and help out by reproducing the issue, review the code in
the PR etc.
## Help wanted

14
docs/HSTS.md
View file

@ -21,14 +21,14 @@ HTTP-only requests to a hostname present in the cache gets internally
## `curl_easy_setopt()` options:
- `CURLOPT_HSTS_CTRL` - enable HSTS for this easy handle
- `CURLOPT_HSTS` - specify filename where to store the HSTS cache on close
(and possibly read from at startup)
- `CURLOPT_HSTS_CTRL` - enable HSTS for this easy handle
- `CURLOPT_HSTS` - specify filename where to store the HSTS cache on close
(and possibly read from at startup)
## curl command line options
- `--hsts [filename]` - enable HSTS, use the file as HSTS cache. If filename
is `""` (no length) then no file is used, only in-memory cache.
- `--hsts [filename]` - enable HSTS, use the file as HSTS cache. If filename
is `""` (no length) then no file is used, only in-memory cache.
## HSTS cache file format
@ -44,5 +44,5 @@ The time stamp is when the entry expires.
## Possible future additions
- `CURLOPT_HSTS_PRELOAD` - provide a set of HSTS hostnames to load first
- ability to save to something else than a file
- `CURLOPT_HSTS_PRELOAD` - provide a set of HSTS hostnames to load first
- ability to save to something else than a file

4
docs/HTTP3.md
View file

@ -33,8 +33,8 @@ master branch using pull-requests, just like ordinary changes.
To fix before we remove the experimental label:
- the used QUIC library needs to consider itself non-beta
- it is fine to "leave" individual backends as experimental if necessary
- the used QUIC library needs to consider itself non-beta
- it is fine to "leave" individual backends as experimental if necessary
# ngtcp2 version

12
docs/INSTALL-CMAKE.md
View file

@ -30,15 +30,15 @@ from the `projects/Windows` Visual Studio solution files, see
You can configure for in source tree builds or for a build tree
that is apart from the source tree.
- Build in the source tree.
- Build in the source tree.
$ cmake -B .
$ cmake -B .
- Build in a separate directory (parallel to the curl source tree in this
example). The build directory is created for you. This is recommended over
building in the source tree to separate source and build artifacts.
- Build in a separate directory (parallel to the curl source tree in this
example). The build directory is created for you. This is recommended over
building in the source tree to separate source and build artifacts.
$ cmake -B ../curl-build
$ cmake -B ../curl-build
For the full list of CMake build configuration variables see
[the corresponding section](#cmake-build-options).

189
docs/INSTALL.md
View file

@ -137,13 +137,13 @@ alter it, you can select how to deal with each individual library.
These options are provided to select the TLS backend to use.
- AmiSSL: `--with-amissl`
- GnuTLS: `--with-gnutls`.
- mbedTLS: `--with-mbedtls`
- OpenSSL: `--with-openssl` (also for BoringSSL, AWS-LC, LibreSSL, and quictls)
- Rustls: `--with-rustls`
- Schannel: `--with-schannel`
- wolfSSL: `--with-wolfssl`
- AmiSSL: `--with-amissl`
- GnuTLS: `--with-gnutls`.
- mbedTLS: `--with-mbedtls`
- OpenSSL: `--with-openssl` (also for BoringSSL, AWS-LC, LibreSSL, and quictls)
- Rustls: `--with-rustls`
- Schannel: `--with-schannel`
- wolfSSL: `--with-wolfssl`
You can build curl with *multiple* TLS backends at your choice, but some TLS
backends cannot be combined: if you build with an OpenSSL fork (or wolfSSL),
@ -161,16 +161,16 @@ start somewhere. Those "root" certificates make the set of Trust Anchors.
While the build system tries to find good defaults on the platform you
use, you may specify these explicitly. The following options are provided:
- `--with-ca-bundle=FILE`: the file that libcurl loads default root
certificates from.
- `--with-ca-path=DIRECTORY`: a directory in which root certificates files
are found.
- `--with-ca-embed=FILE`: a file read *at build time* and added to `libcurl`.
- `--with-ca-fallback`: an OpenSSL specific option for delegating default
trust anchor selection to what OpenSSL thinks is best, *if* there are
no other certificates configured by the application.
- `--with-apple-sectrust`: use the system "SecTrust" service on Apple
operating systems for verification. (Added in 8.17.0)
- `--with-ca-bundle=FILE`: the file that libcurl loads default root
certificates from.
- `--with-ca-path=DIRECTORY`: a directory in which root certificates files
are found.
- `--with-ca-embed=FILE`: a file read *at build time* and added to `libcurl`.
- `--with-ca-fallback`: an OpenSSL specific option for delegating default
trust anchor selection to what OpenSSL thinks is best, *if* there are
no other certificates configured by the application.
- `--with-apple-sectrust`: use the system "SecTrust" service on Apple
operating systems for verification. (Added in 8.17.0)
## MultiSSL and HTTP/3
@ -205,24 +205,24 @@ You can build curl with:
## Building Windows DLLs and C runtime (CRT) linkage issues
As a general rule, building a DLL with static CRT linkage is highly
discouraged, and intermixing CRTs in the same app is something to avoid at
any cost.
As a general rule, building a DLL with static CRT linkage is highly
discouraged, and intermixing CRTs in the same app is something to avoid at
any cost.
Reading and comprehending Microsoft Knowledge Base articles KB94248 and
KB140584 is a must for any Windows developer. Especially important is full
understanding if you are not going to follow the advice given above.
Reading and comprehending Microsoft Knowledge Base articles KB94248 and
KB140584 is a must for any Windows developer. Especially important is full
understanding if you are not going to follow the advice given above.
- [How To Use the C Runtime](https://learn.microsoft.com/troubleshoot/developer/visualstudio/cpp/libraries/use-c-run-time)
- [Runtime Library Compiler Options](https://learn.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library)
- [Potential Errors Passing CRT Objects Across DLL Boundaries](https://learn.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries)
- [How To Use the C Runtime](https://learn.microsoft.com/troubleshoot/developer/visualstudio/cpp/libraries/use-c-run-time)
- [Runtime Library Compiler Options](https://learn.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library)
- [Potential Errors Passing CRT Objects Across DLL Boundaries](https://learn.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries)
If your app is misbehaving in some strange way, or it is suffering from memory
corruption, before asking for further help, please try first to rebuild every
single library your app uses as well as your app using the debug
multi-threaded dynamic C runtime.
If you get linkage errors read section 5.7 of the FAQ document.
If you get linkage errors read section 5.7 of the FAQ document.
## Cygwin
@ -254,14 +254,14 @@ Download the latest version of the `cygwin` packages required (*and suggested*)
<summary>Package List</summary>
```
binutil - required
gcc-core - required
libpsl-devel - required
libtool - required
perl - required
make - required
- NOTE - if there is an error regarding make, open the cygwin terminal, and run:
ln -s /usr/bin/make /usr/bin/gmake
binutil - required
gcc-core - required
libpsl-devel - required
libtool - required
perl - required
make - required
- NOTE - if there is an error regarding make, open the cygwin terminal, and run:
ln -s /usr/bin/make /usr/bin/gmake
```
</details>
@ -282,13 +282,14 @@ Once all the packages have been installed, begin the process of installing curl
</details>
1. `sh configure <configure_options>`
2. `make`
1. `sh configure <configure_options>`
2. `make`
If any error occurs during curl installation, try:
- reinstalling the required `cygwin` packages from the list above
- temporarily move `cygwin` to the top of your path
- install all of the suggested `cygwin` packages
- reinstalling the required `cygwin` packages from the list above
- temporarily move `cygwin` to the top of your path
- install all of the suggested `cygwin` packages
## MS-DOS
@ -323,11 +324,11 @@ cmake . \
Notes:
- Requires DJGPP 2.04 or upper.
- Requires DJGPP 2.04 or upper.
- Compile Watt-32 (and OpenSSL) with the same version of DJGPP. Otherwise
things go wrong because things like FS-extensions and `errno` values have
been changed between releases.
- Compile Watt-32 (and OpenSSL) with the same version of DJGPP. Otherwise
things go wrong because things like FS-extensions and `errno` values have
been changed between releases.
## AmigaOS
@ -373,9 +374,9 @@ for the full list.
If you want to set any of these defines you have the following options:
- Modify `lib/config-win32.h`
- Modify `lib/curl_setup.h`
- Modify the "Preprocessor Definitions" in the libcurl project
- Modify `lib/config-win32.h`
- Modify `lib/curl_setup.h`
- Modify the "Preprocessor Definitions" in the libcurl project
Note: The pre-processor settings can be found using the Visual Studio IDE
under "Project -> Properties -> Configuration Properties -> C/C++ ->
@ -388,8 +389,8 @@ necessary to make the definition of the preprocessor symbol `USE_LWIPSOCK`
visible to libcurl and curl compilation processes. To set this definition you
have the following alternatives:
- Modify `lib/config-win32.h`
- Modify the "Preprocessor Definitions" in the libcurl project
- Modify `lib/config-win32.h`
- Modify the "Preprocessor Definitions" in the libcurl project
Note: The pre-processor settings can be found using the Visual Studio IDE
under "Project -> Properties -> Configuration Properties -> C/C++ ->
@ -578,47 +579,47 @@ know your application is not going to need. Besides specifying the
use, here are some other flags that can reduce the size of the library by
disabling support for some features (run `./configure --help` to see them all):
- `--disable-aws` (cryptographic authentication)
- `--disable-basic-auth` (cryptographic authentication)
- `--disable-bearer-auth` (cryptographic authentication)
- `--disable-digest-auth` (cryptographic authentication)
- `--disable-http-auth` (all HTTP authentication)
- `--disable-kerberos-auth` (cryptographic authentication)
- `--disable-negotiate-auth` (cryptographic authentication)
- `--disable-ntlm` (NTLM authentication)
- `--disable-alt-svc` (HTTP Alt-Svc)
- `--disable-ares` (the C-ARES DNS library)
- `--disable-cookies` (HTTP cookies)
- `--disable-dateparse` (date parsing for time conditionals)
- `--disable-dnsshuffle` (internal server load spreading)
- `--disable-doh` (DNS-over-HTTP)
- `--disable-form-api` (POST form API)
- `--disable-get-easy-options` (lookup easy options at runtime)
- `--disable-headers-api` (API to access headers)
- `--disable-hsts` (HTTP Strict Transport Security)
- `--disable-ipv6` (IPv6)
- `--disable-libcurl-option` (--libcurl C code generation support)
- `--disable-manual` (--manual built-in documentation)
- `--disable-mime` (MIME API)
- `--disable-netrc` (.netrc file)
- `--disable-progress-meter` (graphical progress meter in library)
- `--disable-proxy` (HTTP and SOCKS proxies)
- `--disable-socketpair` (socketpair for asynchronous name resolving)
- `--disable-threaded-resolver` (threaded name resolver)
- `--disable-tls-srp` (Secure Remote Password authentication for TLS)
- `--disable-unix-sockets` (Unix sockets)
- `--disable-verbose` (eliminates debugging strings and error code strings)
- `--disable-versioned-symbols` (versioned symbols)
- `--enable-symbol-hiding` (eliminates unneeded symbols in the shared library)
- `--without-brotli` (Brotli on-the-fly decompression)
- `--without-libpsl` (Public Suffix List in cookies)
- `--without-nghttp2` (HTTP/2 using nghttp2)
- `--without-ngtcp2` (HTTP/2 using ngtcp2)
- `--without-zstd` (Zstd on-the-fly decompression)
- `--without-libidn2` (internationalized domain names)
- `--without-librtmp` (RTMP)
- `--without-ssl` (SSL/TLS)
- `--without-zlib` (gzip/deflate on-the-fly decompression)
- `--disable-aws` (cryptographic authentication)
- `--disable-basic-auth` (cryptographic authentication)
- `--disable-bearer-auth` (cryptographic authentication)
- `--disable-digest-auth` (cryptographic authentication)
- `--disable-http-auth` (all HTTP authentication)
- `--disable-kerberos-auth` (cryptographic authentication)
- `--disable-negotiate-auth` (cryptographic authentication)
- `--disable-ntlm` (NTLM authentication)
- `--disable-alt-svc` (HTTP Alt-Svc)
- `--disable-ares` (the C-ARES DNS library)
- `--disable-cookies` (HTTP cookies)
- `--disable-dateparse` (date parsing for time conditionals)
- `--disable-dnsshuffle` (internal server load spreading)
- `--disable-doh` (DNS-over-HTTP)
- `--disable-form-api` (POST form API)
- `--disable-get-easy-options` (lookup easy options at runtime)
- `--disable-headers-api` (API to access headers)
- `--disable-hsts` (HTTP Strict Transport Security)
- `--disable-ipv6` (IPv6)
- `--disable-libcurl-option` (--libcurl C code generation support)
- `--disable-manual` (--manual built-in documentation)
- `--disable-mime` (MIME API)
- `--disable-netrc` (.netrc file)
- `--disable-progress-meter` (graphical progress meter in library)
- `--disable-proxy` (HTTP and SOCKS proxies)
- `--disable-socketpair` (socketpair for asynchronous name resolving)
- `--disable-threaded-resolver` (threaded name resolver)
- `--disable-tls-srp` (Secure Remote Password authentication for TLS)
- `--disable-unix-sockets` (Unix sockets)
- `--disable-verbose` (eliminates debugging strings and error code strings)
- `--disable-versioned-symbols` (versioned symbols)
- `--enable-symbol-hiding` (eliminates unneeded symbols in the shared library)
- `--without-brotli` (Brotli on-the-fly decompression)
- `--without-libpsl` (Public Suffix List in cookies)
- `--without-nghttp2` (HTTP/2 using nghttp2)
- `--without-ngtcp2` (HTTP/2 using ngtcp2)
- `--without-zstd` (Zstd on-the-fly decompression)
- `--without-libidn2` (internationalized domain names)
- `--without-librtmp` (RTMP)
- `--without-ssl` (SSL/TLS)
- `--without-zlib` (gzip/deflate on-the-fly decompression)
Be sure also to strip debugging symbols from your binaries after compiling
using 'strip' or an option like `-s`. If space is really tight, you may be able
@ -639,10 +640,10 @@ relevant tests by specifying certain key words on the `runtests.pl` command
line. Following is a list of appropriate key words for those configure options
that are not automatically detected:
- `--disable-cookies` !cookies
- `--disable-dateparse` !RETRY-AFTER !`CURLOPT_TIMECONDITION` !`CURLINFO_FILETIME` !`If-Modified-Since` !`curl_getdate` !`-z`
- `--disable-libcurl-option` !`--libcurl`
- `--disable-verbose` !verbose\ logs
- `--disable-cookies` !cookies
- `--disable-dateparse` !RETRY-AFTER !`CURLOPT_TIMECONDITION` !`CURLINFO_FILETIME` !`If-Modified-Since` !`curl_getdate` !`-z`
- `--disable-libcurl-option` !`--libcurl`
- `--disable-verbose` !verbose\ logs
# Ports

81
docs/INTERNALS.md
View file

@ -12,55 +12,54 @@ versions of libs and build tools.
## Portability
We write curl and libcurl to compile with C89 compilers on 32-bit and up
machines. Most of libcurl assumes more or less POSIX compliance but that is
not a requirement.
We write curl and libcurl to compile with C89 compilers on 32-bit and up
machines. Most of libcurl assumes more or less POSIX compliance but that is
not a requirement.
We write libcurl to build and work with lots of third party tools, and we
want it to remain functional and buildable with these and later versions
(older versions may still work but is not what we work hard to maintain):
We write libcurl to build and work with lots of third party tools, and we
want it to remain functional and buildable with these and later versions
(older versions may still work but is not what we work hard to maintain):
## Dependencies
We aim to support these or later versions.
We aim to support these or later versions.
- brotli 1.0.0 (2017-09-21)
- c-ares 1.6.0 (2008-12-09)
- GnuTLS 3.6.5 (2018-12-01)
- libidn2 2.0.0 (2017-03-29)
- LibreSSL 2.9.1 (2019-04-22)
- libssh 0.9.0 (2019-06-28)
- libssh2 1.9.0 (2019-06-20)
- mbedTLS 3.2.0 (2022-07-11)
- MIT Kerberos 1.3 (2003-07-31)
- nghttp2 1.15.0 (2016-09-25)
- OpenLDAP 2.0 (2000-08-01)
- OpenSSL 3.0.0 (2021-09-07)
- Windows XP 5.1 (2001-08-24 - 2009-04-14)
- wolfSSL 3.4.6 (2017-09-22)
- zlib 1.2.5.2 (2011-12-11)
- zstd 1.0 (2016-08-31)
- brotli 1.0.0 (2017-09-21)
- c-ares 1.6.0 (2008-12-09)
- GnuTLS 3.6.5 (2018-12-01)
- libidn2 2.0.0 (2017-03-29)
- LibreSSL 2.9.1 (2019-04-22)
- libssh 0.9.0 (2019-06-28)
- libssh2 1.9.0 (2019-06-20)
- mbedTLS 3.2.0 (2022-07-11)
- MIT Kerberos 1.3 (2003-07-31)
- nghttp2 1.15.0 (2016-09-25)
- OpenLDAP 2.0 (2000-08-01)
- OpenSSL 3.0.0 (2021-09-07)
- Windows XP 5.1 (2001-08-24 - 2009-04-14)
- wolfSSL 3.4.6 (2017-09-22)
- zlib 1.2.5.2 (2011-12-11)
- zstd 1.0 (2016-08-31)
## Build tools
When writing code (mostly for generating stuff included in release tarballs)
we use a few "build tools" and we make sure that we remain functional with
these versions:
When writing code (mostly for generating stuff included in release tarballs)
we use a few "build tools" and we make sure that we remain functional with
these versions:
- cmake 3.7 (2016-11-11)
- GNU autoconf 2.59 (2003-11-06)
- GNU automake 1.7 (2002-09-25)
- GNU libtool 1.4.2 (2001-09-11)
- GNU m4 1.4 (2007-09-21)
- mingw-w64 3.0 (2013-09-20)
- perl 5.8 (2002-07-19), on Windows: 5.22 (2015-06-01)
- Visual Studio 2010 10.0 (2010-04-12 - 2020-07-14)
- cmake 3.7 (2016-11-11)
- GNU autoconf 2.59 (2003-11-06)
- GNU automake 1.7 (2002-09-25)
- GNU libtool 1.4.2 (2001-09-11)
- GNU m4 1.4 (2007-09-21)
- mingw-w64 3.0 (2013-09-20)
- perl 5.8 (2002-07-19), on Windows: 5.22 (2015-06-01)
- Visual Studio 2010 10.0 (2010-04-12 - 2020-07-14)
Library Symbols
===============
## Library Symbols
All symbols used internally in libcurl must use a `Curl_` prefix if they are
used in more than a single file. Single-file symbols must be made static.
Public ("exported") symbols must use a `curl_` prefix. Public API functions
are marked with `CURL_EXTERN` in the public header files so that all others
can be hidden on platforms where this is possible.
All symbols used internally in libcurl must use a `Curl_` prefix if they are
used in more than a single file. Single-file symbols must be made static.
Public ("exported") symbols must use a `curl_` prefix. Public API functions
are marked with `CURL_EXTERN` in the public header files so that all others
can be hidden on platforms where this is possible.

6
docs/KNOWN_BUGS.md
View file

@ -181,9 +181,9 @@ libcurl are not equipped for that at the moment except when built with
_UNICODE and UNICODE defined. Except for Cygwin, Windows cannot use UTF-8 as a
locale.
https://curl.se/bug/?i=345
https://curl.se/bug/?i=731
https://curl.se/bug/?i=3747
https://curl.se/bug/?i=345
https://curl.se/bug/?i=731
https://curl.se/bug/?i=3747
NTLM authentication and Unicode

12
docs/KNOWN_RISKS.md
View file

@ -90,12 +90,12 @@ The curl command blanks the contents of a number of command line arguments to
prevent them from appearing in process listings. It does not blank all
arguments, even though some that are not blanked might contain sensitive data.
- not all systems allow the arguments to be blanked in the first place
- since curl blanks the argument itself they are readable for a short moment
no matter what
- virtually every argument can contain sensitive data, depending on use
- blanking all arguments would make it impractical for users to differentiate
curl command lines in process listings
- not all systems allow the arguments to be blanked in the first place
- since curl blanks the argument itself they are readable for a short moment
no matter what
- virtually every argument can contain sensitive data, depending on use
- blanking all arguments would make it impractical for users to differentiate
curl command lines in process listings
## HTTP headers in redirects

28
docs/MANUAL.md
View file

@ -503,18 +503,18 @@ happening. The different fields in the output have the following meaning:
From left-to-right:
- `%` - percentage completed of the whole transfer
- `Total` - total size of the whole expected transfer
- `%` - percentage completed of the download
- `Received` - currently downloaded amount of bytes
- `%` - percentage completed of the upload
- `Xferd` - currently uploaded amount of bytes
- `Average Speed Dload` - the average transfer speed of the download
- `Average Speed Upload` - the average transfer speed of the upload
- `Time Total` - expected time to complete the operation
- `Time Current` - time passed since the invoke
- `Time Left` - expected time left to completion
- `Curr.Speed` - the average transfer speed the last 5 seconds (the first
- `%` - percentage completed of the whole transfer
- `Total` - total size of the whole expected transfer
- `%` - percentage completed of the download
- `Received` - currently downloaded amount of bytes
- `%` - percentage completed of the upload
- `Xferd` - currently uploaded amount of bytes
- `Average Speed Dload` - the average transfer speed of the download
- `Average Speed Upload` - the average transfer speed of the upload
- `Time Total` - expected time to complete the operation
- `Time Current` - time passed since the invoke
- `Time Left` - expected time left to completion
- `Curr.Speed` - the average transfer speed the last 5 seconds (the first
5 seconds of a transfer is based on less time of course.)
The `-#` option displays a totally different progress bar that does not need
@ -907,8 +907,8 @@ tell the server we use a vt100 terminal, try something like:
Other interesting options for it `-t` include:
- `XDISPLOC=<X display>` Sets the X display location.
- `NEW_ENV=<var,val>` Sets an environment variable.
- `XDISPLOC=<X display>` Sets the X display location.
- `NEW_ENV=<var,val>` Sets an environment variable.
NOTE: The telnet protocol does not specify any way to login with a specified
user and password so curl cannot do that automatically. To do that, you need to

170
docs/Makefile.am
View file

@ -41,93 +41,93 @@ if BUILD_DOCS
CLEANFILES = $(MK_CA_DOCS) $(man_MANS) $(TEST_DOCS)
endif
TESTDOCS = \
tests/FILEFORMAT.md \
tests/HTTP.md \
tests/TEST-SUITE.md
TESTDOCS = \
tests/FILEFORMAT.md \
tests/HTTP.md \
tests/TEST-SUITE.md
INTERNALDOCS = \
internals/BUFQ.md \
internals/BUFREF.md \
internals/CHECKSRC.md \
internals/CLIENT-READERS.md \
internals/CLIENT-WRITERS.md \
internals/CODE_STYLE.md \
internals/CONNECTION-FILTERS.md \
internals/CURLX.md \
internals/DYNBUF.md \
internals/HASH.md \
internals/LLIST.md \
internals/MID.md \
internals/MQTT.md \
internals/MULTI-EV.md \
internals/NEW-PROTOCOL.md \
internals/PORTING.md \
internals/RATELIMITS.md \
internals/README.md \
internals/SCORECARD.md \
internals/SPLAY.md \
internals/STRPARSE.md \
internals/TIME-KEEPING.md \
internals/TLS-SESSIONS.md \
internals/UINT_SETS.md \
internals/WEBSOCKET.md
INTERNALDOCS = \
internals/BUFQ.md \
internals/BUFREF.md \
internals/CHECKSRC.md \
internals/CLIENT-READERS.md \
internals/CLIENT-WRITERS.md \
internals/CODE_STYLE.md \
internals/CONNECTION-FILTERS.md \
internals/CURLX.md \
internals/DYNBUF.md \
internals/HASH.md \
internals/LLIST.md \
internals/MID.md \
internals/MQTT.md \
internals/MULTI-EV.md \
internals/NEW-PROTOCOL.md \
internals/PORTING.md \
internals/RATELIMITS.md \
internals/README.md \
internals/SCORECARD.md \
internals/SPLAY.md \
internals/STRPARSE.md \
internals/TIME-KEEPING.md \
internals/TLS-SESSIONS.md \
internals/UINT_SETS.md \
internals/WEBSOCKET.md
EXTRA_DIST = \
$(CURLPAGES) \
$(INTERNALDOCS) \
$(TESTDOCS) \
ALTSVC.md \
BINDINGS.md \
BUG-BOUNTY.md \
BUGS.md \
CIPHERS.md \
CIPHERS-TLS12.md \
CMakeLists.txt \
CODE_OF_CONDUCT.md \
CODE_REVIEW.md \
CONTRIBUTE.md \
CURL-DISABLE.md \
CURLDOWN.md \
DEPRECATE.md \
DISTROS.md \
EARLY-RELEASE.md \
ECH.md \
EXPERIMENTAL.md \
FAQ.md \
FEATURES.md \
GOVERNANCE.md \
HELP-US.md \
HISTORY.md \
HSTS.md \
HTTP-COOKIES.md \
HTTP3.md \
HTTPSRR.md \
INFRASTRUCTURE.md \
INSTALL \
INSTALL-CMAKE.md \
INSTALL.md \
INTERNALS.md \
IPFS.md \
KNOWN_BUGS.md \
KNOWN_RISKS.md \
MAIL-ETIQUETTE.md \
MANUAL.md \
options-in-versions \
README.md \
RELEASE-PROCEDURE.md \
RUSTLS.md \
ROADMAP.md \
SECURITY-ADVISORY.md \
SPONSORS.md \
SSL-PROBLEMS.md \
SSLCERTS.md \
THANKS \
TODO.md \
TheArtOfHttpScripting.md \
URL-SYNTAX.md \
VERSIONS.md \
VULN-DISCLOSURE-POLICY.md
EXTRA_DIST = \
$(CURLPAGES) \
$(INTERNALDOCS) \
$(TESTDOCS) \
ALTSVC.md \
BINDINGS.md \
BUG-BOUNTY.md \
BUGS.md \
CIPHERS.md \
CIPHERS-TLS12.md \
CMakeLists.txt \
CODE_OF_CONDUCT.md \
CODE_REVIEW.md \
CONTRIBUTE.md \
CURL-DISABLE.md \
CURLDOWN.md \
DEPRECATE.md \
DISTROS.md \
EARLY-RELEASE.md \
ECH.md \
EXPERIMENTAL.md \
FAQ.md \
FEATURES.md \
GOVERNANCE.md \
HELP-US.md \
HISTORY.md \
HSTS.md \
HTTP-COOKIES.md \
HTTP3.md \
HTTPSRR.md \
INFRASTRUCTURE.md \
INSTALL \
INSTALL-CMAKE.md \
INSTALL.md \
INTERNALS.md \
IPFS.md \
KNOWN_BUGS.md \
KNOWN_RISKS.md \
MAIL-ETIQUETTE.md \
MANUAL.md \
options-in-versions \
README.md \
RELEASE-PROCEDURE.md \
RUSTLS.md \
ROADMAP.md \
SECURITY-ADVISORY.md \
SPONSORS.md \
SSL-PROBLEMS.md \
SSLCERTS.md \
THANKS \
TODO.md \
TheArtOfHttpScripting.md \
URL-SYNTAX.md \
VERSIONS.md \
VULN-DISCLOSURE-POLICY.md
CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@

2
docs/TODO.md
View file

@ -427,7 +427,7 @@ context information ourselves.
`CURLOPT_SSL_CTX_FUNCTION` works perfectly for HTTPS and email protocols, but
it has no effect for LDAPS connections.
[curl issue 4108](https://github.com/curl/curl/issues/4108)
[curl issue 4108](https://github.com/curl/curl/issues/4108)
## Paged searches on LDAP server

20
docs/URL-SYNTAX.md
View file

@ -11,9 +11,9 @@ SPDX-License-Identifier: curl
The official "URL syntax" is primarily defined in these two different
specifications:
- [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) (although URL is called
"URI" in there)
- [The WHATWG URL Specification](https://url.spec.whatwg.org/)
- [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) (although URL is called
"URI" in there)
- [The WHATWG URL Specification](https://url.spec.whatwg.org/)
RFC 3986 is the earlier one, and curl has always tried to adhere to that one
(since it shipped in January 2005).
@ -100,13 +100,13 @@ supported by browsers early on and has been mimicked by curl.
Based on what the hostname starts with, curl "guesses" what protocol to use:
- `ftp.` means FTP
- `dict.` means DICT
- `ldap.` means LDAP
- `imap.` means IMAP
- `smtp.` means SMTP
- `pop3.` means POP3
- all other means HTTP
- `ftp.` means FTP
- `dict.` means DICT
- `ldap.` means LDAP
- `imap.` means IMAP
- `smtp.` means SMTP
- `pop3.` means POP3
- all other means HTTP
### Globbing letters

12
docs/VULN-DISCLOSURE-POLICY.md
View file

@ -277,12 +277,12 @@ arguments, even though some that are not blanked might contain sensitive
data. We consider this functionality a best-effort and omissions are not
security vulnerabilities.
- not all systems allow the arguments to be blanked in the first place
- since curl blanks the argument itself they are readable for a short moment
no matter what
- virtually every argument can contain sensitive data, depending on use
- blanking all arguments would make it impractical for users to differentiate
curl command lines in process listings
- not all systems allow the arguments to be blanked in the first place
- since curl blanks the argument itself they are readable for a short moment
no matter what
- virtually every argument can contain sensitive data, depending on use
- blanking all arguments would make it impractical for users to differentiate
curl command lines in process listings
## Busy-loops

32
docs/examples/htmltitle.cpp
View file

@ -25,12 +25,12 @@
* Get a webpage, extract the title with libxml.
* </DESC>
Written by Lars Nilsson
Written by Lars Nilsson
GNU C++ compile command line suggestion (edit paths accordingly):
GNU C++ compile command line suggestion (edit paths accordingly):
g++ -Wall -I/opt/curl/include -I/opt/libxml/include/libxml2 htmltitle.cpp \
-o htmltitle -L/opt/curl/lib -L/opt/libxml/lib -lcurl -lxml2
g++ -Wall -I/opt/curl/include -I/opt/libxml/include/libxml2 htmltitle.cpp \
-o htmltitle -L/opt/curl/lib -L/opt/libxml/lib -lcurl -lxml2
*/
#include <stdio.h>
#include <string.h>
@ -42,7 +42,7 @@
#include <libxml/HTMLparser.h>
//
// Case-insensitive string comparison
// Case-insensitive string comparison
//
#ifdef _WIN32
@ -52,7 +52,7 @@
#endif
//
// libxml callback context structure
// libxml callback context structure
//
struct Context {
Context() : addTitle(false) {}
@ -62,13 +62,13 @@ struct Context {
};
//
// libcurl variables for error strings and returned data
// libcurl variables for error strings and returned data
static char errorBuffer[CURL_ERROR_SIZE];
static std::string buffer;
//
// libcurl write callback function
// libcurl write callback function
//
static size_t writer(char *data, size_t size, size_t nmemb,
std::string *writerData)
@ -82,7 +82,7 @@ static size_t writer(char *data, size_t size, size_t nmemb,
}
//
// libcurl connection initialization
// libcurl connection initialization
//
static bool init(CURL *&curl, const char *url)
{
@ -129,7 +129,7 @@ static bool init(CURL *&curl, const char *url)
}
//
// libxml start element callback function
// libxml start element callback function
//
static void StartElement(void *voidContext,
const xmlChar *name,
@ -145,7 +145,7 @@ static void StartElement(void *voidContext,
}
//
// libxml end element callback function
// libxml end element callback function
//
static void EndElement(void *voidContext,
const xmlChar *name)
@ -157,7 +157,7 @@ static void EndElement(void *voidContext,
}
//
// Text handling helper function
// Text handling helper function
//
static void handleCharacters(Context *context,
const xmlChar *chars,
@ -169,7 +169,7 @@ static void handleCharacters(Context *context,
}
//
// libxml PCDATA callback function
// libxml PCDATA callback function
//
static void Characters(void *voidContext,
const xmlChar *chars,
@ -181,7 +181,7 @@ static void Characters(void *voidContext,
}
//
// libxml CDATA callback function
// libxml CDATA callback function
//
static void cdata(void *voidContext,
const xmlChar *chars,
@ -193,7 +193,7 @@ static void cdata(void *voidContext,
}
//
// libxml SAX callback structure
// libxml SAX callback structure
//
static htmlSAXHandler saxHandler = {
NULL,
@ -231,7 +231,7 @@ static htmlSAXHandler saxHandler = {
};
//
// Parse given (assumed to be) HTML text and return the title
// Parse given (assumed to be) HTML text and return the title
//
static void parseHtml(const std::string &html,
std::string &title)

15
docs/internals/CONNECTION-FILTERS.md
View file

@ -34,9 +34,9 @@ Curl_easy *data connectdata *conn cf-ssl cf-socket
|https://curl.se/|----> | properties |----> | keys |---> | socket |--> OS --> network
+----------------+ +-----------------+ +-------+ +--------+
Curl_write(data, buffer)
Curl_write(data, buffer)
--> Curl_cfilter_write(data, data->conn, buffer)
---> conn->filter->write(conn->filter, data, buffer)
--> conn->filter->write(conn->filter, data, buffer)
```
While connection filters all do different things, they look the same from the
@ -77,10 +77,9 @@ etc.
Each filter does in principle the following:
```
static CURLcode
myfilter_cf_connect(struct Curl_cfilter *cf,
struct Curl_easy *data,
bool *done)
static CURLcode myfilter_cf_connect(struct Curl_cfilter *cf,
struct Curl_easy *data,
bool *done)
{
CURLcode result;
@ -140,8 +139,8 @@ filter, once it is connected, just passes the calls through. Those filters
implementations look like this:
```
ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
const void *buf, size_t len, CURLcode *err)
ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
const void *buf, size_t len, CURLcode *err)
{
return cf->next->cft->do_send(cf->next, data, buf, len, err);
}

9
docs/internals/MQTT.md
View file

@ -51,7 +51,8 @@ Whenever a PUBLISH packet is received, curl outputs two bytes topic length
## Caveats
Remaining limitations:
- Only QoS level 0 is implemented for publish
- No way to set retain flag for publish
- No TLS (mqtts) support
- Naive EAGAIN handling does not handle split messages
- Only QoS level 0 is implemented for publish
- No way to set retain flag for publish
- No TLS (mqtts) support
- Naive EAGAIN handling does not handle split messages

14
docs/internals/WEBSOCKET.md
View file

@ -88,13 +88,13 @@ work has not been started.
Ideas:
- Read stdin and send off as messages. Consider newline as end of fragment.
(default to text? offer option to set binary)
- Respond to PINGs automatically
- Issue PINGs at some default interval (option to switch off/change interval?)
- Allow `-d` to specify (initial) data to send (should the format allow for
multiple separate frames?)
- Exit after N messages received, where N can be zero.
- Read stdin and send off as messages. Consider newline as end of fragment.
(default to text? offer option to set binary)
- Respond to PINGs automatically
- Issue PINGs at some default interval (option to switch off/change interval?)
- Allow `-d` to specify (initial) data to send (should the format allow for
multiple separate frames?)
- Exit after N messages received, where N can be zero.
## Future work

208
docs/libcurl/Makefile.inc
View file

@ -24,107 +24,107 @@
# Shared between CMakeLists.txt and Makefile.am
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_ssls_export.3 \
curl_easy_ssls_import.3 \
curl_easy_strerror.3 \
curl_easy_unescape.3 \
curl_easy_upkeep.3 \
curl_escape.3 \
curl_formadd.3 \
curl_formfree.3 \
curl_formget.3 \
curl_free.3 \
curl_getdate.3 \
curl_getenv.3 \
curl_global_cleanup.3 \
curl_global_init.3 \
curl_global_init_mem.3 \
curl_global_sslset.3 \
curl_global_trace.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_get_offt.3 \
curl_multi_info_read.3 \
curl_multi_init.3 \
curl_multi_notify_disable.3 \
curl_multi_notify_enable.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_wait.3 \
curl_multi_waitfds.3 \
curl_multi_wakeup.3 \
curl_pushheader_byname.3 \
curl_pushheader_bynum.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 \
curl_ws_start_frame.3 \
libcurl-easy.3 \
libcurl-env-dbg.3 \
libcurl-env.3 \
libcurl-errors.3 \
libcurl-multi.3 \
libcurl-security.3 \
libcurl-share.3 \
libcurl-symbols.3 \
libcurl-thread.3 \
libcurl-tutorial.3 \
libcurl-url.3 \
libcurl-ws.3 \
libcurl.3
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_ssls_export.3 \
curl_easy_ssls_import.3 \
curl_easy_strerror.3 \
curl_easy_unescape.3 \
curl_easy_upkeep.3 \
curl_escape.3 \
curl_formadd.3 \
curl_formfree.3 \
curl_formget.3 \
curl_free.3 \
curl_getdate.3 \
curl_getenv.3 \
curl_global_cleanup.3 \
curl_global_init.3 \
curl_global_init_mem.3 \
curl_global_sslset.3 \
curl_global_trace.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_get_offt.3 \
curl_multi_info_read.3 \
curl_multi_init.3 \
curl_multi_notify_disable.3 \
curl_multi_notify_enable.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_wait.3 \
curl_multi_waitfds.3 \
curl_multi_wakeup.3 \
curl_pushheader_byname.3 \
curl_pushheader_bynum.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 \
curl_ws_start_frame.3 \
libcurl-easy.3 \
libcurl-env-dbg.3 \
libcurl-env.3 \
libcurl-errors.3 \
libcurl-multi.3 \
libcurl-security.3 \
libcurl-share.3 \
libcurl-symbols.3 \
libcurl-thread.3 \
libcurl-tutorial.3 \
libcurl-url.3 \
libcurl-ws.3 \
libcurl.3

4
docs/libcurl/curl_formget.md
View file

@ -34,8 +34,8 @@ 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);"
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.

16
docs/libcurl/curl_multi_info_read.md
View file

@ -52,14 +52,14 @@ 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;
};
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

6
docs/libcurl/libcurl-multi.md
View file

@ -177,7 +177,7 @@ 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
- Name resolves unless the c-ares or threaded-resolver backends are used
- file:// transfers
- TELNET transfers
~~~

2
docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md
View file

@ -53,7 +53,7 @@ CURLE_CONV_REQD error code.
If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
For example:
~~~c
#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
~~~
The iconv code in libcurl defaults the network and UTF8 codeset names as

2
docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md
View file

@ -60,7 +60,7 @@ int main(void)
curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data);
curl_easy_perform(curl);
}
}
}
~~~

2
docs/runtests.md
View file

@ -5,7 +5,7 @@ Title: runtests.pl
Section: 1
Source: runtests
See-also:
- runtests.pl
- runtests.pl
Added-in: 7.5
---

2
docs/testcurl.md
View file

@ -5,7 +5,7 @@ Title: testcurl.pl
Section: 1
Source: testcurl
See-also:
- runtests.pl
- runtests.pl
Added-in: 7.11.2
---

32
docs/tests/CI.md
View file

@ -11,13 +11,13 @@ large number of test suites.
Every pull request is verified for each of the following:
- it still builds, warning-free, on Linux, macOS, Windows, BSDs, with both
clang and gcc, autotools and cmake, out-of-tree and in-tree.
- it still builds fine on Windows with all supported MSVC versions
- it follows rudimentary code style rules
- the test suite still runs 100% fine
- the release tarball (the "dist") still works
- different TLS backends and options still compile and pass tests
- it still builds, warning-free, on Linux, macOS, Windows, BSDs, with both
clang and gcc, autotools and cmake, out-of-tree and in-tree.
- it still builds fine on Windows with all supported MSVC versions
- it follows rudimentary code style rules
- the test suite still runs 100% fine
- the release tarball (the "dist") still works
- different TLS backends and options still compile and pass tests
If the pull-request fails one of these tests, it shows up as a red X and you
are expected to fix the problem. If you do not understand what the issue is or
@ -26,15 +26,15 @@ can likely help out.
Consider the following table while looking at pull request failures:
| CI platform as shown in PR | State | What to look at next |
| ----------------------------------- | ------ | -------------------------- |
| Linux / macOS / Windows / ... | stable | all errors and failures |
| Fuzzer | stable | fuzzing results |
| Code analyzers | stable | new findings |
| checkdocs / checksrc / dist / ... | stable | all errors and failures |
| AppVeyor | stable | all errors and failures |
| buildbot/curl_Schannel ... | stable | all errors and failures |
| curl.curl (linux ...) | stable | all errors and failures |
| CI platform as shown in PR | State | What to look at next |
| ----------------------------------- | ------ | -------------------------- |
| Linux / macOS / Windows / ... | stable | all errors and failures |
| Fuzzer | stable | fuzzing results |
| Code analyzers | stable | new findings |
| checkdocs / checksrc / dist / ... | stable | all errors and failures |
| AppVeyor | stable | all errors and failures |
| buildbot/curl_Schannel ... | stable | all errors and failures |
| curl.curl (linux ...) | stable | all errors and failures |
Sometimes the tests fail or run slowly due to a dependency service temporarily
having issues, for example package downloads, or virtualized (non-native)

16
docs/tests/FILEFORMAT.md
View file

@ -302,14 +302,14 @@ test file to load the list content.
Send back this contents instead of the `<data>` one. The `NUM` is set by:
- The test number in the request line is >10000 and this is the remainder
of [test case number]%10000.
- The request was HTTP and included digest details, which adds 1000 to `NUM`
- If an HTTP request is NTLM type-1, it adds 1001 to `NUM`
- If an HTTP request is NTLM type-3, it adds 1002 to `NUM`
- If an HTTP request is Basic and `NUM` is already >=1000, it adds 1 to `NUM`
- If an HTTP request is Negotiate, `NUM` gets incremented by one for each
request with Negotiate authorization header on the same test case.
- The test number in the request line is >10000 and this is the remainder of
[test case number]%10000.
- The request was HTTP and included digest details, which adds 1000 to `NUM`
- If an HTTP request is NTLM type-1, it adds 1001 to `NUM`
- If an HTTP request is NTLM type-3, it adds 1002 to `NUM`
- If an HTTP request is Basic and `NUM` is already >=1000, it adds 1 to `NUM`
- If an HTTP request is Negotiate, `NUM` gets incremented by one for each
request with Negotiate authorization header on the same test case.
Dynamically changing `NUM` in this way allows the test harness to be used to
test authentication negotiation where several different requests must be sent