mirror of
https://github.com/curl/curl.git
synced 2025-04-12 16:20:35 +08:00
docs: address proselint nits
- avoid exclamation marks - use consistent number of spaces after periods: one - avoid clichés - avoid using 'very' Closes #8060
This commit is contained in:
parent
0d380a853f
commit
76d6e719d9
@ -19,7 +19,7 @@ by reading [the INSTALL document](https://curl.se/docs/install.html).
|
||||
|
||||
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](https://curl.se/libcurl/c/libcurl.html) to learn how!
|
||||
page](https://curl.se/libcurl/c/libcurl.html) to learn how.
|
||||
|
||||
You can find answers to the most frequent questions we get in [the FAQ
|
||||
document](https://curl.se/docs/faq.html).
|
||||
@ -47,7 +47,7 @@ downloads.
|
||||
|
||||
## Git
|
||||
|
||||
To download the very latest source from the Git server do this:
|
||||
To download the latest source from the Git server do this:
|
||||
|
||||
git clone https://github.com/curl/curl.git
|
||||
|
||||
|
16
docs/BUGS.md
16
docs/BUGS.md
@ -17,7 +17,7 @@
|
||||
a go at a solution. You can optionally also submit your problem in [curl's
|
||||
bug tracking system](https://github.com/curl/curl/issues).
|
||||
|
||||
Please read the rest of this document below first before doing that!
|
||||
Please read the rest of this document below first before doing that.
|
||||
|
||||
If you feel you need to ask around first, find a suitable [mailing list](
|
||||
https://curl.se/mail/) and post your questions there.
|
||||
@ -66,9 +66,9 @@
|
||||
`--trace` options.
|
||||
|
||||
If curl crashed, causing a core dump (in unix), there is hardly any use to
|
||||
send that huge file to anyone of us. Unless we have an exact same system
|
||||
setup as you, we cannot do much with it. Instead, we ask you to get a stack
|
||||
trace and send that (much smaller) output to us instead!
|
||||
send that huge file to anyone of us. Unless we have the same system setup as
|
||||
you, we cannot do much with it. Instead, we ask you to get a stack trace and
|
||||
send that (much smaller) output to us instead.
|
||||
|
||||
The address and how to subscribe to the mailing lists are detailed in the
|
||||
`MANUAL.md` file.
|
||||
@ -102,9 +102,9 @@
|
||||
it out of an ambition to keep curl and libcurl excellent products and out of
|
||||
pride.
|
||||
|
||||
But please do not assume that you can just lump over something to us and it
|
||||
will then magically be fixed after some given time. Most often we need
|
||||
feedback and help to understand what you have experienced and how to repeat a
|
||||
Please do not assume that you can just lump over something to us and it will
|
||||
then magically be fixed after some given time. Most often we need feedback
|
||||
and help to understand what you have experienced and how to repeat a
|
||||
problem. Then we may only be able to assist YOU to debug the problem and to
|
||||
track down the proper fix.
|
||||
|
||||
@ -209,7 +209,7 @@
|
||||
If the problem have not been understood or reproduced, and there's nobody
|
||||
responding to follow-up questions or questions asking for clarifications or
|
||||
for discussing possible ways to move forward with the task, we take that as a
|
||||
strong suggestion that the bug is not important.
|
||||
strong suggestion that the bug is unimportant.
|
||||
|
||||
Unimportant issues will be closed as inactive sooner or later as they cannot
|
||||
be fixed. The inactivity period (waiting for responses) should not be shorter
|
||||
|
@ -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,
|
||||
|
@ -173,7 +173,7 @@ else if(b) return FALSE;
|
||||
|
||||
## Space around operators
|
||||
|
||||
Please use spaces on both sides of operators in C expressions. Postfix **(),
|
||||
Please use spaces on both sides of operators in C expressions. Postfix **(),
|
||||
[], ->, ., ++, --** and Unary **+, -, !, ~, &** operators excluded they should
|
||||
have no space.
|
||||
|
||||
|
@ -9,8 +9,8 @@ flaws or bugs.
|
||||
### Join the Community
|
||||
|
||||
Skip over to [https://curl.se/mail/](https://curl.se/mail/) and join
|
||||
the appropriate mailing list(s). Read up on details before you post
|
||||
questions. Read this file before you start sending patches! We prefer
|
||||
the appropriate mailing list(s). Read up on details before you post
|
||||
questions. Read this file before you start sending patches. We prefer
|
||||
questions sent to and discussions being held on the mailing list(s), not sent
|
||||
to individuals.
|
||||
|
||||
@ -44,7 +44,7 @@ By submitting a patch to the curl project, you are assumed to have the right
|
||||
to the code and to be allowed by your employer or whatever to hand over that
|
||||
patch/code to us. We will credit you for your changes as far as possible, to
|
||||
give credit but also to keep a trace back to who made what changes. Please
|
||||
always provide us with your full real name when contributing!
|
||||
always provide us with your full real name when contributing,
|
||||
|
||||
### What To Read
|
||||
|
||||
@ -98,7 +98,7 @@ and regression in the future.
|
||||
Please try to get the latest available sources to make your patches against.
|
||||
It makes the lives of the developers so much easier. The best is if you get
|
||||
the most up-to-date sources from the git repository, but the latest release
|
||||
archive is quite OK as well!
|
||||
archive is quite OK as well.
|
||||
|
||||
### Documentation
|
||||
|
||||
|
@ -1,7 +1,7 @@
|
||||
# dynbuf
|
||||
|
||||
This is the internal module for creating and handling "dynamic buffers". This
|
||||
means buffers that can be appended to, dynamically and grow in size to adapt.
|
||||
means buffers that can be appended to, dynamically and grow to adapt.
|
||||
|
||||
There will always be a terminating zero put at the end of the dynamic buffer.
|
||||
|
||||
|
@ -97,7 +97,7 @@ functionality or to favour any particular TLS-providing backend. Specifically,
|
||||
the change reserves a feature bit for ECH support (symbol
|
||||
`CURL_VERSION_ECH`), implements setting and reporting of this bit, includes
|
||||
dummy book-keeping for the symbol, adds a build-time configuration option
|
||||
(`--enable-ech`), provides an extensible check for resources available to
|
||||
(`--enable-ech`), provides an extendable check for resources available to
|
||||
provide ECH support, and defines a compiler pre-processor symbol (`USE_ECH`)
|
||||
accordingly.
|
||||
|
||||
@ -110,7 +110,7 @@ Limitations:
|
||||
|
||||
- Framework is incomplete, as it covers autoconf, but not CMake.
|
||||
|
||||
- Check for available resources, although extensible, refers only to
|
||||
- Check for available resources, although extendable, refers only to
|
||||
specific work in progress ([described
|
||||
here](https://github.com/sftcd/openssl/tree/master/esnistuff)) to
|
||||
implement ECH for OpenSSL, as this is the immediate motivation
|
||||
|
@ -159,7 +159,7 @@ When you are merging patches/PRs...
|
||||
necessary
|
||||
- avoid the "merge" button on GitHub, do it "manually" instead to get full
|
||||
control and full audit trail (github leaves out you as "Committer:")
|
||||
- remember to credit the reporter and the helpers!
|
||||
- remember to credit the reporter and the helpers.
|
||||
|
||||
## Who are maintainers?
|
||||
|
||||
|
@ -28,7 +28,7 @@ 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 your feet wet gently in the project, is to participate in an
|
||||
- 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.
|
||||
|
||||
|
@ -26,7 +26,7 @@ command line.
|
||||
|
||||
HttpGet 1.0 was released on April 8th 1997 with brand new HTTP proxy support.
|
||||
|
||||
We soon found and fixed support for getting currencies over GOPHER. Once FTP
|
||||
We soon found and fixed support for getting currencies over GOPHER. Once FTP
|
||||
download support was added, the name of the project was changed and urlget 2.0
|
||||
was released in August 1997. The http-only days were already passed.
|
||||
|
||||
|
@ -114,7 +114,7 @@ HTTP Alternative Services
|
||||
Alt-Svc is an extension with a corresponding frame (ALTSVC) in HTTP/2 that
|
||||
tells the client about an alternative "route" to the same content for the same
|
||||
origin server that you get the response from. A browser or long-living client
|
||||
can use that hint to create a new connection asynchronously. For libcurl, we
|
||||
can use that hint to create a new connection asynchronously. For libcurl, we
|
||||
may introduce a way to bring such clues to the application and/or let a
|
||||
subsequent request use the alternate route automatically.
|
||||
|
||||
|
@ -79,7 +79,7 @@ have OpenSSL installed in your system, you can run configure like this:
|
||||
|
||||
If you have OpenSSL installed, but with the libraries in one place and the
|
||||
header files somewhere else, you have to set the `LDFLAGS` and `CPPFLAGS`
|
||||
environment variables prior to running configure. Something like this should
|
||||
environment variables prior to running configure. Something like this should
|
||||
work:
|
||||
|
||||
CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure
|
||||
@ -255,7 +255,7 @@ might yet need some additional adjustment, caveat emptor.
|
||||
## Important static libcurl usage note
|
||||
|
||||
When building an application that uses the static libcurl library on Windows,
|
||||
you must add `-DCURL_STATICLIB` to your `CFLAGS`. Otherwise the linker will
|
||||
you must add `-DCURL_STATICLIB` to your `CFLAGS`. Otherwise the linker will
|
||||
look for dynamic import symbols.
|
||||
|
||||
## Legacy Windows and SSL
|
||||
@ -396,7 +396,7 @@ enabled, you will get messages like:
|
||||
getaddrinfo() thread failed to start
|
||||
```
|
||||
|
||||
Do not panic! curl and your program are not broken. You can fix this by:
|
||||
Do not panic. curl and your program are not broken. You can fix this by:
|
||||
|
||||
- Set the environment variable `QIBM_MULTI_THREADED` to `Y` before starting
|
||||
your program. This can be done at whatever scope you feel is appropriate.
|
||||
@ -409,8 +409,8 @@ Download and unpack the curl package.
|
||||
`cd` to the new directory. (e.g. `cd curl-7.12.3`)
|
||||
|
||||
Set environment variables to point to the cross-compile toolchain and call
|
||||
configure with any options you need. Be sure and specify the `--host` and
|
||||
`--build` parameters at configuration time. The following script is an
|
||||
configure with any options you need. Be sure and specify the `--host` and
|
||||
`--build` parameters at configuration time. The following script is an
|
||||
example of cross-compiling for the IBM 405GP PowerPC processor using the
|
||||
toolchain from MonteVista for Hardhat Linux.
|
||||
|
||||
@ -435,8 +435,8 @@ export NM=ppc_405-nm
|
||||
|
||||
You may also need to provide a parameter like `--with-random=/dev/urandom` to
|
||||
configure as it cannot detect the presence of a random number generating
|
||||
device for a target system. The `--prefix` parameter specifies where curl
|
||||
will be installed. If `configure` completes successfully, do `make` and `make
|
||||
device for a target system. The `--prefix` parameter specifies where curl
|
||||
will be installed. If `configure` completes successfully, do `make` and `make
|
||||
install` as usual.
|
||||
|
||||
In some cases, you may be able to simplify the above commands to as little as:
|
||||
@ -448,7 +448,7 @@ In some cases, you may be able to simplify the above commands to as little as:
|
||||
There are a number of configure options that can be used to reduce the size of
|
||||
libcurl for embedded applications where binary size is an important factor.
|
||||
First, be sure to set the `CFLAGS` variable when configuring with any relevant
|
||||
compiler optimization flags to reduce the size of the binary. For gcc, this
|
||||
compiler optimization flags to reduce the size of the binary. For gcc, this
|
||||
would mean at minimum the -Os option, and potentially the `-march=X`,
|
||||
`-mdynamic-no-pic` and `-flto` options as well, e.g.
|
||||
|
||||
@ -459,7 +459,7 @@ due to improved optimization.
|
||||
|
||||
Be sure to specify as many `--disable-` and `--without-` flags on the
|
||||
configure command-line as you can to disable all the libcurl features that you
|
||||
know your application is not going to need. Besides specifying the
|
||||
know your application is not going to need. Besides specifying the
|
||||
`--disable-PROTOCOL` flags for all the types of URLs your application will not
|
||||
use, here are some other flags that can reduce the size of the library:
|
||||
|
||||
@ -488,7 +488,7 @@ the configure command-line, e.g.
|
||||
LDFLAGS="-Wl,-s -Wl,-Bsymbolic -Wl,--gc-sections"
|
||||
|
||||
Be sure also to strip debugging symbols from your binaries after compiling
|
||||
using 'strip' (or the appropriate variant if cross-compiling). If space is
|
||||
using 'strip' (or the appropriate variant if cross-compiling). If space is
|
||||
really tight, you may be able to remove some unneeded sections of the shared
|
||||
library using the -R option to objcopy (e.g. the .comment section).
|
||||
|
||||
@ -502,9 +502,9 @@ in a lower total size than dynamically linking.
|
||||
|
||||
Note that the curl test harness can detect the use of some, but not all, of
|
||||
the `--disable` statements suggested above. Use will cause tests relying on
|
||||
those features to fail. The test harness can be manually forced to skip the
|
||||
those features to fail. The test harness can be manually forced to skip the
|
||||
relevant tests by specifying certain key words on the `runtests.pl` command
|
||||
line. Following is a list of appropriate key words:
|
||||
line. Following is a list of appropriate key words:
|
||||
|
||||
- `--disable-cookies` !cookies
|
||||
- `--disable-manual` !--manual
|
||||
|
@ -73,7 +73,7 @@ git
|
||||
Portability
|
||||
===========
|
||||
|
||||
We write curl and libcurl to compile with C89 compilers. On 32-bit and up
|
||||
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.
|
||||
|
||||
@ -165,10 +165,10 @@ Windows vs Unix
|
||||
`#ifdef HAVE_THAT_WEIRD_FUNCTION`. Since Windows cannot run configure scripts,
|
||||
we maintain a `curl_config-win32.h` file in lib directory that is supposed to
|
||||
look exactly like a `curl_config.h` file would have looked like on a Windows
|
||||
machine!
|
||||
machine.
|
||||
|
||||
Generally speaking: always remember that this will be compiled on dozens of
|
||||
operating systems. Do not walk on the edge!
|
||||
operating systems. Do not walk on the edge.
|
||||
|
||||
<a name="Library"></a>
|
||||
Library
|
||||
@ -192,7 +192,7 @@ Library
|
||||
makes sure we stay absolutely platform independent.
|
||||
|
||||
[ `curl_easy_init()`][2] allocates an internal struct and makes some
|
||||
initializations. The returned handle does not reveal internals. This is the
|
||||
initializations. The returned handle does not reveal internals. This is the
|
||||
`Curl_easy` struct which works as an "anchor" struct for all `curl_easy`
|
||||
functions. All connections performed will get connect-specific data allocated
|
||||
that should be used for things related to particular connections/requests.
|
||||
@ -203,7 +203,7 @@ Library
|
||||
the `Curl_easy` struct.
|
||||
|
||||
`curl_easy_perform()` is just a wrapper function that makes use of the multi
|
||||
API. It basically calls `curl_multi_init()`, `curl_multi_add_handle()`,
|
||||
API. It basically calls `curl_multi_init()`, `curl_multi_add_handle()`,
|
||||
`curl_multi_wait()`, and `curl_multi_perform()` until the transfer is done
|
||||
and then returns.
|
||||
|
||||
@ -431,7 +431,7 @@ multi interface/non-blocking
|
||||
The FTP and the SFTP/SCP protocols are examples of how we adapt and adjust
|
||||
the code to allow non-blocking operations even on multi-stage command-
|
||||
response protocols. They are built around state machines that return when
|
||||
they would otherwise block waiting for data. The DICT, LDAP and TELNET
|
||||
they would otherwise block waiting for data. The DICT, LDAP and TELNET
|
||||
protocols are crappy examples and they are subject for rewrite in the future
|
||||
to better fit the libcurl protocol family.
|
||||
|
||||
@ -674,7 +674,7 @@ Content Encoding
|
||||
## Supported content encodings
|
||||
|
||||
The `deflate`, `gzip` and `br` content encodings are supported by libcurl.
|
||||
Both regular and chunked transfers work fine. The zlib library is required
|
||||
Both regular and chunked transfers work fine. The zlib library is required
|
||||
for the `deflate` and `gzip` encodings, while the brotli decoding library is
|
||||
for the `br` encoding.
|
||||
|
||||
@ -692,12 +692,12 @@ Content Encoding
|
||||
that will work (besides `identity`, which does nothing) are `deflate`,
|
||||
`gzip` and `br`. If a response is encoded using the `compress` or methods,
|
||||
libcurl will return an error indicating that the response could
|
||||
not be decoded. If `<string>` is NULL no `Accept-Encoding` header is
|
||||
not be decoded. If `<string>` is NULL no `Accept-Encoding` header is
|
||||
generated. If `<string>` is a zero-length string, then an `Accept-Encoding`
|
||||
header containing all supported encodings will be generated.
|
||||
|
||||
The [`CURLOPT_ACCEPT_ENCODING`][5] must be set to any non-NULL value for
|
||||
content to be automatically decoded. If it is not set and the server still
|
||||
content to be automatically decoded. If it is not set and the server still
|
||||
sends encoded content (despite not having been asked), the data is returned
|
||||
in its raw form and the `Content-Encoding` type is not checked.
|
||||
|
||||
@ -797,7 +797,7 @@ Track Down Memory Leaks
|
||||
tests/memanalyze.pl dump
|
||||
|
||||
This now outputs a report on what resources that were allocated but never
|
||||
freed etc. This report is fine for posting to the list!
|
||||
freed etc. This report is fine for posting to the list.
|
||||
|
||||
If this does not produce any output, no leak was detected in libcurl. Then
|
||||
the leak is mostly likely to be in your code.
|
||||
@ -837,7 +837,7 @@ Track Down Memory Leaks
|
||||
|
||||
We created an internal "socket to easy handles" hash table that given
|
||||
a socket (file descriptor) returns the easy handle that waits for action on
|
||||
that socket. This hash is made using the already existing hash code
|
||||
that socket. This hash is made using the already existing hash code
|
||||
(previously only used for the DNS cache).
|
||||
|
||||
To make libcurl able to report plain sockets in the socket callback, we had
|
||||
|
@ -373,7 +373,7 @@ allow a user to trick curl into uploading a file.
|
||||
## Referrer
|
||||
|
||||
An HTTP request has the option to include information about which address
|
||||
referred it to the actual page. Curl allows you to specify the referrer to be
|
||||
referred it to the actual page. curl allows you to specify the referrer to be
|
||||
used on the command line. It is especially useful to fool or trick stupid
|
||||
servers or CGI scripts that rely on that information being available or
|
||||
contain certain data.
|
||||
@ -459,9 +459,9 @@ non-existing file to trigger the cookie awareness like:
|
||||
|
||||
The file to read cookies from must be formatted using plain HTTP headers OR as
|
||||
netscape's cookie file. Curl will determine what kind it is based on the file
|
||||
contents. In the above command, curl will parse the header and store the
|
||||
cookies received from www.example.com. curl will send to the server the
|
||||
stored cookies which match the request as it follows the location. The file
|
||||
contents. In the above command, curl will parse the header and store the
|
||||
cookies received from www.example.com. curl will send to the server the
|
||||
stored cookies which match the request as it follows the location. The file
|
||||
"empty.txt" may be a nonexistent file.
|
||||
|
||||
To read and write cookies from a netscape cookie file, you can set both `-b`
|
||||
@ -608,7 +608,7 @@ directory at your ftp site, do:
|
||||
|
||||
curl ftp://user:passwd@my.site.com/README
|
||||
|
||||
But if you want the README file from the root directory of that same site, you
|
||||
If you want the README file from the root directory of that same site, you
|
||||
need to specify the absolute file name:
|
||||
|
||||
curl ftp://user:passwd@my.site.com//README
|
||||
@ -767,7 +767,7 @@ Authentication support is still missing
|
||||
## LDAP
|
||||
|
||||
If you have installed the OpenLDAP library, curl can take advantage of it and
|
||||
offer `ldap://` support. On Windows, curl will use WinLDAP from Platform SDK
|
||||
offer `ldap://` support. On Windows, curl will use WinLDAP from Platform SDK
|
||||
by default.
|
||||
|
||||
Default protocol version used by curl is LDAPv3. LDAPv2 will be used as
|
||||
@ -941,7 +941,7 @@ syntax:
|
||||
http://[2001:1890:1112:1::20]/overview.html
|
||||
|
||||
When this style is used, the `-g` option must be given to stop curl from
|
||||
interpreting the square brackets as special globbing characters. Link local
|
||||
interpreting the square brackets as special globbing characters. Link local
|
||||
and site local addresses including a scope identifier, such as `fe80::1234%1`,
|
||||
may also be used, but the scope portion must be numeric or match an existing
|
||||
network interface on Linux and the percent character must be URL escaped. The
|
||||
|
@ -23,7 +23,7 @@ that supporting this protocol is a grand idea.
|
||||
curl is not here for your protocol. Your protocol is not here for curl. The
|
||||
best cooperation and end result occur when all involved parties mutually see
|
||||
and agree that supporting this protocol in curl would be good for everyone.
|
||||
Heck, for the world!
|
||||
Heck, for the world.
|
||||
|
||||
Consider "selling us" the idea that we need an implementation merged in curl,
|
||||
to be fairly important. *Why* do we want curl to support this new protocol?
|
||||
@ -90,8 +90,8 @@ protocol - but it might require a bit of an effort to make it happen.
|
||||
|
||||
## Documentation
|
||||
|
||||
We cannot assume that users are particularly familiar with specific details
|
||||
and peculiarities of the protocol. It needs documentation.
|
||||
We cannot assume that users are particularly familiar with details and
|
||||
peculiarities of the protocol. It needs documentation.
|
||||
|
||||
Maybe it even needs some internal documentation so that the developers who
|
||||
will try to debug something five years from now can figure out functionality a
|
||||
@ -104,7 +104,7 @@ any NDA or similar.
|
||||
|
||||
We are constantly raising the bar and we are constantly improving the
|
||||
project. A lot of things we did in the past would not be acceptable if done
|
||||
today. Therefore, you might be tempted to use shortcuts or "hacks" you can
|
||||
today. Therefore, you might be tempted to use shortcuts or "hacks" you can
|
||||
spot other - existing - protocol implementations have used, but there is
|
||||
nothing to gain from that. The bar has been raised. Former "cheats" will not be
|
||||
tolerated anymore.
|
||||
|
@ -49,7 +49,7 @@ share API as well, as a context per origin + path (realm?) basically.
|
||||
|
||||
Visible in test 153, 1412 and more.
|
||||
|
||||
## Feedback!
|
||||
## Feedback
|
||||
|
||||
This is early days for parallel transfer support. Keep your eyes open for
|
||||
unintended side effects or downright bugs.
|
||||
|
@ -34,7 +34,7 @@ companies and recent years several such CAs have been found untrustworthy.
|
||||
Certificate Verification
|
||||
------------------------
|
||||
|
||||
libcurl performs peer SSL certificate verification by default. This is done
|
||||
libcurl performs peer SSL certificate verification by default. This is done
|
||||
by using a CA certificate store that the SSL library can use to make sure the
|
||||
peer's server certificate is valid.
|
||||
|
||||
|
@ -20,7 +20,7 @@ changes over time.
|
||||
URL parsers as implemented in browsers, libraries and tools usually opt to
|
||||
support one of the mentioned specifications. Bugs, differences in
|
||||
interpretations and the moving nature of the WHATWG spec does however make it
|
||||
unlikely that multiple parsers treat URLs the exact same way!
|
||||
unlikely that multiple parsers treat URLs the same way.
|
||||
|
||||
## Security
|
||||
|
||||
|
@ -8,5 +8,5 @@ Example: --upload-file local --append ftp://example.com/
|
||||
Added: 4.8
|
||||
---
|
||||
When used in an upload, this makes curl append to the target file instead of
|
||||
overwriting it. If the remote file does not exist, it will be created. Note
|
||||
overwriting it. If the remote file does not exist, it will be created. Note
|
||||
that this flag is ignored by some SFTP servers (including OpenSSH).
|
||||
|
@ -8,6 +8,6 @@ Example: --cert-type PEM --cert file $URL
|
||||
Added: 7.9.3
|
||||
---
|
||||
Tells curl what type the provided client certificate is using. PEM, DER, ENG
|
||||
and P12 are recognized types. If not specified, PEM is assumed.
|
||||
and P12 are recognized types. If not specified, PEM is assumed.
|
||||
|
||||
If this option is used several times, the last one will be used.
|
||||
|
@ -11,7 +11,7 @@ Added: 5.0
|
||||
Tells curl to use the specified client certificate file when getting a file
|
||||
with HTTPS, FTPS or another SSL-based protocol. The certificate must be in
|
||||
PKCS#12 format if using Secure Transport, or PEM format if using any other
|
||||
engine. If the optional password is not specified, it will be queried for on
|
||||
engine. If the optional password is not specified, it will be queried for on
|
||||
the terminal. Note that this option assumes a \&"certificate" file that is the
|
||||
private key and the client certificate concatenated! See --cert and --key to
|
||||
specify them independently.
|
||||
@ -21,9 +21,9 @@ curl the nickname of the certificate to use within the NSS database defined
|
||||
by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the
|
||||
NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be
|
||||
loaded. If you want to use a file from the current directory, please precede
|
||||
it with "./" prefix, in order to avoid confusion with a nickname. If the
|
||||
it with "./" prefix, in order to avoid confusion with a nickname. If the
|
||||
nickname contains ":", it needs to be preceded by "\\" so that it is not
|
||||
recognized as password delimiter. If the nickname contains "\\", it needs to
|
||||
recognized as password delimiter. If the nickname contains "\\", it needs to
|
||||
be escaped as "\\\\" so that it is not recognized as an escape character.
|
||||
|
||||
If curl is built against OpenSSL library, and the engine pkcs11 is available,
|
||||
|
@ -10,7 +10,7 @@ Added: 4.8
|
||||
---
|
||||
Continue/Resume a previous file transfer at the given offset. The given offset
|
||||
is the exact number of bytes that will be skipped, counting from the beginning
|
||||
of the source file before it is transferred to the destination. If used with
|
||||
of the source file before it is transferred to the destination. If used with
|
||||
uploads, the FTP server command SIZE will not be used by curl.
|
||||
|
||||
Use "-C -" to tell curl to automatically find out where/how to resume the
|
||||
|
@ -10,7 +10,7 @@ See-also: cookie-jar junk-session-cookies
|
||||
Added: 4.9
|
||||
---
|
||||
Pass the data to the HTTP server in the Cookie header. It is supposedly
|
||||
the data previously received from the server in a "Set-Cookie:" line. The
|
||||
the data previously received from the server in a "Set-Cookie:" line. The
|
||||
data should be in the format "NAME1=VALUE1; NAME2=VALUE2".
|
||||
|
||||
If no '=' symbol is used in the argument, it is instead treated as a filename
|
||||
|
@ -13,7 +13,7 @@ them with ":" (e.g. "X25519:P-521"). The parameter is available identically
|
||||
in the "openssl s_client/s_server" utilities.
|
||||
|
||||
--curves allows a OpenSSL powered curl to make SSL-connections with exactly
|
||||
the (EC) curve requested by the client, avoiding intransparent client/server
|
||||
the (EC) curve requested by the client, avoiding nontransparent client/server
|
||||
negotiations.
|
||||
|
||||
If this option is set, the default curves list built into openssl will be
|
||||
|
@ -9,7 +9,7 @@ See-also: data-ascii
|
||||
---
|
||||
This posts data exactly as specified with no extra processing whatsoever.
|
||||
|
||||
If you start the data with the letter @, the rest should be a filename. Data
|
||||
If you start the data with the letter @, the rest should be a filename. Data
|
||||
is posted in a similar manner as --data does, except that newlines and
|
||||
carriage returns are preserved and conversions are never done.
|
||||
|
||||
|
@ -14,17 +14,17 @@ Added: 4.0
|
||||
Sends the specified data in a POST request to the HTTP server, in the same way
|
||||
that a browser does when a user has filled in an HTML form and presses the
|
||||
submit button. This will cause curl to pass the data to the server using the
|
||||
content-type application/x-www-form-urlencoded. Compare to --form.
|
||||
content-type application/x-www-form-urlencoded. Compare to --form.
|
||||
|
||||
--data-raw is almost the same but does not have a special interpretation of
|
||||
the @ character. To post data purely binary, you should instead use the
|
||||
--data-binary option. To URL-encode the value of a form field you may use
|
||||
--data-binary option. To URL-encode the value of a form field you may use
|
||||
--data-urlencode.
|
||||
|
||||
If any of these options is used more than once on the same command line, the
|
||||
data pieces specified will be merged together with a separating
|
||||
&-symbol. Thus, using '-d name=daniel -d skill=lousy' would generate a post
|
||||
chunk that looks like \&'name=daniel&skill=lousy'.
|
||||
data pieces specified will be merged with a separating &-symbol. Thus, using
|
||||
\&'-d name=daniel -d skill=lousy' would generate a post chunk that looks like
|
||||
\&'name=daniel&skill=lousy'.
|
||||
|
||||
If you start the data with the letter @, the rest should be a file name to
|
||||
read the data from, or - if you want curl to read the data from stdin. Posting
|
||||
|
@ -26,7 +26,7 @@ file.
|
||||
Tell curl to read content from stdin instead of a file by using - as
|
||||
filename. This goes for both @ and < constructs. When stdin is used, the
|
||||
contents is buffered in memory first by curl to determine its size and allow a
|
||||
possible resend. Defining a part's data from a named non-regular file (such
|
||||
possible resend. Defining a part's data from a named non-regular file (such
|
||||
as a named pipe or similar) is unfortunately not subject to buffering and will
|
||||
be effectively read at transmission time; since the full size is unknown
|
||||
before the transfer starts, such data is sent as chunks by HTTP and rejected
|
||||
|
@ -8,7 +8,7 @@ Example: --netrc-file netrc $URL
|
||||
See-also: netrc user config
|
||||
---
|
||||
This option is similar to --netrc, except that you provide the path (absolute
|
||||
or relative) to the netrc file that curl should use. You can only specify one
|
||||
or relative) to the netrc file that curl should use. You can only specify one
|
||||
netrc file per invocation. If several --netrc-file options are provided,
|
||||
the last one will be used.
|
||||
|
||||
|
@ -6,7 +6,7 @@ Category: tls
|
||||
Example: --no-sessionid $URL
|
||||
See-also: insecure
|
||||
---
|
||||
Disable curl's use of SSL session-ID caching. By default all transfers are
|
||||
Disable curl's use of SSL session-ID caching. By default all transfers are
|
||||
done using the cache. Note that while nothing should ever get hurt by
|
||||
attempting to reuse SSL session-IDs, there seem to be broken SSL
|
||||
implementations in the wild that may require you to disable this in order for
|
||||
|
@ -16,7 +16,7 @@ from your environment by specifying a single colon with this option: "-U :".
|
||||
On systems where it works, curl will hide the given option argument from
|
||||
process listings. This is not enough to protect credentials from possibly
|
||||
getting seen by other users on the same system as they will still be visible
|
||||
for a brief moment before cleared. Such sensitive data should be retrieved
|
||||
from a file instead or similar and never used in clear text in a command line.
|
||||
for a moment before cleared. Such sensitive data should be retrieved from a
|
||||
file instead or similar and never used in clear text in a command line.
|
||||
|
||||
If this option is used several times, the last one will be used.
|
||||
|
@ -36,7 +36,7 @@ User and password that might be provided in the proxy string are URL decoded
|
||||
by curl. This allows you to pass in special characters such as @ by using %40
|
||||
or pass in a colon with %3a.
|
||||
|
||||
The proxy host can be specified the exact same way as the proxy environment
|
||||
The proxy host can be specified the same way as the proxy environment
|
||||
variables, including the protocol prefix (http://) and the embedded user +
|
||||
password.
|
||||
|
||||
|
@ -11,7 +11,7 @@ See-also: request
|
||||
Send an arbitrary command to the remote FTP or SFTP server. Quote commands are
|
||||
sent BEFORE the transfer takes place (just after the initial PWD command in an
|
||||
FTP transfer, to be exact). To make commands take place after a successful
|
||||
transfer, prefix them with a dash '-'. To make commands be sent after curl
|
||||
transfer, prefix them with a dash '-'. To make commands be sent after curl
|
||||
has changed the working directory, just before the transfer command(s), prefix
|
||||
the command with a '+' (this is only supported for FTP). You may specify any
|
||||
number of commands.
|
||||
@ -27,8 +27,8 @@ servers, or one of the commands listed below to SFTP servers.
|
||||
This option can be used multiple times.
|
||||
|
||||
SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands
|
||||
itself before sending them to the server. File names may be quoted
|
||||
shell-style to embed spaces or special characters. Following is the list of
|
||||
itself before sending them to the server. File names may be quoted
|
||||
shell-style to embed spaces or special characters. Following is the list of
|
||||
all supported SFTP quote commands:
|
||||
.RS
|
||||
.IP "atime date file"
|
||||
|
@ -7,5 +7,5 @@ Added: 7.7
|
||||
See-also: egd-file
|
||||
---
|
||||
Specify the path name to file containing what will be considered as random
|
||||
data. The data may be used to seed the random engine for SSL connections. See
|
||||
data. The data may be used to seed the random engine for SSL connections. See
|
||||
also the --egd-file option.
|
||||
|
@ -11,7 +11,7 @@ Example: --referer ";auto" -L $URL
|
||||
Added: 4.0
|
||||
---
|
||||
Sends the "Referrer Page" information to the HTTP server. This can also be set
|
||||
with the --header flag of course. When used with --location you can append
|
||||
with the --header flag of course. When used with --location you can append
|
||||
";auto" to the --referer URL to make curl automatically set the previous URL
|
||||
when it follows a Location: header. The \&";auto" string can be used alone,
|
||||
even if you do not set an initial --referer.
|
||||
|
@ -19,5 +19,5 @@ There's no attempt to decode %-sequences (yet) in the provided file name, so
|
||||
this option may provide you with rather unexpected file names.
|
||||
|
||||
**WARNING**: Exercise judicious use of this option, especially on Windows. A
|
||||
rogue server could send you the name of a DLL or other file that could possibly
|
||||
be loaded automatically by Windows or some third party software.
|
||||
rogue server could send you the name of a DLL or other file that could be
|
||||
loaded automatically by Windows or some third party software.
|
||||
|
@ -9,7 +9,7 @@ Added: 6.0
|
||||
See-also: request-target
|
||||
---
|
||||
(HTTP) Specifies a custom request method to use when communicating with the
|
||||
HTTP server. The specified request method will be used instead of the method
|
||||
HTTP server. The specified request method will be used instead of the method
|
||||
otherwise used (which defaults to GET). Read the HTTP 1.1 specification for
|
||||
details and explanations. Common additional HTTP requests include PUT and
|
||||
DELETE, but related technologies like WebDAV offers PROPFIND, COPY, MOVE and
|
||||
|
@ -10,7 +10,7 @@ The retry timer is reset before the first transfer attempt. Retries will be
|
||||
done as usual (see --retry) as long as the timer has not reached this given
|
||||
limit. Notice that if the timer has not reached the limit, the request will be
|
||||
made and while performing, it may take longer than this given time period. To
|
||||
limit a single request's maximum time, use --max-time. Set this option to
|
||||
limit a single request's maximum time, use --max-time. Set this option to
|
||||
zero to not timeout retries.
|
||||
|
||||
If this option is used several times, the last one will be used.
|
||||
|
@ -14,7 +14,7 @@ response code.
|
||||
|
||||
When curl is about to retry a transfer, it will first wait one second and then
|
||||
for all forthcoming retries it will double the waiting time until it reaches
|
||||
10 minutes which then will be the delay between the rest of the retries. By
|
||||
10 minutes which then will be the delay between the rest of the retries. By
|
||||
using --retry-delay you disable this exponential backoff algorithm. See also
|
||||
--retry-max-time to limit the total time allowed for retries.
|
||||
|
||||
|
@ -6,7 +6,7 @@ Category: important verbose
|
||||
Example: -s $URL
|
||||
Added: 4.0
|
||||
---
|
||||
Silent or quiet mode. Do not show progress meter or error messages. Makes Curl
|
||||
Silent or quiet mode. Do not show progress meter or error messages. Makes Curl
|
||||
mute. It will still output the data you ask for, potentially even to the
|
||||
terminal/stdout unless you redirect it.
|
||||
|
||||
|
@ -7,5 +7,5 @@ See-also: socks5
|
||||
---
|
||||
As part of the GSS-API negotiation a protection mode is negotiated. RFC 1961
|
||||
says in section 4.3/4.4 it should be protected, but the NEC reference
|
||||
implementation does not. The option --socks5-gssapi-nec allows the
|
||||
implementation does not. The option --socks5-gssapi-nec allows the
|
||||
unprotected exchange of the protection mode negotiation.
|
||||
|
@ -6,8 +6,8 @@ Category: tls
|
||||
Example: --ssl pop3://example.com/
|
||||
See-also: insecure ciphers
|
||||
---
|
||||
Try to use SSL/TLS for the connection. Reverts to a non-secure connection if
|
||||
the server does not support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd
|
||||
Try to use SSL/TLS for the connection. Reverts to a non-secure connection if
|
||||
the server does not support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd
|
||||
for different levels of encryption required.
|
||||
|
||||
This option was formerly known as --ftp-ssl (Added in 7.11.0). That option
|
||||
|
@ -8,6 +8,6 @@ See-also: tlsuser
|
||||
---
|
||||
Set TLS authentication type. Currently, the only supported option is "SRP",
|
||||
for TLS-SRP (RFC 5054). If --tlsuser and --tlspassword are specified but
|
||||
--tlsauthtype is not, then this option defaults to "SRP". This option works
|
||||
--tlsauthtype is not, then this option defaults to "SRP". This option works
|
||||
only if the underlying libcurl is built with TLS-SRP support, which requires
|
||||
OpenSSL or GnuTLS with TLS-SRP support.
|
||||
|
@ -29,11 +29,11 @@ curl_easy_getinfo - extract information from a curl handle
|
||||
.B "CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );"
|
||||
|
||||
.SH DESCRIPTION
|
||||
Request internal information from the curl session with this function. The
|
||||
Request internal information from the curl session with this function. The
|
||||
third argument \fBMUST\fP be a pointer to a long, a pointer to a char *, a
|
||||
pointer to a struct curl_slist * or a pointer to a double (as this
|
||||
documentation describes further down). The data pointed-to will be filled in
|
||||
accordingly and can be relied upon only if the function returns CURLE_OK. Use
|
||||
documentation describes further down). The data pointed-to will be filled in
|
||||
accordingly and can be relied upon only if the function returns CURLE_OK. Use
|
||||
this function AFTER a performed transfer if you want to get transfer related
|
||||
data.
|
||||
|
||||
@ -162,7 +162,7 @@ See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP
|
||||
.IP CURLINFO_CONTENT_LENGTH_UPLOAD
|
||||
(Deprecated) Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD(3)\fP
|
||||
.IP CURLINFO_CONTENT_LENGTH_UPLOAD_T
|
||||
Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP
|
||||
Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP
|
||||
.IP CURLINFO_CONTENT_TYPE
|
||||
Content type from the Content-Type header.
|
||||
See \fICURLINFO_CONTENT_TYPE(3)\fP
|
||||
@ -215,7 +215,7 @@ See \fICURLINFO_CERTINFO(3)\fP
|
||||
TLS session info that can be used for further processing.
|
||||
See \fICURLINFO_TLS_SSL_PTR(3)\fP
|
||||
.IP CURLINFO_TLS_SESSION
|
||||
TLS session info that can be used for further processing. See
|
||||
TLS session info that can be used for further processing. See
|
||||
\fICURLINFO_TLS_SESSION(3)\fP. Deprecated option, use
|
||||
\fICURLINFO_TLS_SSL_PTR(3)\fP instead!
|
||||
.IP CURLINFO_CONDITION_UNMET
|
||||
|
@ -33,12 +33,12 @@ interface. This call \fBMUST\fP have a corresponding call to
|
||||
\fIcurl_easy_cleanup(3)\fP when the operation is complete.
|
||||
|
||||
If you did not already call \fIcurl_global_init(3)\fP, \fIcurl_easy_init(3)\fP
|
||||
does it automatically. This may be lethal in multi-threaded cases, since
|
||||
does it automatically. This may be lethal in multi-threaded cases, since
|
||||
\fIcurl_global_init(3)\fP is not thread-safe, and it may result in resource
|
||||
problems because there is no corresponding cleanup.
|
||||
|
||||
You are strongly advised to not allow this automatic behavior, by calling
|
||||
\fIcurl_global_init(3)\fP yourself properly. See the description in
|
||||
\fIcurl_global_init(3)\fP yourself properly. See the description in
|
||||
\fBlibcurl\fP(3) of global environment requirements for details of how to use
|
||||
this function.
|
||||
.SH EXAMPLE
|
||||
|
@ -106,7 +106,7 @@ you allow libcurl to uncompress data automatically.
|
||||
Added in 7.18.0.
|
||||
.SH RETURN VALUE
|
||||
CURLE_OK (zero) means that the option was set properly, and a non-zero return
|
||||
code means something wrong occurred after the new state was set. See the
|
||||
code means something wrong occurred after the new state was set. See the
|
||||
\fIlibcurl-errors(3)\fP man page for the full list with descriptions.
|
||||
.SH "SEE ALSO"
|
||||
.BR curl_easy_cleanup "(3), " curl_easy_reset "(3)"
|
||||
|
@ -29,16 +29,16 @@ curl_easy_setopt \- set options for a curl easy handle
|
||||
CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
|
||||
.SH DESCRIPTION
|
||||
\fIcurl_easy_setopt(3)\fP is used to tell libcurl how to behave. By setting
|
||||
the appropriate options, the application can change libcurl's behavior. All
|
||||
the appropriate options, the application can change libcurl's behavior. All
|
||||
options are set with an \fIoption\fP followed by a \fIparameter\fP. That
|
||||
parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject
|
||||
pointer\fP or a \fBcurl_off_t\fP, depending on what the specific option
|
||||
expects. Read this manual carefully as bad input values may cause libcurl to
|
||||
behave badly! You can only set one option in each function call. A typical
|
||||
behave badly! You can only set one option in each function call. A typical
|
||||
application uses many \fIcurl_easy_setopt(3)\fP calls in the setup phase.
|
||||
|
||||
Options set with this function call are valid for all forthcoming transfers
|
||||
performed using this \fIhandle\fP. The options are not in any way reset
|
||||
performed using this \fIhandle\fP. The options are not in any way reset
|
||||
between transfers, so if you want subsequent transfers with different options,
|
||||
you must change them between the transfers. You can optionally reset all
|
||||
options back to internal default with \fIcurl_easy_reset(3)\fP.
|
||||
@ -536,9 +536,9 @@ Proxy client cert. See \fICURLOPT_PROXY_SSLCERT(3)\fP
|
||||
.IP CURLOPT_PROXY_SSLCERT_BLOB
|
||||
Proxy client cert memory buffer. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP
|
||||
.IP CURLOPT_SSLCERTTYPE
|
||||
Client cert type. See \fICURLOPT_SSLCERTTYPE(3)\fP
|
||||
Client cert type. See \fICURLOPT_SSLCERTTYPE(3)\fP
|
||||
.IP CURLOPT_PROXY_SSLCERTTYPE
|
||||
Proxy client cert type. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP
|
||||
Proxy client cert type. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP
|
||||
.IP CURLOPT_SSLKEY
|
||||
Client key. See \fICURLOPT_SSLKEY(3)\fP
|
||||
.IP CURLOPT_SSLKEY_BLOB
|
||||
|
@ -29,7 +29,7 @@ curl_formadd - add a section to a multipart/formdata HTTP POST
|
||||
.BI "struct curl_httppost ** " lastitem, " ...);"
|
||||
.ad
|
||||
.SH DESCRIPTION
|
||||
This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
|
||||
This function is deprecated. Do not use. See \fIcurl_mime_init(3)\fP instead.
|
||||
|
||||
curl_formadd() is used to append sections when building a multipart/formdata
|
||||
HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
|
||||
@ -112,7 +112,7 @@ The specified file needs to kept around until the associated transfer is done.
|
||||
followed by a filename, makes this part a file upload part. It sets the
|
||||
\fIfilename\fP field to the basename of the provided filename, it reads the
|
||||
contents of the file and passes them as data and sets the content-type if the
|
||||
given file match one of the internally known file extensions. For
|
||||
given file match one of the internally known file extensions. For
|
||||
\fBCURLFORM_FILE\fP the user may send one or more files in one part by
|
||||
providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
|
||||
(and each \fICURLFORM_FILE\fP is allowed to have a
|
||||
@ -131,8 +131,8 @@ is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
|
||||
string, it tells libcurl to use the given string as the \fIfilename\fP in the
|
||||
file upload part instead of the actual file name.
|
||||
.IP CURLFORM_BUFFER
|
||||
is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
|
||||
tells libcurl that the file contents are already present in a buffer. The
|
||||
is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
|
||||
tells libcurl that the file contents are already present in a buffer. The
|
||||
parameter is a string which provides the \fIfilename\fP field in the content
|
||||
header.
|
||||
.IP CURLFORM_BUFFERPTR
|
||||
@ -156,10 +156,10 @@ Another possibility to send options to curl_formadd() is the
|
||||
\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
|
||||
its value. Each curl_forms structure element has a CURLformoption and a char
|
||||
pointer. The final element in the array must be a CURLFORM_END. All available
|
||||
options can be used in an array, except the CURLFORM_ARRAY option itself! The
|
||||
options can be used in an array, except the CURLFORM_ARRAY option itself. The
|
||||
last argument in such an array must always be \fBCURLFORM_END\fP.
|
||||
.IP CURLFORM_CONTENTHEADER
|
||||
specifies extra headers for the form POST section. This takes a curl_slist
|
||||
specifies extra headers for the form POST section. This takes a curl_slist
|
||||
prepared in the usual way using \fBcurl_slist_append\fP and appends the list
|
||||
of headers to those libcurl automatically generates. The list must exist while
|
||||
the POST occurs, if you free it before the post completes you may experience
|
||||
|
@ -28,7 +28,7 @@ curl_formfree - free a previously build multipart/formdata HTTP POST chain
|
||||
.BI "void curl_formfree(struct curl_httppost *" form);
|
||||
.ad
|
||||
.SH DESCRIPTION
|
||||
This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
|
||||
This function is deprecated. Do not use. See \fIcurl_mime_init(3)\fP instead!
|
||||
|
||||
curl_formfree() is used to clean up data previously built/appended with
|
||||
\fIcurl_formadd(3)\fP. This must be called when the data has been used, which
|
||||
|
@ -28,7 +28,7 @@ curl_free - reclaim memory that has been obtained through a libcurl call
|
||||
.BI "void curl_free( char *" ptr " );"
|
||||
.ad
|
||||
.SH DESCRIPTION
|
||||
curl_free reclaims memory that has been obtained through a libcurl call. Use
|
||||
curl_free reclaims memory that has been obtained through a libcurl call. Use
|
||||
\fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from
|
||||
differences in memory management between your application and libcurl.
|
||||
|
||||
|
@ -34,7 +34,7 @@ curl_getdate - Convert a date string to number of seconds
|
||||
pass a NULL there.
|
||||
.SH PARSING DATES AND TIMES
|
||||
A "date" is a string containing several items separated by whitespace. The
|
||||
order of the items is immaterial. A date string may contain many flavors of
|
||||
order of the items is immaterial. A date string may contain many flavors of
|
||||
items:
|
||||
.TP 0.8i
|
||||
.B calendar date items
|
||||
|
@ -35,7 +35,7 @@ You should call \fIcurl_global_cleanup(3)\fP once for each call you make to
|
||||
|
||||
\fBThis function is not thread safe.\fP You must not call it when any other
|
||||
thread in the program (i.e. a thread sharing the same memory) is running.
|
||||
This does not just mean no other thread that is using libcurl. Because
|
||||
This does not just mean no other thread that is using libcurl. Because
|
||||
\fIcurl_global_cleanup(3)\fP calls functions of other libraries that are
|
||||
similarly thread unsafe, it could conflict with any other thread that uses
|
||||
these other libraries.
|
||||
|
@ -28,24 +28,24 @@ curl_global_init - Global libcurl initialisation
|
||||
.BI "CURLcode curl_global_init(long " flags ");"
|
||||
.ad
|
||||
.SH DESCRIPTION
|
||||
This function sets up the program environment that libcurl needs. Think of it
|
||||
This function sets up the program environment that libcurl needs. Think of it
|
||||
as an extension of the library loader.
|
||||
|
||||
This function must be called at least once within a program (a program is all
|
||||
the code that shares a memory space) before the program calls any other
|
||||
function in libcurl. The environment it sets up is constant for the life of
|
||||
function in libcurl. The environment it sets up is constant for the life of
|
||||
the program and is the same for every program, so multiple calls have the same
|
||||
effect as one call.
|
||||
|
||||
The flags option is a bit pattern that tells libcurl exactly what features to
|
||||
init, as described below. Set the desired bits by ORing the values together.
|
||||
In normal operation, you must specify CURL_GLOBAL_ALL. Do not use any other
|
||||
In normal operation, you must specify CURL_GLOBAL_ALL. Do not use any other
|
||||
value unless you are familiar with it and mean to control internal operations
|
||||
of libcurl.
|
||||
|
||||
\fBThis function is not thread safe.\fP You must not call it when any other
|
||||
thread in the program (i.e. a thread sharing the same memory) is running.
|
||||
This does not just mean no other thread that is using libcurl. Because
|
||||
This does not just mean no other thread that is using libcurl. Because
|
||||
\fIcurl_global_init(3)\fP calls functions of other libraries that are
|
||||
similarly thread unsafe, it could conflict with any other thread that uses
|
||||
these other libraries.
|
||||
@ -90,7 +90,7 @@ the functionality of the \fBCURL_GLOBAL_ALL\fP mask.
|
||||
This bit has no point since 7.69.0 but its behavior is instead the default.
|
||||
|
||||
Before 7.69.0: when this flag is set, curl will acknowledge EINTR condition
|
||||
when connecting or when waiting for data. Otherwise, curl waits until full
|
||||
when connecting or when waiting for data. Otherwise, curl waits until full
|
||||
timeout elapses. (Added in 7.30.0)
|
||||
.SH EXAMPLE
|
||||
.nf
|
||||
|
@ -29,7 +29,7 @@ curl_mime_addpart - append a new empty part to a mime structure
|
||||
.ad
|
||||
.SH DESCRIPTION
|
||||
\fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given
|
||||
mime structure and returns a handle to it. The returned part handle can
|
||||
mime structure and returns a handle to it. The returned part handle can
|
||||
subsequently be populated using functions from the mime API.
|
||||
|
||||
\fImime\fP is the handle of the mime structure in which the new part must be
|
||||
|
@ -36,7 +36,7 @@ data to a mime part.
|
||||
\fIpart\fP is the part's to assign contents to.
|
||||
|
||||
\fIfilename\fP points to the null-terminated file's path name. The pointer can
|
||||
be NULL to detach the previous part contents settings. Filename storage can
|
||||
be NULL to detach the previous part contents settings. Filename storage can
|
||||
be safely be reused after this call.
|
||||
|
||||
As a side effect, the part's remote file name is set to the base name of the
|
||||
|
@ -29,7 +29,7 @@ curl_mime_free - free a previously built mime structure
|
||||
.ad
|
||||
.SH DESCRIPTION
|
||||
\fIcurl_mime_free(3)\fP is used to clean up data previously built/appended
|
||||
with \fIcurl_mime_addpart(3)\fP and other mime-handling functions. This must
|
||||
with \fIcurl_mime_addpart(3)\fP and other mime-handling functions. This must
|
||||
be called when the data has been used, which typically means after
|
||||
\fIcurl_easy_perform(3)\fP has been called.
|
||||
|
||||
|
@ -54,7 +54,7 @@ there are slight differences in behavior.
|
||||
We discourage users from using any of these functions in new applications.
|
||||
|
||||
Functions in the curl_mprintf() family produce output according to a format as
|
||||
described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP
|
||||
described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP
|
||||
write output to stdout, the standard output stream; \fBcurl_mfprintf()\fP and
|
||||
\fBcurl_mvfprintf()\fP write output to the given output stream;
|
||||
\fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, \fBcurl_mvsprintf()\fP, and
|
||||
@ -68,8 +68,8 @@ The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP,
|
||||
\fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the
|
||||
functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP,
|
||||
\fBcurl_msnprintf()\fP, respectively, except that they are called with a
|
||||
va_list instead of a variable number of arguments. These functions do not
|
||||
call the va_end macro. Because they invoke the va_arg macro, the value of ap
|
||||
va_list instead of a variable number of arguments. These functions do not
|
||||
call the va_end macro. Because they invoke the va_arg macro, the value of ap
|
||||
is undefined after the call.
|
||||
|
||||
The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the
|
||||
@ -92,11 +92,11 @@ or more \fIflags\fP, an optional minimum \fIfield width\fP, an optional
|
||||
The arguments must correspond properly with the conversion specifier. By
|
||||
default, the arguments are used in the order given, where each '*' (see Field
|
||||
width and Precision below) and each conversion specifier asks for the next
|
||||
argument (and it is an error if insufficiently many arguments are given). One
|
||||
argument (and it is an error if insufficiently many arguments are given). One
|
||||
can also specify explicitly which argument is taken, at each place where an
|
||||
argument is required, by writing "%m$" instead of '%' and "*m$" instead
|
||||
of '*', where the decimal integer m denotes the position in the argument list
|
||||
of the desired argument, indexed starting from 1. Thus,
|
||||
of the desired argument, indexed starting from 1. Thus,
|
||||
|
||||
curl_mprintf("%*d", width, num);
|
||||
|
||||
@ -109,7 +109,7 @@ argument.
|
||||
|
||||
If the style using '$' is used, it must be used throughout for all conversions
|
||||
taking an argument and all width and precision arguments, but it may be mixed
|
||||
with "%%" formats, which do not consume an argument. There may be no gaps in
|
||||
with "%%" formats, which do not consume an argument. There may be no gaps in
|
||||
the numbers of argu‐ ments specified using '$'; for example, if arguments 1
|
||||
and 3 are specified, argument 2 must also be specified somewhere in the format
|
||||
string.
|
||||
@ -135,7 +135,7 @@ produced by a signed conversion.
|
||||
.TP
|
||||
.B +
|
||||
A sign (+ or -) should always be placed before a number produced by a signed
|
||||
conversion. By default, a sign is used only for negative numbers. A '+'
|
||||
conversion. By default, a sign is used only for negative numbers. A '+'
|
||||
overrides a space if both are used.
|
||||
.SH "Field width"
|
||||
An optional decimal digit string (with nonzero first digit) specifying a
|
||||
@ -144,8 +144,8 @@ field width, it will be padded with spaces on the left (or right, if the
|
||||
left-adjustment flag has been given). Instead of a decimal digit string one
|
||||
may write "*" or "*m$" (for some decimal integer m) to specify that the field
|
||||
width is given in the next argument, or in the m-th argument, respec‐ tively,
|
||||
which must be of type int. A negative field width is taken as a '-' flag
|
||||
followed by a positive field width. In no case does a nonexistent or small
|
||||
which must be of type int. A negative field width is taken as a '-' flag
|
||||
followed by a positive field width. In no case does a nonexistent or small
|
||||
field width cause truncation of a field; if the result of a conversion is
|
||||
wider than the field width, the field is expanded to contain the conversion
|
||||
result.
|
||||
@ -174,7 +174,7 @@ short\fP argument.
|
||||
pointer to a long argument
|
||||
.TP
|
||||
.B ll
|
||||
(ell-ell). A following integer conversion corresponds to a \fIlong long\fP or
|
||||
(ell-ell). A following integer conversion corresponds to a \fIlong long\fP or
|
||||
\fIunsigned long long\fP argument, or a following n conversion corresponds to
|
||||
a pointer to a long long argument.
|
||||
.TP
|
||||
@ -193,7 +193,7 @@ A character that specifies the type of conversion to be applied. The
|
||||
conversion specifiers and their meanings are:
|
||||
.TP
|
||||
.B d, i
|
||||
The int argument is converted to signed decimal notation. The precision, if
|
||||
The int argument is converted to signed decimal notation. The precision, if
|
||||
any, gives the minimum number of digits that must appear; if the converted
|
||||
value requires fewer digits, it is padded on the left with zeros. The default
|
||||
precision is 1. When 0 is printed with an explicit precision 0, the output is
|
||||
@ -201,11 +201,11 @@ empty.
|
||||
.TP
|
||||
.B o, u, x, X
|
||||
The unsigned int argument is converted to unsigned octal (o), unsigned decimal
|
||||
(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters
|
||||
(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters
|
||||
abcdef are used for \fBx\fP conversions; the letters ABCDEF are used for
|
||||
\fBX\fP conversions. The precision, if any, gives the minimum number of digits
|
||||
that must appear; if the converted value requires fewer digits, it is padded
|
||||
on the left with zeros. The default precision is 1. When 0 is printed with
|
||||
on the left with zeros. The default precision is 1. When 0 is printed with
|
||||
an explicit precision 0, the output is empty.
|
||||
.TP
|
||||
.B e, E
|
||||
|
@ -46,7 +46,7 @@ is less than the amount of easy handles you have added to the multi handle), you
|
||||
know that there is one or more transfers less "running". You can then call
|
||||
\fIcurl_multi_info_read(3)\fP to get information about each individual
|
||||
completed transfer, and that returned info includes CURLcode and more. If an
|
||||
added handle fails quickly, it may never be counted as a running_handle. You
|
||||
added handle fails quickly, it may never be counted as a running_handle. You
|
||||
could use \fIcurl_multi_info_read(3)\fP to track actual status of the added
|
||||
handles in that case.
|
||||
|
||||
|
@ -34,7 +34,7 @@ CURLMcode curl_multi_poll(CURLM *multi_handle,
|
||||
.ad
|
||||
.SH DESCRIPTION
|
||||
\fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy
|
||||
handles contained in the given multi handle set. It will block until activity
|
||||
handles contained in the given multi handle set. It will block until activity
|
||||
is detected on at least one of the handles or \fItimeout_ms\fP has passed.
|
||||
Alternatively, if the multi handle has a pending internal timeout that has a
|
||||
shorter expiry time than \fItimeout_ms\fP, that shorter time will be used
|
||||
|
@ -29,12 +29,12 @@ CURLMcode curl_multi_setopt(CURLM *multi_handle, CURLMoption option, param);
|
||||
.SH DESCRIPTION
|
||||
\fIcurl_multi_setopt(3)\fP is used to tell a libcurl multi handle how to
|
||||
behave. By using the appropriate options to \fIcurl_multi_setopt(3)\fP, you
|
||||
can change libcurl's behavior when using that multi handle. All options are
|
||||
can change libcurl's behavior when using that multi handle. All options are
|
||||
set with the \fIoption\fP followed by the parameter \fIparam\fP. That
|
||||
parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject
|
||||
pointer\fP or a \fBcurl_off_t\fP type, depending on what the specific option
|
||||
expects. Read this manual carefully as bad input values may cause libcurl to
|
||||
behave badly! You can only set one option in each function call.
|
||||
behave badly. You can only set one option in each function call.
|
||||
|
||||
.SH OPTIONS
|
||||
.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE
|
||||
|
@ -32,8 +32,8 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle,
|
||||
int *running_handles);
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
These functions are deprecated. Do not use! See
|
||||
\fIcurl_multi_socket_action(3)\fP instead!
|
||||
These functions are deprecated. Do not use. See
|
||||
\fIcurl_multi_socket_action(3)\fP instead.
|
||||
|
||||
At return, the integer \fBrunning_handles\fP points to will contain the number
|
||||
of still running easy handles within the multi handle. When this number
|
||||
@ -65,7 +65,7 @@ equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to
|
||||
|
||||
Force libcurl to (re-)check all its internal sockets and transfers instead of
|
||||
just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there
|
||||
should not be any reason to use this function!
|
||||
should not be any reason to use this function.
|
||||
.SH CALLBACK
|
||||
The socket \fBcallback\fP function uses a prototype like this
|
||||
.nf
|
||||
|
@ -34,7 +34,7 @@ CURLMcode curl_multi_wait(CURLM *multi_handle,
|
||||
.ad
|
||||
.SH DESCRIPTION
|
||||
\fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy
|
||||
handles contained in the given multi handle set. It will block until activity
|
||||
handles contained in the given multi handle set. It will block until activity
|
||||
is detected on at least one of the handles or \fItimeout_ms\fP has passed.
|
||||
Alternatively, if the multi handle has a pending internal timeout that has a
|
||||
shorter expiry time than \fItimeout_ms\fP, that shorter time will be used
|
||||
|
@ -124,7 +124,7 @@ decode on get with the CURLU_URLDECODE bit.
|
||||
Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
|
||||
.SH RETURN VALUE
|
||||
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
|
||||
fine. See the \fIlibcurl-errors(3)\fP man page for the full list with
|
||||
fine. See the \fIlibcurl-errors(3)\fP man page for the full list with
|
||||
descriptions.
|
||||
|
||||
If this function returns an error, no URL part is returned.
|
||||
|
@ -112,7 +112,7 @@ sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP
|
||||
option if both are set.
|
||||
.IP CURLU_GUESS_SCHEME
|
||||
If set, will make libcurl allow the URL to be set without a scheme and it
|
||||
instead "guesses" which scheme that was intended based on the host name. If
|
||||
instead "guesses" which scheme that was intended based on the host name. If
|
||||
the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then
|
||||
that scheme will be used, otherwise it picks HTTP. Conflicts with the
|
||||
\fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set.
|
||||
@ -151,7 +151,7 @@ individual parts.
|
||||
Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
|
||||
.SH RETURN VALUE
|
||||
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
|
||||
fine. See the \fIlibcurl-errors(3)\fP man page for the full list with
|
||||
fine. See the \fIlibcurl-errors(3)\fP man page for the full list with
|
||||
descriptions.
|
||||
|
||||
A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP
|
||||
|
@ -63,7 +63,7 @@ Failed to connect() to host or proxy.
|
||||
The server sent data libcurl could not parse. This error code was known as as
|
||||
\fICURLE_FTP_WEIRD_SERVER_REPLY\fP before 7.51.0.
|
||||
.IP "CURLE_REMOTE_ACCESS_DENIED (9)"
|
||||
We were denied access to the resource given in the URL. For FTP, this occurs
|
||||
We were denied access to the resource given in the URL. For FTP, this occurs
|
||||
while trying to change to the remote directory.
|
||||
.IP "CURLE_FTP_ACCEPT_FAILED (10)"
|
||||
While waiting for the server to connect back when an active FTP session is
|
||||
@ -169,7 +169,7 @@ nothing is considered an error.
|
||||
.IP "CURLE_SSL_ENGINE_NOTFOUND (53)"
|
||||
The specified crypto engine was not found.
|
||||
.IP "CURLE_SSL_ENGINE_SETFAILED (54)"
|
||||
Failed setting the selected SSL crypto engine as default!
|
||||
Failed setting the selected SSL crypto engine as default.
|
||||
.IP "CURLE_SEND_ERROR (55)"
|
||||
Failed sending network data.
|
||||
.IP "CURLE_RECV_ERROR (56)"
|
||||
@ -309,7 +309,7 @@ Wakeup is unavailable or failed.
|
||||
A function was called with a bad parameter.
|
||||
.SH "CURLSHcode"
|
||||
The "share" interface will return a CURLSHcode to indicate when an error has
|
||||
occurred. Also consider \fIcurl_share_strerror(3)\fP.
|
||||
occurred. Also consider \fIcurl_share_strerror(3)\fP.
|
||||
.IP "CURLSHE_OK (0)"
|
||||
All fine. Proceed as usual.
|
||||
.IP "CURLSHE_BAD_OPTION (1)"
|
||||
@ -326,7 +326,7 @@ The requested sharing could not be done because the library you use do not have
|
||||
that particular feature enabled. (Added in 7.23.0)
|
||||
.SH "CURLUcode"
|
||||
The URL interface will return a CURLUcode to indicate when an error has
|
||||
occurred. Also consider \fIcurl_url_strerror(3)\fP.
|
||||
occurred. Also consider \fIcurl_url_strerror(3)\fP.
|
||||
.IP "CURLUE_BAD_HANDLE (1)"
|
||||
An invalid CURLU pointer was passed as argument.
|
||||
.IP "CURLUE_BAD_PARTPOINTER (2)"
|
||||
|
@ -71,7 +71,7 @@ Should you change your mind, the easy handle is again removed from the multi
|
||||
stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi
|
||||
handle, you can again use other easy interface functions like
|
||||
\fIcurl_easy_perform(3)\fP on the handle or whatever you think is
|
||||
necessary. You can remove handles at any point in time during transfers.
|
||||
necessary. You can remove handles at any point during transfers.
|
||||
|
||||
Adding the easy handle to the multi handle does not start the transfer.
|
||||
Remember that one of the main ideas with this interface is to let your
|
||||
|
@ -24,7 +24,7 @@
|
||||
.SH NAME
|
||||
libcurl-security \- security considerations when using libcurl
|
||||
.SH "Security"
|
||||
The libcurl project takes security seriously. The library is written with
|
||||
The libcurl project takes security seriously. The library is written with
|
||||
caution and precautions are taken to mitigate many kinds of risks encountered
|
||||
while operating with potentially malicious servers on the Internet. It is a
|
||||
powerful library, however, which allows application writers to make trade-offs
|
||||
@ -33,10 +33,10 @@ the right way, you can use libcurl to transfer data pretty safely.
|
||||
|
||||
Many applications are used in closed networks where users and servers can
|
||||
(possibly) be trusted, but many others are used on arbitrary servers and are
|
||||
fed input from potentially untrusted users. Following is a discussion about
|
||||
fed input from potentially untrusted users. Following is a discussion about
|
||||
some risks in the ways in which applications commonly use libcurl and
|
||||
potential mitigations of those risks. It is by no means comprehensive, but
|
||||
shows classes of attacks that robust applications should consider. The Common
|
||||
potential mitigations of those risks. It is not comprehensive, but shows
|
||||
classes of attacks that robust applications should consider. The Common
|
||||
Weakness Enumeration project at https://cwe.mitre.org/ is a good reference for
|
||||
many of these and similar types of weaknesses of which application writers
|
||||
should be aware.
|
||||
@ -55,7 +55,7 @@ automatically to frequently visited sites. The file contains passwords in
|
||||
clear text and is a real security risk. In some cases, your .netrc is also
|
||||
stored in a home directory that is NFS mounted or used on another network
|
||||
based file system, so the clear text password will fly through your network
|
||||
every time anyone reads that file!
|
||||
every time anyone reads that file.
|
||||
|
||||
For applications that enable .netrc use, a user who manage to set the right
|
||||
URL might then be possible to pass on passwords.
|
||||
@ -95,22 +95,21 @@ Ie use authenticated protocols protected with HTTPS or SSH.
|
||||
Never ever switch off certificate verification.
|
||||
.SH "Redirects"
|
||||
The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP
|
||||
redirects sent by a remote server. These redirects can refer to any kind of
|
||||
redirects sent by a remote server. These redirects can refer to any kind of
|
||||
URL, not just HTTP. libcurl restricts the protocols allowed to be used in
|
||||
redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are
|
||||
enabled by default. Applications may opt to restrict that set further.
|
||||
|
||||
A redirect to a file: URL would cause the libcurl to read (or write) arbitrary
|
||||
files from the local filesystem. If the application returns the data back to
|
||||
files from the local filesystem. If the application returns the data back to
|
||||
the user (as would happen in some kinds of CGI scripts), an attacker could
|
||||
leverage this to read otherwise forbidden data (e.g.
|
||||
file://localhost/etc/passwd).
|
||||
|
||||
If authentication credentials are stored in the ~/.netrc file, or Kerberos
|
||||
is in use, any other URL type (not just file:) that requires
|
||||
authentication is also at risk. A redirect such as
|
||||
ftp://some-internal-server/private-file would then return data even when
|
||||
the server is password protected.
|
||||
If authentication credentials are stored in the ~/.netrc file, or Kerberos is
|
||||
in use, any other URL type (not just file:) that requires authentication is
|
||||
also at risk. A redirect such as ftp://some-internal-server/private-file would
|
||||
then return data even when the server is password protected.
|
||||
|
||||
In the same way, if an unencrypted SSH private key has been configured for the
|
||||
user running the libcurl application, SCP: or SFTP: URLs could access password
|
||||
@ -136,7 +135,7 @@ A user who can control the DNS server of a domain being passed in within a URL
|
||||
can change the address of the host to a local, private address which a
|
||||
server-side libcurl-using application could then use. e.g. the innocuous URL
|
||||
http://fuzzybunnies.example.com/ could actually resolve to the IP address of a
|
||||
server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Applications can
|
||||
server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Applications can
|
||||
mitigate against this by setting a \fICURLOPT_OPENSOCKETFUNCTION(3)\fP and
|
||||
checking the address before a connection.
|
||||
|
||||
@ -144,13 +143,13 @@ All the malicious scenarios regarding redirected URLs apply just as well to
|
||||
non-redirected URLs, if the user is allowed to specify an arbitrary URL that
|
||||
could point to a private resource. For example, a web app providing a
|
||||
translation service might happily translate file://localhost/etc/passwd and
|
||||
display the result. Applications can mitigate against this with the
|
||||
display the result. Applications can mitigate against this with the
|
||||
\fICURLOPT_PROTOCOLS(3)\fP option as well as by similar mitigation techniques
|
||||
for redirections.
|
||||
|
||||
A malicious FTP server could in response to the PASV command return an IP
|
||||
address and port number for a server local to the app running libcurl but
|
||||
behind a firewall. Applications can mitigate against this by using the
|
||||
behind a firewall. Applications can mitigate against this by using the
|
||||
\fICURLOPT_FTP_SKIP_PASV_IP(3)\fP option or \fICURLOPT_FTPPORT(3)\fP.
|
||||
|
||||
Local servers sometimes assume local access comes from friends and trusted
|
||||
@ -174,32 +173,32 @@ as IPv4 addresses. That means that a sanitizing function that filters out
|
||||
addresses like 127.0.0.1 is not sufficient--the equivalent IPv6 addresses ::1,
|
||||
::, 0:00::0:1, ::127.0.0.1 and ::ffff:7f00:1 supplied somehow by an attacker
|
||||
would all bypass a naive filter and could allow access to undesired local
|
||||
resources. IPv6 also has special address blocks like link-local and
|
||||
site-local that generally should not be accessed by a server-side libcurl-using
|
||||
application. A poorly-configured firewall installed in a data center,
|
||||
resources. IPv6 also has special address blocks like link-local and site-local
|
||||
that generally should not be accessed by a server-side libcurl-using
|
||||
application. A poorly configured firewall installed in a data center,
|
||||
organization or server may also be configured to limit IPv4 connections but
|
||||
leave IPv6 connections wide open. In some cases, setting
|
||||
leave IPv6 connections wide open. In some cases, setting
|
||||
\fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4 can be used to limit resolved
|
||||
addresses to IPv4 only and bypass these issues.
|
||||
.SH Uploads
|
||||
When uploading, a redirect can cause a local (or remote) file to be
|
||||
overwritten. Applications must not allow any unsanitized URL to be passed in
|
||||
for uploads. Also, \fICURLOPT_FOLLOWLOCATION(3)\fP should not be used on
|
||||
uploads. Instead, the applications should consider handling redirects itself,
|
||||
uploads. Instead, the applications should consider handling redirects itself,
|
||||
sanitizing each URL first.
|
||||
.SH Authentication
|
||||
Use of \fICURLOPT_UNRESTRICTED_AUTH(3)\fP could cause authentication
|
||||
information to be sent to an unknown second server. Applications can mitigate
|
||||
information to be sent to an unknown second server. Applications can mitigate
|
||||
against this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP and handling
|
||||
redirects itself, sanitizing where necessary.
|
||||
|
||||
Use of the CURLAUTH_ANY option to \fICURLOPT_HTTPAUTH(3)\fP could result in
|
||||
user name and password being sent in clear text to an HTTP server. Instead,
|
||||
user name and password being sent in clear text to an HTTP server. Instead,
|
||||
use CURLAUTH_ANYSAFE which ensures that the password is encrypted over the
|
||||
network, or else fail the request.
|
||||
|
||||
Use of the CURLUSESSL_TRY option to \fICURLOPT_USE_SSL(3)\fP could result in
|
||||
user name and password being sent in clear text to an FTP server. Instead,
|
||||
user name and password being sent in clear text to an FTP server. Instead,
|
||||
use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else
|
||||
fail the request.
|
||||
.SH Cookies
|
||||
@ -301,7 +300,7 @@ right one.
|
||||
A malicious FTP server can respond to PASV commands with the IP+PORT of a
|
||||
totally different machine. Perhaps even a third party host, and when there are
|
||||
many clients trying to connect to that third party, it could create a
|
||||
Distributed Denial-Of-Service attack out of it! If the client makes an upload
|
||||
Distributed Denial-Of-Service attack out of it. If the client makes an upload
|
||||
operation, it can make the client send the data to another site. If the
|
||||
attacker can affect what data the client uploads, it can be made to work as a
|
||||
HTTP request and then the client could be made to issue HTTP requests to third
|
||||
@ -315,7 +314,7 @@ The fact that FTP uses two connections makes it vulnerable in a way that is
|
||||
hard to avoid.
|
||||
.SH "Denial of Service"
|
||||
A malicious server could cause libcurl to effectively hang by sending data
|
||||
slowly, or even no data at all but just keeping the TCP connection open. This
|
||||
slowly, or even no data at all but just keeping the TCP connection open. This
|
||||
could effectively result in a denial-of-service attack. The
|
||||
\fICURLOPT_TIMEOUT(3)\fP and/or \fICURLOPT_LOW_SPEED_LIMIT(3)\fP options can
|
||||
be used to mitigate against this.
|
||||
@ -323,7 +322,7 @@ be used to mitigate against this.
|
||||
A malicious server could cause libcurl to download an infinite amount of data,
|
||||
potentially causing all of memory or disk to be filled. Setting the
|
||||
\fICURLOPT_MAXFILESIZE_LARGE(3)\fP option is not sufficient to guard against
|
||||
this. Instead, applications should monitor the amount of data received within
|
||||
this. Instead, applications should monitor the amount of data received within
|
||||
the write or progress callback and abort once the limit is reached.
|
||||
|
||||
A malicious HTTP server could cause an infinite redirection loop, causing a
|
||||
@ -340,7 +339,7 @@ transactions.
|
||||
A server can supply data which the application may, in some cases, use as a
|
||||
file name. The curl command-line tool does this with
|
||||
\fI--remote-header-name\fP, using the Content-disposition: header to generate
|
||||
a file name. An application could also use \fICURLINFO_EFFECTIVE_URL(3)\fP to
|
||||
a file name. An application could also use \fICURLINFO_EFFECTIVE_URL(3)\fP to
|
||||
generate a file name from a server-supplied redirect URL. Special care must be
|
||||
taken to sanitize such names to avoid the possibility of a malicious server
|
||||
supplying one like "/etc/passwd", "\\autoexec.bat", "prn:" or even ".bashrc".
|
||||
@ -360,7 +359,7 @@ may in fact be used by intruders to gain additional information of a potential
|
||||
target.
|
||||
|
||||
Be sure to limit access to application logs if they could hold private or
|
||||
security-related data. Besides the obvious candidates like user names and
|
||||
security-related data. Besides the obvious candidates like user names and
|
||||
passwords, things like URLs, cookies or even file names could also hold
|
||||
sensitive data.
|
||||
|
||||
|
@ -38,7 +38,7 @@ using the share interface but you must provide your own locking and set
|
||||
.SH TLS
|
||||
If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
|
||||
then of course using the underlying SSL library multi-threaded and those libs
|
||||
might have their own requirements on this issue. You may need to provide one
|
||||
might have their own requirements on this issue. You may need to provide one
|
||||
or two functions to allow it to function properly:
|
||||
.IP OpenSSL
|
||||
OpenSSL 1.1.0+ "can be safely used in multi-threaded applications provided that
|
||||
@ -89,7 +89,7 @@ can find and use thread safe versions of these and other system calls, as
|
||||
otherwise it cannot function fully thread safe. Some operating systems are
|
||||
known to have faulty thread implementations. We have previously received
|
||||
problem reports on *BSD (at least in the past, they may be working fine these
|
||||
days). Some operating systems that are known to have solid and working thread
|
||||
days). Some operating systems that are known to have solid and working thread
|
||||
support are Linux, Solaris and Windows.
|
||||
.IP "curl_global_* functions"
|
||||
These functions are not thread safe. If you are using libcurl with multiple
|
||||
|
@ -236,8 +236,8 @@ commands and receive the transfer. Whenever it receives data, it calls the
|
||||
callback function we previously set. The function may get one byte at a time,
|
||||
or it may get many kilobytes at once. libcurl delivers as much as possible as
|
||||
often as possible. Your callback function should return the number of bytes it
|
||||
\&"took care of". If that is not the exact same amount of bytes that was
|
||||
passed to it, libcurl will abort the operation and return with an error code.
|
||||
\&"took care of". If that is not the same amount of bytes that was passed to
|
||||
it, libcurl will abort the operation and return with an error code.
|
||||
|
||||
When the transfer is complete, the function returns a return code that informs
|
||||
you if it succeeded in its mission or not. If a return code is not enough for
|
||||
@ -274,7 +274,7 @@ a better understanding why the server behaves the way it does. Include headers
|
||||
in the normal body output with \fICURLOPT_HEADER(3)\fP set 1.
|
||||
|
||||
Of course, there are bugs left. We need to know about them to be able to fix
|
||||
them, so we are quite dependent on your bug reports! When you do report
|
||||
them, so we are quite dependent on your bug reports. When you do report
|
||||
suspected bugs in libcurl, please include as many details as you possibly can:
|
||||
a protocol dump that \fICURLOPT_VERBOSE(3)\fP produces, library version, as
|
||||
much as possible of your code that uses libcurl, operating system name and
|
||||
@ -861,7 +861,7 @@ remote host").
|
||||
|
||||
Because of the nature of this operation, where the proxy has no idea what kind
|
||||
of data that is passed in and out through this tunnel, this breaks some of the
|
||||
few advantages that come from using a proxy, such as caching. Many
|
||||
few advantages that come from using a proxy, such as caching. Many
|
||||
organizations prevent this kind of tunneling to other destination port numbers
|
||||
than 443 (which is the default HTTPS port number).
|
||||
|
||||
@ -1292,10 +1292,10 @@ done.
|
||||
|
||||
The multi interface, on the other hand, allows your program to transfer
|
||||
multiple files in both directions at the same time, without forcing you to use
|
||||
multiple threads. The name might make it seem that the multi interface is for
|
||||
multi-threaded programs, but the truth is almost the reverse. The multi
|
||||
multiple threads. The name might make it seem that the multi interface is for
|
||||
multi-threaded programs, but the truth is almost the reverse. The multi
|
||||
interface allows a single-threaded application to perform the same kinds of
|
||||
multiple, simultaneous transfers that multi-threaded programs can perform. It
|
||||
multiple, simultaneous transfers that multi-threaded programs can perform. It
|
||||
allows many of the benefits of multi-threaded transfers without the complexity
|
||||
of managing and synchronizing many threads.
|
||||
|
||||
@ -1320,7 +1320,7 @@ ones at any time), you start the transfers by calling
|
||||
\fIcurl_multi_perform(3)\fP.
|
||||
|
||||
\fIcurl_multi_perform(3)\fP is asynchronous. It will only perform what can be
|
||||
done now and then return back control to your program. It is designed to never
|
||||
done now and then return control to your program. It is designed to never
|
||||
block. You need to keep calling the function until all transfers are
|
||||
completed.
|
||||
|
||||
|
@ -33,10 +33,9 @@ There are many bindings available that bring libcurl access to your favourite
|
||||
language. Look elsewhere for documentation on those.
|
||||
|
||||
libcurl has a global constant environment that you must set up and maintain
|
||||
while using libcurl. This essentially means you call
|
||||
\fIcurl_global_init(3)\fP at the start of your program and
|
||||
\fIcurl_global_cleanup(3)\fP at the end. See \fBGLOBAL CONSTANTS\fP below for
|
||||
details.
|
||||
while using libcurl. This essentially means you call \fIcurl_global_init(3)\fP
|
||||
at the start of your program and \fIcurl_global_cleanup(3)\fP at the end. See
|
||||
\fBGLOBAL CONSTANTS\fP below for details.
|
||||
|
||||
If libcurl was compiled with support for multiple SSL backends, the function
|
||||
\fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP
|
||||
@ -143,20 +142,20 @@ handles can take advantage of the single shared pool.
|
||||
.SH "GLOBAL CONSTANTS"
|
||||
There are a variety of constants that libcurl uses, mainly through its
|
||||
internal use of other libraries, which are too complicated for the
|
||||
library loader to set up. Therefore, a program must call a library
|
||||
library loader to set up. Therefore, a program must call a library
|
||||
function after the program is loaded and running to finish setting up
|
||||
the library code. For example, when libcurl is built for SSL
|
||||
the library code. For example, when libcurl is built for SSL
|
||||
capability via the GNU TLS library, there is an elaborate tree inside
|
||||
that library that describes the SSL protocol.
|
||||
|
||||
\fIcurl_global_init(3)\fP is the function that you must call. This may
|
||||
\fIcurl_global_init(3)\fP is the function that you must call. This may
|
||||
allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so
|
||||
the companion function \fIcurl_global_cleanup(3)\fP releases them.
|
||||
|
||||
The basic rule for constructing a program that uses libcurl is this: Call
|
||||
\fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately
|
||||
after the program starts, while it is still only one thread and before it uses
|
||||
libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the
|
||||
libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the
|
||||
program exits, when the program is again only one thread and after its last
|
||||
use of libcurl.
|
||||
|
||||
@ -169,34 +168,34 @@ It \fIis\fP required that the functions be called when no other thread
|
||||
in the program is running.
|
||||
|
||||
These global constant functions are \fInot thread safe\fP, so you must
|
||||
not call them when any other thread in the program is running. It
|
||||
not call them when any other thread in the program is running. It
|
||||
is not good enough that no other thread is using libcurl at the time,
|
||||
because these functions internally call similar functions of other
|
||||
libraries, and those functions are similarly thread-unsafe. You cannot
|
||||
libraries, and those functions are similarly thread-unsafe. You cannot
|
||||
generally know what these libraries are, or whether other threads are
|
||||
using them.
|
||||
|
||||
The global constant situation merits special consideration when the
|
||||
code you are writing to use libcurl is not the main program, but rather
|
||||
a modular piece of a program, e.g. another library. As a module,
|
||||
a modular piece of a program, e.g. another library. As a module,
|
||||
your code does not know about other parts of the program -- it does not
|
||||
know whether they use libcurl or not. And its code does not necessarily
|
||||
know whether they use libcurl or not. And its code does not necessarily
|
||||
run at the start and end of the whole program.
|
||||
|
||||
A module like this must have global constant functions of its own, just like
|
||||
\fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus
|
||||
\fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus
|
||||
has control at the beginning and end of the program and has a place to call
|
||||
the libcurl functions. Note that if multiple modules in the program use
|
||||
libcurl, they all will separately call the libcurl functions, and that is OK
|
||||
because only the first \fIcurl_global_init(3)\fP and the last
|
||||
\fIcurl_global_cleanup(3)\fP in a program change anything. (libcurl uses a
|
||||
reference count in static memory).
|
||||
the libcurl functions. If multiple modules in the program use libcurl, they
|
||||
all will separately call the libcurl functions, and that is OK because only
|
||||
the first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP
|
||||
in a program change anything. (libcurl uses a reference count in static
|
||||
memory).
|
||||
|
||||
In a C++ module, it is common to deal with the global constant situation by
|
||||
defining a special class that represents the global constant environment of
|
||||
the module. A program always has exactly one object of the class, in static
|
||||
storage. That way, the program automatically calls the constructor of the
|
||||
object as the program starts up and the destructor as it terminates. As the
|
||||
the module. A program always has exactly one object of the class, in static
|
||||
storage. That way, the program automatically calls the constructor of the
|
||||
object as the program starts up and the destructor as it terminates. As the
|
||||
author of this libcurl-using module, you can make the constructor call
|
||||
\fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP
|
||||
and satisfy libcurl's requirements without your user having to think about it.
|
||||
@ -205,25 +204,25 @@ initialize it from DllMain or a static initializer because Windows holds the
|
||||
loader lock during that time and it could cause a deadlock.)
|
||||
|
||||
\fIcurl_global_init(3)\fP has an argument that tells what particular parts of
|
||||
the global constant environment to set up. In order to successfully use any
|
||||
the global constant environment to set up. In order to successfully use any
|
||||
value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you
|
||||
must have specific knowledge of internal workings of libcurl and all other
|
||||
parts of the program of which it is part.
|
||||
|
||||
A special part of the global constant environment is the identity of the
|
||||
memory allocator. \fIcurl_global_init(3)\fP selects the system default memory
|
||||
memory allocator. \fIcurl_global_init(3)\fP selects the system default memory
|
||||
allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your
|
||||
own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a
|
||||
own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a
|
||||
modular program -- all modules in the program that might use libcurl would
|
||||
have to agree on one allocator.
|
||||
|
||||
There is a failsafe in libcurl that makes it usable in simple situations
|
||||
without you having to worry about the global constant environment at all:
|
||||
\fIcurl_easy_init(3)\fP sets up the environment itself if it has not been done
|
||||
yet. The resources it acquires to do so get released by the operating system
|
||||
yet. The resources it acquires to do so get released by the operating system
|
||||
automatically when the program exits.
|
||||
|
||||
This failsafe feature exists mainly for backward compatibility because
|
||||
there was a time when the global functions did not exist. Because it
|
||||
is sufficient only in the simplest of programs, it is not recommended
|
||||
for any program to rely on it.
|
||||
This failsafe feature exists mainly for backward compatibility because there
|
||||
was a time when the global functions did not exist. Because it is sufficient
|
||||
only in the simplest of programs, it is not recommended for any program to
|
||||
rely on it.
|
||||
|
@ -30,7 +30,7 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME_T, curl_off_t
|
||||
.SH DESCRIPTION
|
||||
Pass a pointer to a curl_off_t to receive the time, in microseconds, it took
|
||||
from the start until the SSL/SSH connect/handshake to the remote host was
|
||||
completed. This time is most often close to the
|
||||
completed. This time is most often close to the
|
||||
\fICURLINFO_PRETRANSFER_TIME_T(3)\fP time, except for cases such as HTTP
|
||||
pipelining where the pretransfer time can be delayed due to waits in line for
|
||||
the pipeline and more.
|
||||
|
Loading…
x
Reference in New Issue
Block a user