diff options
| -rw-r--r-- | README | 6 | ||||
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | docs/CHECKSRC.md | 13 | ||||
| -rw-r--r-- | docs/CONTRIBUTE.md | 4 | ||||
| -rw-r--r-- | docs/DEPRECATE.md | 4 | ||||
| -rw-r--r-- | docs/HISTORY.md | 4 | ||||
| -rw-r--r-- | docs/HTTP3.md | 2 | ||||
| -rw-r--r-- | docs/INTERNALS.md | 7 | ||||
| -rw-r--r-- | docs/SECURITY-PROCESS.md | 4 | ||||
| -rw-r--r-- | docs/WEBSOCKET.md | 4 | ||||
| -rw-r--r-- | docs/examples/README.md | 8 | ||||
| -rw-r--r-- | docs/libcurl/ABI.md | 4 | ||||
| -rw-r--r-- | tests/FILEFORMAT.md | 44 | ||||
| -rw-r--r-- | tests/README.md | 27 | ||||
| -rw-r--r-- | tests/unit/README.md | 4 | ||||
| -rw-r--r-- | winbuild/README.md | 2 |
16 files changed, 68 insertions, 71 deletions
@@ -13,7 +13,7 @@ README libcurl is the library curl is using to do its job. It is readily available to be used by your software. Read the libcurl.3 man page to - learn how! + learn how. You find answers to the most frequent questions we get in the FAQ document. @@ -36,7 +36,7 @@ WEBSITE GIT - To download the very latest source off the GIT server do this: + To download the latest source code off the GIT server do this: git clone https://github.com/curl/curl.git @@ -44,7 +44,7 @@ GIT SECURITY PROBLEMS - Report suspected security problems via our HackerOne page and not in public! + Report suspected security problems via our HackerOne page and not in public. https://hackerone.com/curl @@ -64,7 +64,7 @@ To download the latest source from the Git server do this: ## Security problems Report suspected security problems via [our HackerOne -page](https://hackerone.com/curl) and not in public! +page](https://hackerone.com/curl) and not in public. ## Notice diff --git a/docs/CHECKSRC.md b/docs/CHECKSRC.md index 58a33d7bb..5fe1c52ef 100644 --- a/docs/CHECKSRC.md +++ b/docs/CHECKSRC.md @@ -41,7 +41,7 @@ warnings are: more appropriate `char *name` style. The asterisk should sit right next to the name without a space in between. -- `BADCOMMAND`: There's a bad `!checksrc!` instruction in the code. See the +- `BADCOMMAND`: There's a bad `checksrc` instruction in the code. See the **Ignore certain warnings** section below for details. - `BANNEDFUNC`: A banned function was used. The functions sprintf, vsprintf, @@ -56,7 +56,7 @@ warnings are: - `COMMANOSPACE`: a comma without following space -- `COPYRIGHT`: the file is missing a copyright statement! +- `COPYRIGHT`: the file is missing a copyright statement - `CPPCOMMENTS`: `//` comment detected, that is not C89 compliant @@ -113,7 +113,7 @@ warnings are: - `SPACESEMICOLON`: there was a space before semicolon, ` ;`. -- `TABS`: TAB characters are not allowed! +- `TABS`: TAB characters are not allowed - `TRAILINGSPACE`: Trailing whitespace on the line @@ -146,10 +146,9 @@ different ways to do this. ### Inline ignore You can control what to ignore within a specific source file by providing -instructions to checksrc in the source code itself. You need a magic marker -that is `!checksrc!` followed by the instruction. The instruction can ask to -ignore a specific warning N number of times or you ignore all of them until -you mark the end of the ignored section. +instructions to checksrc in the source code itself. See examples below. The +instruction can ask to ignore a specific warning N number of times or you +ignore all of them until you mark the end of the ignored section. Inline ignores are only done for that single specific source code file. diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md index 506af9b45..712f3e9b2 100644 --- a/docs/CONTRIBUTE.md +++ b/docs/CONTRIBUTE.md @@ -291,8 +291,8 @@ still fine. This means that all files need to have their license and copyright information clearly stated. Ideally by having the standard curl source code header, with an accurate copyright year range and the SPDX-License-Identifier included. If -the header does not work, you can use a smaller header or as a last resort add -the information for a specific file to the `.reuse/dep5` file. +the header does not work, you can use a smaller header or add the information +for a specific file to the `.reuse/dep5` file. We update copyright year ranges to end on the year of the most recent change of the individual file. diff --git a/docs/DEPRECATE.md b/docs/DEPRECATE.md index a90c60b8f..3ee4b1e39 100644 --- a/docs/DEPRECATE.md +++ b/docs/DEPRECATE.md @@ -10,8 +10,8 @@ how your use case cannot be satisfied properly using a workaround. We remove support for building curl with the NSS TLS library in August 2023. -- There are very few users left who use curl+NSS -- NSS has very few users outside of curl as well (primarily Firefox) +- There are few users left who use curl+NSS +- NSS has few users outside of curl as well (primarily Firefox) - NSS is harder than ever to find documentation for - NSS was always "best" used with Red Hat Linux when they provided additional features on top of the regular NSS that is not shipped by the vanilla library diff --git a/docs/HISTORY.md b/docs/HISTORY.md index 6268b87ef..87760a4d6 100644 --- a/docs/HISTORY.md +++ b/docs/HISTORY.md @@ -184,11 +184,11 @@ curl_formparse() function August: Curl and libcurl 7.12.1 Public curl release number: 82 - Releases counted from the very beginning: 109 + Releases counted from the beginning: 109 Available command line options: 96 Available curl_easy_setopt() options: 120 Number of public functions in libcurl: 36 - Amount of public website mirrors: 12 + Amount of public website mirrors: 12 Number of known libcurl bindings: 26 2005 diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 132a93dce..1ca9eb8c6 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -253,7 +253,7 @@ development and experimenting. ## Prerequisite(s) An existing local HTTP/1.1 server that hosts files. Preferably also a few huge -ones. You can easily create huge local files like `truncate -s=8G 8GB` - they +ones. You can easily create huge local files like `truncate -s=8G 8GB` - they are huge but do not occupy that much space on disk since they are just big holes. diff --git a/docs/INTERNALS.md b/docs/INTERNALS.md index 7da0be5a5..afb13b512 100644 --- a/docs/INTERNALS.md +++ b/docs/INTERNALS.md @@ -64,7 +64,6 @@ 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. (There are exceptions, - but they are to be changed to follow this pattern in future versions.) 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. + 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. diff --git a/docs/SECURITY-PROCESS.md b/docs/SECURITY-PROCESS.md index efa47e157..3203146e1 100644 --- a/docs/SECURITY-PROCESS.md +++ b/docs/SECURITY-PROCESS.md @@ -158,7 +158,7 @@ stall and never end, so applications that cannot deal with never-ending transfers already need to have counter-measures established. If the problem avoids the regular counter-measures when it causes a never- -ending transfer, it might very well be a security problem. +ending transfer, it might be a security problem. ## Not practically possible @@ -208,7 +208,7 @@ security vulnerabilities. - not all systems allow the arguments to be blanked in the first place - since curl blanks the argument itself they will be readable for a short - moment in time no matter what + 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 diff --git a/docs/WEBSOCKET.md b/docs/WEBSOCKET.md index dc6f1f248..cab8a6f1d 100644 --- a/docs/WEBSOCKET.md +++ b/docs/WEBSOCKET.md @@ -102,8 +102,8 @@ WebSocket myself. Here are the reasons why I have decided to move forward with WebSocket in curl **without using libWebSocket**: -- doxygen generated docs only makes them very hard to navigate. No tutorial, - no clearly written explanatory pages for specific functions. +- doxygen generated docs only makes them hard to navigate. No tutorial, no + clearly written explanatory pages for specific functions. - seems (too) tightly integrated with a specific TLS library, while we want to support WebSocket with whatever TLS library libcurl was already made to diff --git a/docs/examples/README.md b/docs/examples/README.md index 1ad9f2214..f70a8b44a 100644 --- a/docs/examples/README.md +++ b/docs/examples/README.md @@ -27,10 +27,10 @@ want you do reorganize them like: `curl-config --cc` -o example example.c `curl-config --cflags --libs` -**Please** do not use the `curl.se` site as a test target for your -libcurl applications/experiments. Even if some of the examples use that site -as a URL at some places, it does not mean that the URLs work or that we expect -you to actually torture our website with your tests! Thanks. +**Please** do not use the `curl.se` site as a test target for your libcurl +applications/experiments. Even if some of the examples use that site as a URL +at some places, it does not mean that the URLs work or that we expect you to +actually torture our website with your tests. Thanks. ## Examples diff --git a/docs/libcurl/ABI.md b/docs/libcurl/ABI.md index b70e18ad9..270c6d526 100644 --- a/docs/libcurl/ABI.md +++ b/docs/libcurl/ABI.md @@ -39,8 +39,8 @@ ABI - Application Binary Interface 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. + We are determined to bump the SONAME as rarely as possible. Ideally, we never + do it again. ## Downgrades diff --git a/tests/FILEFORMAT.md b/tests/FILEFORMAT.md index dc1092b8e..a1d1c12ea 100644 --- a/tests/FILEFORMAT.md +++ b/tests/FILEFORMAT.md @@ -6,13 +6,13 @@ SPDX-License-Identifier: curl # curl test suite file format -The curl test suite's file format is very simple and extensible, closely -resembling XML. All data for a single test case resides in a single ASCII -file. Labels mark the beginning and the end of all sections, and each label -must be written in its own line. Comments are either XML-style (enclosed with -`<!--` and `-->`) or shell script style (beginning with `#`) and must appear -on their own lines and not alongside actual test data. Most test data files -are syntactically valid XML, although a few files are not (lack of support for +The curl test suite's file format is simple and extendable, closely resembling +XML. All data for a single test case resides in a single ASCII file. Labels +mark the beginning and the end of all sections, and each label must be written +in its own line. Comments are either XML-style (enclosed with `<!--` and +`-->`) or shell script style (beginning with `#`) and must appear on their own +lines and not alongside actual test data. Most test data files are +syntactically valid XML, although a few files are not (lack of support for character entities and the preservation of CR/LF characters at the end of lines are the biggest differences). @@ -185,11 +185,11 @@ that will be checked/used if specified. ### `<keywords>` A newline-separated list of keywords describing what this test case uses and -tests. Try to use already used keywords. These keywords will be used for +tests. Try to use already used keywords. These keywords will be used for statistical/informational purposes and for choosing or skipping classes of -tests. "Keywords" must begin with an alphabetic character, "-", "[" or "{" -and may actually consist of multiple words separated by spaces which are -treated together as a single identifier. +tests. Keywords must begin with an alphabetic character, `-`, `[` or `{` and +may actually consist of multiple words separated by spaces which are treated +together as a single identifier. When using curl built with Hyper, the keywords must include HTTP or HTTPS for 'hyper mode' to kick in and make line ending checks work for tests. @@ -245,7 +245,7 @@ Send back this contents instead of the <data> one. The num is set by: Dynamically changing num in this way allows the test harness to be used to test authentication negotiation where several different requests must be sent to complete a transfer. The response to each request is found in its own data -section. Validating the entire negotiation sequence can be done by specifying +section. Validating the entire negotiation sequence can be done by specifying a datacheck section. ### `<connect>` @@ -369,7 +369,7 @@ What server(s) this test case requires/uses. Available servers: - `socks4` - `socks5` -Give only one per line. This subsection is mandatory. +Give only one per line. This subsection is mandatory. ### `<features>` A list of features that MUST be present in the client/library for this test to @@ -437,9 +437,9 @@ Features testable here are: - `wolfssh` - `wolfssl` -as well as each protocol that curl supports. A protocol only needs to be -specified if it is different from the server (useful when the server -is `none`). +as well as each protocol that curl supports. A protocol only needs to be +specified if it is different from the server (useful when the server is +`none`). ### `<killserver>` Using the same syntax as in `<server>` but when mentioned here these servers @@ -505,20 +505,20 @@ Set `option="no-include"` to prevent the test script to slap on the `--include` argument. Set `option="binary-trace"` to use `--trace` instead of `--trace-ascii` for -tracing. Suitable for binary-oriented protocols such as MQTT. +tracing. Suitable for binary-oriented protocols such as MQTT. Set `timeout="secs"` to override default server logs advisor read lock -timeout. This timeout is used by the test harness, once that the command has +timeout. This timeout is used by the test harness, once that the command has completed execution, to wait for the test server to write out server side log files and remove the lock that advised not to read them. The "secs" parameter is the not negative integer number of seconds for the timeout. This `timeout` attribute is documented for completeness sake, but is deep test harness stuff -and only needed for very singular and specific test cases. Avoid using it. +and only needed for singular and specific test cases. Avoid using it. Set `delay="secs"` to introduce a time delay once that the command has completed execution and before the `<postcheck>` section runs. The "secs" parameter is the not negative integer number of seconds for the delay. This -'delay' attribute is intended for very specific test cases, and normally not +'delay' attribute is intended for specific test cases, and normally not needed. ### `<file name="log/filename" [nonewline="yes"]>` @@ -542,7 +542,7 @@ example. ### `<strip>` One regex per line that is removed from the protocol dumps before the -comparison is made. This is very useful to remove dependencies on dynamically +comparison is made. This is useful to remove dependencies on dynamically changing protocol data such as port numbers or user-agent strings. ### `<strippart>` @@ -582,7 +582,7 @@ If 'nonewline' is set, we will cut off the trailing newline of this given data before comparing with the one actually received by the client ### `<file name="log/filename" [mode="text"]>` -The file's contents must be identical to this after the test is complete. Use +The file's contents must be identical to this after the test is complete. Use the mode="text" attribute if the output is in text mode on platforms that have a text/binary difference. diff --git a/tests/README.md b/tests/README.md index 2aa9f2b41..daa168014 100644 --- a/tests/README.md +++ b/tests/README.md @@ -113,15 +113,15 @@ SPDX-License-Identifier: curl Tests which use the ssh test server, SCP/SFTP/SOCKS tests, might be badly influenced by the output of system wide or user specific shell startup scripts, .bashrc, .profile, /etc/csh.cshrc, .login, /etc/bashrc, etc. which - output text messages or escape sequences on user login. When these shell + output text messages or escape sequences on user login. When these shell startup messages or escape sequences are output they might corrupt the expected stream of data which flows to the sftp-server or from the ssh - client which can result in bad test behavior or even prevent the test - server from running. + client which can result in bad test behavior or even prevent the test server + from running. If the test suite ssh or sftp server fails to start up and logs the message 'Received message too long' then you are certainly suffering the unwanted - output of a shell startup script. Locate, cleanup or adjust the shell + output of a shell startup script. Locate, cleanup or adjust the shell script. ### Memory test @@ -137,7 +137,7 @@ SPDX-License-Identifier: curl runtests.pl's `-t` option will enable torture testing mode, which runs each test many times and makes each different memory allocation fail on each - successive run. This tests the out of memory error handling code to ensure + successive run. This tests the out of memory error handling code to ensure that memory leaks do not occur even in those situations. It can help to compile curl with `CPPFLAGS=-DMEMDEBUG_LOG_SYNC` when using this option, to ensure that the memory log file is properly written even if curl crashes. @@ -145,10 +145,9 @@ SPDX-License-Identifier: curl ### Debug If a test case fails, you can conveniently get the script to invoke the - debugger (gdb) for you with the server running and the exact same command - line parameters that failed. Just invoke `runtests.pl <test number> -g` and - then just type 'run' in the debugger to perform the command through the - debugger. + debugger (gdb) for you with the server running and the same command line + parameters that failed. Just invoke `runtests.pl <test number> -g` and then + just type 'run' in the debugger to perform the command through the debugger. ### Logs @@ -166,8 +165,8 @@ SPDX-License-Identifier: curl ### Code coverage gcc provides a tool that can determine the code coverage figures for the - test suite. To use it, configure curl with `CFLAGS='-fprofile-arcs - -ftest-coverage -g -O0'`. Make sure you run the normal and torture tests to + test suite. To use it, configure curl with `CFLAGS='-fprofile-arcs + -ftest-coverage -g -O0'`. Make sure you run the normal and torture tests to get more full coverage, i.e. do: make test @@ -179,14 +178,14 @@ SPDX-License-Identifier: curl ggcov -r lib src The text mode tool gcov may also be used, but it doesn't handle object files - in more than one directory very well. + in more than one directory correctly. ### Remote testing The runtests.pl script provides some hooks to allow curl to be tested on a - machine where perl can not be run. The test framework in this case runs on + machine where perl can not be run. The test framework in this case runs on a workstation where perl is available, while curl itself is run on a remote - system using ssh or some other remote execution method. See the comments at + system using ssh or some other remote execution method. See the comments at the beginning of runtests.pl for details. ## Test case numbering diff --git a/tests/unit/README.md b/tests/unit/README.md index 29bd3f325..0d32e010f 100644 --- a/tests/unit/README.md +++ b/tests/unit/README.md @@ -36,14 +36,14 @@ We put tests that focus on an area or a specific function into a single C source file. The source file should be named 'unitNNNN.c' where NNNN is a previously unused number. -Add your test to `tests/unit/Makefile.inc` (if it is a unit test). Add your +Add your test to `tests/unit/Makefile.inc` (if it is a unit test). Add your test data file name to `tests/data/Makefile.inc` You also need a separate file called `tests/data/testNNNN` (using the same number) that describes your test case. See the test1300 file for inspiration and the `tests/FILEFORMAT.md` documentation. -For the actual C file, here's a very simple example: +For the actual C file, here's a simple example: ~~~c #include "curlcheck.h" diff --git a/winbuild/README.md b/winbuild/README.md index 22ecfe4ef..bcc4a61f2 100644 --- a/winbuild/README.md +++ b/winbuild/README.md @@ -59,7 +59,7 @@ Open a Visual Studio Command prompt: Using the **'VS [version] [platform] [type] Command Prompt'** menu entry:
where [version] is the Visual Studio version, [platform] is e.g. x64 and
- [type] Native of Cross platform build. This type of command prompt may not
+ [type] Native of Cross platform build. This type of command prompt may not
exist in all Visual Studio versions.
See also: [Set the Path and Environment Variables for Command-Line Builds](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line)
|