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.
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
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
## 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
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,
- `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
- `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
### 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.
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.
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
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
## 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.
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.
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
- 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
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
`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
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
# 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).
### `<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.
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>`
- `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
- `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
`--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"]>`
### `<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>`
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.
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
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.
### 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
### 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
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
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"
\r
Using the **'VS [version] [platform] [type] Command Prompt'** menu entry:\r
where [version] is the Visual Studio version, [platform] is e.g. x64 and\r
- [type] Native of Cross platform build. This type of command prompt may not\r
+ [type] Native of Cross platform build. This type of command prompt may not\r
exist in all Visual Studio versions.\r
\r
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)\r
projects / thirdparty / curl.git / commitdiff
