From 006f561f6ee62a486b71bc21ff8cacb840dcda91 Mon Sep 17 00:00:00 2001 From: Florian Imdahl Date: Thu, 26 Feb 2026 19:48:57 +0100 Subject: [PATCH] docs: some nitpicks - replaced double spaces with single space where applicable - replaced "favourite" with "favorite" - added language identifiers to code blocks in markdown files - added extra line after code blocks and after headings in markdown files Cloes #20748 --- .github/scripts/badwords.txt | 1 + docs/BINDINGS.md | 2 +- docs/CIPHERS.md | 9 +++++++++ docs/ECH.md | 4 ++-- docs/INSTALL.md | 4 ++-- docs/IPFS.md | 5 +++-- docs/internals/BUFQ.md | 19 ++++++++++--------- docs/internals/CLIENT-READERS.md | 6 +++--- docs/internals/CLIENT-WRITERS.md | 8 ++++---- docs/internals/CONNECTION-FILTERS.md | 9 +++++---- docs/internals/SCORECARD.md | 8 ++++---- docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md | 2 +- .../opts/CURLOPT_OPENSOCKETFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md | 2 +- docs/tests/HTTP.md | 12 ++++++------ lib/http.c | 2 +- 16 files changed, 54 insertions(+), 41 deletions(-) diff --git a/.github/scripts/badwords.txt b/.github/scripts/badwords.txt index a3eeb9c444..bc26bb02d7 100644 --- a/.github/scripts/badwords.txt +++ b/.github/scripts/badwords.txt @@ -91,3 +91,4 @@ file names\b:filenames ---Curl Corporation \bmanpages[^./;=&{:-]:man pages \bmanpage[^si./;=&{:-]:man page +favour:favor diff --git a/docs/BINDINGS.md b/docs/BINDINGS.md index 9ee5f688a4..9a53f81f29 100644 --- a/docs/BINDINGS.md +++ b/docs/BINDINGS.md @@ -9,7 +9,7 @@ libcurl bindings Creative people have written bindings or interfaces for various environments and programming languages. Using one of these allows you to take advantage of -curl powers from within your favourite language or system. +curl powers from within your favorite language or system. This is a list of all known interfaces as of this writing. diff --git a/docs/CIPHERS.md b/docs/CIPHERS.md index 7d9a1edf47..767b26b726 100644 --- a/docs/CIPHERS.md +++ b/docs/CIPHERS.md @@ -78,6 +78,7 @@ OpenSSL (1.1.1+, curl 7.61.0+), LibreSSL (3.4.1+, curl 8.3.0+), wolfSSL (curl 8.10.0+) and mbedTLS (3.6.0+, curl 8.10.0+). The list of cipher suites that can be used for the `--tls13-ciphers` option: + ``` TLS_AES_128_GCM_SHA256 TLS_AES_256_GCM_SHA384 @@ -118,6 +119,7 @@ A shortened list (based on [recommendations by Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS)) of cipher suites, which are (mostly) supported by all SSL backends, that can be used for the `--ciphers` option: + ``` ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 @@ -180,6 +182,7 @@ curl \ ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \ https://example.com/ ``` + Restrict ciphers to `aes128-gcm` and `chacha20`. Works with OpenSSL, LibreSSL, mbedTLS and wolfSSL. @@ -189,6 +192,7 @@ curl \ --tls13-ciphers TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256 \ https://example.com/ ``` + Restrict to only TLS 1.3 with `aes128-gcm` and `chacha20` ciphers. Works with OpenSSL, LibreSSL, mbedTLS, wolfSSL and Schannel. @@ -198,6 +202,7 @@ curl \ ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \ https://example.com/ ``` + Restrict TLS 1.2 ciphers to `aes128-gcm` and `chacha20`, use default TLS 1.3 ciphers (if TLS 1.3 is available). Works with OpenSSL, LibreSSL, BoringSSL, mbedTLS and wolfSSL. @@ -244,6 +249,7 @@ curl \ --ciphers '-CIPHER_ALL:+AES-128-GCM:+CHACHA20-POLY1305' \ https://example.com/ ``` + Restrict ciphers to `aes128-gcm` and `chacha20` in GnuTLS. ```sh @@ -251,6 +257,7 @@ curl \ --ciphers 'NORMAL:-VERS-ALL:+TLS1.3:-AES-256-GCM' \ https://example.com/ ``` + Restrict to only TLS 1.3 without the `aes256-gcm` cipher. ```sh @@ -258,9 +265,11 @@ curl \ --ciphers 'NORMAL:-VERS-ALL:+TLS1.2:-CIPHER_ALL:+CAMELLIA-128-GCM' \ https://example.com/ ``` + Restrict to only TLS 1.2 with the `CAMELLIA-128-GCM` cipher. ## Further reading + - [OpenSSL cipher suite names documentation](https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-suite-names) - [wolfSSL cipher support documentation](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter04.html#cipher-support) - [mbedTLS cipher suites reference](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/ssl__ciphersuites_8h/) diff --git a/docs/ECH.md b/docs/ECH.md index 042719245c..129378ad75 100644 --- a/docs/ECH.md +++ b/docs/ECH.md @@ -370,7 +370,7 @@ make There are some known issues with the ECH implementation in wolfSSL: - The main issue is that the client currently handles HelloRetryRequest - incorrectly. [HRR issue](https://github.com/wolfSSL/wolfssl/issues/6802).) + incorrectly. [HRR issue](https://github.com/wolfSSL/wolfssl/issues/6802).) The HRR issue means that the client does not work for [this ECH test web site](https://tls-ech.dev/) and any other similarly configured sites. @@ -461,7 +461,7 @@ In another window: ```sh cd $HOME/code/curl/ -./src/curl -vvv --insecure --connect-to foo.example.com:8443:localhost:8443 --ech ecl:AD7+DQA6uwAgACBix2B78sX+EQhEbxMspDOc8Z3xVS5aQpYP0Cxpc2AWPAAEAAEAAQALZXhhbXBsZS5jb20AAA== +./src/curl -vvv --insecure --connect-to foo.example.com:8443:localhost:8443 --ech ecl:AD7+DQA6uwAgACBix2B78sX+EQhEbxMspDOc8Z3xVS5aQpYP0Cxpc2AWPAAEAAEAAQALZXhhbXBsZS5jb20AAA== ``` ### Automated use of ``retry_configs`` not supported so far... diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 7e0329c8e7..8563f4af0f 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -603,11 +603,11 @@ disabling support for some features (run `./configure --help` to see them all): - `--disable-libcurl-option` (--libcurl C code generation support) - `--disable-manual` (--manual built-in documentation) - `--disable-mime` (MIME API) -- `--disable-netrc` (.netrc file) +- `--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-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) diff --git a/docs/IPFS.md b/docs/IPFS.md index c39f802dd9..64e0c53b50 100644 --- a/docs/IPFS.md +++ b/docs/IPFS.md @@ -5,6 +5,7 @@ SPDX-License-Identifier: curl --> # IPFS + For an overview about IPFS, visit the [IPFS project site](https://ipfs.tech/). In IPFS there are two protocols. IPFS and IPNS (their workings are explained @@ -64,12 +65,12 @@ in this link: The IPFS integration in curl hides this gateway logic for you. Instead of providing a full URL to a file on IPFS like this: -``` +```sh curl http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi ``` You can provide it with the IPFS protocol instead: -``` +```sh curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi ``` diff --git a/docs/internals/BUFQ.md b/docs/internals/BUFQ.md index 8136d588f6..9874e5d2e1 100644 --- a/docs/internals/BUFQ.md +++ b/docs/internals/BUFQ.md @@ -14,7 +14,7 @@ to and read from. It manages read and write positions and has a maximum size. Its basic read/write functions have a similar signature and return code handling as many internal curl read and write ones. -``` +```c ssize_t Curl_bufq_write(struct bufq *q, const unsigned char *buf, size_t len, CURLcode *err); - returns the length written into `q` or -1 on error. @@ -29,7 +29,7 @@ ssize_t Curl_bufq_read(struct bufq *q, unsigned char *buf, size_t len, CURLcode To pass data into a `bufq` without an extra copy, read callbacks can be used. -``` +```c typedef ssize_t Curl_bufq_reader(void *reader_ctx, unsigned char *buf, size_t len, CURLcode *err); @@ -45,7 +45,7 @@ once or only read in a maximum amount of bytes. The analog mechanism for write out buffer data is: -``` +```c typedef ssize_t Curl_bufq_writer(void *writer_ctx, const unsigned char *buf, size_t len, CURLcode *err); @@ -60,7 +60,7 @@ remove the amount that `writer` reports. It is possible to get access to the memory of data stored in a `bufq` with: -``` +```c bool Curl_bufq_peek(const struct bufq *q, const unsigned char **pbuf, size_t *plen); ``` @@ -69,7 +69,7 @@ may read. This is only valid until another operation on `bufq` is performed. Instead of reading `bufq` data, one may simply skip it: -``` +```c void Curl_bufq_skip(struct bufq *q, size_t amount); ``` @@ -80,7 +80,7 @@ This removes `amount` number of bytes from the `bufq`. `bufq` is initialized and freed similar to the `dynbuf` module. Code using `bufq` holds a `struct bufq` somewhere. Before it uses it, it invokes: -``` +```c void Curl_bufq_init(struct bufq *q, size_t chunk_size, size_t max_chunks); ``` @@ -91,12 +91,13 @@ about memory management. The user of the `bufq` has the responsibility to call: -``` +```c void Curl_bufq_free(struct bufq *q); ``` + to free all resources held by `q`. It is possible to reset a `bufq` to empty via: -``` +```c void Curl_bufq_reset(struct bufq *q); ``` @@ -154,7 +155,7 @@ the `bufq` from growing ever larger and larger. A `struct bufc_pool` may be used to create chunks for a `bufq` and keep spare ones around. It is initialized and used via: -``` +```c void Curl_bufcp_init(struct bufc_pool *pool, size_t chunk_size, size_t spare_max); void Curl_bufq_initp(struct bufq *q, struct bufc_pool *pool, size_t max_chunks, int opts); diff --git a/docs/internals/CLIENT-READERS.md b/docs/internals/CLIENT-READERS.md index bb94bba95f..9955147b54 100644 --- a/docs/internals/CLIENT-READERS.md +++ b/docs/internals/CLIENT-READERS.md @@ -28,7 +28,7 @@ The transfer loop that sends and receives, is using `Curl_client_read()` to get more data to send for a transfer. If no specific reader has been installed yet, the default one that uses `CURLOPT_READFUNCTION` is added. The prototype is -``` +```c CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen, size_t *nread, bool *eos); ``` @@ -44,7 +44,7 @@ The chain of readers allows processing of the data to send. The definition of a reader is: -``` +```c struct Curl_crtype { const char *name; /* writer name. */ CURLcode (*do_init)(struct Curl_easy *data, struct Curl_creader *writer); @@ -78,7 +78,7 @@ the order in which they are called is relevant for the outcome. When a reader is created, it gets the `phase` property in which it operates. Reader phases are defined like: -``` +```c typedef enum { CURL_CR_NET, /* data send to the network (connection filters) */ CURL_CR_TRANSFER_ENCODE, /* add transfer-encodings */ diff --git a/docs/internals/CLIENT-WRITERS.md b/docs/internals/CLIENT-WRITERS.md index 0e9bc843a7..0f2ff9ffdb 100644 --- a/docs/internals/CLIENT-WRITERS.md +++ b/docs/internals/CLIENT-WRITERS.md @@ -29,13 +29,13 @@ All code in `libcurl` that handles response data is ultimately expected to forward this data via `Curl_client_write()` to the application. The exact prototype of this function is: -``` +```c CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *buf, size_t blen); ``` The `type` argument specifies what the bytes in `buf` actually are. The following bits are defined: -``` +```c #define CLIENTWRITE_BODY (1 << 0) /* non-meta information, BODY */ #define CLIENTWRITE_INFO (1 << 1) /* meta information, not a HEADER */ #define CLIENTWRITE_HEADER (1 << 2) /* meta information, HEADER */ @@ -56,7 +56,7 @@ application callbacks. This is similar to the design of connection filters: client writers can be chained to process the bytes written through them. The definition is: -``` +```c struct Curl_cwtype { const char *name; CURLcode (*do_init)(struct Curl_easy *data, @@ -87,7 +87,7 @@ in which the are called is relevant for the outcome. When a writer is created, one property it gets is the `phase` in which it operates. Writer phases are defined like: -``` +```c typedef enum { CURL_CW_RAW, /* raw data written, before any decoding */ CURL_CW_TRANSFER_DECODE, /* remove transfer-encodings */ diff --git a/docs/internals/CONNECTION-FILTERS.md b/docs/internals/CONNECTION-FILTERS.md index a1987f4956..93bfa334a9 100644 --- a/docs/internals/CONNECTION-FILTERS.md +++ b/docs/internals/CONNECTION-FILTERS.md @@ -76,7 +76,7 @@ etc. Each filter does in principle the following: -``` +```c static CURLcode myfilter_cf_connect(struct Curl_cfilter *cf, struct Curl_easy *data, bool *done) @@ -109,7 +109,7 @@ transfers. The memory footprint of a filter is relatively small: -``` +```c struct Curl_cfilter { const struct Curl_cftype *cft; /* the type providing implementation */ struct Curl_cfilter *next; /* next filter in chain */ @@ -138,13 +138,14 @@ zero cost *if the filter does not transform the data*. An http proxy or socks filter, once it is connected, just passes the calls through. Those filters implementations look like this: -``` +```c 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); } ``` + The `recv` implementation is equivalent. ## Filter Types @@ -231,7 +232,7 @@ Users of `curl` may activate them by adding the name of the filter type to the `--trace-config` argument. For example, in order to get more detailed tracing of an HTTP/2 request, invoke curl with: -``` +```sh > curl -v --trace-config ids,time,http/2 https://curl.se/ ``` diff --git a/docs/internals/SCORECARD.md b/docs/internals/SCORECARD.md index 145267f8c3..019ddc5963 100644 --- a/docs/internals/SCORECARD.md +++ b/docs/internals/SCORECARD.md @@ -25,7 +25,7 @@ locally build `src/curl` (by default). A typical invocation for measuring performance of HTTP/2 downloads would be: -``` +```sh curl> python3 tests/http/scorecard.py -d h2 ``` @@ -35,7 +35,7 @@ JSON instead of text. Help for all command line options are available via: -``` +```sh curl> python3 tests/http/scorecard.py -h ``` @@ -48,7 +48,7 @@ specify these in some way if you are just interested in a particular case. For example, to run downloads of a 1 MB resource only, 100 times with at max 6 parallel transfers, use: -``` +```sh curl> python3 tests/http/scorecard.py -d --download-sizes=1mb --download-count=100 --download-parallel=6 h2 ``` @@ -69,7 +69,7 @@ interactive SVG. Either clone the `Flamegraph` repository next to your `curl` project or set the environment variable `FLAMEGRAPH` to the location of your clone. Then run scorecard with the `--flame` option, like -``` +```sh curl> FLAMEGRAPH=/Users/sei/projects/FlameGraph python3 tests/http/scorecard.py \ -r --request-count=50000 --request-parallels=100 --samples=1 --flame h2 ``` diff --git a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md index d2dda82dd8..939161bee0 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md @@ -28,7 +28,7 @@ typedef enum { CURLIOE_LAST /* never use */ } curlioerr; -typedef enum { +typedef enum { CURLIOCMD_NOP, /* no operation */ CURLIOCMD_RESTARTREAD, /* restart the read stream from start */ CURLIOCMD_LAST /* never use */ diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md index 3591516358..e08f53b8a7 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md @@ -22,7 +22,7 @@ CURLOPT_OPENSOCKETFUNCTION - callback for opening socket ~~~c #include -typedef enum { +typedef enum { CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */ } curlsocktype; diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md index c73bdcadf9..2080aa9483 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md @@ -22,7 +22,7 @@ CURLOPT_SOCKOPTFUNCTION - callback for setting socket options ~~~c #include -typedef enum { +typedef enum { CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */ CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */ CURLSOCKTYPE_LAST /* never use */ diff --git a/docs/tests/HTTP.md b/docs/tests/HTTP.md index 658abac255..87ec815425 100644 --- a/docs/tests/HTTP.md +++ b/docs/tests/HTTP.md @@ -16,7 +16,7 @@ The test cases and necessary files are in `tests/http`. You can invoke `pytest` from there or from the top level curl checkout and it finds all tests. -``` +```sh curl> pytest test/http platform darwin -- Python 3.9.15, pytest-6.2.0, py-1.10.0, pluggy-0.13.1 rootdir: /Users/sei/projects/curl @@ -30,7 +30,7 @@ times. `-k ` can be used to run only matching test cases. The `expr` can be something resembling a python test or just a string that needs to match test cases in their names. -``` +```sh curl/tests/http> pytest -vv -k test_01_02 ``` @@ -76,21 +76,21 @@ Several test cases are parameterized, for example with the HTTP version to use. If you want to run a test with a particular protocol only, use a command line like: -``` +```sh curl/tests/http> pytest -k "test_02_06 and h2" ``` Test cases can be repeated, with the `pytest-repeat` module (`pip install pytest-repeat`). Like in: -``` +```sh curl/tests/http> pytest -k "test_02_06 and h2" --count=100 ``` which then runs this test case a hundred times. In case of flaky tests, you can make pytest stop on the first one with: -``` +```sh curl/tests/http> pytest -k "test_02_06 and h2" --count=100 --maxfail=1 ``` @@ -99,7 +99,7 @@ of log files, the verbosity of pytest is also used to collect curl trace output. If you specify `-v` three times, the `curl` command is started with `--trace`: -``` +```sh curl/tests/http> pytest -vvv -k "test_02_06 and h2" --count=100 --maxfail=1 ``` diff --git a/lib/http.c b/lib/http.c index 50b128c531..61d426d9f5 100644 --- a/lib/http.c +++ b/lib/http.c @@ -328,7 +328,7 @@ fail: #endif -/* pickoneauth() selects the most favourable authentication method from the +/* pickoneauth() selects the most favorable authentication method from the * ones available and the ones we want. * * return TRUE if one was picked