deliberately and carefully. If not, a reviewer must help the author to realize
the mistake.
-curl and libcurl are similarly very strict on not modifying existing
-behavior. API and ABI stability is not enough, the behavior should also remain
-intact as far as possible.
+curl and libcurl are similarly strict on not modifying existing behavior. API
+and ABI stability is not enough, the behavior should also remain intact as far
+as possible.
## Code style
Source code that has a common style is easier to read than code that uses
different styles in different places. It helps making the code feel like one
-single code base. Easy-to-read is a very important property of code and helps
+single code base. Easy-to-read is an important property of code and helps
making it easier to review when new things are added and it helps debugging
code when developers are trying to figure out why things go wrong. A unified
style is more important than individual contributors having their own personal
## Long lines
Source code in curl may never be wider than 79 columns and there are two
-reasons for maintaining this even in the modern era of very large and high
+reasons for maintaining this even in the modern era of large and high
resolution screens:
-1. Narrower columns are easier to read than very wide ones. There's a reason
+1. Narrower columns are easier to read than wide ones. There's a reason
newspapers have used columns for decades or centuries.
2. Narrower columns allow developers to easier show multiple pieces of code
## New block on a new line
-We never write multiple statements on the same source line, even for very
-short if() conditions.
+We never write multiple statements on the same source line, even for short
+if() conditions.
```c
if(a)
### Patch Against Recent Sources
Please try to get the latest available sources to make your patches against.
-It makes the lives of the developers so much easier. The very 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!
+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!
### Documentation
test case that verifies that it works as documented. If every submitter also
posts a few test cases, it won't end up as a heavy burden on a single person!
-If you don't have test cases or perhaps you have done something that is very
-hard to write tests for, do explain exactly how you have otherwise tested and
+If you don't have test cases or perhaps you have done something that is hard
+to write tests for, do explain exactly how you have otherwise tested and
verified your changes.
## Sharing Your Changes
submitter of a change, you are the owner of that change until it has been merged.
Respond on the list or on github about the change and answer questions and/or
-fix nits/flaws. This is very important. We will take lack of replies as a
-sign that you're not very anxious to get your patch accepted and we tend to
-simply drop such changes.
+fix nits/flaws. This is important. We will take lack of replies as a sign that
+you're not anxious to get your patch accepted and we tend to simply drop such
+changes.
### About pull requests
### Write Access to git Repository
-If you are a very frequent contributor, you may be given push access to the
-git repository and then you'll be able to push your changes straight into the
-git repo instead of sending changes as pull requests or by mail as patches.
+If you are a frequent contributor, you may be given push access to the git
+repository and then you'll be able to push your changes straight into the git
+repo instead of sending changes as pull requests or by mail as patches.
Just ask if this is what you'd want. You will be required to have posted
several high quality patches first, before you can be granted push access.
another tool that uses libcurl.
We do not add things to curl that other small and available tools already do
- very well at the side. curl's output can be piped into another program or
+ well at the side. curl's output can be piped into another program or
redirected to another file for the next program to interpret.
We focus on protocol related issues and improvements. If you want to do more
- magic with the supported protocols than curl currently does, chances are good
- we will agree. If you want to add more protocols, we may very well agree.
+ magic with the supported protocols than curl currently does, chances are
+ good we will agree. If you want to add more protocols, we may agree.
If you want someone else to do all the work while you wait for us to
- implement it for you, that is not a very friendly attitude. We spend a
+ implement it for you, that is not a friendly attitude. We spend a
considerable time already on maintaining and developing curl. In order to
get more out of us, you should consider trading in some of your time and
effort in return. Simply go to the GitHub repo which resides at
The reason why static libraries is much harder to deal with is that for them
we don't get any help but the script itself must know or check what more
libraries that are needed (with shared libraries, that dependency "chain" is
- handled automatically). This is a very error-prone process and one that also
+ handled automatically). This is a error-prone process and one that also
tends to vary over time depending on the release versions of the involved
components and may also differ between operating systems.
- For that reason, configure does very little attempts to actually figure this
- out and you are instead encouraged to set LIBS and LDFLAGS accordingly when
- you invoke configure, and point out the needed libraries and set the
- necessary flags yourself.
+ For that reason, configure does few attempts to actually figure this out and
+ you are instead encouraged to set LIBS and LDFLAGS accordingly when you
+ invoke configure, and point out the needed libraries and set the necessary
+ flags yourself.
2.2 Does curl work with other SSL libraries?
Also note that regular HTTP (using Basic authentication) and FTP passwords
are sent as cleartext across the network. All it takes for anyone to fetch
- them is to listen on the network. Eavesdropping is very easy. Use more secure
+ them is to listen on the network. Eavesdropping is easy. Use more secure
authentication methods (like Digest, Negotiate or even NTLM) or consider the
SSL-based alternatives HTTPS and FTPS.
4.16 My HTTP POST or PUT requests are slow!
libcurl makes all POST and PUT requests (except for POST requests with a
- very tiny request body) use the "Expect: 100-continue" header. This header
+ tiny request body) use the "Expect: 100-continue" header. This header
allows the server to deny the operation early so that libcurl can bail out
before having to send any data. This is useful in authentication
cases and others.
6. License Issues
- curl and libcurl are released under a MIT/X derivative license. The license is
- very liberal and should not impose a problem for your project. This section
- is just a brief summary for the cases we get the most questions. (Parts of
- this section was much enhanced by Bjorn Reese.)
+ curl and libcurl are released under a MIT/X derivative license. The license
+ is liberal and should not impose a problem for your project. This section is
+ just a brief summary for the cases we get the most questions. (Parts of this
+ section was much enhanced by Bjorn Reese.)
We are not lawyers and this is not legal advice. You should probably consult
one if you want true and accurate legal insights without our prejudice. Note
Some projects mark small issues as "beginner friendly", "bite-sized" or
similar. We don't do that in curl since such issues never linger around long
-enough. Simple issues get handled very fast.
+enough. Simple issues get handled fast.
If you're looking for a smaller or simpler task in the project to help out
with as an entry-point into the project, perhaps because you are a newcomer or
Cookies are set to the client with the Set-Cookie: header and are sent to
servers with the Cookie: header.
- For a very long time, the only spec explaining how to use cookies was the
+ For a long time, the only spec explaining how to use cookies was the
original [Netscape spec from 1994](https://curl.se/rfc/cookie_spec.html).
In 2011, [RFC6265](https://www.ietf.org/rfc/rfc6265.txt) was finally
I've made things simple. Almost every function in libcurl returns a CURLcode,
that must be `CURLE_OK` if everything is OK or otherwise a suitable error
- code as the `curl/curl.h` include file defines. The very spot that detects an
+ code as the `curl/curl.h` include file defines. The place that detects an
error must use the `Curl_failf()` function to set the human-readable error
description.
tests/memanalyze.pl dump
This now outputs a report on what resources that were allocated but never
- freed etc. This report is very fine for posting to the list!
+ freed etc. This report is fine for posting to the list!
If this doesn't produce any output, no leak was detected in libcurl. Then
the leak is mostly likely to be in your code.
1. The application can use whatever event system it likes as it gets info
from libcurl about what file descriptors libcurl waits for what action
- on. (The previous API returns `fd_sets` which is very
- `select()`-centric).
+ on. (The previous API returns `fd_sets` which is `select()`-centric).
2. When the application discovers action on a single socket, it calls
libcurl and informs that there was action on this particular socket and
get "good" random) so applications trying to avoid the init for
performance reasons would do wrong anyway
- D) never very carefully documented so all this mostly just happened to work
+ D) not documented carefully so all this mostly just happened to work
for some users
However, in spite of the problems with the feature, there were some users who
5.12 flaky Windows CI builds
We run many CI builds for each commit and PR on github, and especially a
- number of the Windows builds are very flaky. This means that we rarely get
- all CI builds go green and complete without errors. This is very unfortunate
- as it makes us sometimes miss actual build problems and it is surprising to
- newcomers to the project who (rightfully) don't expect this.
+ number of the Windows builds are flaky. This means that we rarely get all CI
+ builds go green and complete without errors. This is unfortunate as it makes
+ us sometimes miss actual build problems and it is surprising to newcomers to
+ the project who (rightfully) don't expect this.
See https://github.com/curl/curl/issues/6972
Each mailing list is targeted to a specific set of users and subjects,
please use the one or the ones that suit you the most.
- Each mailing list has hundreds up to thousands of readers, meaning that
- each mail sent will be received and read by a very large number of people.
- People from various cultures, regions, religions and continents.
+ Each mailing list has hundreds up to thousands of readers, meaning that each
+ mail sent will be received and read by a large number of people. People
+ from various cultures, regions, religions and continents.
1.2 Netiquette
send the email, your post will just be silently discarded.
If you posted for the first time to the mailing list, you first need to wait
- for an administrator to allow your email to go through (moderated). This normally
- happens very quickly but in case we're asleep, you may have to wait a few
- hours.
+ for an administrator to allow your email to go through (moderated). This
+ normally happens quickly but in case we're asleep, you may have to wait a
+ few hours.
Once your email goes through it is sent out to several hundred or even
- thousands of recipients. Your email may cover an area that not that many people
- know about or are interested in. Or possibly the person who knows about it
- is on vacation or under a very heavy work load right now. You may have to wait
- for a response and you should not expect to get a response at all, but
- hopefully you get an answer within a couple of days.
+ thousands of recipients. Your email may cover an area that not that many
+ people know about or are interested in. Or possibly the person who knows
+ about it is on vacation or under a heavy work load right now. You may have
+ to wait for a response and you should not expect to get a response at all,
+ but hopefully you get an answer within a couple of days.
You do yourself and all of us a service when you include as many details as
possible already in your first email. Mention your operating system and
curl --dump-header headers.txt curl.se
-Note that headers stored in a separate file can be very useful at a later time
-if you want curl to use cookies sent by the server. More about that in the
+Note that headers stored in a separate file can be useful at a later time if
+you want curl to use cookies sent by the server. More about that in the
cookies section.
## POST (HTTP)
curl -Y 3000 -y 60 www.far-away-site.com
-This can very well be used in combination with the overall time limit, so
-that the above operation must be completed in whole within 30 minutes:
+This can be used in combination with the overall time limit, so that the above
+operation must be completed in whole within 30 minutes:
curl -m 1800 -Y 3000 -y 60 www.far-away-site.com
## Extra Headers
-When using curl in your own very special programs, you may end up needing
-to pass on your own custom headers when getting a web page. You can do
-this by using the `-H` flag.
+When using curl in your own programs, you may end up needing to pass on your
+own custom headers when getting a web page. You can do this by using the `-H`
+flag.
Example, send the header `X-you-and-me: yes` to the server when getting a
page:
curl ftp://user:passwd@my.site.com/README
-But if you want the README file from the root directory of that very same
-site, you need to specify the absolute file name:
+But 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
`--netrc-optional` options). This is not restricted to just FTP, so curl can
use it for all protocols where authentication is used.
-A very simple `.netrc` file could look something like:
+A simple `.netrc` file could look something like:
machine curl.se login iamdaniel password mysecret
## TELNET
-The curl telnet support is basic and very easy to use. Curl passes all data
-passed to it on stdin to the remote server. Connect to a remote telnet server
-using a command line similar to:
+The curl telnet support is basic and easy to use. Curl passes all data passed
+to it on stdin to the remote server. Connect to a remote telnet server using a
+command line similar to:
curl telnet://remote.server.com
issues.
Who is on this list? There are a couple of criteria you must meet, and then we
-might ask you to join the list or you can ask to join it. It really isn't very
-formal. We basically only require that you have a long-term presence in the
-curl project and you have shown an understanding for the project and its way
-of working. You must've been around for a good while and you should have no
-plans in vanishing in the near future.
+might ask you to join the list or you can ask to join it. It really isn't a
+formal process. We basically only require that you have a long-term presence
+in the curl project and you have shown an understanding for the project and
+its way of working. You must've been around for a good while and you should
+have no plans in vanishing in the near future.
We do not make the list of participants public mostly because it tends to vary
somewhat over time and a list somewhere will only risk getting outdated.
CURLOPT_PINNEDPUBLICKEY does not consider the hashes of intermediate & root
certificates when comparing the pinned keys. Therefore it is not compatible
with "HTTP Public Key Pinning" as there also intermediate and root
- certificates can be pinned. This is very useful as it prevents webadmins from
+ certificates can be pinned. This is useful as it prevents webadmins from
"locking themselves out of their servers".
Adding this feature would make curls pinning 100% compatible to HPKP and
18.6 Option to make -Z merge lined based outputs on stdout
When a user requests multiple lined based files using -Z and sends them to
- stdout, curl will not "merge" and send complete lines fine but may very well
- send partial lines from several sources.
+ stdout, curl will not "merge" and send complete lines fine but may send
+ partial lines from several sources.
https://github.com/curl/curl/issues/5175
## The HTTP Protocol
- HTTP is the protocol used to fetch data from web servers. It is a very simple
+ HTTP is the protocol used to fetch data from web servers. It is a simple
protocol that is built upon TCP/IP. The protocol also allows information to
get sent to the server from the client using a few different methods, as will
be shown here.
your browser. That's generally a good thing when you want to be able to
bookmark that page with your given data, but it is an obvious disadvantage if
you entered secret information in one of the fields or if there are a large
- amount of fields creating a very long and unreadable URL.
+ amount of fields creating a long and unreadable URL.
The HTTP protocol then offers the POST method. This way the client sends the
data separated from the URL and thus you won't see any of it in the URL
address field.
- The form would look very similar to the previous one:
+ The form would look similar to the previous one:
```html
<form method="POST" action="junk.cgi">
## Hidden Fields
- A very common way for HTML based applications to pass state information
- between pages is to add hidden fields to the forms. Hidden fields are already
- filled in, they aren't displayed to the user and they get passed along just
- as all the other fields.
+ A common way for HTML based applications to pass state information between
+ pages is to add hidden fields to the forms. Hidden fields are already filled
+ in, they aren't displayed to the user and they get passed along just as all
+ the other fields.
A similar example form with one visible field, one hidden field and one
submit button could look like:
## Figure Out What A POST Looks Like
When you're about fill in a form and send to a server by using curl instead
- of a browser, you're of course very interested in sending a POST exactly the
- way your browser does.
+ of a browser, you're of course interested in sending a POST exactly the way
+ your browser does.
An easy way to get to see this, is to save the HTML page with the form on
your local disk, modify the 'method' to a GET, and press the submit button
able to watch your passwords if you pass them as plain command line
options. There are ways to circumvent this.
- It is worth noting that while this is how HTTP Authentication works, very
- many websites will not use this concept when they provide logins etc. See the
- Web Login chapter further below for more details on that.
+ It is worth noting that while this is how HTTP Authentication works, many
+ websites will not use this concept when they provide logins etc. See the Web
+ Login chapter further below for more details on that.
# More HTTP Headers
## User Agent
- Very similar to the referer field, all HTTP requests may set the User-Agent
+ Similar to the referer field, all HTTP requests may set the User-Agent
field. It names what user agent (client) that is being used. Many
applications use this information to decide how to display pages. Silly web
programmers try to make different pages for users of different browsers to
## Check what the browsers do
- A very good helper to make sure you do this right, is the web browsers'
- developers tools that let you view all headers you send and receive (even
- when using HTTPS).
+ A good helper to make sure you do this right, is the web browsers' developers
+ tools that let you view all headers you send and receive (even when using
+ HTTPS).
A more raw approach is to capture the HTTP traffic on the network with tools
such as Wireshark or tcpdump and check what headers that were sent and
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
-very unlikely that multiple parsers treat URLs the exact same way!
+unlikely that multiple parsers treat URLs the exact same way!
## Security
1. If you have an application that runs as or in a server application, getting
an unfiltered URL can trick your application to access a local resource
instead of a remote resource. Protecting yourself against localhost accesses
- is very hard when accepting user provided URLs.
+ is hard when accepting user provided URLs.
2. Such custom URLs can access other ports than you planned as port numbers
are part of the regular URL format. The combination of a local host and a
This option can be used multiple times.
-Users very often want to both read cookies from a file and write updated
-cookies back to a file, so using both --cookie and --cookie-jar in the same
-command line is common.
+Users often want to both read cookies from a file and write updated cookies
+back to a file, so using both --cookie and --cookie-jar in the same command
+line is common.
.RS
.IP multicwd
curl does a single CWD operation for each path part in the given URL. For deep
-hierarchies this means very many commands. This is how RFC 1738 says it should
+hierarchies this means many commands. This is how RFC 1738 says it should
be done. This is the default but the slowest behavior.
.IP nocwd
curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full
Example: --netrc-optional $URL
Added: 7.9.8
---
-Very similar to --netrc, but this option makes the .netrc usage **optional**
+Similar to --netrc, but this option makes the .netrc usage **optional**
and not mandatory as the --netrc option does.
neither world- nor group-readable). The environment variable "HOME" is used
to find the home directory.
-A quick and very simple example of how to setup a *.netrc* to allow curl
-to FTP to the machine host.domain.com with user name \&'myself' and password
-\&'secret' should look similar to:
+A quick and simple example of how to setup a *.netrc* to allow curl to FTP to
+the machine host.domain.com with user name \&'myself' and password \&'secret'
+should look similar to:
.B "machine host.domain.com login myself password secret"
descriptive information, to the given output file. Use "-" as filename to have
the output sent to stdout.
-This is very similar to --trace, but leaves out the hex part and only shows
-the ASCII part of the dump. It makes smaller output that might be easier to
-read for untrained humans.
+This is similar to --trace, but leaves out the hex part and only shows the
+ASCII part of the dump. It makes smaller output that might be easier to read
+for untrained humans.
This option is global and does not need to be specified for each use of
--next.
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.
When using Kerberos V5 with a Windows based server you should include the
Windows domain name in the user name, in order for the server to successfully
automatically on download, libcurl will continue to uncompress the entire
downloaded chunk and it will cache the data uncompressed. This has the side-
effect that if you download something that is compressed a lot, it can result
-in a very large data amount needing to be allocated to save the data during
-the pause. This said, you should probably consider not using paused receiving
-if you allow libcurl to uncompress data automatically.
+in a large data amount needing to be allocated to save the data during the
+pause. This said, you should probably consider not using paused receiving if
+you allow libcurl to uncompress data automatically.
.SH AVAILABILITY
Added in 7.18.0.
.SH RETURN VALUE
Added in 7.18.2.
.SH RETURN VALUE
On success, returns \fBCURLE_OK\fP and stores the number of bytes actually
-sent into \fB*n\fP. Note that this may very well be less than the amount you
-wanted to send.
+sent into \fB*n\fP. Note that this may be less than the amount you wanted to
+send.
On failure, returns the appropriate error code.
is retained. It is possible to unassign part's contents by setting
\fIdata\fP to NULL.
-Setting very large data is memory consuming: one might consider using
+Setting large data is memory consuming: one might consider using
\fIcurl_mime_data_cb(3)\fP in such a case.
.SH EXAMPLE
.nf
calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or
\fIcurl_easy_cleanup(3)\fP.
-The 'CURLMsg' struct is very simple and only contains very basic information.
-If more involved information is wanted, the particular "easy handle" is
-present in that struct and can be used in subsequent regular
-\fIcurl_easy_getinfo(3)\fP calls (or similar):
+The 'CURLMsg' struct is simple and only contains basic information. If more
+involved information is wanted, the particular "easy handle" is present in
+that struct and can be used in subsequent regular \fIcurl_easy_getinfo(3)\fP
+calls (or similar):
.nf
struct CURLMsg {
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 very 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.
+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.
When \fIrunning_handles\fP is set to zero (0) on the return of this function,
there is no longer any transfers in progress.
the simpler and older multi interface approach.
The timeout value returned in the long \fBtimeout\fP points to, is in number
-of milliseconds at this very moment. If 0, it means you should proceed
-immediately without waiting for anything. If it returns -1, there's no timeout
-at all set.
+of milliseconds at this moment. If 0, it means you should proceed immediately
+without waiting for anything. If it returns -1, there's no timeout at all set.
An application that uses the multi_socket API SHOULD NOT use this function, but
SHOULD instead use \fIcurl_multi_setopt(3)\fP and its
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
\fICURLOPT_URL(3)\fP is only option you really must set, as otherwise there
can be no transfer. Another commonly used option is \fICURLOPT_VERBOSE(3)\fP
-that will help you see what libcurl is doing under the hood, very useful when
-debugging for example. The \fIcurl_easy_setopt(3)\fP man page has a full index
-of the over 200 available options.
+that will help you see what libcurl is doing under the hood, which is useful
+when debugging for example. The \fIcurl_easy_setopt(3)\fP man page has a full
+index of the over 200 available options.
If you at any point would like to blank all previously set options for a
single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also
can be a misspelled protocol string or just a protocol libcurl has no code
for.
.IP "CURLE_FAILED_INIT (2)"
-Very early initialization code failed. This is likely to be an internal error
-or problem, or a resource problem where something fundamental couldn't get
-done at init time.
+Early initialization code failed. This is likely to be an internal error or
+problem, or a resource problem where something fundamental couldn't get done
+at init time.
.IP "CURLE_URL_MALFORMAT (3)"
The URL was not properly formatted.
.IP "CURLE_NOT_BUILT_IN (4)"
.BR curl_easy_strerror "(3), " curl_multi_strerror "(3), "
.BR curl_share_strerror "(3), " curl_url_strerror "(3), "
.BR CURLOPT_ERRORBUFFER "(3), " CURLOPT_VERBOSE "(3), "
-.BR CURLOPT_DEBUGFUNCTION "(3)"
\ No newline at end of file
+.BR CURLOPT_DEBUGFUNCTION "(3)"
should be aware.
.SH "Command Lines"
If you use a command line tool (such as curl) that uses libcurl, and you give
-options to the tool on the command line those options can very likely get read
-by other users of your system when they use 'ps' or other tools to list
-currently running processes.
+options to the tool on the command line those options can get read by other
+users of your system when they use 'ps' or other tools to list currently
+running processes.
To avoid these problems, never feed sensitive things to programs using command
line options. Write them to a protected file and use the \-K option to avoid
plain text anywhere.
.SH "Clear Text Passwords"
Many of the protocols libcurl supports send name and password unencrypted as
-clear text (HTTP Basic authentication, FTP, TELNET etc). It is very easy for
-anyone on your network or a network nearby yours to just fire up a network
-analyzer tool and eavesdrop on your passwords. Don't let the fact that HTTP
-Basic uses base64 encoded passwords fool you. They may not look readable at a
-first glance, but they very easily "deciphered" by anyone within seconds.
+clear text (HTTP Basic authentication, FTP, TELNET etc). It is easy for anyone
+on your network or a network nearby yours to just fire up a network analyzer
+tool and eavesdrop on your passwords. Don't let the fact that HTTP Basic uses
+base64 encoded passwords fool you. They may not look readable at a first
+glance, but they are easily "deciphered" by anyone within seconds.
To avoid this problem, use an authentication mechanism or other protocol that
doesn't let snoopers see your password: Digest, CRAM-MD5, Kerberos, SPNEGO or
hard to avoid.
.SH "Denial of Service"
A malicious server could cause libcurl to effectively hang by sending data
-very 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
+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.
.SH "Setuid applications using libcurl"
libcurl-using applications that set the 'setuid' bit to run with elevated or
modified rights also implicitly give that extra power to libcurl and this
-should only be done after very careful considerations.
+should only be done after careful considerations.
Giving setuid powers to the application means that libcurl can save files using
those new rights (if for example the `SSLKEYLOGFILE` environment variable is
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 2015 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 2015 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
former signal handler while another thread should still ignore it.
.IP "Name resolving"
\fBgethostby* functions and other system calls.\fP These functions, provided
-by your operating system, must be thread safe. It is very important that
-libcurl can find and use thread safe versions of these and other system calls,
-as otherwise it can't function fully thread safe. Some operating systems are
+by your operating system, must be thread safe. It is important that libcurl
+can find and use thread safe versions of these and other system calls, as
+otherwise it can't 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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
on a large amount of different operating systems and environments.
You program libcurl the same way on all platforms that libcurl runs on. There
-are only very few minor considerations that differ. If you just make sure to
-write your code portable enough, you may very well create yourself a very
-portable program. libcurl shouldn't stop you from that.
+are only a few minor details that differ. If you just make sure to write your
+code portable enough, you can create a portable program. libcurl shouldn't
+stop you from that.
.SH "Global Preparation"
The program must initialize some of the libcurl functionality globally. That
\fIcurl_global_init(3)\fP hasn't been called by the time
\fIcurl_easy_perform(3)\fP is called and if that is the case, libcurl runs the
function itself with a guessed bit pattern. Please note that depending solely
-on this is not considered nice nor very good.
+on this is not considered nice nor good.
When the program no longer uses libcurl, it should call
\fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It will
data your application receive by using the \fICURLOPT_DEBUGFUNCTION(3)\fP.
Getting some in-depth knowledge about the protocols involved is never wrong,
-and if you're trying to do funny things, you might very well understand
-libcurl and how to use it better if you study the appropriate RFC documents
-at least briefly.
+and if you're trying to do funny things, you might understand libcurl and how
+to use it better if you study the appropriate RFC documents at least briefly.
.SH "Upload Data to a Remote Site"
libcurl tries to keep a protocol independent approach to most transfers, thus
-uploading to a remote FTP site is very similar to uploading data to an HTTP
-server with a PUT request.
+uploading to a remote FTP site is similar to uploading data to an HTTP server
+with a PUT request.
Of course, first you either create an easy handle or you re-use one existing
one. Then you set the URL to operate on just like before. This is the remote
curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L);
-And a very basic example of how such a .netrc file may look like:
+And a basic example of how such a .netrc file may look like:
.nf
machine myhost.mydomain.com
restrictions on what can actually happen. A requested URL that might not be a
HTTP URL will be still be passed to the HTTP proxy to deliver back to
libcurl. This happens transparently, and an application may not need to
-know. I say "may", because at times it is very important to understand that
-all operations over an HTTP proxy use the HTTP protocol. For example, you
-can't invoke your own custom FTP commands or even proper FTP directory
-listings.
+know. I say "may", because at times it is important to understand that all
+operations over an HTTP proxy use the HTTP protocol. For example, you can't
+invoke your own custom FTP commands or even proper FTP directory listings.
.IP "Proxy Options"
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
-very 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).
Each easy handle will attempt to keep the last few connections alive for a
while in case they are to be used again. You can set the size of this "cache"
-with the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is very
-seldom any point in changing this value, and if you think of changing this it
-is often just a matter of thinking again.
+with the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is rarely
+any point in changing this value, and if you think of changing this it is
+often just a matter of thinking again.
To force your upcoming request to not use an already existing connection (it
will even close one first if there happens to be one alive to the same host
.IP CUSTOMREQUEST
If just changing the actual HTTP request keyword is what you want, like when
GET, HEAD or POST is not good enough for you, \fICURLOPT_CUSTOMREQUEST(3)\fP
-is there for you. It is very simple to use:
+is there for you. It is simple to use:
curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST");
.IP "HTTP Version"
All HTTP requests includes the version number to tell the server which version
-we support. libcurl speaks HTTP 1.1 by default. Some very old servers don't
-like getting 1.1-requests and when dealing with stubborn old things like that,
-you can tell libcurl to use 1.0 instead by doing something like this:
+we support. libcurl speaks HTTP 1.1 by default. Some old servers don't like
+getting 1.1-requests and when dealing with stubborn old things like that, you
+can tell libcurl to use 1.0 instead by doing something like this:
curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
you want to make, for example, your FTP transfers to behave differently.
Sending custom commands to an FTP server means that you need to send the
-commands exactly as the FTP server expects them (RFC959 is a good guide
-here), and you can only use commands that work on the control-connection
-alone. All kinds of commands that require data interchange and thus need
-a data-connection must be left to libcurl's own judgement. Also be aware
-that libcurl will do its very best to change directory to the target
-directory before doing any transfer, so if you change directory (with CWD
-or similar) you might confuse libcurl and then it might not attempt to
-transfer the file in the correct remote directory.
+commands exactly as the FTP server expects them (RFC959 is a good guide here),
+and you can only use commands that work on the control-connection alone. All
+kinds of commands that require data interchange and thus need a
+data-connection must be left to libcurl's own judgement. Also be aware that
+libcurl will do its best to change directory to the target directory before
+doing any transfer, so if you change directory (with CWD or similar) you might
+confuse libcurl and then it might not attempt to transfer the file in the
+correct remote directory.
A little example that deletes a given file before an operation:
When you then call select(), it'll return when one of the file handles signal
action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do
what it wants to do. Take note that libcurl does also feature some time-out
-code so we advise you to never use very long timeouts on select() before you
-call \fIcurl_multi_perform(3)\fP again. \fIcurl_multi_timeout(3)\fP is
-provided to help you get a suitable timeout period.
+code so we advise you to never use long timeouts on select() before you call
+\fIcurl_multi_perform(3)\fP again. \fIcurl_multi_timeout(3)\fP is provided to
+help you get a suitable timeout period.
Another precaution you should use: always call \fIcurl_multi_fdset(3)\fP
immediately before the select() call since the current set of file descriptors
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.SH DESCRIPTION
Pass a pointer to a double to receive the time, in seconds, it took from the
start until the SSL/SSH connect/handshake to the remote host was completed.
-This time is most often very near to the \fICURLINFO_PRETRANSFER_TIME(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.
+This time is most often close to the \fICURLINFO_PRETRANSFER_TIME(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.
When a redirect is followed, the time from each request is added together.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 2018 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 2018 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME_T, curl_off_t *timep);
.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 very near 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.
+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
+\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.
When a redirect is followed, the time from each request is added together.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
Pass in a pointer to a char pointer and get the last used effective HTTP
method.
-In cases when you've asked libcurl to follow redirects, the method may very
-well not be the same method the first request would use.
+In cases when you've asked libcurl to follow redirects, the method may not be
+the same method the first request would use.
The \fBmethodp\fP pointer will be NULL or pointing to private memory you MUST
NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.SH DESCRIPTION
Pass in a pointer to a char pointer and get the last used effective URL.
-In cases when you've asked libcurl to follow redirects, it may very well not
-be the same value you set with \fICURLOPT_URL(3)\fP.
+In cases when you've asked libcurl to follow redirects, it may not be the same
+value you set with \fICURLOPT_URL(3)\fP.
The \fBurlp\fP pointer will be NULL or pointing to private memory you MUST NOT
free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the URL a redirect \fIwould\fP
take you to if you would enable \fICURLOPT_FOLLOWLOCATION(3)\fP. This can come
-very handy if you think using the built-in libcurl redirect logic isn't good
-enough for you but you would still prefer to avoid implementing all the magic
-of figuring out the new URL.
+handy if you think using the built-in libcurl redirect logic isn't good enough
+for you but you would still prefer to avoid implementing all the magic of
+figuring out the new URL.
This URL is also set if the \fICURLOPT_MAXREDIRS(3)\fP limit prevented a
redirect to happen (since 7.54.1).
transfer is started.
libcurl will use this handle and its contents read-only and will not change
-its contents. An application can very well update the contents of the URL
-handle after a transfer is done and if the same handle is then used in a
-subsequent request the updated contents will then be used.
+its contents. An application can update the contents of the URL handle after a
+transfer is done and if the same handle is then used in a subsequent request
+the updated contents will then be used.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
- /* only reuse addresses for a very short time */
+ /* only reuse addresses for a short time */
curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L);
ret = curl_easy_perform(curl);
\fBmust be at least CURL_ERROR_SIZE bytes big\fP.
You must keep the associated buffer available until libcurl no longer needs
-it. Failing to do so will cause very odd behavior or even crashes. libcurl
-will need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same
-option again to use a different pointer.
+it. Failing to do so will cause odd behavior or even crashes. libcurl will
+need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same option
+again to use a different pointer.
Do not rely on the contents of the buffer unless an error code was returned.
Since 7.60.0 libcurl will initialize the contents of the error buffer to an
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
will make libcurl send the same method again.
For users who think the existing location following is too naive, too simple
-or just lacks features, it is very easy to instead implement your own redirect
+or just lacks features, it is easy to instead implement your own redirect
follow logic with the use of \fIcurl_easy_getinfo(3)\fP's
\fICURLINFO_REDIRECT_URL(3)\fP option instead of using
\fICURLOPT_FOLLOWLOCATION(3)\fP.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
This function gets called by libcurl as soon as it has received header
data. The header callback will be called once for each header and only
-complete header lines are passed on to the callback. Parsing headers is very
-easy using this. \fIbuffer\fP points to the delivered data, and the size of
-that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that the
-header line is null-terminated!
+complete header lines are passed on to the callback. Parsing headers is easy
+to do using this callback. \fIbuffer\fP points to the delivered data, and the
+size of that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that
+the header line is null-terminated!
The pointer named \fIuserdata\fP is the one you set with the
\fICURLOPT_HEADERDATA(3)\fP option.
.SH DESCRIPTION
Pass a pointer to a linked list of \fIaliases\fP to be treated as valid HTTP
200 responses. Some servers respond with a custom header response line. For
-example, SHOUTcast servers respond with "ICY 200 OK". Also some very old
-Icecast 1.3.x servers will respond like that for certain user agent headers or
-in absence of such. By including this string in your list of aliases,
-the response will be treated as a valid HTTP header line such as
-"HTTP/1.0 200 OK".
+example, SHOUTcast servers respond with "ICY 200 OK". Also some old Icecast
+1.3.x servers will respond like that for certain user agent headers or in
+absence of such. By including this string in your list of aliases, the
+response will be treated as a valid HTTP header line such as "HTTP/1.0 200
+OK".
The linked list should be a fully valid list of struct curl_slist structs, and
be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and
The "connection cache" that holds previously used connections. When a new
request is to be done, it will consider any connection that matches for
-reuse. The \fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying
-very old connections for reuse, since old connections have a high risk of not
+reuse. The \fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too
+old connections for reuse, since old connections have a high risk of not
working and thus trying them is a performance loss and sometimes service loss
due to the difficulties to figure out the situation. If a connection is found
in the cache that is older than this set \fImaxage\fP, it will instead be
libcurl features a connection cache that holds previously used connections.
When a new request is to be done, it will consider any connection that matches
for reuse. The \fICURLOPT_MAXLIFETIME_CONN(3)\fP limit prevents libcurl from
-trying very old connections for reuse. This can be used for client-side load
+trying too old connections for reuse. This can be used for client-side load
balancing. If a connection is found in the cache that is older than this set
\fImaxlifetime\fP, it will instead be closed once any in-progress transfers
complete.
When you set a host name to use, do not assume that there's any particular
single port number used widely for proxies. Specify it!
.SH PROTOCOLS
-All except file://. Note that some protocols don't do very well over proxy.
+All except file://. Note that some protocols don't work well over proxy.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if you can.
This function gets called by libcurl instead of its internal equivalent with a
-frequent interval. While data is being transferred it will be called very
+frequent interval. While data is being transferred it will be called
frequently, and during slow periods like when nothing is being transferred it
can slow down to about one call per second.
When you set a host name to use, do not assume that there's any particular
single port number used widely for proxies. Specify it!
.SH PROTOCOLS
-All except file://. Note that some protocols don't do very well over proxy.
+All except file://. Note that some protocols don't work well over proxy.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.IP CURLPROXY_HTTPS
HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS)
.IP CURLPROXY_HTTP_1_0
-HTTP 1.0 Proxy. This is very similar to CURLPROXY_HTTP except it uses HTTP/1.0
-for any CONNECT tunnelling. It does not change the HTTP version of the actual
-HTTP requests, controlled by \fICURLOPT_HTTP_VERSION(3)\fP.
+HTTP 1.0 Proxy. This is similar to CURLPROXY_HTTP except it uses HTTP/1.0 for
+any CONNECT tunnelling. It does not change the HTTP version of the actual HTTP
+requests, controlled by \fICURLOPT_HTTP_VERSION(3)\fP.
.IP CURLPROXY_SOCKS4
SOCKS4 Proxy.
.IP CURLPROXY_SOCKS4A
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
If you have an application that runs as or in a server application, getting an
unfiltered URL can easily trick your application to access a local resource
-instead of a remote. Protecting yourself against localhost accesses is very
-hard when accepting user provided URLs.
+instead of a remote. Protecting yourself against localhost accesses is hard
+when accepting user provided URLs.
Such custom URLs can also access other ports than you planned as port numbers
are part of the regular URL format. The combination of a local host and a
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_VERBOSE, long onoff);
.SH DESCRIPTION
Set the \fIonoff\fP parameter to 1 to make the library display a lot of
-verbose information about its operations on this \fIhandle\fP. Very useful for
+verbose information about its operations on this \fIhandle\fP. Useful for
libcurl and/or protocol debugging and understanding. The verbose information
will be sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP.
shown above.
This function gets called by libcurl instead of its internal equivalent with a
-frequent interval. While data is being transferred it will be called very
+frequent interval. While data is being transferred it will be called
frequently, and during slow periods like when nothing is being transferred it
can slow down to about one call per second.
projects / thirdparty / curl.git / commitdiff
