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).
## 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
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.
`--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.
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.
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
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,
## 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.
### 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.
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
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
# 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.
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.
- 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
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?
- 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.
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.
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.
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
## 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
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.
`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.
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:
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.
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:
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).
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
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.
`#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
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.
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.
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.
## 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.
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.
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.
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
## 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.
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`
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
## 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
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
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?
## 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
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.
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.
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.
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
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).
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.
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.
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,
---
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
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
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
---
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.
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
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
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.
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
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.
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.
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.
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"
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.
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.
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.
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
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.
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.
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.
---
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.
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
---
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.
.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.
.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
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
\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
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)"
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.
.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
.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
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
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
\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
.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
.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.
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
\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.
.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.
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
.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
\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
.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.
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
\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
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);
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.
.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
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.
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
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
.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
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.
.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
.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
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
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
.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
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.
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.
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
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
.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)"
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)"
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)"
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
.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
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.
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.
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
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.
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
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
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
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.
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
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".
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.
.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
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
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
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
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).
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.
\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.
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
.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.
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.
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.
.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.
projects / thirdparty / curl.git / commitdiff
