Previously this was one single manpage for two functions but as they are
two separate ones since a while back, they should each clearly document
their single specific functions.
Follow-up to eefcc1bda4Closes#14068
- use imperative form
- use lowercase
- no period
- unify some phrases
- fix curl_multi_socket and curl_multi_socket_all to keep their own
descriptions
Closes#14062
Fix issues detected.
Also:
- One of the `.vc` files used LF EOLs, while the other didn't.
Make that one also use LF EOLs, as this is apparently supported by
`nmake`.
- Drop `.dsw` and `.btn` types from `.gitattributes`.
The repository doesn't use them.
- Sync section order with the rest of files in
`tests/certs/EdelCurlRoot-ca.prm`.
- Indent/align `.prm` and `.pem` files.
- Delete dummy `[something]` section from `.prm` and `.pem` files.
Mental note:
MSVC `.sln` files seem to accept spaces for indentation and also support
LF line-endings. I cannot test this and I don't know what's more
convenient when updating them, so left them as-is, with specific
exclusions.
Closes#14031
When libcurl discards a connection there are two phases this may go
through: "shutdown" and "closing". If a connection is aborted, the
shutdown phase is skipped and it is closed right away.
The connection filters attached to the connection implement the phases
in their `do_shutdown()` and `do_close()` callbacks. Filters carry now a
`shutdown` flags next to `connected` to keep track of the shutdown
operation.
Filters are shut down from top to bottom. If a filter is not connected,
its shutdown is skipped. Notable filters that *do* something during
shutdown are HTTP/2 and TLS. HTTP/2 sends the GOAWAY frame. TLS sends
its close notify and expects to receive a close notify from the server.
As sends and receives may EAGAIN on the network, a shutdown is often not
successful right away and needs to poll the connection's socket(s). To
facilitate this, such connections are placed on a new shutdown list
inside the connection cache.
Since managing this list requires the cooperation of a multi handle,
only the connection cache belonging to a multi handle is used. If a
connection was in another cache when being discarded, it is removed
there and added to the multi's cache. If no multi handle is available at
that time, the connection is shutdown and closed in a one-time,
best-effort attempt.
When a multi handle is destroyed, all connection still on the shutdown
list are discarded with a final shutdown attempt and close. In curl
debug builds, the environment variable `CURL_GRACEFUL_SHUTDOWN` can be
set to make this graceful with a timeout in milliseconds given by the
variable.
The shutdown list is limited to the max number of connections configured
for a multi cache. Set via CURLMOPT_MAX_TOTAL_CONNECTIONS. When the
limit is reached, the oldest connection on the shutdown list is
discarded.
- In multi_wait() and multi_waitfds(), collect all connection caches
involved (each transfer might carry its own) into a temporary list.
Let each connection cache on the list contribute sockets and
POLLIN/OUT events it's connections are waiting for.
- in multi_perform() collect the connection caches the same way and let
them peform their maintenance. This will make another non-blocking
attempt to shutdown all connections on its shutdown list.
- for event based multis (multi->socket_cb set), add the sockets and
their poll events via the callback. When `multi_socket()` is invoked
for a socket not known by an active transfer, forward this to the
multi's cache for processing. On closing a connection, remove its
socket(s) via the callback.
TLS connection filters MUST NOT send close nofity messages in their
`do_close()` implementation. The reason is that a TLS close notify
signals a success. When a connection is aborted and skips its shutdown
phase, the server needs to see a missing close notify to detect
something has gone wrong.
A graceful shutdown of FTP's data connection is performed implicitly
before regarding the upload/download as complete and continuing on the
control connection. For FTP without TLS, there is just the socket close
happening. But with TLS, the sent/received close notify signals that the
transfer is complete and healthy. Servers like `vsftpd` verify that and
reject uploads without a TLS close notify.
- added test_19_* for shutdown related tests
- test_19_01 and test_19_02 test for TCP RST packets
which happen without a graceful shutdown and should
no longer appear otherwise.
- add test_19_03 for handling shutdowns by the server
- add test_19_04 for handling shutdowns by curl
- add test_19_05 for event based shutdowny by server
- add test_30_06/07 and test_31_06/07 for shutdown checks
on FTP up- and downloads.
Closes#13976
There are a places where man pages reference deprecated CURLOPT options,
where it doesn't make sense, replace them with the reccomended
replacement option.
also remove reference to the removed mesalink TLS backend
Closes#13951
Introduce new notation for CURLOPT_INTERFACE / --interface:
ifhost!<interface>!<host>
Binding to an interface doesn't set the address, and an interface can
have multiple addresses.
When binding to an address (without interface), the kernel is free to
choose the route, and it can route through any device that can access
the target address, not necessarily the one with the chosen address.
Moreover, it is possible for different interfaces to have the same IP
address, on which case we need to provide a way to be more specific.
Factor out the parsing part of interface option, and add unit tests:
1663.
Closes#13719
- similar to openssl, use a shared 'credentials' instance
among TLS connections with a plain configuration.
- different to openssl, a connection with a client certificate
is not eligible to sharing.
- document CURLOPT_CA_CACHE_TIMEOUT in man page
Closes#13795
Used for extracting:
- when used asking for a scheme, it will return CURLUE_NO_SCHEME if the
stored information was a guess
- when used asking for a URL, the URL is returned without a scheme, like
when previously given to the URL parser when it was asked to guess
- as soon as the scheme is set explicitly, it is no longer internally
marked as guessed
The idea being:
1. allow a user to figure out if a URL's scheme was set as a result of
guessing
2. extract the URL without a guessed scheme
3. this makes it work similar to how we already deal with port numbers
Extend test 1560 to verify.
Closes#13616
Like when we list a series of options and then want to add "normal" text
again afterwards.
Without this, the indentation level wrongly continues even after the
final "##" header, making following text wrongly appear to belong to the
header above.
Adjusted several curldown files to use this.
Fixes#13803
Reported-by: Jay Satiro
Closes#13806
- Clear data->state.os_errno before transfer.
- Explain the change in behavior in the CURLINFO_OS_ERRNO doc.
- Add to the CURLINFO_OS_ERRNO doc the list of libcurl network-related
errors that may cause the errno to be saved.
data->state.os_errno is saved before libcurl returns a network-related
failure such as connection failure. It is accessible to the user via
CURLINFO_OS_ERRNO so they can get more information about the failure.
Prior to this change it wasn't cleared before transfer, so if a user
retrieved the saved errno it could be from a previous transfer. That is
because an errno is not always saved for network-related errors.
Closes https://github.com/curl/curl/pull/13574
CURLOPT_EGDSOCKET and CURLOPT_RANDOM_FILE are both completely dead
so remove their example sections since the code there is useless.
There is still a way to inject a random file for OpenSSL older than
1.1.0 but it's not what the example showed (and it's not even done
with this option) so we refrain from documenting it here.
Closes: #13540
Reviewed-by: Daniel Stenberg <daniel@haxx.se>
Fix wording of comments, and misquotings where `' is markdown parsed
where it shouldn't be, and remove a misspelled preprocessor comment
which really isn't needed (and removing it makes it match surrounding
code better).
Closes: #13538
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Use a lookup list to set the cipher suites, allowing the
ciphers to be set by either openssl or IANA names.
To keep the binary size of the lookup list down we compress
each entry in the cipher list down to 2 + 6 bytes using the
C preprocessor.
Closes#13442
- Call OPENSSL_thread_stop on thread termination (DLL_THREAD_DETACH)
to prevent a memory leak in case OpenSSL is linked statically.
- Warn in libcurl-thread.3 that if OpenSSL is linked statically then it
may require thread cleanup.
OpenSSL may need per-thread cleanup to stop a memory leak. For Windows
and Cygwin if libcurl was built as a DLL then we can do that for the
user by calling OPENSSL_thread_stop on thread termination. However, if
libcurl was built statically then we do not have notification of thread
termination and cannot do that for the user.
Also, there are several other unusual cases where it may be necessary
for the user to call OPENSSL_thread_stop, so in the libcurl-thread
warning I added a link to the OpenSSL documentation.
Co-authored-by: Viktor Szakats
Reported-by: southernedge@users.noreply.github.com
Reported-by: zmcx16@users.noreply.github.com
Ref: https://www.openssl.org/docs/man3.0/man3/OPENSSL_thread_stop.html#NOTES
Fixes https://github.com/curl/curl/issues/12327
Closes https://github.com/curl/curl/pull/12408
The rustls backend advertises SSLSUPP_TLS13_CIPHERSUITES, but
the code does not actually seem to support it (yet?). Removed
the flag and corrected documentation.
Closes#13452
By default the API inhibits empty queries and fragments extracted.
Unless this new flag is set.
This also makes the behavior more consistent: without it set, zero
length queries and fragments are considered not present in the URL. With
the flag set, they are returned as a zero length strings if they were in
fact present in the URL.
This applies when extracting the individual query and fragment
components and for the full URL.
Closes#13396
The bounds of the size parameter were not specified, and nor was it
specified how to disable the maximum file size check.
The documentation also incorrectly stated that CURLOPT_MAXFILESIZE
always returns CURLE_OK and that CURLOPT_MAXFILESIZE_LARGE only returns
CURLE_OK or CURLE_UNKNOWN_OPTION.
It also did not mention what the default value is, which is zero. This
commit updates the documentation to make note of all these things.
Closes#13372
It's important to set `CURLOPT_NOPROGRESS` to `0` if you want your
transfer callback function, set by `CURLOPT_XFERINFOFUNCTION`, getting
called. To emphasize this to the users, add this to the code example.
Closes#13348
Rename custom target to namespaced (unique) names to avoid colliding
with 3rd-party projects (e.g. libzip) built together with curl.
Reported-by: hammlee96 on github
Fixes#13324Closes#13326
- add `CURL_TRC_READ()` and `CURL_TRC_WRITE()`
- use in generic client writers and readers, as well
as http headers, chunking and websockets
Closes#13223
This time limit the number of files per command to avoid exceeding
limitations of certain OS/shell envs.
Such known env is Windows with the `cmd.exe` shell, which features an
8K command-line length limit to this day.
Allowlisting `UNIX` to have no limit and using a limit of 200 for other
envs to be safe. If there is a way to detect `cmd.exe` and/or we know
which precise envs are sensitive to this, we can tweak these conditions
further.
Even with the low limit, this patch reduces external commands by 200x,
making builds much faster.
Ref: #127622620aa930b (initial)
Ref: #13047f03c85635f (revert)
Reviewed-by: Daniel Stenberg
Closes#13207
Remove the PROTOCOLS section from the source files completely and
instead generate them based on the header data in the curldown files.
It also generates TLS backend information for options marked for TLS as
protocol.
Closes#13175
All man pages that are listed to be for TLS now must also specify
exactly what TLS backends the option works for, or use All if they all
work.
cd2nroff makes sure this is done and that the listed backends exist.
Closes#13168
- CURLINFO_TLS_SESSION.md: remove mention of NSS
- CURLINFO_TLS_SSL_PTR.md: remove NSS leftover
- CURLOPT_CAINFO.md: drop mention of backends not supporting this
- CURLOPT_CAPATH.md: wolfSSL also supports this
Closes#13166
The mandatory header now has a mandatory list of protocols for which the
manpage is relevant.
Most man pages already has a "PROTOCOLS" section, but this introduces a
stricter way to specify the relevant protocols.
cd2nroff verifies that at least one protocol is mentioned (which can be
`*`).
This information is not used just yet, but A) the PROTOCOLS section can
now instead get generated and get a unified wording across all manpages
and B) this allows us to more reliably filter/search for protocol
specific manpages/options.
Closes#13166
Create ASCII version of manpage without nroff
- build src/tool_hugegelp.c from the ascii manpage
- move the the manpage and the ascii version build to docs/cmdline-opts
- remove all use of nroff from the build process
- should make the build entirely reproducible (by avoiding nroff)
- partly reverts 2620aa9 to build libcurl option man pages one by one
in cmake because the appveyor builds got all crazy until I did
The ASCII version of the manpage
- is built with gen.pl, just like the manpage is
- has a right-justified column making the appearance similar to the previous
version
- uses a 4-space indent per level (instead of the old version's 7)
- does not do hyphenation of words (which nroff does)
History
We first made the curl build use nroff for building the hugehelp file in
December 1998, for curl 5.2.
Closes#13047
This fixes miscellaneous typos and duplicated words in the docs, lib
and test comments and a few user facing errorstrings.
Author: RainRat on Github
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Reviewed-by: Dan Fandrich <dan@coneharvesters.com>
Closes: #13019
The curldown conversion accidentally replaced daniel@haxx.se with
just daniel.se. This reverts back to the proper email address in
the curldown docs as well as in a few other stray places where it
was incorrect (while unrelated to curldown).
Reviewed-by: Daniel Stenberg <daniel@haxx.se>
Closes: #12997
- refs #12397 where it is dicussed how to en-/disable verbose output
of DoH operations
- introducing `struct curl_trc_feat` to track a curl feature for
tracing
- adding `data->state.feat` optionally pointing to the feature a
transfer belongs to
- adding trace functions and verbosity checks on features
- using trace feature in DoH code
- documenting `doh` as feature for `--trace-config`
Closes#12411
- when data arrived in several chunks, the collection into
the passed buffer always started at offset 0, overwriting
the data already there.
adding test_20_07 to verify fix
- debug environment var CURL_WS_CHUNK_SIZE can be used to
influence the buffer chunk size used for en-/decoding.
Closes#12945
- can be borrowed by transfer during recv-write operation
- needs to be released before borrowing again
- adjustis size to `data->set.buffer_size`
- used in transfer.c readwrite_data()
Closes#12805
Make sure we use \< and \> in markdown all over so that it renders
correctly, on GitHub and elsewhere. cd2nroff now outputs a warning if it
finds an unescaled angle bracket.
Ref: #12854Closes#12869
When setting the CURLOPT_SSLCERT option to a certificate thumprint, it
is required to have a backslash between the "store location", "store
name" and "thumbprint" tokens. These slashes were present in the
previous documentation, but were missed in the transition to markdown
documentation.
Closes#12854
Rework CMake options for building/using curl tool and libcurl manuals.
- rename `ENABLE_MANUAL` to `ENABLE_CURL_MANUAL`, meaning:
to build man page and built-in manual for curl tool.
- rename `BUILD_DOCS` to `BUILD_LIBCURL_DOCS`, meaning:
to build man pages for libcurl.
- `BUILD_LIBCURL_DOCS` now works without having to enable
`ENABLE_CURL_MANUAL` too.
- drop support for existing CMake-level `USE_MANUAL` option to avoid
confusion. (It used to work with the effect of current
`ENABLE_CURL_MANUAL`, but only by accident.)
Assisted-by: Richard Levitte
Ref: #12771Closes#12773
This means words, phrases or things we have decided not to use - words that
are spelled right according to the dictionary but we want to avoid. In the
name of consistency and better documentation.
Closes#12764
- cmake: enable `BUILD_DOCS` by default (this controls converting and
installing `.3` files from `.md` sources)
- cmake: speed up generating `.3` files by using a single command per
directory, instead of a single command per file. This reduces external
commands by about a thousand. (There remains some CMake logic kicking
in resulting in 500 -one per file- external `-E touch_nocreate` calls.)
- cd2nroff: add ability to process multiple input files.
- cd2nroff: add `-k` option to use the source filename to form the
output filename. (instead of the default in-file `Title:` line.)
Follow-up to 3f08d80b22
Follow-up to ea0b575dab#12753
Follow-up to eefcc1bda4#12730Closes#12762
curldown is this new file format for libcurl man pages. It is markdown
inspired with differences:
- Each file has a set of leading headers with meta-data
- Supports a small subset of markdown
- Uses .md file extensions for editors/IDE/GitHub to treat them nicely
- Generates man pages very similar to the previous ones
- Generates man pages that still convert nicely to HTML on the website
- Detects and highlights mentions of curl symbols automatically (when
their man page section is specified)
tools:
- cd2nroff: converts from curldown to nroff man page
- nroff2cd: convert an (old) nroff man page to curldown
- cdall: convert many nroff pages to curldown versions
- cd2cd: verifies and updates a curldown to latest curldown
This setup generates .3 versions of all the curldown versions at build time.
CI:
Since the documentation is now technically markdown in the eyes of many
things, the CI runs many more tests and checks on this documentation,
including proselint, link checkers and tests that make sure we capitalize the
first letter after a period...
Closes#12730
- remove use of .BI for code snippet
- stop using .br, just do a blank line
- remove use of .PP
- remove use for .sp
- remove backslash in .IP
- use .IP instead of .TP
Closes#12731
... since this funtion has not supported null pointer fd_set arguments since
at least 2006. (That's when I stopped my git blame journey)
Fixes#12691
Reported-by: sfan5 on github
Closes#12692
Returns the time, in microseconds, during which this transfer was held
in a waiting queue before it started "for real". A transfer might be put
in a queue if after getting started, it cannot create a new connection
etc due to set conditions and limits imposed by the application.
Ref: #12293Closes#12368
- Escape inner quotes with two backslashes.
Two backslashes escapes the backslash for the man page and will show as
a single backslash.
eg: "{\\"name\\": \\"daniel\\"}" shows as "{\"name\": \"daniel\"}".
Closes https://github.com/curl/curl/pull/12588
A new error code to be used when an internal field grows too large, like
when a dynbuf reaches its maximum. Previously it would return
CURLE_OUT_OF_MEMORY for this, which is highly misleading.
Ref: #12268Closes#12269
- use the correct include file
- make sure they are declared as in the header file
- fix minor nroff syntax mistakes (missing .fi)
These are verified by verify-synopsis.pl, which extracts the SYNPOSIS
code and runs it through gcc.
Closes#12402
Windows compilers define `_WIN32` automatically. Windows SDK headers
or build env defines `WIN32`, or we have to take care of it. The
agreement seems to be that `_WIN32` is the preferred practice here.
Make the source code rely on that to detect we're building for Windows.
Public `curl.h` was using `WIN32`, `__WIN32__` and `CURL_WIN32` for
Windows detection, next to the official `_WIN32`. After this patch it
only uses `_WIN32` for this. Also, make it stop defining `CURL_WIN32`.
There is a slight chance these break compatibility with Windows
compilers that fail to define `_WIN32`. I'm not aware of any obsolete
or modern compiler affected, but in case there is one, one possible
solution is to define this macro manually.
grepping for `WIN32` remains useful to discover Windows-specific code.
Also:
- extend `checksrc` to ensure we're not using `WIN32` anymore.
- apply minor formatting here and there.
- delete unnecessary checks for `!MSDOS` when `_WIN32` is present.
Co-authored-by: Jay Satiro
Reviewed-by: Daniel Stenberg
Closes#12376
- Add an explanation of the CURL_BLOB_COPY flag to CURLOPT_CAINFO_BLOB
and CURLOPT_PROXY_CAINFO_BLOB docs.
All the other _BLOB option docs already have the same explanation.
Closes https://github.com/curl/curl/pull/12277
Remove the CURL_CA_FALLBACK logic. That build option was added to allow
primarily OpenSSL to use the default paths for loading the CA certs. For
GnuTLS it was instead made to load the "system certs", which is
different and not desirable.
The native CA store loading is now asked for with this option.
Follow-up to 7b55279d1d
Co-authored-by: Jay Satiro
Closes#12137
- Move documentation of libcurl environment variables used only in debug
builds from libcurl-env into a separate document libcurl-env-dbg.
- Document more debug environment variables.
Previously undocumented or missing a description:
CURL_ALTSVC_HTTP, CURL_DBG_SOCK_WBLOCK, CURL_DBG_SOCK_WPARTIAL,
CURL_DBG_QUIC_WBLOCK, CURL_DEBUG, CURL_DEBUG_SIZE, CURL_GETHOSTNAME,
CURL_HSTS_HTTP, CURL_FORCETIME, CURL_SMALLREQSEND, CURL_SMALLSENDS,
CURL_TIME.
Closes https://github.com/curl/curl/pull/11811
- Warn that the user's debug callback may be called with the handle
parameter set to an internal handle.
Without this warning the user may assume that the only handles their
debug callback receives are the easy handles on which they set
CURLOPT_DEBUGFUNCTION.
This is a follow-up to f8cee8cc which changed DoH handles to inherit
the debug callback function set in the user's easy handle. As a result
those handles are now passed to the user's debug callback function.
Closes https://github.com/curl/curl/pull/12034
Previously it would only stop them from getting started if the size is
known to be too big then.
Update the libcurl and curl docs accordingly.
Fixes#11810
Reported-by: Elliot Killick
Assisted-by: Jay Satiro
Closes#11820
At least FreeBSD preserves cwd across makefile lines, so rules
consisting of more than one "cd X; do_something" must be explicitly run
in a subshell to avoid this. This problem caused the Cirrus FreeBSD
build to fail when parallel make jobs were enabled.
- delete completed TODO from `./CMakeLists.txt`.
- convert a C++ comment to C89 in `./CMake/CurlTests.c`.
- delete duplicate EOLs from EOF.
- add missing EOL at EOF.
- delete whitespace at EOL (except from expected test results).
- convert tabs to spaces.
- convert CRLF EOLs to LF in GHA yaml.
- text casing fixes in `./CMakeLists.txt`.
- fix a codespell typo in `packages/OS400/initscript.sh`.
Closes#11772
