git clone https://github.com/curl/curl.git
- (you'll get a directory named curl created, filled with the source code)
+ (you will get a directory named curl created, filled with the source code)
SECURITY PROBLEMS
git clone https://github.com/curl/curl.git
-(you'll get a directory named curl created, filled with the source code)
+(you will get a directory named curl created, filled with the source code)
## Security problems
# Who is eligible for a reward?
Everyone and anyone who reports a security problem in a released curl version
-that hasn't already been reported can ask for a bounty.
+that has not already been reported can ask for a bounty.
Vulnerabilities in features that are off by default and documented as
experimental are not eligible for a reward.
## Where to report
- If you can't fix a bug yourself and submit a fix for it, try to report an as
+ If you cannot fix a bug yourself and submit a fix for it, try to report an as
detailed report as possible to a curl mailing list to allow one of us to have
a go at a solution. You can optionally also submit your problem in [curl's
bug tracking system](https://github.com/curl/curl/issues).
- your operating system's name and version number
- - what version of curl you're using (`curl -V` is fine)
+ - what version of curl you are using (`curl -V` is fine)
- versions of the used libraries that libcurl is built to use
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 can't do much with it. Instead, we ask you to get a stack
+ 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
## libcurl problems
- When you've written your own application with libcurl to perform transfers,
+ When you have written your own application with libcurl to perform transfers,
it is even more important to be specific and detailed when reporting bugs.
Tell us the libcurl version and your operating system. Tell us the name and
version of all relevant sub-components like for example the SSL library
- you're using and what name resolving your libcurl uses. If you use SFTP or
+ you are using and what name resolving your libcurl uses. If you use SFTP or
SCP, the libssh2 version is relevant etc.
Showing us a real source code example repeating your problem is the best way
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've experienced and how to repeat a
+ 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.
## How to get a stack trace
First, you must make sure that you compile all sources with `-g` and that you
- don't 'strip' the final executable. Try to avoid optimizing the code as well,
+ do not 'strip' the final executable. Try to avoid optimizing the code as well,
remove `-O`, `-O2` etc from the compiler options.
Run the program until it cores.
The list that is presented is the stack trace. If everything worked, it is
supposed to contain the chain of functions that were called when curl
- crashed. Include the stack trace with your detailed bug report. It'll help a
+ crashed. Include the stack trace with your detailed bug report. it will help a
lot.
## Bugs in libcurl bindings
The developers in the curl project do not have bandwidth or energy enough to
maintain several branches or to spend much time on hunting down problems in
- old versions when chances are we already fixed them or at least that they've
+ old versions when chances are we already fixed them or at least that they have
changed nature and appearance in later versions.
When you experience a problem and want to report it, you really SHOULD
- include the version number of the curl you're using when you experience the
- issue. If that version number shows us that you're using an out-of-date curl,
+ include the version number of the curl you are using when you experience the
+ issue. If that version number shows us that you are using an out-of-date curl,
you should also try out a modern curl version to see if the problem persists
or how/if it has changed in appearance.
experimental build or similar, to get this confirmed or not.
At times people insist that they cannot upgrade to a modern curl version, but
- instead they "just want the bug fixed". That's fine, just don't count on us
- spending many cycles on trying to identify which single commit, if that's
- even possible, that at some point in the past fixed the problem you're now
+ instead they "just want the bug fixed". That is fine, just do not count on us
+ spending many cycles on trying to identify which single commit, if that is
+ even possible, that at some point in the past fixed the problem you are now
experiencing.
Security wise, it is almost always a bad idea to lag behind the current curl
When a new issue is posted in the issue tracker or on the mailing list, the
team of developers first need to see the report. Maybe they took the day off,
- maybe they're off in the woods hunting. Have patience. Allow at least a few
+ maybe they are off in the woods hunting. Have patience. Allow at least a few
days before expecting someone to have responded.
In the issue tracker you can expect that some labels will be set on the issue
## First response
- If your issue/bug report wasn't perfect at once (and few are), chances are
+ If your issue/bug report was not perfect at once (and few are), chances are
that someone will ask follow-up questions. Which version did you use? Which
options did you use? How often does the problem occur? How can we reproduce
this problem? Which protocols does it involve? Or perhaps much more specific
## Not reproducible
- For problems that we can't reproduce and can't understand even after having
+ For problems that we cannot reproduce and cannot understand even after having
gotten all the info we need and having studied the source code over again,
are really hard to solve so then we may require further work from you who
actually see or experience the problem.
## Unresponsive
- If the problem haven't been understood or reproduced, and there's nobody
+ 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.
- Unimportant issues will be closed as inactive sooner or later as they can't
+ 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
than two weeks but may extend months.
Bugs that are filed and are understood can unfortunately end up in the
"nobody cares enough about it to work on it" category. Such bugs are
- perfectly valid problems that *should* get fixed but apparently aren't. We
+ perfectly valid problems that *should* get fixed but apparently are not. We
try to mark such bugs as `KNOWN_BUGS material` after a time of inactivity and
if no activity is noticed after yet some time those bugs are added to the
`KNOWN_BUGS` document and are closed in the issue tracker.
## `KNOWN_BUGS`
This is a list of known bugs. Bugs we know exist and that have been pointed
- out but that haven't yet been fixed. The reasons for why they haven't been
+ out but that have not yet been fixed. The reasons for why they have not been
fixed can involve anything really, but the primary reason is that nobody has
considered these problems to be important enough to spend the necessary time
and effort to have them fixed.
## `TODO`
- Issues that are filed or reported that aren't really bugs but more missing
+ Issues that are filed or reported that are not really bugs but more missing
features or ideas for future improvements and so on are marked as
'enhancement' or 'feature-request' and will be added to the `TODO` document
- and the issues are closed. We don't keep TODO items open in the issue
+ and the issues are closed. We do not keep TODO items open in the issue
tracker.
The `TODO` document is full of ideas and suggestions of what we can add or
- fix one day. You're always encouraged and free to grab one of those items and
+ fix one day. you are always encouraged and free to grab one of those items and
take up a discussion with the curl development team on how that could be
implemented or provided in the project so that you can work on ticking it odd
that document.
The [issue and pull request trackers](https://github.com/curl/curl) only
holds "active" entries open (using a non-precise definition of what active
- actually is, but they're at least not completely dead). Those that are
+ actually is, but they are at least not completely dead). Those that are
abandoned or in other ways dormant will be closed and sometimes added to
`TODO` and `KNOWN_BUGS` instead.
- `COPYRIGHT`: the file is missing a copyright statement!
-- `CPPCOMMENTS`: `//` comment detected, that's not C89 compliant
+- `CPPCOMMENTS`: `//` comment detected, that is not C89 compliant
- `DOBRACE`: only use one space after do before open brace
- `TYPEDEFSTRUCT`: we frown upon (most) typedefed structs
- `UNUSEDIGNORE`: a checksrc inlined warning ignore was asked for but not used,
- that's an ignore that should be removed or changed to get used.
+ that is an ignore that should be removed or changed to get used.
### Extended warnings
Currently there is one extended warning which can be enabled:
-- `COPYRIGHTYEAR`: the current changeset hasn't updated the copyright year in
+- `COPYRIGHTYEAR`: the current changeset has not updated the copyright year in
the source file
## Ignore certain warnings
/* !checksrc! enable LONGLINE */
-If the enabling isn't performed before the end of the file, it will be enabled
+If the enabling is not performed before the end of the file, it will be enabled
automatically for the next file.
You can also opt to ignore just N violations so that if you have a single long
-line you just can't shorten and is agreed to be fine anyway:
+line you just cannot shorten and is agreed to be fine anyway:
/* !checksrc! disable LONGLINE 1 */
### Directory wide ignore patterns
-This is a method we've transitioned away from. Use inline ignores as far as
+This is a method we have transitioned away from. Use inline ignores as far as
possible.
Make a `checksrc.skip` file in the directory of the source code with the
## Code style
Most code style nits are detected by checksrc but not all. Only leave remarks
-on style deviation once checksrc doesn't find anymore.
+on style deviation once checksrc does not find anymore.
Minor nits from fresh submitters can also be handled by the maintainer when
-merging, in case it seems like the submitter isn't clear on what to do. We
+merging, in case it seems like the submitter is not clear on what to do. We
want to make the process fun and exciting for new contributors.
## Encourage consistency
not OK. A code review must also verify that the submitted documentation update
matches the code submission.
-English isn't everyone's first language, be mindful of this and help the
+English is not everyone's first language, be mindful of this and help the
submitter improve the text if it needs a rewrite to read better.
-## Code shouldn't be hard to understand
+## Code should not be hard to understand
Source code should be written to maximize readability and be easy to
understand.
-## Functions shouldn't be large
+## Functions should not be large
A single function should never be large as that makes it hard to follow and
understand all the exit points and state changes. Some existing functions in
## Naming
Try using a non-confusing naming scheme for your new functions and variable
-names. It doesn't necessarily have to mean that you should use the same as in
+names. It does not necessarily have to mean that you should use the same as in
other places of the code, just that the names should be logical,
-understandable and be named according to what they're used for. File-local
+understandable and be named according to what they are used for. File-local
functions should be made static. We like lower case names.
See the [INTERNALS](https://curl.se/dev/internals.html#symbols) document on
## Comments
-Since we write C89 code, **//** comments are not allowed. They weren't
+Since we write C89 code, **//** comments are not allowed. They were not
introduced in the C standard until C99. We use only __/* comments */__.
```c
(handle->set.httpversion != CURL_HTTP_VERSION_1_0) &&
(handle->set.httpreq == HTTPREQ_GET ||
handle->set.httpreq == HTTPREQ_HEAD))
- /* didn't ask for HTTP/1.0 and a GET or HEAD */
+ /* did not ask for HTTP/1.0 and a GET or HEAD */
return TRUE;
```
We also hang out on IRC in #curl on libera.chat
-If you're at all interested in the code side of things, consider clicking
+If you are at all interested in the code side of things, consider clicking
'watch' on the [curl repo on GitHub](https://github.com/curl/curl) to be
notified of pull requests and new issues posted there.
otherwise.
If you add a larger piece of code, you can opt to make that file or set of
-files to use a different license as long as they don't enforce any changes to
+files to use a different license as long as they do not enforce any changes to
the rest of the package and they make sense. Such "separate parts" can not be
-GPL licensed (as we don't want copyleft to affect users of libcurl) but they
+GPL licensed (as we do not want copyleft to affect users of libcurl) but they
must use "GPL compatible" licenses (as we want to allow users to use libcurl
properly in GPL licensed environments).
[CODE_STYLE](https://curl.se/dev/code-style.html) already established in
the project. Consistent style makes code easier to read and mistakes less
likely to happen. Run `make checksrc` before you submit anything, to make sure
-you follow the basic style. That script doesn't verify everything, but if it
+you follow the basic style. That script does not verify everything, but if it
complains you know you have work to do.
### Non-clobbering All Over
-When you write new functionality or fix bugs, it is important that you don't
+When you write new functionality or fix bugs, it is important that you do not
fiddle all over the source files and functions. Remember that it is likely
that other people have done changes in the same source files as you have and
possibly even in the same functions. If you bring completely new
### Write Separate Changes
It is annoying when you get a huge patch from someone that is said to fix 511
-odd problems, but discussions and opinions don't agree with 510 of them - or
+odd problems, but discussions and opinions do not agree with 510 of them - or
509 of them were already fixed in a different way. Then the person merging
this change needs to extract the single interesting patch from somewhere
within the huge pile of source, and that creates a lot of extra work.
### Test Cases
Since the introduction of the test suite, we can quickly verify that the main
-features are working as they're supposed to. To maintain this situation and
+features are working as they are supposed to. To maintain this situation and
improve it, all new features and functions that are added need to be tested
in the test suite. Every feature that is added should get at least one valid
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!
+posts a few test cases, it will not 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 hard
+If you do not 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.
Respond on the list or on github about the change and answer questions and/or
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
+you are not anxious to get your patch accepted and we tend to simply drop such
changes.
### About pull requests
- ... the test suite still runs 100% fine
- ... the release tarball (the "dist") still works
- ... it builds fine in-tree as well as out-of-tree
- - ... code coverage doesn't shrink drastically
+ - ... code coverage does not shrink drastically
If the pull-request fails one of these tests, it will show up as a red X and
-you are expected to fix the problem. If you don't understand when the issue is
+you are expected to fix the problem. If you do not understand when the issue is
or have other problems to fix the complaint, just ask and other project
members will likely be able to help out.
Make the patch against as recent source versions as possible.
-If you've followed the tips in this document and your patch still hasn't been
+If you have followed the tips in this document and your patch still has not been
incorporated or responded to after some weeks, consider resubmitting it to the
list or better yet: change it to a pull request.
The first line is a succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- - don't capitalize first letter
+ - do not capitalize first letter
- no dot (.) at the end
The `[area]` in the first line can be `http2`, `cookies`, `openssl` or
similar. There's no fixed list to select from but using the same "area" as
other related changes could make sense.
-Don't forget to use commit --author="" if you commit someone else's work, and
+Do not forget to use commit --author="" if you commit someone else's work, and
make sure that you have your own user and email setup correctly in git before
you commit
### Write Access to git Repository
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
+repository and then you will 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
+Just ask if this is what you would want. You will be required to have posted
several high quality patches first, before you can be granted push access.
### How To Make a Patch with git
As usual, group your commits so that you commit all changes at once that
constitute a logical change.
-Once you have done all your commits and you're happy with what you see, you
+Once you have done all your commits and you are happy with what you see, you
can make patches out of your changes that are suitable for mailing:
git format-patch remotes/origin/master
email the
[curl-library mailing list](https://lists.haxx.se/listinfo/curl-library)
as soon as possible and explain to us why this is a problem for you and
-how your use case can't be satisfied properly using a workaround.
+how your use case cannot be satisfied properly using a workaround.
## Past removals
void Curl_dyn_init(struct dynbuf *s, size_t toobig);
```
-This inits a struct to use for dynbuf and it can't fail. The `toobig` value
+This inits a struct to use for dynbuf and it cannot fail. The `toobig` value
**must** be set to the maximum size we allow this buffer instance to grow to.
The functions below will return `CURLE_OUT_OF_MEMORY` when hitting this limit.
1.8 I have a problem who do I mail?
1.9 Where do I buy commercial support for curl?
1.10 How many are using curl?
- 1.11 Why don't you update ca-bundle.crt
+ 1.11 Why do you not update ca-bundle.crt
1.12 I have a problem who can I chat with?
1.13 curl's ECCN number?
1.14 How do I submit my patch?
3. Usage Problems
3.1 curl: (1) SSL is disabled, https: not supported
3.2 How do I tell curl to resume a transfer?
- 3.3 Why doesn't my posting using -F work?
+ 3.3 Why does my posting using -F not work?
3.4 How do I tell curl to run custom FTP commands?
3.5 How can I disable the Accept: */* header?
3.6 Does curl support ASP, XML, XHTML or HTML version Y?
4. Running Problems
4.2 Why do I get problems when I use & or % in the URL?
4.3 How can I use {, }, [ or ] to specify multiple URLs?
- 4.4 Why do I get downloaded data even though the web page doesn't exist?
+ 4.4 Why do I get downloaded data even though the web page does not exist?
4.5 Why do I get return code XXX from a HTTP server?
4.5.1 "400 Bad Request"
4.5.2 "401 Unauthorized"
4.6 Can you tell me what error code 142 means?
4.7 How do I keep user names and passwords secret in curl command lines?
4.8 I found a bug!
- 4.9 curl can't authenticate to the server that requires NTLM?
- 4.10 My HTTP request using HEAD, PUT or DELETE doesn't work!
+ 4.9 curl cannot authenticate to the server that requires NTLM?
+ 4.10 My HTTP request using HEAD, PUT or DELETE does not work!
4.11 Why do my HTTP range requests return the full document?
4.12 Why do I get "certificate verify failed" ?
4.13 Why is curl -R on Windows one hour off?
4.14 Redirects work in browser but not with curl!
- 4.15 FTPS doesn't work
+ 4.15 FTPS does not work
4.16 My HTTP POST or PUT requests are slow!
4.17 Non-functional connect timeouts on Windows
4.18 file:// URLs containing drive letters (Windows, NetWare)
- 4.19 Why doesn't curl return an error when the network cable is unplugged?
- 4.20 curl doesn't return error for HTTP non-200 responses!
+ 4.19 Why does not curl return an error when the network cable is unplugged?
+ 4.20 curl does not return error for HTTP non-200 responses!
5. libcurl Issues
5.1 Is libcurl thread-safe?
Project cURL is entirely free and open. We do this voluntarily, mostly in
our spare time. Companies may pay individual developers to work on curl,
- but that's up to each company and developer. This is not controlled by nor
+ but that is up to each company and developer. This is not controlled by nor
supervised in any way by the curl project.
We get help from companies. Haxx provides website, bandwidth, mailing lists
It is impossible to tell.
- We don't know how many users that knowingly have installed and use curl.
+ We do not know how many users that knowingly have installed and use curl.
- We don't know how many users that use curl without knowing that they are in
+ We do not know how many users that use curl without knowing that they are in
fact using it.
- We don't know how many users that downloaded or installed curl and then
+ We do not know how many users that downloaded or installed curl and then
never use it.
In 2020, we estimate that curl runs in roughly ten billion installations
world wide.
- 1.11 Why don't you update ca-bundle.crt
+ 1.11 Why do you not update ca-bundle.crt
- In the cURL project we've decided not to attempt to keep this file updated
+ In the cURL project we have decided not to attempt to keep this file updated
(or even present) since deciding what to add to a ca cert bundle is an
- undertaking we've not been ready to accept, and the one we can get from
+ undertaking we have not been ready to accept, and the one we can get from
Mozilla is perfectly fine so there's no need to duplicate that work.
Today, with many services performed over HTTPS, every operating system
1.12 I have a problem who can I chat with?
There's a bunch of friendly people hanging out in the #curl channel on the
- IRC network libera.chat. If you're polite and nice, chances are good that
+ IRC network libera.chat. If you are polite and nice, chances are good that
you can get -- or provide -- help instantly.
1.13 curl's ECCN number?
1.14 How do I submit my patch?
We strongly encourage you to submit changes and improvements directly as
- "pull requests" on github: https://github.com/curl/curl/pulls
+ "pull requests" on GitHub: https://github.com/curl/curl/pulls
- If you for any reason can't or won't deal with github, send your patch to
- the curl-library mailing list. We're many subscribers there and there are
+ If you for any reason cannot or will not deal with GitHub, send your patch to
+ the curl-library mailing list. We are many subscribers there and there are
lots of people who can review patches, comment on them and "receive" them
properly.
configure checks for.
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
+ we do not 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 error-prone process and one that also
tends to vary over time depending on the release versions of the involved
3.1 curl: (1) SSL is disabled, https: not supported
If you get this output when trying to get anything from a https:// server,
- it means that the instance of curl/libcurl that you're using was built
+ it means that the instance of curl/libcurl that you are using was built
without support for this protocol.
- This could've happened if the configure script that was run at build time
- couldn't find all libs and include files curl requires for SSL to work. If
+ This could have happened if the configure script that was run at build time
+ could not find all libs and include files curl requires for SSL to work. If
the configure script fails to find them, curl is simply built without SSL
support.
To get the https:// support into a curl that was previously built but that
reports that https:// is not supported, you should dig through the document
- and logs and check out why the configure script doesn't find the SSL libs
+ and logs and check out why the configure script does not find the SSL libs
and/or include files.
- Also, check out the other paragraph in this FAQ labeled "configure doesn't
+ Also, check out the other paragraph in this FAQ labeled "configure does not
find OpenSSL even when it is installed".
3.2 How do I tell curl to resume a transfer?
curl supports resumed transfers both ways on both FTP and HTTP.
Try the -C option.
- 3.3 Why doesn't my posting using -F work?
+ 3.3 Why does my posting using -F not work?
- You can't arbitrarily use -F or -d, the choice between -F or -d depends on
+ You cannot arbitrarily use -F or -d, the choice between -F or -d depends on
the HTTP operation you need curl to do and what the web server that will
receive your post expects.
- If the form you're trying to submit uses the type 'multipart/form-data',
+ If the form you are trying to submit uses the type 'multipart/form-data',
then and only then you must use the -F type. In all the most common cases,
you should use -d which then causes a posting with the type
'application/x-www-form-urlencoded'.
This is described in some detail in the MANUAL and TheArtOfHttpScripting
- documents, and if you don't understand it the first time, read it again
+ documents, and if you do not understand it the first time, read it again
before you post questions about this to the mailing list. Also, try reading
through the mailing list archives for old postings and questions regarding
this.
You can tell curl to perform optional commands both before and/or after a
file transfer. Study the -Q/--quote option.
- Since curl is used for file transfers, you don't normally use curl to
+ Since curl is used for file transfers, you do not normally use curl to
perform FTP commands without transferring anything. Therefore you must
always specify a URL to transfer to/from even when doing custom FTP
commands, or use -I which implies the "no body" option sent to libcurl.
3.6 Does curl support ASP, XML, XHTML or HTML version Y?
- To curl, all contents are alike. It doesn't matter how the page was
+ To curl, all contents are alike. It does not matter how the page was
generated. It may be ASP, PHP, Perl, shell-script, SSI or plain HTML
- files. There's no difference to curl and it doesn't even know what kind of
+ files. There's no difference to curl and it does not even know what kind of
language that generated the page.
See also item 3.14 regarding javascript.
3.8 How do I tell curl to follow HTTP redirects?
curl does not follow so-called redirects by default. The Location: header
- that informs the client about this is only interpreted if you're using the
+ that informs the client about this is only interpreted if you are using the
-L/--location option. As in:
curl -L http://redirector.com
All the various bindings to libcurl are made by other projects and people,
outside of the cURL project. The cURL project itself only produces libcurl
- with its plain C API. If you don't find anywhere else to ask you can ask
+ with its plain C API. If you do not find anywhere else to ask you can ask
about bindings on the curl-library list too, but be prepared that people on
that list may not know anything about bindings.
XML-RPC are all such ones. You can use -X to set custom requests and -H to
set custom headers (or replace internally generated ones).
- Using libcurl is of course just as good and you'd just use the proper
+ Using libcurl is of course just as good and you would just use the proper
library options to do the same.
3.11 How do I POST with a different Content-Type?
Because when you use a HTTP proxy, the protocol spoken on the network will
be HTTP, even if you specify a FTP URL. This effectively means that you
- normally can't use FTP-specific features such as FTP upload and FTP quote
+ normally cannot use FTP-specific features such as FTP upload and FTP quote
etc.
There is one exception to this rule, and that is if you can "tunnel through"
Exactly what kind of quotes and how to do this is entirely up to the shell
or command line interpreter that you are using. For most unix shells, you
can more or less pick either single (') or double (") quotes. For
- Windows/DOS prompts I believe you're forced to use double (") quotes.
+ Windows/DOS prompts I believe you are forced to use double (") quotes.
Please study the documentation for your particular environment. Examples in
the curl docs will use a mix of both of these as shown above. You must
.pac files are a netscape invention and are sometimes used by organizations
to allow them to differentiate which proxies to use. The .pac contents is
just a Javascript program that gets invoked by the browser and that returns
- the name of the proxy to connect to. Since curl doesn't support Javascript,
- it can't support .pac proxy configuration either.
+ the name of the proxy to connect to. Since curl does not support Javascript,
+ it cannot support .pac proxy configuration either.
Some workarounds usually suggested to overcome this Javascript dependency:
The server you communicate with may require that you can provide this in
order to prove that you actually are who you claim to be. If the server
- doesn't require this, you don't need a client certificate.
+ does not require this, you do not need a client certificate.
A client certificate is always used together with a private key, and the
private key has a pass phrase that protects it.
3.19 How do I get HTTP from a host using a specific IP address?
- For example, you may be trying out a website installation that isn't yet in
+ For example, you may be trying out a website installation that is not yet in
the DNS. Or you have a site using multiple IP addresses for a given host
name and you want to address a specific one out of the set.
3.20 How to SFTP from my user's home directory?
Contrary to how FTP works, SFTP and SCP URLs specify the exact directory to
- work with. It means that if you don't specify that you want the user's home
+ work with. It means that if you do not specify that you want the user's home
directory, you get the actual root directory.
To specify a file in your user's home directory, you need to use the correct
When passing on a URL to curl to use, it may respond that the particular
protocol is not supported or disabled. The particular way this error message
- is phrased is because curl doesn't make a distinction internally of whether
+ is phrased is because curl does not make a distinction internally of whether
a particular protocol is not supported (i.e. never got any code added that
knows how to speak that protocol) or if it was explicitly disabled. curl can
be built to only support a given set of protocols, and the rest would then
"curl http://example.com" it will use GET. If you use -d or -F curl will use
POST, -I will cause a HEAD and -T will make it a PUT.
- If for whatever reason you're not happy with these default choices that curl
+ If for whatever reason you are not happy with these default choices that curl
does for you, you can override those request methods by specifying -X
[WHATEVER]. This way you can for example send a DELETE by doing "curl -X
DELETE [URL]".
request-body in a GET request with something like "curl -X GET -d data
[URL]"
- Note that -X doesn't actually change curl's behavior as it only modifies the
+ Note that -X does not actually change curl's behavior as it only modifies the
actual string sent in the request, but that may of course trigger a
different set of events.
curl -g 'www.site.com/weirdname[].html'
- 4.4 Why do I get downloaded data even though the web page doesn't exist?
+ 4.4 Why do I get downloaded data even though the web page does not exist?
- curl asks remote servers for the page you specify. If the page doesn't exist
+ curl asks remote servers for the page you specify. If the page does not exist
at the server, the HTTP protocol defines how the server should respond and
- that means that headers and a "page" will be returned. That's simply how
+ that means that headers and a "page" will be returned. That is simply how
HTTP works.
By using the --fail option you can tell curl explicitly to not get any data
- if the HTTP return code doesn't say success.
+ if the HTTP return code does not say success.
4.5 Why do I get return code XXX from a HTTP server?
This problem has two sides:
The first part is to avoid having clear-text passwords in the command line
- so that they don't appear in 'ps' outputs and similar. That is easily
+ so that they do not appear in 'ps' outputs and similar. That is easily
avoided by using the "-K" option to tell curl to read parameters from a file
or stdin to which you can pass the secret info. curl itself will also
attempt to "hide" the given password by blanking out the option - this
- doesn't work on all platforms.
+ does not work on all platforms.
To keep the passwords in your account secret from the rest of the world is
not a task that curl addresses. You could of course encrypt them somehow to
It is not a bug if the behavior is documented. Read the docs first.
Especially check out the KNOWN_BUGS file, it may be a documented bug!
- If it is a problem with a binary you've downloaded or a package for your
+ If it is a problem with a binary you have downloaded or a package for your
particular platform, try contacting the person who built the package/archive
you have.
If there is a bug, read the BUGS document first. Then report it as described
in there.
- 4.9 curl can't authenticate to the server that requires NTLM?
+ 4.9 curl cannot authenticate to the server that requires NTLM?
NTLM support requires OpenSSL, GnuTLS, mbedTLS, NSS, Secure Transport, or
Microsoft Windows libraries at build-time to provide this functionality.
NTLM is a Microsoft proprietary protocol. Proprietary formats are evil. You
should not use such ones.
- 4.10 My HTTP request using HEAD, PUT or DELETE doesn't work!
+ 4.10 My HTTP request using HEAD, PUT or DELETE does not work!
Many web servers allow or demand that the administrator configures the
server properly for these requests to work on the web server.
Some servers seem to support HEAD only on certain kinds of URLs.
To fully grasp this, try the documentation for the particular server
- software you're trying to interact with. This is not anything curl can do
+ software you are trying to interact with. This is not anything curl can do
anything about.
4.11 Why do my HTTP range requests return the full document?
4.12 Why do I get "certificate verify failed" ?
When you invoke curl and get an error 60 error back it means that curl
- couldn't verify that the server's certificate was good. curl verifies the
+ could not verify that the server's certificate was good. curl verifies the
certificate using the CA cert bundle and verifying for which names the
certificate has been granted.
At times, you find that the verification works in your favorite browser but
fails in curl. When this happens, the reason is usually that the server
sends an incomplete cert chain. The server is mandated to send all
- "intermediate certificates" but doesn't. This typically works with browsers
+ "intermediate certificates" but does not. This typically works with browsers
anyway since they A) cache such certs and B) supports AIA which downloads
such missing certificates on demand. This is a server misconfiguration. A
good way to figure out if this is the case it to use the SSL Labs server
manually figure out what the page is set to do, or write a script that parses
the results and fetches the new URL.
- 4.15 FTPS doesn't work
+ 4.15 FTPS does not work
curl supports FTPS (sometimes known as FTP-SSL) both implicit and explicit
mode.
before having to send any data. This is useful in authentication
cases and others.
- However, many servers don't implement the Expect: stuff properly and if the
- server doesn't respond (positively) within 1 second libcurl will continue
+ However, many servers do not implement the Expect: stuff properly and if the
+ server does not respond (positively) within 1 second libcurl will continue
and send off the data anyway.
You can disable libcurl's use of the Expect: header the same way you disable
Also, even on non-Windows systems there may run a firewall or anti-virus
software or similar that accepts the connection but does not actually do
anything else. This will make (lib)curl to consider the connection connected
- and thus the connect timeout won't trigger.
+ and thus the connect timeout will not trigger.
4.18 file:// URLs containing drive letters (Windows, NetWare)
file://D:/blah.txt
- You'll find that even if D:\blah.txt does exist, curl returns a 'file
+ you will find that even if D:\blah.txt does exist, curl returns a 'file
not found' error.
According to RFC 1738 (https://www.ietf.org/rfc/rfc1738.txt),
most implementations. In the above example, 'D:' is treated as the
host component, and is taken away. Thus, curl tries to open '/blah.txt'.
If your system is installed to drive C:, that will resolve to 'C:\blah.txt',
- and if that doesn't exist you will get the not found error.
+ and if that does not exist you will get the not found error.
To fix this problem, use file:// URLs with *three* leading slashes:
In either case, curl should now be looking for the correct file.
- 4.19 Why doesn't curl return an error when the network cable is unplugged?
+ 4.19 Why does not curl return an error when the network cable is unplugged?
Unplugging a cable is not an error situation. The TCP/IP protocol stack
was designed to be fault tolerant, so even though there may be a physical
- break somewhere the connection shouldn't be affected, just possibly
+ break somewhere the connection should not be affected, just possibly
delayed. Eventually, the physical break will be fixed or the data will be
re-routed around the physical problem through another path.
connection to make sure it is still available to send data. That should
reliably detect any TCP/IP network failure.
- But even that won't detect the network going down before the TCP/IP
+ But even that will not detect the network going down before the TCP/IP
connection is established (e.g. during a DNS lookup) or using protocols that
- don't use TCP. To handle those situations, curl offers a number of timeouts
+ do not use TCP. To handle those situations, curl offers a number of timeouts
on its own. --speed-limit/--speed-time will abort if the data transfer rate
falls too low, and --connect-timeout and --max-time can be used to put an
overall timeout on the connection phase or the entire transfer.
by having the application monitor the network connection on its own using an
OS-specific mechanism, then signaling libcurl to abort (see also item 5.13).
- 4.20 curl doesn't return error for HTTP non-200 responses!
+ 4.20 curl does not return error for HTTP non-200 responses!
Correct. Unless you use -f (--fail).
- When doing HTTP transfers, curl will perform exactly what you're asking it
+ When doing HTTP transfers, curl will perform exactly what you are asking it
to do and if successful it will not return an error. You can use curl to
test your web server's "file not found" page (that gets 404 back), you can
use it to check your authentication protected web pages (that gets a 401
The specific HTTP response code does not constitute a problem or error for
curl. It simply sends and delivers HTTP as you asked and if that worked,
everything is fine and dandy. The response code is generally providing more
- higher level error information that curl doesn't care about. The error was
+ higher level error information that curl does not care about. The error was
not in the HTTP transfer.
If you want your command line to treat error codes in the 400 and up range
libcurl has excellent support for transferring multiple files. You should
just repeatedly set new URLs with curl_easy_setopt() and then transfer it
with curl_easy_perform(). The handle you get from curl_easy_init() is not
- only reusable, but you're even encouraged to reuse it if you can, as that
+ only reusable, but you are even encouraged to reuse it if you can, as that
will enable libcurl to use persistent connections.
5.4 Does libcurl do Winsock initialization on win32 systems?
When building an application that uses the static libcurl library, you must
add -DCURL_STATICLIB to your CFLAGS. Otherwise the linker will look for
- dynamic import symbols. If you're using Visual Studio, you need to instead
+ dynamic import symbols. If you are using Visual Studio, you need to instead
add CURL_STATICLIB in the "Preprocessor Definitions" section.
If you get linker error like "unknown symbol __imp__curl_easy_init ..." you
have linked against the wrong (static) library. If you want to use the
- libcurl.dll and import lib, you don't need any extra CFLAGS, but use one of
+ libcurl.dll and import lib, you do not need any extra CFLAGS, but use one of
the import libraries below. These are the libraries produced by the various
lib/Makefile.* files:
5.8 libcurl.so.X: open failed: No such file or directory
This is an error message you might get when you try to run a program linked
- with a shared version of libcurl and your run-time linker (ld.so) couldn't
+ with a shared version of libcurl and your run-time linker (ld.so) could not
find the shared library named libcurl.so.X. (Where X is the number of the
current libcurl ABI, typically 3 or 4).
* Set an environment variable (LD_LIBRARY_PATH for example) where ld.so
should check for libs
- * Adjust the system's config to check for libs in the directory where you've
+ * Adjust the system's config to check for libs in the directory where you have
put the dir (like Linux's /etc/ld.so.conf)
'man ld.so' and 'man ld' will tell you more details
can do this with include the progress callback, the read callback and the
write callback.
- If you're using the multi interface, you can also stop a transfer by
+ If you are using the multi interface, you can also stop a transfer by
removing the particular easy handle from the multi stack at any moment you
think the transfer is done or when you wish to abort the transfer.
5.14 Using C++ non-static functions for callbacks?
- libcurl is a C library, it doesn't know anything about C++ member functions.
+ libcurl is a C library, it does not know anything about C++ member functions.
You can overcome this "limitation" with relative ease using a static
member function that is passed a pointer to the class:
a symlink etc. If the FTP server supports the MLSD command then it will
return data in a machine-readable format that can be parsed for type. The
types are specified by RFC3659 section 7.5.1. If MLSD is not supported then
- you have to work with what you're given. The LIST output format is entirely
- at the server's own liking and the NLST output doesn't reveal any types and
- in many cases doesn't even include all the directory entries. Also, both LIST
+ you have to work with what you are given. The LIST output format is entirely
+ at the server's own liking and the NLST output does not reveal any types and
+ in many cases does not even include all the directory entries. Also, both LIST
and NLST tend to hide unix-style hidden files (those that start with a dot)
by default so you need to do "LIST -a" or similar to see them.
but still in the same single thread.
libcurl will potentially internally use threads for name resolving, if it
- was built to work like that, but in those cases it'll create the child
+ was built to work like that, but in those cases it will create the child
threads by itself and they will only be used and then killed internally by
libcurl and never exposed to the outside.
Yes!
- The LGPL license doesn't clash with other licenses.
+ The LGPL license does not clash with other licenses.
6.5 Can I modify curl/libcurl for my program and keep the changes secret?
8.1 Why does curl use C89?
- As with everything in curl, there's a history and we keep using what we've
+ As with everything in curl, there's a history and we keep using what we have
used before until someone brings up the subject and argues for and works on
changing it.
We started out using C89 in the 1990s because that was the only way to write
a truly portable C program and have it run as widely as possible. C89 was for
a long time even necessary to make things work on otherwise considered modern
- platforms such as Windows. Today, we don't really know how many users that
+ platforms such as Windows. Today, we do not really know how many users that
still require the use of a C89 compiler.
We will continue to use C89 for as long as nobody brings up a strong enough
- reason for us to change our minds. The core developers of the project don't
+ reason for us to change our minds. The core developers of the project do not
feel restricted by this and we are not convinced that going C99 will offer us
enough of a benefit to warrant the risk of cutting off a share of users.
## Security team members
-We have a security team. That's the team of people who are subscribed to the
+We have a security team. That is the team of people who are subscribed to the
curl-security mailing list; the receivers of security reports from users and
developers. This list of people will vary over time but should be skilled
developers familiar with the curl project.
## BDFL
-That's Daniel.
+That is Daniel.
# Maintainers
### Merge advice
-When you're merging patches/PRs...
+When you are merging patches/PRs...
- make sure the commit messages follow our template
-- squash patch sets into a few logical commits even if the PR didn't, if
+- squash patch sets into a few logical commits even if the PR did not, if
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:")
## Smaller tasks
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
+similar. We do not do that in curl since such issues never linger around long
enough. Simple issues get handled fast.
-If you're looking for a smaller or simpler task in the project to help out
+If you are 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
even maybe not a terribly experienced developer, here's our advice:
## Work on known bugs
-Some bugs are known and haven't yet received attention and work enough to get
+Some bugs are known and have not yet received attention and work enough to get
fixed. We collect such known existing flaws in the
[KNOWN_BUGS](https://curl.se/docs/knownbugs.html) page. Many of them link
to the original bug report with some additional details, but some may also
collection of test results from the automatic curl build and tests that are
performed by volunteers. Fixing compiler warnings and errors shown there is
something we value greatly. Also, if you own or run systems or architectures
-that aren't already tested in the autobuilds, we also appreciate more
+that are not already tested in the autobuilds, we also appreciate more
volunteers running builds automatically to help us keep curl portable.
## TODO items
Ideas for features and functions that we have considered worthwhile to
implement and provide are kept in the
[TODO](https://curl.se/docs/todo.html) file. Some of the ideas are
-rough. Some are well thought out. Some probably aren't really suitable
+rough. Some are well thought out. Some probably are not really suitable
anymore.
Before you invest a lot of time on a TODO item, do bring it up for discussion
We offer [guidelines](https://curl.se/dev/contribute.html) that are
suitable to be familiar with before you decide to contribute to curl. If
-you're used to open source development, you'll probably not find many
+you are used to open source development, you will probably not find many
surprises in there.
August: first announcement of curl on freshmeat.net.
October: with the curl 4.9 release and the introduction of cookie support,
-curl was no longer released under the GPL license. Now we're at 4000 lines of
+curl was no longer released under the GPL license. Now we are at 4000 lines of
code, we switched over to the MPL license to restrict the effects of
"copyleft".
Cookies are either "session cookies" which typically are forgotten when the
session is over which is often translated to equal when browser quits, or
- the cookies aren't session cookies they have expiration dates after which
+ the cookies are not session cookies they have expiration dates after which
the client will throw them away.
Cookies are set to the client with the Set-Cookie: header and are sent to
`-b, --cookie`
tell curl a file to read cookies from and start the cookie engine, or if it
- isn't a file it will pass on the given string. -b name=var works and so does
+ is not a file it will pass on the given string. -b name=var works and so does
-b cookiefile.
`-j, --junk-session-cookies`
that when doing subsequent parallel requests.
While libcurl sets up a connection to a HTTP server there is a period during
-which it doesn't know if it can pipeline or do multiplexing and if you add new
+which it does not know if it can pipeline or do multiplexing and if you add new
transfers in that period, libcurl will default to start new connections for
those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you
can ask that a transfer should rather wait and see in case there's a
curl tool limitations
---------------------
-The command line tool doesn't support HTTP/2 server push. It supports
+The command line tool does not support HTTP/2 server push. It supports
multiplexing when the parallel transfer option is used.
HTTP Alternative Services
## QUIC libraries
-QUIC libraries we're experimenting with:
+QUIC libraries we are experimenting with:
[ngtcp2](https://github.com/ngtcp2/ngtcp2)
## Limitations
-The hyper backend doesn't support
+The hyper backend does not support
- `CURLOPT_IGNORE_CONTENT_LENGTH`
- `--raw` and disabling `CURLOPT_HTTP_TRANSFER_DECODING`
- Builds libcurl without large file support
- Does not support all SSL libraries (only OpenSSL, Schannel,
Secure Transport, and mbed TLS, NSS, WolfSSL)
- - Doesn't allow different resolver backends (no c-ares build support)
+ - Does not allow different resolver backends (no c-ares build support)
- No RTMP support built
- - Doesn't allow build curl and libcurl debug enabled
- - Doesn't allow a custom CA bundle path
- - Doesn't allow you to disable specific protocols from the build
- - Doesn't find or use krb4 or GSS
- - Rebuilds test files too eagerly, but still can't run the tests
- - Doesn't detect the correct strerror_r flavor when cross-compiling (issue #1123)
+ - Does not allow build curl and libcurl debug enabled
+ - Does not allow a custom CA bundle path
+ - Does not allow you to disable specific protocols from the build
+ - Does not find or use krb4 or GSS
+ - Rebuilds test files too eagerly, but still cannot run the tests
+ - Does not detect the correct strerror_r flavor when cross-compiling (issue #1123)
Command Line CMake
# Unix
-A normal Unix installation is made in three or four steps (after you've
+A normal Unix installation is made in three or four steps (after you have
unpacked the source archive):
./configure --with-openssl [--with-gnutls --with-wolfssl]
The configure script always tries to find a working SSL library unless
explicitly told not to. If you have OpenSSL installed in the default search
-path for your compiler/linker, you don't need to do anything special. If you
+path for your compiler/linker, you do not need to do anything special. If you
have OpenSSL installed in `/usr/local/ssl`, you can run configure like:
./configure --with-openssl
CPPFLAGS="-I/path/to/ssl/include" LDFLAGS="-L/path/to/ssl/lib" ./configure
If you have shared SSL libs installed in a directory where your run-time
-linker doesn't find them (which usually causes configure failures), you can
+linker does not find them (which usually causes configure failures), you can
provide this option to gcc to set a hard-coded path to the run-time linker:
LDFLAGS=-Wl,-R/usr/local/ssl/lib ./configure --with-openssl
./configure --disable-thread
-If you're a curl developer and use gcc, you might want to enable more debug
+If you are a curl developer and use gcc, you might want to enable more debug
options with the `--enable-debug` option.
curl can be built to use a whole range of libraries to provide various useful
Almost identical to the unix installation. Run the configure script in the
curl source tree root with `sh configure`. Make sure you have the `sh`
-executable in `/bin/` or you'll see the configure fail toward the end.
+executable in `/bin/` or you will see the configure fail toward the end.
Run `make`
./configure --host aarch64-linux-android --with-pic --disable-shared
-Note that this won't give you SSL/TLS support. If you need SSL/TLS, you have
+Note that this will not give you SSL/TLS support. If you need SSL/TLS, you have
to build curl against a SSL/TLS layer, e.g. OpenSSL, because it's impossible for
curl to access Android's native SSL/TLS layer. To build curl for Android using
OpenSSL, follow the OpenSSL build instructions and then install `libssl.a` and
./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN/sysroot/usr"
Note, however, that you must target at least Android M (API level 23) or `configure`
-won't be able to detect OpenSSL since `stderr` (and the like) weren't defined
+will not be able to detect OpenSSL since `stderr` (and the like) were not defined
before Android M.
# IBM i
## Multithreading notes
-By default, jobs in IBM i won't start with threading enabled. (Exceptions
+By default, jobs in IBM i will not start with threading enabled. (Exceptions
include interactive PASE sessions started by `QP2TERM` or SSH.) If you use
curl in an environment without threading when options like async DNS were
-enabled, you'll messages like:
+enabled, you will messages like:
```
getaddrinfo() thread failed to start
```
-Don't panic! curl and your program aren't 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.
This is a probably incomplete list of known CPU architectures and operating
systems that curl has been compiled for. If you know a system curl compiles
-and runs on, that isn't listed, please let us know!
+and runs on, that is not listed, please let us know!
## 85 Operating Systems
===
All changes to the sources are committed to the git repository as soon as
- they're somewhat verified to work. Changes shall be committed as independently
+ they are somewhat verified to work. Changes shall be committed as independently
as possible so that individual changes can be easily spotted and tracked
afterwards.
===========
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's
+ machines. Most of libcurl assumes more or less POSIX compliance but that is
not a requirement.
We write libcurl to build and work with lots of third party tools, and we
-----------------
On systems where configure runs, we aim at working on them all - if they have
- a suitable C compiler. On systems that don't run configure, we strive to keep
+ a suitable C compiler. On systems that do not run configure, we strive to keep
curl running correctly on:
- Windows 98
2. Windows requires a couple of init calls for the socket stuff.
- That's taken care of by the `curl_global_init()` call, but if other libs
+ That is taken care of by the `curl_global_init()` call, but if other libs
also do it etc there might be reasons for applications to alter that
behavior.
Inside the source code, We make an effort to avoid `#ifdef [Your OS]`. All
conditionals that deal with features *should* instead be in the format
- `#ifdef HAVE_THAT_WEIRD_FUNCTION`. Since Windows can't run configure scripts,
+ `#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!
Generally speaking: always remember that this will be compiled on dozens of
- operating systems. Don't walk on the edge!
+ operating systems. Do not walk on the edge!
<a name="Library"></a>
Library
The functions are named after the protocols they handle.
The protocol-specific functions of course deal with protocol-specific
- negotiations and setup. When they're ready to start the actual file
+ negotiations and setup. When they are ready to start the actual file
transfer they call the `Curl_setup_transfer()` function (in
`lib/transfer.c`) to setup the transfer and returns.
connections so this is not normally called when `curl_easy_perform()` is
used. This function is only used when we are certain that no more transfers
are going to be made on the connection. It can be also closed by force, or
- it can be called to make sure that libcurl doesn't keep too many
+ it can be called to make sure that libcurl does not keep too many
connections alive at the same time.
This function cleans up all resources that are associated with a single
more).
`lib/getenv.c` offers `curl_getenv()` which is for reading environment
- variables in a neat platform independent way. That's used in the client, but
+ variables in a neat platform independent way. That is used in the client, but
also in `lib/url.c` when checking the proxy environment variables. Note that
contrary to the normal unix `getenv()`, this returns an allocated buffer that
must be `free()`ed after use.
`lib/netrc.c` holds the `.netrc` parser.
- `lib/timeval.c` features replacement functions for systems that don't have
+ `lib/timeval.c` features replacement functions for systems that do not have
`gettimeofday()` and a few support functions for timeval conversions.
A function named `curl_version()` that returns the full curl version string
- When the transfer operation is complete, the connection is left
open. Particular options may tell libcurl not to, and protocols may signal
- closure on connections and then they won't be kept open, of course.
+ closure on connections and then they will not be kept open, of course.
- When `curl_easy_cleanup()` is called, we close all still opened connections,
unless of course the multi interface "owns" the connections.
Library Symbols
===============
- All symbols used internally in libcurl must use a `Curl_` prefix if they're
+ All symbols used internally in libcurl must use a `Curl_` prefix if they are
used in more than a single file. Single-file symbols must be made static.
Public ("exported") symbols must use a `curl_` prefix. (There are exceptions,
but they are to be changed to follow this pattern in future versions.) Public
Return Codes and Informationals
===============================
- I've made things simple. Almost every function in libcurl returns a CURLcode,
+ I have 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 place that detects an
error must use the `Curl_failf()` function to set the human-readable error
must supply a fair number of informational messages by using the
`Curl_infof()` function. Those messages are only displayed when the user
explicitly asks for them. They are best used when revealing information that
- isn't otherwise obvious.
+ is not otherwise obvious.
<a name="abi"></a>
API/ABI
`httpserver.pl` and `ftpserver.pl` before all the test cases are performed.
The test suite currently only runs on Unix-like platforms.
- You'll find a description of the test suite in the `tests/README` file, and
+ you will find a description of the test suite in the `tests/README` file, and
the test case data files in the `tests/FILEFORMAT` file.
The test suite automatically detects if curl was built with the memory
Lastly, I also changed libcurl to be single-threaded rather than
multi-threaded, again this was to prevent some duplicate symbol errors. I'm
not sure why I needed to change everything to single-threaded, but when I
- didn't I got redefinition errors for several CRT functions (`malloc()`,
+ did not I got redefinition errors for several CRT functions (`malloc()`,
`stricmp()`, etc.)
<a name="curl_off_t"></a>
## `CURLRES_IPV6`
this host has `getaddrinfo()` and family, and thus we use that. The host may
- not be able to resolve IPv6, but we don't really have to take that into
- account. Hosts that aren't IPv6-enabled have `CURLRES_IPV4` defined.
+ not be able to resolve IPv6, but we do not really have to take that into
+ account. Hosts that are not IPv6-enabled have `CURLRES_IPV4` defined.
## `CURLRES_ARES`
This now outputs a report on what resources that were allocated but never
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
+ If this does not produce any output, no leak was detected in libcurl. Then
the leak is mostly likely to be in your code.
<a name="multi_socket"></a>
==================
This section should cover 7.32.0 pretty accurately, but will make sense even
-for older and later versions as things don't change drastically that often.
+for older and later versions as things do not change drastically that often.
<a name="Curl_easy"></a>
## Curl_easy
performance boost.
Each `connectdata` identifies a single physical connection to a server. If
- the connection can't be kept alive, the connection will be closed after use
+ the connection cannot be kept alive, the connection will be closed after use
and then this struct can be removed from the cache and freed.
Thus, the same `Curl_easy` can be used multiple times and each time select
The concrete function pointer prototypes can be found in `lib/urldata.h`.
- `->scheme` is the URL scheme name, usually spelled out in uppercase. That's
+ `->scheme` is the URL scheme name, usually spelled out in uppercase. That is
"HTTP" or "FTP" etc. SSL versions of the protocol need their own
`Curl_handler` setup so HTTPS separate from HTTP.
`->doing` keeps getting called while issuing the transfer request command(s)
- `->done` gets called when the transfer is complete and DONE. That's after the
+ `->done` gets called when the transfer is complete and DONE. That is after the
main data has been transferred.
`->do_more` gets called during the `DO_MORE` state. The FTP protocol uses
limit which "direction" of socket actions that the main engine will
concern itself with.
- - `PROTOPT_NONETWORK` - a protocol that doesn't use network (read `file:`)
+ - `PROTOPT_NONETWORK` - a protocol that does not use network (read `file:`)
- `PROTOPT_NEEDSPWD` - this protocol needs a password and will use a default
one unless one is provided
- - `PROTOPT_NOURLQUERY` - this protocol can't handle a query part on the URL
+ - `PROTOPT_NOURLQUERY` - this protocol cannot handle a query part on the URL
(?foo=bar)
<a name="conncache"></a>
holds.
Then individual `Curl_easy` structs can be made to share specific things
- that they otherwise wouldn't, such as cookies.
+ that they otherwise would not, such as cookies.
The `Curl_share` struct can currently hold cookies, DNS cache and the SSL
session cache.
1.5 Expect-100 meets 417
1.6 Unnecessary close when 401 received waiting for 100
1.7 Deflate error after all content was received
- 1.8 DoH isn't used for all name resolves when enabled
+ 1.8 DoH is not used for all name resolves when enabled
1.11 CURLOPT_SEEKFUNCTION not called with CURLFORM_STREAM
2. TLS
2.1 CURLINFO_SSL_VERIFYRESULT has limited support
2.2 DER in keychain
2.3 Unable to use PKCS12 certificate with Secure Transport
- 2.4 Secure Transport won't import PKCS#12 client certificates without a password
+ 2.4 Secure Transport will not import PKCS#12 client certificates without a password
2.5 Client cert handling with Issuer DN differs between backends
2.6 CURL_GLOBAL_SSL
2.7 Client cert (MTLS) issues with Schannel
2.8 Schannel disable CURLOPT_SSL_VERIFYPEER and verify hostname
- 2.9 TLS session cache doesn't work with TFO
+ 2.9 TLS session cache does not work with TFO
2.10 Store TLS context per transfer instead of per connection
2.11 Schannel TLS 1.2 handshake bug in old Windows versions
2.12 FTPS with Schannel times out file list operation
5.2 curl-config --libs contains private details
5.3 curl compiled on OSX 10.13 failed to run on OSX 10.10
5.4 Build with statically built dependency
- 5.5 can't handle Unicode arguments in non-Unicode builds on Windows
+ 5.5 cannot handle Unicode arguments in non-Unicode builds on Windows
5.7 Visual Studio project gaps
5.8 configure finding libs in wrong directory
5.9 Utilize Requires.private directives in libcurl.pc
6.2 MIT Kerberos for Windows build
6.3 NTLM in system context uses wrong name
6.4 Negotiate and Kerberos V5 need a fake user name
- 6.5 NTLM doesn't support password with § character
+ 6.5 NTLM does not support password with § character
6.6 libcurl can fail to try alternatives with --proxy-any
- 6.7 Don't clear digest for single realm
+ 6.7 Do not clear digest for single realm
6.8 RTSP authentication breaks without redirect support
6.9 SHA-256 digest not supported in Windows SSPI builds
6.10 curl never completes Negotiate over HTTP
6.11 Negotiate on Windows fails
- 6.12 Can't use Secure Transport with Crypto Token Kit
+ 6.12 cannot use Secure Transport with Crypto Token Kit
7. FTP
7.1 FTP without or slow 220 response
7.11 FTPS upload data loss with TLS 1.3
8. TELNET
- 8.1 TELNET and time limitations don't work
+ 8.1 TELNET and time limitations do not work
8.2 Microsoft telnet server
9. SFTP and SCP
- 9.1 SFTP doesn't do CURLOPT_POSTQUOTE correct
- 9.2 wolfssh: publickey auth doesn't work
+ 9.1 SFTP does not do CURLOPT_POSTQUOTE correct
+ 9.2 wolfssh: publickey auth does not work
9.3 Remote recursive folder creation with SFTP
10. SOCKS
11. Internals
11.1 Curl leaks .onion hostnames in DNS
11.2 error buffer not set if connection to multiple addresses fails
- 11.3 Disconnects don't do verbose
+ 11.3 Disconnects do not do verbose
11.4 HTTP test server 'connection-monitor' problems
11.5 Connection information when using TCP Fast Open
11.6 slow connect to localhost on Windows
11.7 signal-based resolver timeouts
11.8 DoH leaks memory after followlocation
- 11.9 DoH doesn't inherit all transfer options
+ 11.9 DoH does not inherit all transfer options
11.10 Blocking socket operations in non-blocking API
11.11 A shared connection cache is not thread-safe
11.12 'no_proxy' string-matches IPv6 numerical addresses
12. LDAP
12.1 OpenLDAP hangs after returning results
12.2 LDAP on Windows does authentication wrong?
- 12.3 LDAP on Windows doesn't work
+ 12.3 LDAP on Windows does not work
12.4 LDAPS with NSS is slow
13. TCP/IP
18.5 HTTP/3 download with quiche halts after a while
18.6 HTTP/3 multipart POST with quiche fails
18.7 HTTP/3 quiche upload large file fails
- 18.8 HTTP/3 doesn't support client certs
- 18.9 connection migration doesn't work
+ 18.8 HTTP/3 does not support client certs
+ 18.9 connection migration does not work
==============================================================================
See https://github.com/curl/curl/issues/2719
-1.8 DoH isn't used for all name resolves when enabled
+1.8 DoH is not used for all name resolves when enabled
Even if DoH is specified to be used, there are some name resolves that are
done without it. This should be fixed. When the internal function
- `Curl_resolver_wait_resolv()` is called, it doesn't use DoH to complete the
+ `Curl_resolver_wait_resolv()` is called, it does not use DoH to complete the
resolve as it otherwise should.
See https://github.com/curl/curl/pull/3857 and
1.11 CURLOPT_SEEKFUNCTION not called with CURLFORM_STREAM
I'm using libcurl to POST form data using a FILE* with the CURLFORM_STREAM
- option of curl_formadd(). I've noticed that if the connection drops at just
+ option of curl_formadd(). I have noticed that if the connection drops at just
the right time, the POST is reattempted without the data from the file. It
- seems like the file stream position isn't getting reset to the beginning of
+ seems like the file stream position is not getting reset to the beginning of
the file. I found the CURLOPT_SEEKFUNCTION option and set that with a
- function that performs an fseek() on the FILE*. However, setting that didn't
+ function that performs an fseek() on the FILE*. However, setting that did not
seem to fix the issue or even get called. See
https://github.com/curl/curl/issues/768
2.2 DER in keychain
- Curl doesn't recognize certificates in DER format in keychain, but it works
+ Curl does not recognize certificates in DER format in keychain, but it works
with PEM. https://curl.se/bug/view.cgi?id=1065
2.3 Unable to use PKCS12 certificate with Secure Transport
See https://github.com/curl/curl/issues/5403
-2.4 Secure Transport won't import PKCS#12 client certificates without a password
+2.4 Secure Transport will not import PKCS#12 client certificates without a password
libcurl calls SecPKCS12Import with the PKCS#12 client certificate, but that
function rejects certificates that do not have a password.
2.5 Client cert handling with Issuer DN differs between backends
- When the specified client certificate doesn't match any of the
+ When the specified client certificate does not match any of the
server-specified DNs, the OpenSSL and GnuTLS backends behave differently.
The github discussion may contain a solution.
https://github.com/curl/curl/issues/3284
-2.9 TLS session cache doesn't work with TFO
+2.9 TLS session cache does not work with TFO
See https://github.com/curl/curl/issues/4301
handshake, curl has sent an HTTP request to the server and at the same time
the server has sent a TLS hello request (renegotiate) to curl. Both are
waiting for the other to respond. OpenSSL is supposed to send a handshake
- response but doesn't.
+ response but does not.
https://github.com/curl/curl/issues/6785
https://github.com/openssl/openssl/issues/14722
3.4 AUTH PLAIN for SMTP is not working on all servers
- Specifying "--login-options AUTH=PLAIN" on the command line doesn't seem to
+ Specifying "--login-options AUTH=PLAIN" on the command line does not seem to
work correctly.
See https://github.com/curl/curl/issues/4080
4.1 -J and -O with %-encoded file names
- -J/--remote-header-name doesn't decode %-encoded file names. RFC6266 details
+ -J/--remote-header-name does not decode %-encoded file names. RFC6266 details
how it should be done. The can of worm is basically that we have no charset
handling in curl and ascii >=128 is a challenge for us. Not to mention that
decoding also means that we need to check for nastiness that is attempted,
embedded slashes should be cut off.
https://curl.se/bug/view.cgi?id=1294
- -O also doesn't decode %-encoded names, and while it has even less
+ -O also does not decode %-encoded names, and while it has even less
information about the charset involved the process is similar to the -J case.
- Note that we won't add decoding to -O without the user asking for it with
+ Note that we will not add decoding to -O without the user asking for it with
some other means as well, since -O has always been documented to use the name
exactly as specified in the URL.
4.3 --retry and transfer timeouts
If using --retry and the transfer timeouts (possibly due to using -m or
- -y/-Y) the next attempt doesn't resume the transfer properly from what was
+ -y/-Y) the next attempt does not resume the transfer properly from what was
downloaded in the previous attempt but will truncate and restart at the
original position where it was at before the previous failed attempt. See
https://curl.se/mail/lib-2008-01/0080.html and Mandriva bug report
We welcome help to improve curl's ability to link with static libraries, but
it is likely a task that we can never fully support.
-5.5 can't handle Unicode arguments in non-Unicode builds on Windows
+5.5 cannot handle Unicode arguments in non-Unicode builds on Windows
- If a URL or filename can't be encoded using the user's current codepage then
+ If a URL or filename cannot be encoded using the user's current codepage then
it can only be encoded properly in the Unicode character set. Windows uses
UTF-16 encoding for Unicode and stores it in wide characters, however curl
and libcurl are not equipped for that at the moment except when built with
- _UNICODE and UNICODE defined. And, except for Cygwin, Windows can't use UTF-8
+ _UNICODE and UNICODE defined. And, except for Cygwin, Windows cannot use UTF-8
as a locale.
https://curl.se/bug/?i=345
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.
+ the project who (rightfully) do not expect this.
See https://github.com/curl/curl/issues/6972
new conn->bits.want_authentication which is set when any of the authentication
options are set.
-6.5 NTLM doesn't support password with § character
+6.5 NTLM does not support password with § character
https://github.com/curl/curl/issues/2120
authentication will cause libcurl to abort trying other options if the
failed method has a higher preference than the alternatives. As an example,
--proxy-any against a proxy which advertise Negotiate and NTLM, but which
- fails to set up Kerberos authentication won't proceed to try authentication
+ fails to set up Kerberos authentication will not proceed to try authentication
using NTLM.
https://github.com/curl/curl/issues/876
-6.7 Don't clear digest for single realm
+6.7 Do not clear digest for single realm
https://github.com/curl/curl/issues/3267
6.10 curl never completes Negotiate over HTTP
- Apparently it isn't working correctly...?
+ Apparently it is not working correctly...?
See https://github.com/curl/curl/issues/5235
https://github.com/curl/curl/issues/5881
-6.12 Can't use Secure Transport with Crypto Token Kit
+6.12 cannot use Secure Transport with Crypto Token Kit
https://github.com/curl/curl/issues/7048
When doing FTP over a socks proxy or CONNECT through HTTP proxy and the multi
interface is used, libcurl will fail if the (passive) TCP connection for the
- data transfer isn't more or less instant as the code does not properly wait
+ data transfer is not more or less instant as the code does not properly wait
for the connect to be confirmed. See test case 564 for a first shot at a test
case.
7.4 FTP with ACCT
When doing an operation over FTP that requires the ACCT command (but not when
- logging in), the operation will fail since libcurl doesn't detect this and
+ logging in), the operation will fail since libcurl does not detect this and
thus fails to issue the correct command:
https://curl.se/bug/view.cgi?id=635
7.5 ASCII FTP
- FTP ASCII transfers do not follow RFC959. They don't convert the data
+ FTP ASCII transfers do not follow RFC959. They do not convert the data
accordingly (not for sending nor for receiving). RFC 959 section 3.1.1.1
clearly describes how this should be done:
When 'multi_done' is called before the transfer has been completed the normal
way, it is considered a "premature" transfer end. In this situation, libcurl
- closes the connection assuming it doesn't know the state of the connection so
- it can't be reused for subsequent requests.
+ closes the connection assuming it does not know the state of the connection so
+ it cannot be reused for subsequent requests.
- With FTP however, this isn't necessarily true but there are a bunch of
+ With FTP however, this is not necessarily true but there are a bunch of
situations (listed in the ftp_done code) where it *could* keep the connection
- alive even in this situation - but the current code doesn't. Fixing this would
+ alive even in this situation - but the current code does not. Fixing this would
allow libcurl to reuse FTP connections better.
7.9 Passive transfer tries only one IP address
message. When curl closes the upload connection if unread data has been
received (such as a TLS handshake message) then the TCP protocol sends an
RST to the server, which may cause the server to discard or truncate the
- upload if it hasn't read all sent data yet, and then return an error to curl
+ upload if it has not read all sent data yet, and then return an error to curl
on the control channel connection.
Since 7.78.0 this is mostly fixed. curl will do a single read before closing
8. TELNET
-8.1 TELNET and time limitations don't work
+8.1 TELNET and time limitations do not work
- When using telnet, the time limitation options don't work.
+ When using telnet, the time limitation options do not work.
https://curl.se/bug/view.cgi?id=846
8.2 Microsoft telnet server
9. SFTP and SCP
-9.1 SFTP doesn't do CURLOPT_POSTQUOTE correct
+9.1 SFTP does not do CURLOPT_POSTQUOTE correct
When libcurl sends CURLOPT_POSTQUOTE commands when connected to a SFTP server
using the multi interface, the commands are not being sent correctly and
report but it cannot be accepted as-is. See
https://curl.se/bug/view.cgi?id=748
-9.2 wolfssh: publickey auth doesn't work
+9.2 wolfssh: publickey auth does not work
When building curl to use the wolfSSH backend for SFTP, the publickey
- authentication doesn't work. This is simply functionality not written for curl
+ authentication does not work. This is simply functionality not written for curl
yet, the necessary API for make this work is provided by wolfSSH.
See https://github.com/curl/curl/issues/4820
10.3 FTPS over SOCKS
- libcurl doesn't support FTPS over a SOCKS proxy.
+ libcurl does not support FTPS over a SOCKS proxy.
10.4 active FTP over a SOCKS
- libcurl doesn't support active FTP over a SOCKS proxy
+ libcurl does not support active FTP over a SOCKS proxy
11. Internals
CURLE_COULDNT_CONNECT. But the error buffer set by CURLOPT_ERRORBUFFER
remains empty. Issue: https://github.com/curl/curl/issues/544
-11.3 Disconnects don't do verbose
+11.3 Disconnects do not do verbose
Due to how libcurl keeps connections alive in the "connection pool" after use
to potentially transcend the life-time of the initial easy handle that was
used to drive the transfer over that connection, it uses a *separate* and
internal easy handle when it shuts down the connection. That separate
connection might not have the exact same settings as the original easy
- handle, and in particular it is often note-worthy that it doesn't have the
+ handle, and in particular it is often note-worthy that it does not have the
same VERBOSE and debug callbacks setup so that an application will not get
the protocol data for the disconnect phase of a transfer the same way it got
all the other data.
11.4 HTTP test server 'connection-monitor' problems
- The 'connection-monitor' feature of the sws HTTP test server doesn't work
+ The 'connection-monitor' feature of the sws HTTP test server does not work
properly if some tests are run in unexpected order. Like 1509 and then 1525.
See https://github.com/curl/curl/issues/868
HAPPY_EYEBALLS_TIMEOUT define exactly. Lowering that define speeds up the
connection, suggesting a problem in the HE handling.
- If we can *know* that we're talking to a local host, we should lower the
+ If we can *know* that we are talking to a local host, we should lower the
happy eyeballs delay timeout for IPv6 (related: hardcode the "localhost"
addresses, mentioned in TODO). Possibly we should reduce that delay for all.
https://github.com/curl/curl/issues/4592
-11.9 DoH doesn't inherit all transfer options
+11.9 DoH does not inherit all transfer options
Some options are not inherited because they are not relevant for the DoH SSL
connections, or inheriting the option may result in unexpected behavior. For
11.12 'no_proxy' string-matches IPv6 numerical addresses
- This has the downside that "::1" for example doesn't match "::0:1" even
+ This has the downside that "::1" for example does not match "::0:1" even
though they are in fact the same address.
See https://github.com/curl/curl/issues/5745
https://github.com/curl/curl/issues/3116
-12.3 LDAP on Windows doesn't work
+12.3 LDAP on Windows does not work
A simple curl command line getting "ldap://ldap.forumsys.com" returns an
error that says "no memory" !
13.1 --interface for ipv6 binds to unusable IP address
Since IPv6 provides a lot of addresses with different scope, binding to an
- IPv6 address needs to take the proper care so that it doesn't bind to a
+ IPv6 address needs to take the proper care so that it does not bind to a
locally scoped address as that is bound to fail.
https://github.com/curl/curl/issues/686
14.1 DICT responses show the underlying protocol
- When getting a DICT response, the protocol parts of DICT aren't stripped off
+ When getting a DICT response, the protocol parts of DICT are not stripped off
from the output.
https://github.com/curl/curl/issues/1809
15.4 build docs/curl.1
- The cmake build doesn't create the docs/curl.1 file and therefore must rely on
+ The cmake build does not create the docs/curl.1 file and therefore must rely on
it being there already. This makes the --manual option not work and test
- cases like 1139 can't function.
+ cases like 1139 cannot function.
15.5 build on Linux links libcurl to libdl
- ... which it shouldn't need to!
+ ... which it should not need to!
See https://github.com/curl/curl/issues/6165
This application crashes at startup with libcurl 7.74.0 (and presumably later
versions too) after we cleaned up OpenSSL initialization. Since this is the
only known application to do this, we suspect it is related to something they
- are doing in their setup that isn't kosher. We have not been able to get in
+ are doing in their setup that is not kosher. We have not been able to get in
contact with them nor got any technical details to help us debug this
further.
https://github.com/curl/curl/issues/7532
-18.8 HTTP/3 doesn't support client certs
+18.8 HTTP/3 does not support client certs
aka "mutual authentication".
https://github.com/curl/curl/issues/7625
-18.9 connection migration doesn't work
+18.9 connection migration does not work
https://github.com/curl/curl/issues/7695
1.5 Moderation of new posters
Several of the curl mailing lists automatically make all posts from new
- subscribers be moderated. This means that after you've subscribed and
+ subscribers be moderated. This means that after you have subscribed and
sent your first mail to a list, that mail will not be let through to the
list until a mailing list administrator has verified that it is OK and
permits it to get posted.
anything good and only puts the light even more on the offender: which was
the entire purpose of it getting sent to the list in the first place.
- Don't feed the trolls!
+ Do not feed the trolls!
1.7 How to unsubscribe
You can unsubscribe the same way you subscribed in the first place. You go
- to the page for the particular mailing list you're subscribed to and you enter
+ to the page for the particular mailing list you are subscribed to and you enter
your email address and password and press the unsubscribe button.
Also, the instructions to unsubscribe are included in the headers of every
1.8 I posted, now what?
- If you aren't subscribed with the exact same email address that you used to
+ If you are not subscribed with the exact same email address that you used to
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 quickly but in case we're asleep, you may have to wait a
+ normally happens quickly but in case we are asleep, you may have to wait a
few hours.
Once your email goes through it is sent out to several hundred or even
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
- environment. Tell us which curl version you're using and tell us what you
+ environment. Tell us which curl version you are using and tell us what you
did, what happened and what you expected would happen. Preferably, show us
what you did with details enough to allow others to help point out the problem
or repeat the same steps in their locations.
Many mail programs and web archivers use information within mails to keep
them together as "threads", as collections of posts that discuss a certain
- subject. If you don't intend to reply on the same or similar subject, don't
+ subject. If you do not intend to reply on the same or similar subject, do not
just hit reply on an existing mail and change subject, create a new mail.
2.2 Reply to the List
reply" or "reply to all", and not just reply to the author of the single
mail you reply to.
- We're actively discouraging replying back to the single person by setting
+ We are actively discouraging replying back to the single person by setting
the Reply-To: field in outgoing mails back to the mailing list address,
making it harder for people to mail the author directly, if only by mistake.
2.4 Do Not Top-Post
- If you reply to a message, don't use top-posting. Top-posting is when you
+ If you reply to a message, do not use top-posting. Top-posting is when you
write the new text at the top of a mail and you insert the previous quoted
mail conversation below. It forces users to read the mail in a backwards
order to properly understand it.
When you reply to a mail. You let the mail client insert the previous mail
quoted. Then you put the cursor on the first line of the mail and you move
- down through the mail, deleting all parts of the quotes that don't add
+ down through the mail, deleting all parts of the quotes that do not add
context for your comments. When you want to add a comment you do so, inline,
right after the quotes that relate to your comment. Then you continue
downwards again.
- When most of the quotes have been removed and you've added your own words,
- you're done!
+ When most of the quotes have been removed and you have added your own words,
+ you are done!
2.5 HTML is not for mails
## Verbose / Debug
-If curl fails where it isn't supposed to, if the servers don't let you in, if
-you can't understand the responses: use the `-v` flag to get verbose
+If curl fails where it is not supposed to, if the servers do not let you in, if
+you cannot understand the responses: use the `-v` flag to get verbose
fetching. Curl will output lots of info and what it sends and receives in
-order to let the user see all client-server interaction (but it won't show you
+order to let the user see all client-server interaction (but it will not show you
the actual data).
curl -v ftp://ftp.upload.com/
should expire (`expire=DATE`), for what domain to use it (`domain=NAME`) and
if it should be used on secure connections only (`secure`).
-If you've received a page from a server that contains a header like:
+If you have received a page from a server that contains a header like:
```http
Set-Cookie: sessionid=boo123; path="/foo";
- Curr.Speed - the average transfer speed the last 5 seconds (the first
5 seconds of a transfer is based on less time of course.)
-The `-#` option will display a totally different progress bar that doesn't
+The `-#` option will display a totally different progress bar that does not
need much explanation!
## Speed Limit
curl -m 1800 -Y 3000 -y 60 www.far-away-site.com
Forcing curl not to transfer data faster than a given rate is also possible,
-which might be useful if you're using a limited bandwidth connection and you
-don't want your transfer to use all of it (sometimes referred to as
+which might be useful if you are using a limited bandwidth connection and you
+do not want your transfer to use all of it (sometimes referred to as
"bandwidth throttle").
Make curl transfer data no faster than 10 kilobytes per second:
url = "http://help.with.curl.com/curlhelp.html"
You can specify another config file to be read by using the `-K`/`--config`
-flag. If you set config file name to `-` it'll read the config from stdin,
+flag. If you set config file name to `-` it will read the config from stdin,
which can be handy if you want to hide options from being visible in process
tables etc:
The default way for curl is to issue the PASV command which causes the server
to open another port and await another connection performed by the
-client. This is good if the client is behind a firewall that doesn't allow
+client. This is good if the client is behind a firewall that does not allow
incoming connections.
curl ftp.download.com
-If the server, for example, is behind a firewall that doesn't allow
-connections on ports other than 21 (or if it just doesn't support the `PASV`
+If the server, for example, is behind a firewall that does not allow
+connections on ports other than 21 (or if it just does not support the `PASV`
command), the other way to do it is to use the `PORT` command and instruct the
server to connect to the client on the given IP number and port (as parameters
to the PORT command).
ALL_PROXY
-A comma-separated list of host names that shouldn't go through any proxy is
+A comma-separated list of host names that should not go through any proxy is
set in (only an asterisk, `*` matches all hosts)
NO_PROXY
Unix introduced the `.netrc` concept a long time ago. It is a way for a user
to specify name and password for commonly visited FTP sites in a file so that
-you don't have to type them in each time you visit those sites. You realize
+you do not have to type them in each time you visit those sites. You realize
this is a big security risk if someone else gets hold of your passwords, so
-therefore most unix programs won't read this file unless it is only readable
-by yourself (curl doesn't care though).
+therefore most unix programs will not read this file unless it is only readable
+by yourself (curl does not care though).
Curl supports `.netrc` files if told to (using the `-n`/`--netrc` and
`--netrc-optional` options). This is not restricted to just FTP, so curl can
- `NEW_ENV=<var,val>` Sets an environment variable.
NOTE: The telnet protocol does not specify any way to login with a specified
-user and password so curl can't do that automatically. To do that, you need to
+user and password so curl cannot do that automatically. To do that, you need to
track when the login prompt is received and send the username and password
accordingly.
Note that curl cannot use persistent connections for transfers that are used
in subsequence curl invokes. Try to stuff as many URLs as possible on the same
-command line if they are using the same host, as that'll make the transfers
+command line if they are using the same host, as that will make the transfers
faster. If you use an HTTP proxy for file transfers, practically all transfers
will be persistent.
### curl-users
-Users of the command line tool. How to use it, what doesn't work, new
+Users of the command line tool. How to use it, what does not work, new
features, related tools, questions, news, installations, compilations,
running, porting etc.
- Only QoS level 0 is implemented for publish
- No way to set retain flag for publish
- No TLS (mqtts) support
- - Naive EAGAIN handling won't handle split messages
+ - Naive EAGAIN handling will not handle split messages
### URL
There should be a documented URL format. If there is an RFC for it there is no
-question about it but the syntax doesn't have to be a published RFC. It could
+question about it but the syntax does not have to be a published RFC. It could
be enough if it is already in use by other implementations.
If you make up the syntax just in order to be able to propose it to curl, then
curl test cases. We must have the implementation get tested by CI jobs,
torture tests and more.
-We've experienced many times in the past how new implementations were brought
+We have experienced many times in the past how new implementations were brought
to curl and immediately once the code had been merged, the originator vanished
from the face of the earth. That is fine, but we need to take the necessary
precautions so when it happens we are still fine.
The protocol specification itself should be freely available without requiring
any NDA or similar.
-## Don't compare
+## Do not compare
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
spot other - existing - protocol implementations have used, but there is
-nothing to gain from that. The bar has been raised. Former "cheats" won't be
+nothing to gain from that. The bar has been raised. Former "cheats" will not be
tolerated anymore.
Connections are shared fine between different easy handles, but the
"authentication contexts" are not. So for example doing HTTP Digest auth with
one handle for a particular transfer and then continue on with another handle
-that reuses the same connection, the second handle can't send the necessary
+that reuses the same connection, the second handle cannot send the necessary
Authorization header at once since the context is only kept in the original
easy handle.
# Documentation
-You'll find a mix of various documentation in this directory and
+you will find a mix of various documentation in this directory and
subdirectories, using several different formats. Some of them are not ideal
for reading directly in your browser.
-If you'd rather see the rendered version of the documentation, check out the
+If you would rather see the rendered version of the documentation, check out the
curl website's [documentation section](https://curl.se/docs/) for
general curl stuff or the [libcurl section](https://curl.se/libcurl/) for
libcurl related documentation.
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 a
+might ask you to join the list or you can ask to join it. It really is not 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
+its way of working. You must have 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
When using said CA bundle to verify a server cert, you will experience
problems if your CA store does not contain the certificates for the
- intermediates if the server doesn't provide them.
+ intermediates if the server does not provide them.
The TLS protocol mandates that the intermediate certificates are sent in the
handshake, but as browsers have ways to survive or work around such
omissions, missing intermediates in TLS handshakes still happen that
- browser-users won't notice.
+ browser-users will not notice.
Browsers work around this problem in two ways: they cache intermediate
certificates from previous transfers and some implement the TLS "AIA"
## Ciphers
- Clients give servers a list of ciphers to select from. If the list doesn't
+ Clients give servers a list of ciphers to select from. If the list does not
include any ciphers the server wants/can use, the connection handshake
fails.
BEAST is the name of a TLS 1.0 attack that surfaced 2011. When adding means
to mitigate this attack, it turned out that some broken servers out there in
- the wild didn't work properly with the BEAST mitigation in place.
+ the wild did not work properly with the BEAST mitigation in place.
To make such broken servers work, the --ssl-allow-beast option was
introduced. Exactly as it sounds, it re-introduces the BEAST vulnerability
depending on the OS or build configuration. The --ssl-no-revoke option was
introduced in 7.44.0 to disable revocation checking but currently is only
supported for Schannel (the native Windows SSL library), with an exception
- in the case of Windows' Untrusted Publishers block list which it seems can't
+ in the case of Windows' Untrusted Publishers block list which it seems cannot
be bypassed. This option may have broader support to accommodate other SSL
backends in the future.
If libcurl was built with Schannel or Secure Transport support (the native SSL
libraries included in Windows and Mac OS X), then this does not apply to
you. Scroll down for details on how the OS-native engines handle SSL
-certificates. If you're not sure, then run "curl -V" and read the results. If
+certificates. If you are not sure, then run "curl -V" and read the results. If
the version string says `Schannel` in it, then it was built with Schannel
support.
This system is about trust. In your local CA certificate store you have certs
from *trusted* Certificate Authorities that you then can use to verify that the
-server certificates you see are valid. They're signed by one of the CAs you
+server certificates you see are valid. they are signed by one of the CAs you
trust.
Which CAs do you trust? You can decide to trust the same set of companies your
-operating system trusts, or the set one of the known browsers trust. That's
+operating system trusts, or the set one of the known browsers trust. That is
basically trust via someone else you trust. You should just be aware that
modern operating systems and browsers are setup to trust *hundreds* of
companies and recent years several such CAs have been found untrustworthy.
certificates that are signed by CAs present in the store, you can be sure
that the remote server really is the one it claims to be.
-If the remote server uses a self-signed certificate, if you don't install a CA
-cert store, if the server uses a certificate signed by a CA that isn't
+If the remote server uses a self-signed certificate, if you do not install a CA
+cert store, if the server uses a certificate signed by a CA that is not
included in the store you use or if the remote host is an impostor
impersonating your favorite site, and you want to transfer files from this
server, do one of the following:
certificate store or use it stand-alone as described. Just remember that
the security is no better than the way you obtained the certificate.
- 4. If you're using the curl command line tool, you can specify your own CA
+ 4. If you are using the curl command line tool, you can specify your own CA
cert file by setting the environment variable `CURL_CA_BUNDLE` to the path
of your choice.
- If you're using the curl command line tool on Windows, curl will search
+ If you are using the curl command line tool on Windows, curl will search
for a CA cert file named "curl-ca-bundle.crt" in these directories and in
this order:
1. application's directory
way for you: [CA Extract](https://curl.se/docs/caextract.html)
Neglecting to use one of the above methods when dealing with a server using a
-certificate that isn't signed by one of the certificates in the installed CA
+certificate that is not signed by one of the certificates in the installed CA
certificate store, will cause SSL to report an error ("certificate verify
failed") during the handshake and SSL will then refuse further communication
with that server.
1.15 Monitor connections in the connection pool
1.16 Try to URL encode given URL
1.17 Add support for IRIs
- 1.18 try next proxy if one doesn't work
+ 1.18 try next proxy if one does not work
1.19 provide timing info for each redirect
1.20 SRV and URI DNS records
1.21 netrc caching and sharing
5.3 Rearrange request header order
5.4 Allow SAN names in HTTP/2 server push
5.5 auth= in URLs
- 5.6 alt-svc should fallback if alt-svc doesn't work
+ 5.6 alt-svc should fallback if alt-svc does not work
6. TELNET
6.1 ditch stdin
19. Build
19.1 roffit
19.2 Enable PIE and RELRO by default
- 19.3 Don't use GNU libtool on OpenBSD
+ 19.3 Do not use GNU libtool on OpenBSD
19.4 Package curl for Windows in a signed installer
19.5 make configure use --cache-file more and better
1.2 Consult %APPDATA% also for .netrc
- %APPDATA%\.netrc is not considered when running on Windows. Shouldn't it?
+ %APPDATA%\.netrc is not considered when running on Windows. should not it?
See https://github.com/curl/curl/issues/4016
Currently the libssh2 SSH based code uses it, but to remove PATH_MAX from
there we need libssh2 to properly tell us when we pass in a too small buffer
- and its current API (as of libssh2 1.2.7) doesn't.
+ and its current API (as of libssh2 1.2.7) does not.
1.6 native IDN support on macOS
is may cause name resolves to fail unless res_init() is called. We should
consider calling res_init() + retry once unconditionally on all name resolve
failures to mitigate against this. Firefox works like that. Note that Windows
- doesn't have res_init() or an alternative.
+ does not have res_init() or an alternative.
https://github.com/curl/curl/issues/2251
close them with the CURLOPT_CLOSESOCKETFUNCTION callback. However, c-ares
does not use those functions and instead opens and closes the sockets
itself. This means that when curl passes the c-ares socket to the
- CURLMOPT_SOCKETFUNCTION it isn't owned by the application like other sockets.
+ CURLMOPT_SOCKETFUNCTION it is not owned by the application like other sockets.
See https://github.com/curl/curl/issues/2734
reuse purpose it is verified that it is still alive.
Those connections may get closed by the server side for idleness or they may
- get a HTTP/2 ping from the peer to verify that they're still alive. By adding
+ get a HTTP/2 ping from the peer to verify that they are still alive. By adding
monitoring of the connections while in the pool, libcurl can detect dead
connections (and close them) better and earlier, and it can handle HTTP/2
pings to keep such ones alive even when not actively doing transfers on them.
To make that work smoothly for curl users even on Windows, curl would
probably need to be able to convert from several input encodings.
-1.18 try next proxy if one doesn't work
+1.18 try next proxy if one does not work
Allow an application to specify a list of proxies to try, and failing to
connect to the first go on and try the next instead until the list is
1.32 add asynch getaddrinfo support
Use getaddrinfo_a() to provide an asynch name resolver backend to libcurl
- that doesn't use threads and doesn't depend on c-ares. The getaddrinfo_a
- function is (probably?) glibc specific but that's a widely used libc among
+ that does not use threads and does not depend on c-ares. The getaddrinfo_a
+ function is (probably?) glibc specific but that is a widely used libc among
our users.
https://github.com/curl/curl/pull/6746
2.1 More non-blocking
- Make sure we don't ever loop because of non-blocking sockets returning
+ Make sure we do not ever loop because of non-blocking sockets returning
EWOULDBLOCK or similar. Blocking cases include:
- Name resolves on non-windows unless c-ares or the threaded resolver is used.
2.4 Split connect and authentication process
The multi interface treats the authentication process as part of the connect
- phase. As such any failures during authentication won't trigger the relevant
+ phase. As such any failures during authentication will not trigger the relevant
QUIT or LOGOFF for protocols such as IMAP, POP3 and SMTP.
2.5 Edge-triggered sockets should work
2.8 dynamically decide to use socketpair
- For users who don't use curl_multi_wait() or don't care for
+ For users who do not use curl_multi_wait() or do not care for
curl_multi_wakeup(), we could introduce a way to make libcurl NOT
create a socketpair in the multi handle.
4.5 ASCII support
- FTP ASCII transfers do not follow RFC959. They don't convert the data
+ FTP ASCII transfers do not follow RFC959. They do not convert the data
accordingly.
4.6 GSSAPI via Windows SSPI
Additionally this should be implemented for proxy base URLs as well.
-5.6 alt-svc should fallback if alt-svc doesn't work
+5.6 alt-svc should fallback if alt-svc does not work
The alt-svc: header provides a set of alternative services for curl to use
instead of the original. If the first attempted one fails, it should try the
6.2 ditch telnet-specific select
Move the telnet support's network select() loop go away and merge the code
- into the main transfer loop. Until this is done, the multi interface won't
+ into the main transfer loop. Until this is done, the multi interface will not
work for telnet.
6.3 feature negotiation debug data
11.4 Create remote directories
Support for creating remote directories when uploading a file to a directory
- that doesn't exist on the server, just like --ftp-create-dirs.
+ that does not exist on the server, just like --ftp-create-dirs.
12. FILE
"Look at SSL cafile - quick traces look to me like these are done on every
request as well, when they should only be necessary once per SSL context (or
once per handle)". The major improvement we can rather easily do is to make
- sure we don't create and kill a new SSL "context" for every request, but
+ sure we do not create and kill a new SSL "context" for every request, but
instead make one for every connection and re-use that SSL context in the same
style connections are re-used. It will make us use slightly more memory but
it will libcurl do less creations and deletions of SSL contexts.
13.6 Provide callback for cert verification
OpenSSL supports a callback for customised verification of the peer
- certificate, but this doesn't seem to be exposed in the libcurl APIs. Could
+ certificate, but this does not seem to be exposed in the libcurl APIs. Could
it be? There's so much that could be done if it were!
13.8 Support DANE
AIA can provide various things like CRLs but more importantly information
about intermediate CA certificates that can allow validation path to be
- fulfilled when the HTTPS server doesn't itself provide them.
+ fulfilled when the HTTPS server does not itself provide them.
Since AIA is about downloading certs on demand to complete a TLS handshake,
it is probably a bit tricky to get done right.
The SFTP code in libcurl checks the file size *before* a transfer starts and
then proceeds to transfer exactly that amount of data. If the remote file
- grows while the transfer is in progress libcurl won't notice and will not
+ grows while the transfer is in progress libcurl will not notice and will not
adapt. The OpenSSH SFTP command line tool does and libcurl could also just
attempt to download more to see if there is more to get...
17.5 SSH over HTTPS proxy with more backends
- The SSH based protocols SFTP and SCP didn't work over HTTPS proxy at
+ The SSH based protocols SFTP and SCP did not work over HTTPS proxy at
all until PR https://github.com/curl/curl/pull/6021 brought the
functionality with the libssh2 backend. Presumably, this support
can/could be added for the other backends as well.
When --retry is used and curl actually retries transfer, it should use the
already transferred data and do a resumed transfer for the rest (when
- possible) so that it doesn't have to transfer the same data again that was
+ possible) so that it does not have to transfer the same data again that was
already transferred before the retry.
See https://github.com/curl/curl/issues/1084
provides the "may overwrite any file" risk.
This is extra tricky if the original URL has no file name part at all since
- then the current code path will error out with an error message, and we can't
+ then the current code path will error out with an error message, and we cannot
*know* already at that point if curl will be redirected to a URL that has a
file name...
- If splitting up the work improves the transfer rate, it could then be done
again. Then again, etc up to a limit.
- This way, if transfer B fails (because Range: isn't supported) it will let
+ This way, if transfer B fails (because Range: is not supported) it will let
transfer A remain the single one. N and M could be set to some sensible
defaults.
Users who are for example doing large downloads in CI or remote setups might
want the occasional progress meter update to see that the transfer is
- progressing and hasn't stuck, but they may not appreciate the
+ progressing and has not stuck, but they may not appreciate the
many-times-a-second frequency curl can end up doing it with now.
19. Build
to no impact, neither on the performance nor on the general functionality of
curl.
-19.3 Don't use GNU libtool on OpenBSD
+19.3 Do not use GNU libtool on OpenBSD
When compiling curl on OpenBSD with "--enable-debug" it will give linking
errors when you use GNU libtool. This can be fixed by using the libtool
provided by OpenBSD itself. However for this the user always needs to invoke
20.2 nicer lacking perl message
- If perl wasn't found by the configure script, don't attempt to run the tests
- but explain something nice why it doesn't.
+ If perl was not found by the configure script, do not attempt to run the tests
+ but explain something nice why it does not.
20.3 more protocols supported
20.5 Add support for concurrent connections
Tests 836, 882 and 938 were designed to verify that separate connections
- aren't used when using different login credentials in protocols that
- shouldn't re-use a connection under such circumstances.
+ are not used when using different login credentials in protocols that
+ should not re-use a connection under such circumstances.
- Unfortunately, ftpserver.pl doesn't appear to support multiple concurrent
+ Unfortunately, ftpserver.pl does not appear to support multiple concurrent
connections. The read while() loop seems to loop until it receives a
disconnect from the client, where it then enters the waiting for connections
loop. When the client opens a second connection to the server, the first
- connection hasn't been dropped (unless it has been forced - which we
- shouldn't do in these tests) and thus the wait for connections loop is never
+ connection has not been dropped (unless it has been forced - which we
+ should not do in these tests) and thus the wait for connections loop is never
entered to receive the second connection.
20.6 Use the RFC6265 test suite
20.7 Support LD_PRELOAD on macOS
- LD_RELOAD doesn't work on macOS, but there are tests which require it to run
+ LD_RELOAD does not work on macOS, but there are tests which require it to run
properly. Look into making the preload support in runtests.pl portable such
that it uses DYLD_INSERT_LIBRARIES on macOS.
## Background
- This document assumes that you're familiar with HTML and general networking.
+ This document assumes that you are familiar with HTML and general networking.
The increasing amount of applications moving to the web has made "HTTP
Scripting" more frequently requested and wanted. To be able to automatically
want to know the amount of milliseconds between two points in a transfer. For
those, and other similar situations, the
[`--trace-time`](https://curl.se/docs/manpage.html#--trace-time) option
- is what you need. It'll prepend the time to each trace output line:
+ is what you need. it will prepend the time to each trace output line:
curl --trace-ascii d.txt --trace-time http://example.com/
## Spec
The Uniform Resource Locator format is how you specify the address of a
- particular resource on the Internet. You know these, you've seen URLs like
+ particular resource on the Internet. You know these, you have seen URLs like
https://curl.se or https://yourbank.com a million times. RFC 3986 is the
canonical spec. And yeah, the formal name is not URL, it is URI.
## Host
The host name is usually resolved using DNS or your /etc/hosts file to an IP
- address and that's what curl will communicate with. Alternatively you specify
+ address and that is what curl will communicate with. Alternatively you specify
the IP address directly in the URL instead of a name.
For development and other trying out situations, you can point to a different
## Port number
Each protocol curl supports operates on a default port number, be it over TCP
- or in some cases UDP. Normally you don't have to take that into
+ or in some cases UDP. Normally you do not have to take that into
consideration, but at times you run test servers on other ports or
similar. Then you can specify the port number in the URL with a colon and a
number immediately following the host name. Like when doing HTTP to port
A single curl command line may involve one or many URLs. The most common case
is probably to just use one, but you can specify any amount of URLs. Yes
- any. No limits. You'll then get requests repeated over and over for all the
+ any. No limits. you will then get requests repeated over and over for all the
given URLs.
Example, send two GETs:
## Multiple HTTP methods in a single command line
Sometimes you need to operate on several URLs in a single command line and do
- different HTTP methods on each. For this, you'll enjoy the
+ different HTTP methods on each. For this, you will enjoy the
[`--next`](https://curl.se/docs/manpage.html#-:) option. It is basically
a separator that separates a bunch of options from the next. All the URLs
before `--next` will get the same method and will get all the POST data
merged into one.
- When curl reaches the `--next` on the command line, it'll sort of reset the
+ When curl reaches the `--next` on the command line, it will sort of reset the
method and the POST data and allow a new set.
Perhaps this is best shown with a few examples. To send first a HEAD and then
previous URL.
If the original form was seen on the page `www.example.com/when/birth.html`,
- the second page you'll get will become
+ the second page you will get will become
`www.example.com/when/junk.cgi?birthyear=1905&press=OK`.
Most search engines work this way.
## POST
The GET method makes all input field names get displayed in the URL field of
- your browser. That's generally a good thing when you want to be able to
+ your browser. That is 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 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
+ data separated from the URL and thus you will not see any of it in the URL
address field.
The form would look similar to the previous one:
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
+ in, they are not 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
</form>
```
- To POST this with curl, you won't have to think about if the fields are
- hidden or not. To curl they're all the same:
+ To POST this with curl, you will not have to think about if the fields are
+ hidden or not. To curl they are all the same:
curl --data "birthyear=1905&press=OK&person=daniel" [URL]
## 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 interested in sending a POST exactly the way
+ When you are about fill in a form and send to a server by using curl instead
+ of a browser, you are 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
## Basic Authentication
HTTP Authentication is the ability to tell the server your username and
- password so that it can verify that you're allowed to do the request you're
+ password so that it can verify that you are allowed to do the request you are
doing. The Basic authentication used in HTTP (which is the type curl uses by
default) is **plain text** based, which means it sends username and password
only slightly obfuscated, but still fully readable by anyone that sniffs on
A HTTP request may include a 'referer' field (yes it is misspelled), which
can be used to tell from which URL the client got to this particular
resource. Some programs/scripts check the referer field of requests to verify
- that this wasn't arriving from an external site or an unknown page. While
+ that this was not arriving from an external site or an unknown page. While
this is a stupid way to check something so easily forged, many scripts still
do it. Using curl, you can put anything you want in the referer-field and
thus more easily be able to fool the server into serving your request.
At times, you will see that getting a page with curl will not return the same
page that you see when getting the page with your browser. Then you know it
- is time to set the User Agent field to fool the server into thinking you're
+ is time to set the User Agent field to fool the server into thinking you are
one of those browsers.
To make curl look like Internet Explorer 5 on a Windows 2000 box:
curl --user-agent "Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)" [URL]
- Or why not look like you're using Netscape 4.73 on an old Linux box:
+ Or why not look like you are using Netscape 4.73 on an old Linux box:
curl --user-agent "Mozilla/4.73 [en] (X11; U; Linux 2.2.15 i686)" [URL]
## Other redirects
Browser typically support at least two other ways of redirects that curl
- doesn't: first the html may contain a meta refresh tag that asks the browser
+ does not: first the html may contain a meta refresh tag that asks the browser
to load a specific URL after a set number of seconds, or it may use
javascript to do it.
Curl's "cookie engine" gets enabled when you use the
[`--cookie`](https://curl.se/docs/manpage.html#-b) option. If you only
want curl to understand received cookies, use `--cookie` with a file that
- doesn't exist. Example, if you want to let curl understand cookies from a
+ does not exist. Example, if you want to let curl understand cookies from a
page and follow a location (and thus possibly send back cookies it received),
you can invoke it like:
format that Netscape and Mozilla once used. It is a convenient way to share
cookies between scripts or invokes. The `--cookie` (`-b`) switch
automatically detects if a given file is such a cookie file and parses it,
- and by using the `--cookie-jar` (`-c`) option you'll make curl write a new
+ and by using the `--cookie-jar` (`-c`) option you will make curl write a new
cookie file at the end of an operation:
curl --cookie cookies.txt --cookie-jar newcookies.txt \
verifying the server's certificate against a locally stored CA cert
bundle. Failing the verification will cause curl to deny the connection. You
must then use [`--insecure`](https://curl.se/docs/manpage.html#-k)
- (`-k`) in case you want to tell curl to ignore that the server can't be
+ (`-k`) in case you want to tell curl to ignore that the server cannot be
verified.
More about server certificate verification and ca cert bundles can be read in
curl -X POST http://example.org/
- ... but curl will still think and act as if it sent a GET so it won't send
+ ... but curl will still think and act as if it sent a GET so it will not send
any request body etc.
# Web Login
Some web-based login systems feature various amounts of javascript, and
sometimes they use such code to set or modify cookie contents. Possibly they
do that to prevent programmed logins, like this manual describes how to...
- Anyway, if reading the code isn't enough to let you repeat the behavior
+ Anyway, if reading the code is not enough to let you repeat the behavior
manually, capturing the HTTP requests done by your browsers and analyzing the
sent cookies is usually a working method to work out how to shortcut the
javascript need.
## Some debug tricks
- Many times when you run curl on a site, you'll notice that the site doesn't
+ Many times when you run curl on a site, you will notice that the site does not
seem to respond the same way to your curl requests as it does to your
browser's.
security risk.
URLs for IMAP, POP3 and SMTP also support *login options* as part of the
-userinfo field. They're provided as a semicolon after the password and then
+userinfo field. they are provided as a semicolon after the password and then
the options.
## Hostname
### Windows-specific FILE details
-curl accepts that the FILE URL's path starts with a "drive letter". That's a
+curl accepts that the FILE URL's path starts with a "drive letter". That is a
single letter `a` to `z` followed by a colon or a pipe character (`|`).
The Windows operating system itself will convert some file accesses to perform
imap://user:password@mail.example.com/INBOX?TEXT%20%22foo%20bar%22
-.. but if you wanted matching UID numbers you'd have to use a custom request:
+.. but if you wanted matching UID numbers you would have to use a custom request:
imap://user:password@mail.example.com/INBOX -X "UID SEARCH TEXT \"foo bar\""
Version Numbers and Releases
============================
- Curl is not only curl. Curl is also libcurl. They're actually individually
+ Curl is not only curl. Curl is also libcurl. they are actually individually
versioned, but they usually follow each other closely.
The version numbering is always built up using the same system:
Added: 4.8
---
When used in an upload, this makes curl append to the target file instead of
-overwriting it. If the remote file doesn't 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).
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 isn't 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.
record and use cookies. Another way to activate it is to use the --cookie
option.
-If the cookie jar can't be created or written to, the whole curl operation
-won't fail or even report an error clearly. Using --verbose will get a warning
-displayed, but that is the only visible feedback you get about this possibly
-lethal situation.
+If the cookie jar cannot be created or written to, the whole curl operation
+will not fail or even report an error clearly. Using --verbose will get a
+warning displayed, but that is the only visible feedback you get about this
+possibly lethal situation.
If this option is used several times, the last specified file name will be
used.
If no '=' symbol is used in the argument, it is instead treated as a filename
to read previously stored cookie from. This option also activates the cookie
engine which will make curl record incoming cookies, which may be handy if
-you're using this in combination with the --location option or do multiple URL
+you are using this in combination with the --location option or do multiple URL
transfers on the same invoke. If the file name is exactly a minus ("-"), curl
will instead read the contents from stdin.
The file specified with --cookie is only used as input. No cookies will be
written to the file. To store cookies, use the --cookie-jar option.
-If you use the Set-Cookie file format and don't specify a domain then the
+If you use the Set-Cookie file format and do not specify a domain then the
cookie is not sent since the domain will never match. To address this, set a
domain in Set-Cookie line (doing that will include sub-domains) or preferably:
use the Netscape format.
.RS
.IP "content"
This will make curl URL-encode the content and pass that on. Just be careful
-so that the content doesn't contain any = or @ symbols, as that will then make
+so that the content does not contain any = or @ symbols, as that will then make
the syntax match one of the other cases below!
.IP "=content"
This will make curl URL-encode the content and pass that on. The preceding =
read the data from, or - if you want curl to read the data from stdin. Posting
data from a file named \&'foobar' would thus be done with --data @foobar. When
--data is told to read from a file like that, carriage returns and newlines
-will be stripped out. If you don't want the @ character to have a special
+will be stripped out. If you do not want the @ character to have a special
interpretation use --data-raw instead.
comes to user credentials.
.RS
.IP "none"
-Don't allow any delegation.
+Do not allow any delegation.
.IP "policy"
Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos
service ticket, which is a matter of realm policy.
Example: --ftp-create-dirs -T file ftp://example.com/remote/path/file
Added: 7.10.7
---
-When an FTP or SFTP URL/operation uses a path that doesn't currently exist on
+When an FTP or SFTP URL/operation uses a path that does not currently exist on
the server, the standard behavior of curl is to fail. Using this option, curl
will instead attempt to create missing directories.
option.
If this option is used several times, only the first one is used. Undoing an
-enforced passive really isn't doable but you must then instead enforce the
+enforced passive really is not doable but you must then instead enforce the
correct --ftp-port again.
Passive mode means that curl will try the EPSV command first and then PASV,
---
Require SSL/TLS for the FTP login, clear for transfer. Allows secure
authentication, but non-encrypted data transfers for efficiency. Fails the
-transfer if the server doesn't support SSL/TLS.
+transfer if the server does not support SSL/TLS.
the URL with a HEAD request.
If this option is used several times, only the first one is used. This is
-because undoing a GET doesn't make sense, but you should then instead enforce
+because undoing a GET does not make sense, but you should then instead enforce
the alternative method you prefer.
header that has the same name as one of the internal ones curl would use, your
externally set header will be used instead of the internal one. This allows
you to make even trickier stuff than curl would normally do. You should not
-replace internally set headers without knowing perfectly well what you're
+replace internally set headers without knowing perfectly well what you are
doing. Remove an internal header by giving a replacement without content on
the right side of the colon, as in: -H \&"Host:". If you send the custom
header with no-value then its header must be terminated with a semicolon, such
For FTP (since 7.46.0), skip the RETR command to figure out the size before
downloading a file.
-This option doesn't work for HTTP if libcurl was built to use hyper.
+This option does not work for HTTP if libcurl was built to use hyper.
When curl is told to read cookies from a given file, this option will make it
discard all "session cookies". This will basically have the same effect as if
a new session is started. Typical browsers always discard session cookies when
-they're closed down.
+they are closed down.
Added: 7.10
---
Specify the maximum transfer rate you want curl to use - for both downloads
-and uploads. This feature is useful if you have a limited pipe and you'd like
+and uploads. This feature is useful if you have a limited pipe and you would like
your transfer not to use your entire bandwidth. To make it slower than it
otherwise would be.
(FTP)
When listing an FTP directory, this switch forces a name-only view. This is
especially useful if the user wants to machine-parse the contents of an FTP
-directory since the normal directory view doesn't use a standard look or
+directory since the normal directory view does not use a standard look or
format. When used like this, the option causes an NLST command to be sent to
the server instead of LIST.
---
Like --location, but will allow sending the name + password to all hosts that
the site may redirect to. This may or may not introduce a security breach if
-the site redirects you to a site to which you'll send your authentication info
-(which is plaintext in the case of HTTP Basic authentication).
+the site redirects you to a site to which you will send your authentication
+info (which is plaintext in the case of HTTP Basic authentication).
option will make curl redo the request on the new place. If used together with
--include or --head, headers from all requested pages will be shown. When
authentication is used, curl only sends its credentials to the initial
-host. If a redirect takes curl to a different host, it won't be able to
+host. If a redirect takes curl to a different host, it will not be able to
intercept the user+password. See also --location-trusted on how to change
this. You can limit the amount of redirects to follow by using the
--max-redirs option.
When using this option, you must also provide a fake --user option to activate
the authentication code properly. Sending a '-u :' is enough as the user name
-and password from the --user option aren't actually used.
+and password from the --user option are not actually used.
If this option is used several times, only the first one is used.
directory for login name and password. This is typically used for FTP on
Unix. If used with HTTP, curl will enable user authentication. See
*netrc(5)* and *ftp(1)* for details on the file format. Curl will not
-complain if that file doesn't have the right permissions (it should be
+complain if that file does not have the right permissions (it should be
neither world- nor group-readable). The environment variable "HOME" is used
to find the home directory.
The given output directory is used for all URLs and output options on the
command line, up until the first --next.
-If the specified target directory doesn't exist, the operation will fail
+If the specified target directory does not exist, the operation will fail
unless --create-dirs is also used.
If this option is used multiple times, the last specified directory will be
curl -o aa example.com -o bb example.net
-and the order of the -o options and the URLs doesn't matter, just that the
+and the order of the -o options and the URLs does not matter, just that the
first -o is for the first URL and so on, so the above command line can also be
written as
.IP "ALL_PROXY [protocol://]<host>[:port]"
Sets the proxy server to use if no protocol-specific proxy is set.
.IP "NO_PROXY <comma-separated list of hosts/domains>"
-list of host names that shouldn't go through any proxy. If set to an asterisk
+list of host names that should not go through any proxy. If set to an asterisk
\&'*' only, it matches all hosts. Each name in this list is matched as either
a domain name which contains the hostname, or the hostname itself.
versions should then be given without enclosing brackets.
IPv6 numerical addresses are compared as strings, so they will only match if
-the representations are the same: "::1" is the same as "::0:1" but they don't
+the representations are the same: "::1" is the same as "::0:1" but they do not
match.
.IP "CURL_SSL_BACKEND <TLS backend>"
If curl was built with support for "MultiSSL", meaning that it has built-in
support for more than one TLS backend, this environment variable can be set to
the case insensitive name of the particular backend to use when curl is
-invoked. Setting a name that isn't a built-in alternative will make curl
+invoked. Setting a name that is not a built-in alternative will make curl
stay with the default.
SSL backend names (case-insensitive): bearssl, gnutls, gskit, mbedtls,
The proxy string may be specified with a protocol:// prefix to specify
alternative proxy protocols. (Added in 7.21.7)
-If no protocol is specified in the proxy string or if the string doesn't match
+If no protocol is specified in the proxy string or if the string does not match
a supported one, the proxy will be treated as an HTTP proxy.
The supported proxy protocol prefixes are as follows:
enabled or was explicitly disabled at build-time. To make curl able to do
this, you probably need another build of libcurl!
.IP 5
-Couldn't resolve proxy. The given proxy host could not be resolved.
+Could not resolve proxy. The given proxy host could not be resolved.
.IP 6
-Couldn't resolve host. The given remote host could not be resolved.
+Could not resolve host. The given remote host could not be resolved.
.IP 7
Failed to connect to host.
.IP 8
-Weird server reply. The server sent data curl couldn't parse.
+Weird server reply. The server sent data curl could not parse.
.IP 9
FTP access denied. The server denied login or denied access to the particular
resource or directory you wanted to reach. Most often you tried to change to a
-directory that doesn't exist on the server.
+directory that does not exist on the server.
.IP 10
FTP accept failed. While waiting for the server to connect back when an active
FTP session is used, an error code was sent over the control connection or
similar.
.IP 11
-FTP weird PASS reply. Curl couldn't parse the reply sent to the PASS request.
+FTP weird PASS reply. Curl could not parse the reply sent to the PASS request.
.IP 12
During an active FTP session while waiting for the server to connect back to
curl, the timeout expired.
.IP 13
-FTP weird PASV reply, Curl couldn't parse the reply sent to the PASV request.
+FTP weird PASV reply, Curl could not parse the reply sent to the PASV request.
.IP 14
-FTP weird 227 format. Curl couldn't parse the 227-line the server sent.
+FTP weird 227 format. Curl could not parse the 227-line the server sent.
.IP 15
-FTP can't get host. Couldn't resolve the host IP we got in the 227-line.
+FTP cannot use host. Could not resolve the host IP we got in the 227-line.
.IP 16
HTTP/2 error. A problem was detected in the HTTP2 framing layer. This is
somewhat generic and can be one out of several problems, see the error message
for details.
.IP 17
-FTP couldn't set binary. Couldn't change transfer method to binary.
+FTP could not set binary. Could not change transfer method to binary.
.IP 18
Partial file. Only a part of the file was transferred.
.IP 19
-FTP couldn't download/access the given file, the RETR (or similar) command
+FTP could not download/access the given file, the RETR (or similar) command
failed.
.IP 21
FTP quote error. A quote command returned error from the server.
error with the HTTP error code being 400 or above. This return code only
appears if --fail is used.
.IP 23
-Write error. Curl couldn't write data to a local filesystem or similar.
+Write error. Curl could not write data to a local filesystem or similar.
.IP 25
-FTP couldn't STOR file. The server denied the STOR operation, used for FTP
+FTP could not STOR file. The server denied the STOR operation, used for FTP
uploading.
.IP 26
Read error. Various reading problems.
FTP PORT failed. The PORT command failed. Not all FTP servers support the PORT
command, try doing a transfer using PASV instead!
.IP 31
-FTP couldn't use REST. The REST command failed. This command is used for
+FTP could not use REST. The REST command failed. This command is used for
resumed FTP transfers.
.IP 33
-HTTP range error. The range "command" didn't work.
+HTTP range error. The range "command" did not work.
.IP 34
HTTP post error. Internal post-request generation error.
.IP 35
SSL connect error. The SSL handshaking failed.
.IP 36
-Bad download resume. Couldn't continue an earlier aborted download.
+Bad download resume. Could not continue an earlier aborted download.
.IP 37
-FILE couldn't read file. Failed to open the file. Permissions?
+FILE could not read file. Failed to open the file. Permissions?
.IP 38
LDAP cannot bind. LDAP bind operation failed.
.IP 39
.IP 51
The peer's SSL certificate or SSH MD5 fingerprint was not OK.
.IP 52
-The server didn't reply anything, which here is considered an error.
+The server did not reply anything, which here is considered an error.
.IP 53
SSL crypto engine not found.
.IP 54
.IP 58
Problem with the local certificate.
.IP 59
-Couldn't use specified SSL cipher.
+Could not use specified SSL cipher.
.IP 60
Peer certificate cannot be authenticated with known CA certificates.
.IP 61
curl is powered by libcurl for all transfer-related features. See
*libcurl(3)* for details.
.SH URL
-The URL syntax is protocol-dependent. You'll find a detailed description in
+The URL syntax is protocol-dependent. You find a detailed description in
RFC 3986.
You can specify multiple URLs or parts of URLs by writing part sets within
separator. The long "double-dash" form, --data for example, requires a space
between it and its value.
-Short version options that don't need any additional values can be used
+Short version options that do not need any additional values can be used
immediately next to each other, like for example you can specify all the
options -O, -L and -v at once as -OLv.
configuration.
You should also be aware that many HTTP/1.1 servers do not have this feature
-enabled, so that when you attempt to get a range, you'll instead get the whole
-document.
+enabled, so that when you attempt to get a range, you will instead get the
+whole document.
FTP and SFTP range downloads only support the simple 'start-stop' syntax
(optionally with one of the numbers omitted). FTP use depends on the extended
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 don't set an initial --referer.
+even if you do not set an initial --referer.
If this option is used several times, the last one will be used.
If the server specifies a file name and a file with that name already exists
in the current working directory it will not be overwritten and an error will
-occur. If the server doesn't specify a file name then this option has no
+occur. If the server does not specify a file name then this option has no
effect.
There's no attempt to decode %-sequences (yet) in the provided file name, so
---
Tells curl to use an alternative "target" (path) instead of using the path as
provided in the URL. Particularly useful when wanting to issue HTTP requests
-without leading slash or other data that doesn't follow the regular URL
+without leading slash or other data that does not follow the regular URL
pattern, like "OPTIONS *".
DELETE, but related technologies like WebDAV offers PROPFIND, COPY, MOVE and
more.
-Normally you don't need this option. All sorts of GET, HEAD, POST and PUT
+Normally you do not need this option. All sorts of GET, HEAD, POST and PUT
requests are rather invoked by using dedicated command line options.
This option only changes the actual word used in the HTTP request, it does not
The method string you set with --request will be used for all requests, which
if you for example use --location may cause unintended side-effects when curl
-doesn't change request method according to the HTTP 30x response codes - and
+does not change request method according to the HTTP 30x response codes - and
similar.
(FTP)
possible with redirected input or output. For example, before retrying it
removes output data from a failed partial transfer that was written to an
output file. However this is not true of data redirected to a | pipe or >
-file, which are not reset. We strongly suggest don't parse or record output
-via redirect in combination with this option, since you may receive duplicate
-data.
+file, which are not reset. We strongly suggest you do not parse or record
+output via redirect in combination with this option, since you may receive
+duplicate data.
By default curl will not error on an HTTP response code that indicates an HTTP
error, if the transfer was successful. For example, if a server replies 404
Example: --retry-max-time 30 --retry 10 $URL
---
The retry timer is reset before the first transfer attempt. Retries will be
-done as usual (see --retry) as long as the timer hasn't reached this given
-limit. Notice that if the timer hasn't reached the limit, the request will be
+done as usual (see --retry) as long as the timer has not reached this given
+limit. Notice that if the timer has not reached the limit, the request will be
made and while performing, it may take longer than this given time period. To
limit a single request's maximum time, use --max-time. Set this option to
zero to not timeout retries.
Use this authorisation identity (authzid), during SASL PLAIN authentication,
in addition to the authentication identity (authcid) as specified by --user.
-If the option isn't specified, the server will derive the authzid from the
+If the option is not specified, the server will derive the authzid from the
authcid, but if specified, and depending on the server implementation, it may
be used to access another user's inbox, that the user has been granted access
to, or a shared mailbox for example.
Example: -s $URL
Added: 4.0
---
-Silent or quiet mode. Don't 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.
Example: --ssl-allow-beast $URL
---
This option tells curl to not work around a security flaw in the SSL3 and
-TLS1.0 protocols known as BEAST. If this option isn't used, the SSL layer may
-use workarounds known to cause interoperability problems with some older SSL
-implementations.
+TLS1.0 protocols known as BEAST. If this option is not used, the SSL layer
+may use workarounds known to cause interoperability problems with some older
+SSL implementations.
**WARNING**: this option loosens the SSL security, and by using this flag you
ask for exactly that.
Example: --ssl-reqd ftp://example.com
---
Require SSL/TLS for the connection. Terminates the connection if the server
-doesn't support SSL/TLS.
+does not support SSL/TLS.
This option was formerly known as --ftp-ssl-reqd.
Example: --ssl pop3://example.com/
---
Try to use SSL/TLS for the connection. Reverts to a non-secure connection if
-the server doesn't support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd
+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
Example: --suppress-connect-headers --include -x proxy $URL
Added: 7.54.0
---
-When --proxytunnel is used and a CONNECT request is made don't output proxy
+When --proxytunnel is used and a CONNECT request is made do not output proxy
CONNECT response headers. This option is meant to be used with --dump-header or
--include which are used to show protocol headers in the output. It has no
effect on debug options such as --verbose or --trace, or any statistics.
details about this option.
Since 7.50.2, curl sets this option by default and you need to explicitly
-switch it off if you don't want it on.
+switch it off if you do not want it on.
---
Request a file that has been modified later than the given time and date, or
one that has been modified before that time. The <date expression> can be all
-sorts of date strings or if it doesn't match any internal ones, it is taken as
+sorts of date strings or if it does not match any internal ones, it is taken as
a filename and tries to get the modification date (mtime) from <file>
instead. See the *curl_getdate(3)* man pages for date expression details.
Set password for use with the TLS authentication method specified with
--tlsauthtype. Requires that --tlsuser also be set.
-This doesn't work with TLS 1.3.
+This option does not work with TLS 1.3.
Set username for use with the TLS authentication method specified with
--tlsauthtype. Requires that --tlspassword also is set.
-This doesn't work with TLS 1.3.
+This option does not work with TLS 1.3.
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
-obtain a Kerberos Ticket. If you don't then the initial authentication
+obtain a Kerberos Ticket. If you do not, then the initial authentication
handshake may fail.
When using NTLM, the user name can be specified simply as the user name,
curl.
If you only want HTTP headers in the output, --include might be the option
-you're looking for.
+you are looking for.
-If you think this option still doesn't give you enough details, consider using
+If you think this option still does not give you enough details, consider using
--trace or --trace-ascii instead.
This option is global and does not need to be specified for each use of
same index number as the origin globbed URL. (Added in 7.75.0)
.TP
.B url_effective
-The URL that was fetched last. This is most meaningful if you've told curl
+The URL that was fetched last. This is most meaningful if you have told curl
to follow location: headers.
.RE
.IP
`curl-config --cc --cflags --libs` -o example example.c
-Some compilers don't like having the arguments in this order but instead
+Some compilers do not like having the arguments in this order but instead
want you do reorganize them like:
`curl-config --cc` -o example example.c `curl-config --cflags --libs`
**Please** do not use the `curl.se` site as a test target for your
libcurl applications/experiments. Even if some of the examples use that site
-as a URL at some places, it doesn't mean that the URLs work or that we expect
+as a URL at some places, it does not mean that the URLs work or that we expect
you to actually torture our website with your tests! Thanks.
## Examples
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* set user name and password for the authentication */
curl_easy_setopt(curl, CURLOPT_USERPWD, "user:password");
- /* Now run off and do what you've been told! */
+ /* Now run off and do what you have been told! */
res = curl_easy_perform(curl);
/* Check for errors */
if(res != CURLE_OK)
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* send all data to this function */
curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, WriteCallback);
- /* some servers don't like requests that are made without a user-agent
+ /* some servers do not like requests that are made without a user-agent
field, so we provide one */
curl_easy_setopt(curl_handle, CURLOPT_USERAGENT,
"libcurl-speedchecker/" CHKSPEED_VERSION);
/* cleanup curl stuff */
curl_easy_cleanup(curl_handle);
- /* we're done with libcurl, so clean it up */
+ /* we are done with libcurl, so clean it up */
curl_global_cleanup();
return 0;
return 1;
}
- /* HTTP-header style cookie. If you use the Set-Cookie format and don't
+ /* HTTP-header style cookie. If you use the Set-Cookie format and do not
specify a domain then the cookie is sent for any domain and will not be
modified, likely not what you intended. Starting in 7.43.0 any-domain
cookies will not be exported either. For more information refer to the
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * Copyright (c) 2000 - 2020 David Odin (aka DindinX) for MandrakeSoft
+ * Copyright (c) 2000 - 2021 David Odin (aka DindinX) for MandrakeSoft
*/
/* <DESC>
* use the libcurl in a gtk-threaded application
gtk_widget_show_all(Window);
if(!g_thread_create(&my_thread, argv[1], FALSE, NULL) != 0)
- g_warning("can't create the thread");
+ g_warning("cannot create the thread");
gdk_threads_enter();
gtk_main();
err = read(g->tfd, &count, sizeof(uint64_t));
if(err == -1) {
- /* Note that we may call the timer callback even if the timerfd isn't
+ /* Note that we may call the timer callback even if the timerfd is not
* readable. It's possible that there are multiple events stored in the
* epoll buffer (i.e. the timer may have fired multiple times). The
* event count is cleared after the first call so future events in the
curl_multi_setopt(g.multi, CURLMOPT_TIMERFUNCTION, multi_timer_cb);
curl_multi_setopt(g.multi, CURLMOPT_TIMERDATA, &g);
- /* we don't call any curl_multi_socket*() function yet as we have no handles
+ /* we do not call any curl_multi_socket*() function yet as we have no handles
added! */
fprintf(MSG_OUT, "Entering wait loop\n");
curl_multi_setopt(g.multi, CURLMOPT_TIMERFUNCTION, multi_timer_cb);
curl_multi_setopt(g.multi, CURLMOPT_TIMERDATA, &g);
- /* we don't call any curl_multi_socket*() function yet as we have no handles
+ /* we do not call any curl_multi_socket*() function yet as we have no handles
added! */
ev_loop(g.loop, 0);
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
fd = fopen("debugit", "rb"); /* open file to upload */
if(!fd)
- return 1; /* can't continue */
+ return 1; /* cannot continue */
/* to get the file size */
if(fstat(fileno(fd), &file_info) != 0)
- return 1; /* can't continue */
+ return 1; /* cannot continue */
curl = curl_easy_init();
if(curl) {
CURLMcode mc; /* curl_multi_fdset() return code */
/* only attempt to fill buffer if transactions still running and buffer
- * doesn't exceed required size already
+ * does not exceed required size already
*/
if((!file->still_running) || (file->buffer_pos > want))
return 0;
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* open file for writing */
out->stream = fopen(out->filename, "wb");
if(!out->stream)
- return -1; /* failure, can't open file to write */
+ return -1; /* failure, cannot open file to write */
}
return fwrite(buffer, size, nmemb, out->stream);
}
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* open file for writing */
out->stream = fopen(out->filename, "wb");
if(!out->stream)
- return -1; /* failure, can't open file to write */
+ return -1; /* failure, cannot open file to write */
}
return fwrite(buffer, size, nmemb, out->stream);
}
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE,
(curl_off_t)fsize);
- /* Now run off and do what you've been told! */
+ /* Now run off and do what you have been told! */
res = curl_easy_perform(curl);
/* Check for errors */
if(res != CURLE_OK)
/* we pass our 'chunk' struct to the callback function */
curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)&chunk);
- /* some servers don't like requests that are made without a user-agent
+ /* some servers do not like requests that are made without a user-agent
field, so we provide one */
curl_easy_setopt(curl_handle, CURLOPT_USERAGENT, "libcurl-agent/1.0");
free(chunk.memory);
- /* we're done with libcurl, so clean it up */
+ /* we are done with libcurl, so clean it up */
curl_global_cleanup();
return 0;
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
curl_multi_setopt(g->multi, CURLMOPT_TIMERFUNCTION, update_timeout_cb);
curl_multi_setopt(g->multi, CURLMOPT_TIMERDATA, g);
- /* we don't call any curl_multi_socket*() function yet as we have no handles
+ /* we do not call any curl_multi_socket*() function yet as we have no handles
added! */
g_main_loop_run(gmain);
curl_multi_setopt(g.multi, CURLMOPT_TIMERFUNCTION, multi_timer_cb);
curl_multi_setopt(g.multi, CURLMOPT_TIMERDATA, &g);
- /* we don't call any curl_multi_socket*() function yet as we have no handles
+ /* we do not call any curl_multi_socket*() function yet as we have no handles
added! */
event_base_dispatch(g.evbase);
- /* this, of course, won't get called since only way to stop this program is
- via ctrl-C, but it is here to show how cleanup /would/ be done. */
+ /* this, of course, will not get called since only way to stop this program
+ is via ctrl-C, but it is here to show how cleanup /would/ be done. */
clean_fifo(&g);
event_del(&g.timer_event);
event_base_free(g.evbase);
printf(">\n");
}
else {
- /* if it doesn't have a name, then it's probably text, cdata, etc... */
+ /* if it does not have a name, then it's probably text, cdata, etc... */
TidyBuffer buf;
tidyBufInit(&buf);
tidyNodeGetText(doc, child, &buf);
#include <curl/mprintf.h>
#ifndef CURLPIPE_MULTIPLEX
-/* This little trick will just make sure that we don't enable pipelining for
+/* This little trick will just make sure that we do not enable pipelining for
libcurls old enough to not have this symbol. It is _not_ defined to zero in
a recent libcurl header. */
#define CURLPIPE_MULTIPLEX 0
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
(void)num_headers; /* unused */
if(pushindex == MAX_FILES)
- /* can't fit anymore */
+ /* cannot fit anymore */
return CURL_PUSH_DENY;
/* write to this buffer */
#include <curl/curl.h>
#ifndef CURLPIPE_MULTIPLEX
-#error "too old libcurl, can't do HTTP/2 server push!"
+#error "too old libcurl, cannot do HTTP/2 server push!"
#endif
static
/* here's a new stream, save it in a new file for each new push */
out = fopen(filename, "wb");
if(!out) {
- /* if we can't save it, deny it */
+ /* if we cannot save it, deny it */
fprintf(stderr, "Failed to create output file for push\n");
return CURL_PUSH_DENY;
}
#include <curl/mprintf.h>
#ifndef CURLPIPE_MULTIPLEX
-/* This little trick will just make sure that we don't enable pipelining for
+/* This little trick will just make sure that we do not enable pipelining for
libcurls old enough to not have this symbol. It is _not_ defined to zero in
a recent libcurl header. */
#define CURLPIPE_MULTIPLEX 0
known_offset = 1;
}
secs = epoch_offset + tv.tv_sec;
- now = localtime(&secs); /* not thread safe but we don't care */
+ now = localtime(&secs); /* not thread safe but we do not care */
curl_msnprintf(timebuf, sizeof(timebuf), "%02d:%02d:%02d.%06ld",
now->tm_hour, now->tm_min, now->tm_sec, (long)tv.tv_usec);
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
- /* Forcing HTTP/3 will make the connection fail if the server isn't
+ /* Forcing HTTP/3 will make the connection fail if the server is not
accessible over QUIC + HTTP/3 on the given host and port.
Consider using CURLOPT_ALTSVC instead! */
curl_easy_setopt(curl, CURLOPT_HTTP_VERSION, (long)CURL_HTTP_VERSION_3);
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
chunk = curl_slist_append(chunk, "Host: example.com");
/* Add a header with "blank" contents to the right of the colon. Note that
- we're then using a semicolon in the string we pass to curl! */
+ we are then using a semicolon in the string we pass to curl! */
chunk = curl_slist_append(chunk, "X-silly-header;");
/* set our custom set of headers */
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
headers = curl_slist_append(headers, "Content-Type: literature/classic");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
- /* pass on content in request body. When CURLOPT_POSTFIELDSIZE isn't used,
+ /* pass on content in request body. When CURLOPT_POSTFIELDSIZE is not used,
curl does strlen to get the size. */
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, olivertwist);
name, not only a directory */
curl_easy_setopt(curl, CURLOPT_URL, url);
- /* Now run off and do what you've been told! */
+ /* Now run off and do what you have been told! */
res = curl_easy_perform(curl);
/* Check for errors */
if(res != CURLE_OK)
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE,
(curl_off_t)file_info.st_size);
- /* Now run off and do what you've been told! */
+ /* Now run off and do what you have been told! */
res = curl_easy_perform(curl);
/* Check for errors */
if(res != CURLE_OK)
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
#ifdef SKIP_PEER_VERIFICATION
/*
- * If you want to connect to a site who isn't using a certificate that is
+ * If you want to connect to a site who is not using a certificate that is
* signed by one of the certs in the CA bundle you have, you can skip the
* verification of the server's certificate. This makes the connection
* A LOT LESS SECURE.
#ifdef SKIP_HOSTNAME_VERIFICATION
/*
- * If the site you're connecting to uses a different host name that what
+ * If the site you are connecting to uses a different host name that what
* they have mentioned in their server certificate's commonName (or
* subjectAltName) fields, libcurl will refuse to connect. You can skip
* this check, but this will make the connection less secure.
* SELECT to ensure you are creating the message in the OUTBOX. */
curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/100");
- /* In this case, we're using a callback function to specify the data. You
+ /* In this case, we are using a callback function to specify the data. You
* could just use the CURLOPT_READDATA option to specify a FILE pointer to
* read from. */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
curl_easy_setopt(curl, CURLOPT_URL,
"imaps://imap.example.com/INBOX/;UID=1");
- /* If you want to connect to a site who isn't using a certificate that is
+ /* If you want to connect to a site who is not using a certificate that is
* signed by one of the certs in the CA bundle you have, you can skip the
* verification of the server's certificate. This makes the connection
* A LOT LESS SECURE.
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
#endif
- /* If the site you're connecting to uses a different host name that what
+ /* If the site you are connecting to uses a different host name that what
* they have mentioned in their server certificate's commonName (or
* subjectAltName) fields, libcurl will refuse to connect. You can skip
* this check, but this will make the connection less secure. */
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
curl_easy_strerror(res));
else {
/* Set the EXPUNGE command, although you can use the CLOSE command if you
- * don't want to know the result of the STORE */
+ * do not want to know the result of the STORE */
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "EXPUNGE");
/* Perform the second custom request */
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
curl_easy_setopt(curl, CURLOPT_URL,
"imap://imap.example.com/INBOX/;UID=1");
- /* In this example, we'll start with a plain text connection, and upgrade
+ /* In this example, we will start with a plain text connection, and upgrade
* to Transport Layer Security (TLS) using the STARTTLS command. Be careful
* of using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer
* will continue anyway - see the security discussion in the libcurl
* tutorial for more details. */
curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
- /* If your server doesn't have a valid certificate, then you can disable
+ /* If your server does not have a valid certificate, then you can disable
* part of the Transport Layer Security protection by setting the
* CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST options to 0 (false).
* curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
for(i = 0; i<HANDLECOUNT; i++)
handles[i] = curl_easy_init();
- /* set the options (I left out a few, you'll get the point anyway) */
+ /* set the options (I left out a few, you will get the point anyway) */
curl_easy_setopt(handles[HTTP_HANDLE], CURLOPT_URL, "https://example.com");
curl_easy_setopt(handles[FTP_HANDLE], CURLOPT_URL, "ftp://example.com");
http_handle = curl_easy_init();
- /* set the options (I left out a few, you'll get the point anyway) */
+ /* set the options (I left out a few, you will get the point anyway) */
curl_easy_setopt(http_handle, CURLOPT_URL, "https://www.example.com/");
curl_easy_setopt(http_handle, CURLOPT_DEBUGFUNCTION, my_trace);
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
}
else {
if(timeout_ms == 0)
- timeout_ms = 1; /* 0 means directly call socket_action, but we'll do it
+ timeout_ms = 1; /* 0 means directly call socket_action, but we will do it
in a bit */
struct timeval tv;
tv.tv_sec = timeout_ms / 1000;
for(i = 0; i<HANDLECOUNT; i++)
handles[i] = curl_easy_init();
- /* set the options (I left out a few, you'll get the point anyway) */
+ /* set the options (I left out a few, you will get the point anyway) */
curl_easy_setopt(handles[HTTP_HANDLE], CURLOPT_URL, "https://example.com");
curl_easy_setopt(handles[FTP_HANDLE], CURLOPT_URL, "ftp://example.com");
http_handle = curl_easy_init();
- /* set the options (I left out a few, you'll get the point anyway) */
+ /* set the options (I left out a few, you will get the point anyway) */
curl_easy_setopt(http_handle, CURLOPT_URL, "https://www.example.com/");
/* init a multi stack */
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
}
else {
if(timeout_ms == 0)
- timeout_ms = 1; /* 0 means directly call socket_action, but we'll do it
+ timeout_ms = 1; /* 0 means directly call socket_action, but we will do it
in a bit */
uv_timer_start(&timeout, on_timeout, timeout_ms, 0);
}
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
* pop3s:// rather than pop3:// to request a SSL based connection. */
curl_easy_setopt(curl, CURLOPT_URL, "pop3s://pop.example.com/1");
- /* If you want to connect to a site who isn't using a certificate that is
+ /* If you want to connect to a site who is not using a certificate that is
* signed by one of the certs in the CA bundle you have, you can skip the
* verification of the server's certificate. This makes the connection
* A LOT LESS SECURE.
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
#endif
- /* If the site you're connecting to uses a different host name that what
+ /* If the site you are connecting to uses a different host name that what
* they have mentioned in their server certificate's commonName (or
* subjectAltName) fields, libcurl will refuse to connect. You can skip
* this check, but this will make the connection less secure. */
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* This will retrieve message 1 from the user's mailbox */
curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1");
- /* In this example, we'll start with a plain text connection, and upgrade
+ /* In this example, we will start with a plain text connection, and upgrade
* to Transport Layer Security (TLS) using the STLS command. Be careful of
* using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer
* will continue anyway - see the security discussion in the libcurl
* tutorial for more details. */
curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
- /* If your server doesn't have a valid certificate, then you can disable
+ /* If your server does not have a valid certificate, then you can disable
* part of the Transport Layer Security protection by setting the
* CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST options to 0 (false).
* curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* we pass our 'chunk' struct to the callback function */
curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);
- /* some servers don't like requests that are made without a user-agent
+ /* some servers do not like requests that are made without a user-agent
field, so we provide one */
curl_easy_setopt(curl, CURLOPT_USERAGENT, "libcurl-agent/1.0");
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, postthis);
- /* if we don't provide POSTFIELDSIZE, libcurl will strlen() by
+ /* if we do not provide POSTFIELDSIZE, libcurl will strlen() by
itself */
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long)strlen(postthis));
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* Example code that uploads a file name 'foo' to a remote script that accepts
* "HTML form based" (as described in RFC1738) uploads using HTTP POST.
*
- * The imaginary form we'll fill in looks like:
+ * The imaginary form we will fill in looks like:
*
* <form method="post" enctype="multipart/form-data" action="examplepost.cgi">
* Enter file: <input type="file" name="sendfile" size="40">
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* Example code that uploads a file name 'foo' to a remote script that accepts
* "HTML form based" (as described in RFC1738) uploads using HTTP POST.
*
- * The imaginary form we'll fill in looks like:
+ * The imaginary form we will fill in looks like:
*
* <form method="post" enctype="multipart/form-data" action="examplepost.cgi">
* Enter file: <input type="file" name="sendfile" size="40">
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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 LIBCURL_VERSION_NUM >= 0x072000
/* xferinfo was introduced in 7.32.0, no earlier libcurl versions will
- compile as they won't have the symbols around.
+ compile as they will not have the symbols around.
If built with a newer libcurl, but running with an older libcurl:
curl_easy_setopt() will fail in run-time trying to set the new
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
const char *request = "GET / HTTP/1.0\r\nHost: example.com\r\n\r\n";
size_t request_len = strlen(request);
- /* A general note of caution here: if you're using curl_easy_recv() or
+ /* A general note of caution here: if you are using curl_easy_recv() or
curl_easy_send() to implement HTTP or _any_ other protocol libcurl
- supports "natively", you're doing it wrong and you should stop.
+ supports "natively", you are doing it wrong and you should stop.
This example uses HTTP only to show how to use this API, it does not
suggest that writing an application doing this is sensible.
return 1;
}
- /* Extract the socket from the curl handle - we'll need it for waiting. */
+ /* Extract the socket from the curl handle - we will need it for
+ waiting. */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
if(res != CURLE_OK) {
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/*
* This is an example showing how to get a single file from an SFTP server.
* It delays the actual destination file creation until the first write
- * callback so that it won't create an empty file in case the remote file
- * doesn't exist or something else fails.
+ * callback so that it will not create an empty file in case the remote file
+ * does not exist or something else fails.
*/
struct FtpFile {
/* open file for writing */
out->stream = fopen(out->filename, "wb");
if(!out->stream)
- return -1; /* failure, can't open file to write */
+ return -1; /* failure, cannot open file to write */
}
return fwrite(buffer, size, nmemb, out->stream);
}
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, postthis);
- /* if we don't provide POSTFIELDSIZE, libcurl will strlen() by
+ /* if we do not provide POSTFIELDSIZE, libcurl will strlen() by
itself */
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long)strlen(postthis));
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
3.1. set a #define USE_ENGINE
3.2. set pEngine to the name of the crypto engine you use
3.3. set pKeyName to the key identifier you want to use
- 4. if you don't use a crypto engine:
+ 4. if you do not use a crypto engine:
4.1. set pKeyName to the file name of your client key
4.2. if the format of the key file is DER, set pKeyType to "DER"
/* use crypto engine */
if(curl_easy_setopt(curl, CURLOPT_SSLENGINE, pEngine) != CURLE_OK) {
/* load the crypto engine */
- fprintf(stderr, "can't set crypto engine\n");
+ fprintf(stderr, "cannot set crypto engine\n");
break;
}
if(curl_easy_setopt(curl, CURLOPT_SSLENGINE_DEFAULT, 1L) != CURLE_OK) {
/* set the crypto engine as default */
/* only needed for the first time you load
a engine in a curl object... */
- fprintf(stderr, "can't set crypto engine as default\n");
+ fprintf(stderr, "cannot set crypto engine as default\n");
break;
}
}
/* set the file with the certs vaildating the server */
curl_easy_setopt(curl, CURLOPT_CAINFO, pCACertFile);
- /* disconnect if we can't validate server's cert */
+ /* disconnect if we cannot validate server's cert */
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
/* Perform the request, res will get the return code */
pthread_t tid[NUMT];
int i;
- /* Make sure I don't create more threads than urls. */
+ /* Make sure I do not create more threads than urls. */
for(i = 0; i < NUMT && i < num_urls ; i++) {
int error = pthread_create(&tid[i],
NULL, /* default attributes please */
G_CALLBACK(cb_delete), NULL);
if(!g_thread_create(&create_thread, progress_bar, FALSE, NULL) != 0)
- g_warning("can't create the thread");
+ g_warning("cannot create the thread");
gtk_main();
gdk_threads_leave();
/* Force PLAIN authentication */
curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=PLAIN");
- /* Note that this option isn't strictly required, omitting it will result
+ /* Note that this option is not strictly required, omitting it will result
* in libcurl sending the MAIL FROM command with empty sender data. All
* autoresponses should have an empty reverse-path, and should be directed
* to the address in the reverse-path which triggered them. Otherwise,
recipients = curl_slist_append(recipients, TO_ADDR);
curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
- /* We're using a callback function to specify the payload (the headers and
+ /* We are using a callback function to specify the payload (the headers and
* body of the message). You could just use the CURLOPT_READDATA option to
* specify a FILE pointer to read from. */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
/* Free the list of recipients */
curl_slist_free_all(recipients);
- /* curl won't send the QUIT command until you call cleanup, so you should
- * be able to re-use this connection for additional messages (setting
- * CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and calling
- * curl_easy_perform() again. It may not be a good idea to keep the
- * connection open for a very long time though (more than a few minutes
- * may result in the server timing out the connection), and you do want to
- * clean up in the end.
+ /* curl will not send the QUIT command until you call cleanup, so you
+ * should be able to re-use this connection for additional messages
+ * (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and
+ * calling curl_easy_perform() again. It may not be a good idea to keep
+ * the connection open for a very long time though (more than a few
+ * minutes may result in the server timing out the connection), and you do
+ * want to clean up in the end.
*/
curl_easy_cleanup(curl);
}
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* Free the list of recipients */
curl_slist_free_all(recipients);
- /* Curl won't send the QUIT command until you call cleanup, so you should
- * be able to re-use this connection for additional requests. It may not be
- * a good idea to keep the connection open for a very long time though
- * (more than a few minutes may result in the server timing out the
+ /* curl will not send the QUIT command until you call cleanup, so you
+ * should be able to re-use this connection for additional requests. It
+ * may not be a good idea to keep the connection open for a very long time
+ * though (more than a few minutes may result in the server timing out the
* connection) and you do want to clean up in the end.
*/
curl_easy_cleanup(curl);
/* This is the URL for your mailserver */
curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com");
- /* Note that this option isn't strictly required, omitting it will result
+ /* Note that this option is not strictly required, omitting it will result
* in libcurl sending the MAIL FROM command with empty sender data. All
* autoresponses should have an empty reverse-path, and should be directed
* to the address in the reverse-path which triggered them. Otherwise,
recipients = curl_slist_append(recipients, CC_ADDR);
curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
- /* We're using a callback function to specify the payload (the headers and
+ /* We are using a callback function to specify the payload (the headers and
* body of the message). You could just use the CURLOPT_READDATA option to
* specify a FILE pointer to read from. */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
/* Free the list of recipients */
curl_slist_free_all(recipients);
- /* curl won't send the QUIT command until you call cleanup, so you should
- * be able to re-use this connection for additional messages (setting
- * CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and calling
- * curl_easy_perform() again. It may not be a good idea to keep the
- * connection open for a very long time though (more than a few minutes
- * may result in the server timing out the connection), and you do want to
- * clean up in the end.
+ /* curl will not send the QUIT command until you call cleanup, so you
+ * should be able to re-use this connection for additional messages
+ * (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and
+ * calling curl_easy_perform() again. It may not be a good idea to keep
+ * the connection open for a very long time though (more than a few
+ * minutes may result in the server timing out the connection), and you do
+ * want to clean up in the end.
*/
curl_easy_cleanup(curl);
}
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
/* This is the URL for your mailserver */
curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com");
- /* Note that this option isn't strictly required, omitting it will result
+ /* Note that this option is not strictly required, omitting it will result
* in libcurl sending the MAIL FROM command with empty sender data. All
* autoresponses should have an empty reverse-path, and should be directed
* to the address in the reverse-path which triggered them. Otherwise,
curl_slist_free_all(recipients);
curl_slist_free_all(headers);
- /* curl won't send the QUIT command until you call cleanup, so you should
- * be able to re-use this connection for additional messages (setting
- * CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and calling
- * curl_easy_perform() again. It may not be a good idea to keep the
- * connection open for a very long time though (more than a few minutes
- * may result in the server timing out the connection), and you do want to
- * clean up in the end.
+ /* curl will not send the QUIT command until you call cleanup, so you
+ * should be able to re-use this connection for additional messages
+ * (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and
+ * calling curl_easy_perform() again. It may not be a good idea to keep
+ * the connection open for a very long time though (more than a few
+ * minutes may result in the server timing out the connection), and you do
+ * want to clean up in the end.
*/
curl_easy_cleanup(curl);
/* This is the URL for your mailserver */
curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com");
- /* Note that this option isn't strictly required, omitting it will result in
+ /* Note that this option is not strictly required, omitting it will result in
* libcurl sending the MAIL FROM command with empty sender data. All
* autoresponses should have an empty reverse-path, and should be directed
* to the address in the reverse-path which triggered them. Otherwise, they
recipients = curl_slist_append(recipients, CC_MAIL);
curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
- /* We're using a callback function to specify the payload (the headers and
+ /* We are using a callback function to specify the payload (the headers and
* body of the message). You could just use the CURLOPT_READDATA option to
* specify a FILE pointer to read from. */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
* than smtp:// to request a SSL based connection. */
curl_easy_setopt(curl, CURLOPT_URL, "smtps://mainserver.example.net");
- /* If you want to connect to a site who isn't using a certificate that is
+ /* If you want to connect to a site who is not using a certificate that is
* signed by one of the certs in the CA bundle you have, you can skip the
* verification of the server's certificate. This makes the connection
* A LOT LESS SECURE.
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
#endif
- /* If the site you're connecting to uses a different host name that what
+ /* If the site you are connecting to uses a different host name that what
* they have mentioned in their server certificate's commonName (or
* subjectAltName) fields, libcurl will refuse to connect. You can skip
* this check, but this will make the connection less secure. */
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
#endif
- /* Note that this option isn't strictly required, omitting it will result
+ /* Note that this option is not strictly required, omitting it will result
* in libcurl sending the MAIL FROM command with empty sender data. All
* autoresponses should have an empty reverse-path, and should be directed
* to the address in the reverse-path which triggered them. Otherwise,
recipients = curl_slist_append(recipients, CC_MAIL);
curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
- /* We're using a callback function to specify the payload (the headers and
+ /* We are using a callback function to specify the payload (the headers and
* body of the message). You could just use the CURLOPT_READDATA option to
* specify a FILE pointer to read from. */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
* matches your server configuration. */
curl_easy_setopt(curl, CURLOPT_URL, "smtp://mainserver.example.net:587");
- /* In this example, we'll start with a plain text connection, and upgrade
+ /* In this example, we will start with a plain text connection, and upgrade
* to Transport Layer Security (TLS) using the STARTTLS command. Be careful
* of using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer
* will continue anyway - see the security discussion in the libcurl
* tutorial for more details. */
curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
- /* If your server doesn't have a valid certificate, then you can disable
+ /* If your server does not have a valid certificate, then you can disable
* part of the Transport Layer Security protection by setting the
* CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST options to 0 (false).
* curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
* for more information. */
curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem");
- /* Note that this option isn't strictly required, omitting it will result
+ /* Note that this option is not strictly required, omitting it will result
* in libcurl sending the MAIL FROM command with empty sender data. All
* autoresponses should have an empty reverse-path, and should be directed
* to the address in the reverse-path which triggered them. Otherwise,
recipients = curl_slist_append(recipients, CC_MAIL);
curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
- /* We're using a callback function to specify the payload (the headers and
+ /* We are using a callback function to specify the payload (the headers and
* body of the message). You could just use the CURLOPT_READDATA option to
* specify a FILE pointer to read from. */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
* 1) This example requires libcurl 7.34.0 or above.
* 2) Not all email servers support this command and even if your email server
* does support it, it may respond with a 252 response code even though the
- * address doesn't exist.
+ * address does not exist.
*/
int main(void)
/* Free the list of recipients */
curl_slist_free_all(recipients);
- /* Curl won't send the QUIT command until you call cleanup, so you should
- * be able to re-use this connection for additional requests. It may not be
- * a good idea to keep the connection open for a very long time though
- * (more than a few minutes may result in the server timing out the
+ /* curl will not send the QUIT command until you call cleanup, so you
+ * should be able to re-use this connection for additional requests. It
+ * may not be a good idea to keep the connection open for a very long time
+ * though (more than a few minutes may result in the server timing out the
* connection) and you do want to clean up in the end.
*/
curl_easy_cleanup(curl);
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
curl = curl_easy_init();
curl_easy_setopt(curl, CURLOPT_URL, url);
- /* this example doesn't verify the server's certificate, which means we
+ /* this example does not verify the server's certificate, which means we
might be downloading stuff from an impostor */
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
{
pthread_t tid[NUMT];
int i;
- (void)argc; /* we don't use any arguments in this example */
+ (void)argc; /* we do not use any arguments in this example */
(void)argv;
/* Must initialize libcurl before any threads are started */
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * 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
size_t real_size = length * nmemb;
struct ParserStruct *state = (struct ParserStruct *) XML_GetUserData(parser);
- /* Only parse if we're not already in a failure state. */
+ /* Only parse if we are not already in a failure state. */
if(state->ok && XML_Parse(parser, contents, real_size, 0) == 0) {
int error_code = XML_GetErrorCode(parser);
fprintf(stderr, "Parsing response buffer of length %lu failed"
In libcurl land, you cannot tell by the libcurl version number if that
libcurl is binary compatible or not with another libcurl version. As a rule,
- we don't break the ABI so you can *always* upgrade to a later version without
+ we do not break the ABI so you can *always* upgrade to a later version without
any loss or change in functionality.
## Soname Bumps
## Downgrades
- Going to an older libcurl version from one you're currently using can be a
+ Going to an older libcurl version from one you are currently using can be a
tricky thing. Mostly we add features and options to newer libcurls as that
- won't break ABI or hamper existing applications. This has the implication
+ will not break ABI or hamper existing applications. This has the implication
that going backwards may get you in a situation where you pick a libcurl that
- doesn't support the options your application needs. Or possibly you even
+ does not support the options your application needs. Or possibly you even
downgrade so far so you cross an ABI break border and thus a different
soname, and then your application may need to adapt to the modified ABI.
This might close all connections this handle has used and possibly has kept
open until now - unless it was attached to a multi handle while doing the
-transfers. Don't call this function if you intend to transfer more files,
+transfers. Do not call this function if you intend to transfer more files,
re-using handles is a key to good performance with libcurl.
Occasionally you may get your progress callback or header callback called from
the input \fIstring\fP to find out the size. This function does not accept
input strings longer than \fBCURL_MAX_INPUT_LENGTH\fP (8 MB).
-You must \fIcurl_free(3)\fP the returned string when you're done with it.
+You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH ENCODING
libcurl is typically not aware of, nor does it care about, character
encodings. \fIcurl_easy_escape(3)\fP encodes the data byte-by-byte into the
A connection can be paused by using this function or by letting the read or
the write callbacks return the proper magic return code
(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback
-that returns pause signals to the library that it couldn't take care of any
+that returns pause signals to the library that it could not take care of any
data at all, and that data will then be delivered again to the callback when
the transfer is unpaused.
.IP CURLPAUSE_RECV
Pause receiving data. There will be no data received on this connection until
this function is called again without this bit set. Thus, the write callback
-(\fICURLOPT_WRITEFUNCTION(3)\fP) won't be called.
+(\fICURLOPT_WRITEFUNCTION(3)\fP) will not be called.
.IP CURLPAUSE_SEND
Pause sending data. There will be no data sent on this connection until this
function is called again without this bit set. Thus, the read callback
-(\fICURLOPT_READFUNCTION(3)\fP) won't be called.
+(\fICURLOPT_READFUNCTION(3)\fP) will not be called.
.IP CURLPAUSE_ALL
Convenience define that pauses both directions.
.IP CURLPAUSE_CONT
.fi
.SH "MEMORY USE"
When pausing a read by returning the magic return code from a write callback,
-the read data is already in libcurl's internal buffers so it'll have to keep
+the read data is already in libcurl's internal buffers so it will have to keep
it in an allocated buffer until the receiving is again unpaused using this
function.
if(res == CURLE_OK) {
/* Extract the socket from the curl handle -
- we'll need it for waiting. */
+ we will need it for waiting. */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
/* read data */
if(res == CURLE_OK) {
/* Extract the socket from the curl handle -
- we'll need it for waiting. */
+ we will need it for waiting. */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
/* send data */
.IP CURLOPT_XOAUTH2_BEARER
OAuth2 bearer token. See \fICURLOPT_XOAUTH2_BEARER(3)\fP
.IP CURLOPT_DISALLOW_USERNAME_IN_URL
-Don't allow username in URL. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP
+Do not allow username in URL. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP
.SH HTTP OPTIONS
.IP CURLOPT_AUTOREFERER
Automatically set Referer: header. See \fICURLOPT_AUTOREFERER(3)\fP
\fBCURLE_BAD_FUNCTION_ARGUMENT\fP is returned when the argument to an option
is invalid, like perhaps out of range.
-If you try to set an option that libcurl doesn't know about, perhaps because
+If you try to set an option that libcurl does not know about, perhaps because
the library is too old to support it or the option was removed in a recent
version, this function will return \fICURLE_UNKNOWN_OPTION\fP. If support for
the option was disabled at compile-time, it will return
longer string can be unescaped if the string length is returned in this
parameter.
-You must \fIcurl_free(3)\fP the returned string when you're done with it.
+You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
int decodelen;
char *decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen);
if(decoded) {
- /* don't assume printf() works on the decoded data! */
+ /* do not assume printf() works on the decoded data! */
printf("Decoded: ");
/* ... */
curl_free(decoded);
A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a
two-digit hexadecimal number).
-If the 'length' argument is set to 0, curl_escape() will use strlen() on the
-input 'url' string to find out the size.
+If the \fBlengthf\fP argument is set to 0, curl_escape() will use strlen() on
+the input \fBurl\fP string to find out the size.
-You must \fIcurl_free(3)\fP the returned string when you're done with it.
+You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH EXAMPLE
.nf
char *output = curl_escape("data to convert", 15);
curl_formadd() is used to append sections when building a multipart/formdata
HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
-at a time until you've added all the sections you want included and then you
+at a time until you have added all the sections you want included and then you
pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_HTTPPOST(3)\fP.
\fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated
invokes it should be left as set to allow repeated invokes to find the end of
First, there are some basics you need to understand about multipart/formdata
posts. Each part consists of at least a NAME and a CONTENTS part. If the part
is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
-Below, we'll discuss what options you use to set these properties in the
+Below, we will discuss what options you use to set these properties in the
parts you want to add to your post.
The options listed first are for making normal parts. The options from
.SH OPTIONS
.IP CURLFORM_COPYNAME
followed by a string which provides the \fIname\fP of this part. libcurl
-copies the string so your application doesn't need to keep it around after
-this function call. If the name isn't NUL-terminated, you must set its length
+copies the string so your application does not need to keep it around after
+this function call. If the name is not NUL-terminated, you must set its length
with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to contain
zero-valued bytes. The copied data will be freed by \fIcurl_formfree(3)\fP.
.IP CURLFORM_PTRNAME
followed by a string which provides the \fIname\fP of this part. libcurl
will use the pointer and refer to the data in your application, so you
must make sure it remains until curl no longer needs it. If the name
-isn't NUL-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
+is not NUL-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
The \fIname\fP is not allowed to contain zero-valued bytes.
.IP CURLFORM_COPYCONTENTS
followed by a pointer to the contents of this part, the actual data
-to send away. libcurl copies the provided data, so your application doesn't
-need to keep it around after this function call. If the data isn't null
-terminated, or if you'd like it to contain zero bytes, you must
+to send away. libcurl copies the provided data, so your application does not
+need to keep it around after this function call. If the data is not null
+terminated, or if you would like it to contain zero bytes, you must
set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
data will be freed by \fIcurl_formfree(3)\fP.
.IP CURLFORM_PTRCONTENTS
followed by a pointer to the contents of this part, the actual data
to send away. libcurl will use the pointer and refer to the data in your
application, so you must make sure it remains until curl no longer needs it.
-If the data isn't NUL-terminated, or if you'd like it to contain zero bytes,
+If the data is not NUL-terminated, or if you would like it to contain zero bytes,
you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP.
.IP CURLFORM_CONTENTLEN
followed by a curl_off_t value giving the length of the contents. Note that
the POST occurs, if you free it before the post completes you may experience
problems.
-When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
+When you have passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
-you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
+you have called \fIcurl_easy_cleanup(3)\fP for the curl handle.
See example below.
.SH EXAMPLE
callback should return the buffer length passed to it on success.
If the \fBCURLFORM_STREAM\fP option is used in the formpost, it will prevent
-\fIcurl_formget(3)\fP from working until you've performed the actual HTTP
+\fIcurl_formget(3)\fP from working until you have performed the actual HTTP
request as only then will libcurl get the actual read callback to use!
.SH EXAMPLE
.nf
emulate its behavior and provide an identical interface for all operating
systems libcurl builds on (including win32).
-You must \fIcurl_free(3)\fP the returned string when you're done with it.
+You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH EXAMPLE
.nf
char *width = curl_getenv("COLUMNS");
A pointer to a null-terminated string or NULL if it failed to find the
specified name.
.SH NOTE
-Under unix operating systems, there isn't any point in returning an allocated
-memory, although other systems won't work properly if this isn't done. The
+Under unix operating systems, there is no point in returning an allocated
+memory, although other systems will not work properly if this is not done. The
unix implementation thus has to suffer slightly from the drawbacks of other
systems.
.SH "SEE ALSO"
\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 doesn't 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.
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. Don't use any other
-value unless you are familiar with it and mean to control internal operations of
-libcurl.
+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 doesn't 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.
\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 doesn't just mean no other thread that is using libcurl.
+This does not just mean no other thread that is using libcurl.
.SH EXAMPLE
.nf
/* choose a specific backend */
cause it to stop the current transfer.
If you stop the current transfer by returning 0 "pre-maturely" (i.e. before the
-server expected it, like when you've said you will upload N bytes and you
+server expected it, like when you have said you will upload N bytes and you
upload less than N bytes), you may experience that the server "hangs" waiting
-for the rest of the data that won't come.
+for the rest of the data that will not come.
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
connection re-use.
If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (and you
-really should if you're working event-based with
+really should if you are working event-based with
\fIcurl_multi_socket_action(3)\fP and friends), that callback will be called
from within this function to ask for an updated timer so that your main event
loop will get the activity on this handle to get started.
When set, the \fIsockptr\fP pointer will be passed to all future socket
callbacks for the specific \fIsockfd\fP socket.
-If the given \fIsockfd\fP isn't already in use by libcurl, this function will
+If the given \fIsockfd\fP is not already in use by libcurl, this function will
return an error.
libcurl only keeps one single pointer associated with a socket, so calling
When our socket-callback gets called by libcurl and we get to know about yet
another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out
the particular data so that when we get updates about this same socket again,
-we don't have to find the struct associated with this socket by ourselves.
+we do not have to find the struct associated with this socket by ourselves.
.SH "SEE ALSO"
.BR curl_multi_setopt "(3), " curl_multi_socket_action "(3) "
This function extracts file descriptor information from a given multi_handle.
libcurl returns its fd_set sets. The application can use these to select() on,
but be sure to FD_ZERO them before calling this function as
-\fIcurl_multi_fdset(3)\fP only adds its own descriptors, it doesn't zero or
+\fIcurl_multi_fdset(3)\fP only adds its own descriptors, it does not zero or
otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should
be called as soon as one of them is ready to be read from or written to.
If no file descriptors are set by libcurl, \fImax_fd\fP will contain -1 when
this function returns. Otherwise it will contain the highest descriptor number
libcurl set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl
-currently does something that isn't possible for your application to monitor
+currently does something that is not possible for your application to monitor
with a socket and unfortunately you can then not know exactly when the current
action is completed using select(). You then need to wait a while before you
proceed and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless
When doing select(), you should use \fIcurl_multi_timeout(3)\fP to figure out
how long to wait for action. Call \fIcurl_multi_perform(3)\fP even if no
activity has been seen on the fd_sets after the timeout expires as otherwise
-internal retries and timeouts may not work as you'd think and want.
+internal retries and timeouts may not work as you would think and want.
If one of the sockets used by libcurl happens to be larger than what can be
set in an fd_set, which on POSIX systems means that the file descriptor is
integer-pointer.
If the amount of \fIrunning_handles\fP is changed from the previous call (or
-is less than the amount of easy handles you've added to the multi handle), you
+is less than the amount of easy handles you have added to the multi handle), you
know that there is one or more transfers less "running". You can then call
\fIcurl_multi_info_read(3)\fP to get information about each individual
completed transfer, and that returned info includes CURLcode and more. If an
.SH RETURN VALUE
The standard CURLMcode for multi interface error codes. Note that it returns a
CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl
-doesn't know of.
+does not know of.
.SH "SEE ALSO"
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
.BR curl_multi_socket "(3), " curl_multi_info_read "(3)"
Proceeding means either doing the socket-style timeout action: call the
\fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set
-to CURL_SOCKET_TIMEOUT, or call \fIcurl_multi_perform(3)\fP if you're using
+to CURL_SOCKET_TIMEOUT, or call \fIcurl_multi_perform(3)\fP if you are using
the simpler and older multi interface approach.
The timeout value returned in the long \fBtimeout\fP points to, is in number
future. They will instead be made "available" by source code access only, and
then as curlx_strequal() and curlx_strenqual().
.SH RETURN VALUE
-Non-zero if the strings are identical. Zero if they're not.
+Non-zero if the strings are identical. Zero if they are not.
.SH "SEE ALSO"
.BR strcmp "(3), " strcasecmp "(3)"
If the 'length' argument is set to 0, curl_unescape() will use strlen() on the
input 'url' string to find out the size.
-You must \fIcurl_free(3)\fP the returned string when you're done with it.
+You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
int decodelen;
char *decoded = curl_unescape("%63%75%72%6c", 12, &decodelen);
if(decoded) {
- /* don't assume printf() works on the decoded data! */
+ /* do not assume printf() works on the decoded data! */
printf("Decoded: ");
/* ... */
curl_free(decoded);
encode on set with the CURLU_URLENCODE bit.
If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part will
-be appended on the end of the existing query - and if the previous part didn't
+be appended on the end of the existing query - and if the previous part did not
end with an ampersand (&), an ampersand will be inserted before the new
appended part.
permits empty authority sections, similar to how file scheme is handled.
.IP CURLU_PATH_AS_IS
When set for \fBCURLUPART_URL\fP, this makes libcurl skip the normalization of
-the path. That's the procedure where curl otherwise removes sequences of
+the path. That is the procedure where curl otherwise removes sequences of
dot-slash and dot-dot etc. The same option used for transfers is called
\fICURLOPT_PATH_AS_IS(3)\fP.
.IP CURLU_ALLOW_SPACE
.fi
\fIage\fP describes what the age of this struct is. The number depends on how
-new the libcurl you're using is. You are however guaranteed to get a struct
+new the libcurl you are using is. You are however guaranteed to get a struct
that you have a matching struct for in the header, as you tell libcurl your
"age" with the input argument.
(Added in 7.22.0)
.IP CURL_VERSION_PSL
libcurl was built with support for Mozilla's Public Suffix List. This makes
-libcurl ignore cookies with a domain that's on the list.
+libcurl ignore cookies with a domain that is on the list.
(Added in 7.47.0)
.IP CURL_VERSION_SPNEGO
libcurl was built with support for SPNEGO authentication (Simple and Protected
interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle.
You continue by setting all the options you want in the upcoming transfer, the
-most important among them is the URL itself (you can't transfer anything
+most important among them is the URL itself (you cannot transfer anything
without a specified URL as you may have figured out yourself). You might want
to set some callbacks as well that will be called from the library when data
is available etc. \fIcurl_easy_setopt(3)\fP is used for all this.
\fIcurl_easy_duphandle(3)\fP.
When all is setup, you tell libcurl to perform the transfer using
-\fIcurl_easy_perform(3)\fP. It will then do the entire operation and won't
+\fIcurl_easy_perform(3)\fP. It will then do the entire operation and will not
return until it is done (successfully or not).
After the transfer has been made, you can set new options and make another
-transfer, or if you're done, cleanup the session by calling
-\fIcurl_easy_cleanup(3)\fP. If you want persistent connections, you don't
+transfer, or if you are done, cleanup the session by calling
+\fIcurl_easy_cleanup(3)\fP. If you want persistent connections, you do not
cleanup immediately, but instead run ahead and perform other transfers using
the same easy handle.
.SH "SEE ALSO"
.IP CURL_SSL_BACKEND
When libcurl is built to support multiple SSL backends, it will select a
specific backend at first use. If no selection is done by the program using
-libcurl, this variable's selection will be used. Setting a name that isn't a
+libcurl, this variable's selection will be used. Setting a name that is not a
built-in alternative will make libcurl stay with the default.
SSL backend names (case-insensitive): bearssl, gnutls, gskit, mbedtls,
checked as the primary way to find the "current" home directory in which
the .netrc file is likely to exist.
.IP LOGNAME
-User name to use when invoking the ntlm-wb tool, if NTLMUSER wasn't set.
+User name to use when invoking the ntlm-wb tool, if NTLMUSER was not set.
.IP NO_PROXY
This has the same functionality as the \fICURLOPT_NOPROXY(3)\fP option: it
gives libcurl a comma-separated list of host name patterns for which libcurl
used to find the directory for NSS PKI database instead of the built-in.
.IP USER
User name to use when invoking the ntlm-wb tool, if NTLMUSER and LOGNAME
-weren't set.
+were not set.
.SH "Debug Variables"
There's a set of variables only recognized and used if libcurl was built
"debug enabled", which should never be true for a library used in production.
All fine. Proceed as usual.
.IP "CURLE_UNSUPPORTED_PROTOCOL (1)"
The URL you passed to libcurl used a protocol that this libcurl does not
-support. The support might be a compile-time option that you didn't use, it
+support. The support might be a compile-time option that you did not use, it
can be a misspelled protocol string or just a protocol libcurl has no code
for.
.IP "CURLE_FAILED_INIT (2)"
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
+problem, or a resource problem where something fundamental could not get done
at init time.
.IP "CURLE_URL_MALFORMAT (3)"
The URL was not properly formatted.
.IP "CURLE_COULDNT_CONNECT (7)"
Failed to connect() to host or proxy.
.IP "CURLE_WEIRD_SERVER_REPLY (8)"
-The server sent data libcurl couldn't parse. This error code was known as as
+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
.IP "CURLE_PARTIAL_FILE (18)"
A file transfer was shorter or larger than expected. This happens when the
server first reports an expected transfer size, and then delivers data that
-doesn't match the previously given size.
+does not match the previously given size.
.IP "CURLE_FTP_COULDNT_RETR_FILE (19)"
This was either a weird reply to a 'RETR' command or a zero byte transfer
complete.
Operation timeout. The specified time-out period was reached according to the
conditions.
.IP "CURLE_FTP_PORT_FAILED (30)"
-The FTP PORT command returned error. This mostly happens when you haven't
+The FTP PORT command returned error. This mostly happens when you have not
specified a good enough address for libcurl to use. See
\fICURLOPT_FTPPORT(3)\fP.
.IP "CURLE_FTP_COULDNT_USE_REST (31)"
The download could not be resumed because the specified offset was out of the
file boundary.
.IP "CURLE_FILE_COULDNT_READ_FILE (37)"
-A file given with FILE:// couldn't be opened. Most likely because the file
-path doesn't identify an existing file. Did you check file permissions?
+A file given with FILE:// could not be opened. Most likely because the file
+path does not identify an existing file. Did you check file permissions?
.IP "CURLE_LDAP_CANNOT_BIND (38)"
LDAP cannot bind. LDAP bind operation failed.
.IP "CURLE_LDAP_SEARCH_FAILED (39)"
Nothing was returned from the server, and under the circumstances, getting
nothing is considered an error.
.IP "CURLE_SSL_ENGINE_NOTFOUND (53)"
-The specified crypto engine wasn't found.
+The specified crypto engine was not found.
.IP "CURLE_SSL_ENGINE_SETFAILED (54)"
Failed setting the selected SSL crypto engine as default!
.IP "CURLE_SEND_ERROR (55)"
.IP "CURLM_BAD_HANDLE (1)"
The passed-in handle is not a valid CURLM handle.
.IP "CURLM_BAD_EASY_HANDLE (2)"
-An easy handle was not good/valid. It could mean that it isn't an easy handle
+An easy handle was not good/valid. It could mean that it is not an easy handle
at all, or possibly that the handle already is in use by this or another multi
handle.
.IP "CURLM_OUT_OF_MEMORY (3)"
Not enough memory was available.
(Added in 7.12.0)
.IP "CURLSHE_NOT_BUILT_IN (5)"
-The requested sharing could not be done because the library you use don't have
+The requested sharing could not be done because the library you use do not have
that particular feature enabled. (Added in 7.23.0)
.SH "CURLUcode"
The URL interface will return a CURLUcode to indicate when an error has
.IP "CURLUE_BAD_PORT_NUMBER (4)"
The port number was not a decimal number between 0 and 65535.
.IP "CURLUE_UNSUPPORTED_SCHEME (5)"
-This libcurl build doesn't support the given URL scheme.
+This libcurl build does not support the given URL scheme.
.IP "CURLUE_URLDECODE (6)"
URL decode error, most likely because of rubbish in the input.
.IP "CURLUE_OUT_OF_MEMORY (7)"
All functions in the multi interface are prefixed with curl_multi.
.SH "OBJECTIVES"
-The multi interface offers several abilities that the easy interface doesn't.
+The multi interface offers several abilities that the easy interface does not.
They are mainly:
1. Enable a "pull" interface. The application that uses libcurl decides where
Remember that one of the main ideas with this interface is to let your
application drive. You drive the transfers by invoking
\fIcurl_multi_perform(3)\fP. libcurl will then transfer data if there is
-anything available to transfer. It'll use the callbacks and everything else
-you have setup in the individual easy handles. It'll transfer data on all
+anything available to transfer. it will use the callbacks and everything else
+you have setup in the individual easy handles. it will transfer data on all
current transfers in the multi stack that are ready to transfer anything. It
may be all, it may be none. When there's nothing more to do for now, it
returns back to the calling application.
better scale upward and beyond thousands of simultaneous transfers without
losing performance.
-When you've added your initial set of handles, you call
+When you have added your initial set of handles, you call
\fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the sockfd
-argument, and you'll get callbacks call that sets you up and you then continue
+argument, and you will get callbacks call that sets you up and you then continue
to call \fIcurl_multi_socket_action(3)\fP accordingly when you get activity on
-the sockets you've been asked to wait on, or if the timeout timer expires.
+the sockets you have been asked to wait on, or if the timeout timer expires.
You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has
completed, as it then has a message saying so.
For applications that enable .netrc use, a user who manage to set the right
URL might then be possible to pass on passwords.
-To avoid these problems, don't use .netrc files and never store passwords in
+To avoid these problems, do not use .netrc files and never store passwords in
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 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
+tool and eavesdrop on your passwords. do not 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
+does not let snoopers see your password: Digest, CRAM-MD5, Kerberos, SPNEGO or
NTLM authentication. Or even better: use authenticated protocols that protect
the entire connection and everything sent over it.
.SH "Un-authenticated Connections"
-Protocols that don't have any form of cryptographic authentication cannot
+Protocols that do not have any form of cryptographic authentication cannot
with any certainty know that they communicate with the right remote server.
If your application is using a fixed scheme or fixed host name, it is not safe
.SH "IPv6 Addresses"
libcurl will normally handle IPv6 addresses transparently and just as easily
as IPv4 addresses. That means that a sanitizing function that filters out
-addresses like 127.0.0.1 isn't sufficient--the equivalent IPv6 addresses ::1,
+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 shouldn't be accessed by a server-side libcurl-using
+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
order to protect applications for inadvertent probes of for example internal
networks etc. This resulted in CVE-2019-15601 and the associated security fix.
-However, we've since been made aware of the fact that the previous fix was far
+However, we have since been made aware of the fact that the previous fix was far
from adequate as there are several other ways to accomplish more or less the
same thing: accessing a remote host over the network instead of the local file
system.
The conclusion we have come to is that this is a weakness or feature in the
Windows operating system itself, that we as an application cannot safely
-protect users against. It would just be a whack-a-mole race we don't want to
+protect users against. It would just be a whack-a-mole race we do not want to
participate in. There are too many ways to do it and there's no knob we can
use to turn off the practice.
network. curl cannot protect you against this.
.SH "What if the user can set the URL"
Applications may find it tempting to let users set the URL that it can work
-on. That's probably fine, but opens up for mischief and trickery that you as
+on. That is probably fine, but opens up for mischief and trickery that you as
an application author may want to address or take precautions against.
If your curl-using script allow a custom URL do you also, perhaps
if creative use of special characters are applied?
If the user can set the URL, the user can also specify the scheme part to
-other protocols that you didn't intend for users to use and perhaps didn't
+other protocols that you did not intend for users to use and perhaps did not
consider. curl supports over 20 different URL schemes. "http://" might be what
you thought, "ftp://" or "imap://" might be what the user gives your
application. Also, cross-protocol operations might be done by using a
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
\fIcurl_share_setopt(3)\fP.
Since you can use this share from multiple threads, and libcurl has no
-internal thread synchronization, you must provide mutex callbacks if you're
+internal thread synchronization, you must provide mutex callbacks if you are
using this multi-threaded. You set lock and unlock functions with
\fIcurl_share_setopt(3)\fP too.
\fICURLOPT_SHARE(3)\fP to NULL for that easy handle. To make a handle stop
sharing a particular data, you can \fICURLSHOPT_UNSHARE\fP it.
-When you're done using the share, make sure that no easy handle is still using
+When you are done using the share, make sure that no easy handle is still using
it, and call \fIcurl_share_cleanup(3)\fP on the handle.
.SH "SEE ALSO"
.BR curl_share_init "(3), " curl_share_setopt "(3), " curl_share_cleanup "(3)"
\fBgethostby* functions and other system calls.\fP These functions, provided
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
+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
You program libcurl the same way on all platforms that libcurl runs on. There
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
+code portable enough, you can create a portable program. libcurl should not
stop you from that.
.SH "Global Preparation"
.RS
.IP "CURL_GLOBAL_WIN32"
which only does anything on Windows machines. When used on
-a Windows machine, it'll make libcurl initialize the win32 socket
+a Windows machine, it will make libcurl initialize the win32 socket
stuff. Without having that initialized properly, your program cannot use
sockets properly. You should only do this once for each application, so if
your program already does this or of another library in use does it, you
.RE
libcurl has a default protection mechanism that detects if
-\fIcurl_global_init(3)\fP hasn't been called by the time
+\fIcurl_global_init(3)\fP has not 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 good.
Many of the options you set in libcurl are "strings", pointers to data
terminated with a zero byte. When you set strings with
-\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they don't need
+\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they do not need
to be kept around in your application after being set[4].
One of the most basic properties to set in the handle is the URL. You set your
curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct);
Using that property, you can easily pass local data between your application
-and the function that gets invoked by libcurl. libcurl itself won't touch the
+and the function that gets invoked by libcurl. libcurl itself will not touch the
data you pass with \fICURLOPT_WRITEDATA(3)\fP.
libcurl offers its own default internal callback that will take care of the
-data if you don't set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It
+data if you do not set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It
will then simply output the received data to stdout. You can have the default
callback write the data to a different file handle by passing a 'FILE *' to a
file opened for writing with the \fICURLOPT_WRITEDATA(3)\fP option.
Now, we need to take a step back and have a deep breath. Here's one of those
rare platform-dependent nitpicks. Did you spot it? On some platforms[2],
-libcurl won't be able to operate on files opened by the program. Thus, if you
+libcurl will not be able to operate on files opened by the program. Thus, if you
use the default callback and pass in an open file with
\fICURLOPT_WRITEDATA(3)\fP, it will crash. You should therefore avoid this to
make your program run fine virtually everywhere.
(\fICURLOPT_WRITEDATA(3)\fP was formerly known as \fICURLOPT_FILE\fP. Both
names still work and do the same thing).
-If you're using libcurl as a win32 DLL, you MUST use the
+If you are using libcurl as a win32 DLL, you MUST use the
\fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP - or you
will experience crashes.
-There are of course many more options you can set, and we'll get back to a few
+There are of course many more options you can set, and we will get back to a few
of them later. Let's instead continue to the actual transfer:
success = curl_easy_perform(easyhandle);
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 isn't enough for
+you if it succeeded in its mission or not. If a return code is not enough for
you, you can use the \fICURLOPT_ERRORBUFFER(3)\fP to point libcurl to a buffer
-of yours where it'll store a human readable error message as well.
+of yours where it will store a human readable error message as well.
If you then want to transfer another file, the handle is ready to be used
again. Mind you, it is even preferred that you re-use an existing handle if
libcurl is thread safe but there are a few exceptions. Refer to
\fIlibcurl-thread(3)\fP for more information.
-.SH "When It Doesn't Work"
+.SH "When It does not Work"
There will always be times when the transfer fails for some reason. You might
have set the wrong libcurl option or misunderstood what the libcurl option
actually does, or the remote server might return non-standard replies that
confuse the library which then confuses your program.
There's one golden rule when these things occur: set the
-\fICURLOPT_VERBOSE(3)\fP option to 1. It'll cause the library to spew out the
+\fICURLOPT_VERBOSE(3)\fP option to 1. it will cause the library to spew out the
entire protocol details it sends, some internal info and some received
-protocol data as well (especially when using FTP). If you're using HTTP,
+protocol data as well (especially when using FTP). If you are using HTTP,
adding the headers in the received output to study is also a clever way to get
a better understanding why the server behaves the way it does. Include headers
in the normal body output with \fICURLOPT_HEADER(3)\fP set 1.
Of course, there are bugs left. We need to know about them to be able to fix
-them, so we're 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
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 understand libcurl and how
+and if you are 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"
curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, 1L);
-A few protocols won't behave properly when uploads are done without any prior
+A few protocols will not behave properly when uploads are done without any prior
knowledge of the expected file size. So, set the upload file size using the
\fICURLOPT_INFILESIZE_LARGE(3)\fP for all known file sizes like this[1]:
curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size);
.fi
-When you call \fIcurl_easy_perform(3)\fP this time, it'll perform all the
-necessary operations and when it has invoked the upload it'll call your
+When you call \fIcurl_easy_perform(3)\fP this time, it will perform all the
+necessary operations and when it has invoked the upload it will call your
supplied callback to get the data to upload. The program should return as much
data as possible in every invoke, as that is likely to make the upload perform
as fast as possible. The callback should return the number of bytes it wrote
All these examples have been cases where the password has been optional, or
at least you could leave it out and have libcurl attempt to do its job
-without it. There are times when the password isn't optional, like when
-you're using an SSL private key for secure transfers.
+without it. There are times when the password is not optional, like when
+you are using an SSL private key for secure transfers.
To pass the known private key password to libcurl:
.fi
While the simple examples above cover the majority of all cases where HTTP
-POST operations are required, they don't do multi-part formposts. Multi-part
+POST operations are required, they do not do multi-part formposts. Multi-part
formposts were introduced as a better way to post (possibly large) binary data
-and were first documented in the RFC1867 (updated in RFC2388). They're called
-multi-part because they're built by a chain of parts, each part being a single
+and were first documented in the RFC1867 (updated in RFC2388). they are called
+multi-part because they are built by a chain of parts, each part being a single
unit of data. Each part has its own name and contents. You can in fact create
and post a multi-part formpost with the regular libcurl POST support described
above, but that would require that you build a formpost yourself and provide
ought to be converted to the MIME API. It is however described here as an
aid to conversion.
-Using \fIcurl_formadd\fP, you add parts to the form. When you're done adding
+Using \fIcurl_formadd\fP, you add parts to the form. When you are done adding
parts, you post the whole form.
The MIME API example above is expressed as follows using this function:
If any of the input arguments is unknown, a 0 will be passed. The first
argument, the 'clientp' is the pointer you pass to libcurl with
-\fICURLOPT_PROGRESSDATA(3)\fP. libcurl won't touch it.
+\fICURLOPT_PROGRESSDATA(3)\fP. libcurl will not touch it.
.SH "libcurl with C++"
will ask the proxy for it instead of trying to connect to the actual host
identified in the URL.
-If you're using a SOCKS proxy, you may find that libcurl doesn't quite support
+If you are using a SOCKS proxy, you may find that libcurl does not quite support
all operations through it.
For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain
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 important to understand that all
-operations over an HTTP proxy use the HTTP protocol. For example, you can't
+operations over an HTTP proxy use the HTTP protocol. For example, you cannot
invoke your own custom FTP commands or even proper FTP directory listings.
.IP "Proxy Options"
and that is most likely *not* the one you would like it to be.
There are two special environment variables. 'all_proxy' is what sets proxy
-for any URL in case the protocol specific variable wasn't set, and
+for any URL in case the protocol specific variable was not set, and
\&'no_proxy' defines a list of hosts that should not use a proxy even though a
variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all
hosts.
this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS
proxy).
-libcurl has no means to interpret or evaluate Javascript and thus it doesn't
+libcurl has no means to interpret or evaluate Javascript and thus it does not
support this. If you get yourself in a position where you face this nasty
invention, the following advice have been mentioned and used in the past:
reduces re-connection time.
FTP connections that are kept alive save a lot of time, as the command-
-response round-trips are skipped, and also you don't risk getting blocked
+response round-trips are skipped, and also you do not risk getting blocked
without permission to login again like on many FTP servers only allowing N
persons to be logged in at the same time.
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
-you're about to operate on), you can do that by setting
+you are about to operate on), you can do that by setting
\fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar spirit, you can also forbid
the upcoming request to be "lying" around and possibly get re-used after the
request by setting \fICURLOPT_FORBID_REUSE(3)\fP to 1.
.SH "HTTP Headers Used by libcurl"
-When you use libcurl to do HTTP requests, it'll pass along a series of headers
+When you use libcurl to do HTTP requests, it will pass along a series of headers
automatically. It might be good for you to know and understand these. You
can replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option.
When using the custom request, you change the request keyword of the actual
request you are performing. Thus, by default you make a GET request but you can
also make a POST operation (as described before) and then replace the POST
-keyword if you want to. You're the boss.
+keyword if you want to. you are the boss.
.IP "Modify Headers"
HTTP-like protocols pass a series of headers to the server when doing the
-request, and you're free to pass any amount of extra headers that you
+request, and you are free to pass any amount of extra headers that you
think fit. Adding headers is this easy:
.nf
.fi
\&... and if you think some of the internally generated headers, such as
-Accept: or Host: don't contain the data you want them to contain, you can
+Accept: or Host: do not contain the data you want them to contain, you can
replace them by simply setting them too:
.nf
.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 old servers don't like
+we support. libcurl speaks HTTP 1.1 by default. Some old servers do not 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:
.IP "FTP Custom CUSTOMREQUEST"
If you do want to list the contents of an FTP directory using your own defined
FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP will do just that. "NLST" is the
-default one for listing directories but you're free to pass in your idea of a
+default one for listing directories but you are free to pass in your idea of a
good alternative.
.SH "Cookies Without Chocolate Chips"
the name and value to the client, and expects it to get sent back on every
subsequent request to the server that matches the particular conditions
set. The conditions include that the domain name and path match and that the
-cookie hasn't become too old.
+cookie has not become too old.
In real-world cases, servers send new cookies to replace existing ones to
update them. Server use cookies to "track" users and to keep "sessions".
Cookies are sent from server to clients with the header Set-Cookie: and
-they're sent from clients to servers with the Cookie: header.
+they are sent from clients to servers with the Cookie: header.
To just send whatever cookie you want to a server, you can use
\fICURLOPT_COOKIE(3)\fP to set a cookie string like this:
kept in memory and used properly in subsequent requests when the same handle
is used. Many times this is enough, and you may not have to save the cookies
to disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP
-doesn't have to exist to enable the parser, so a common way to just enable the
-parser and not read any cookies is to use the name of a file you know doesn't
+does not have to exist to enable the parser, so a common way to just enable the
+parser and not read any cookies is to use the name of a file you know does not
exist.
-If you would rather use existing cookies that you've previously received with
+If you would rather use existing cookies that you have previously received with
your Netscape or Mozilla browsers, you can make libcurl use that cookie file
as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as libcurl
will automatically find out what kind of file it is and act accordingly.
connect back to it. The first option is the default and it is also what works
best for all the people behind firewalls, NATs or IP-masquerading setups.
libcurl then tells the server to open up a new port and wait for a second
-connection. This is by default attempted with EPSV first, and if that doesn't
+connection. This is by default attempted with EPSV first, and if that does not
work it tries PASV instead. (EPSV is an extension to the original FTP spec
and does not exist nor work on all FTP servers.)
depend on that fact. It makes it easier for you to add custom header parsers
etc.
-\&"Headers" for FTP transfers equal all the FTP server responses. They aren't
+\&"Headers" for FTP transfers equal all the FTP server responses. They are not
actually true headers, but in this case we pretend they are! ;-)
.SH "Post Transfer Information"
See \fIcurl_easy_getinfo(3)\fP.
.SH "The multi Interface"
The easy interface as described in detail in this document is a synchronous
-interface that transfers one file at a time and doesn't return until it is
+interface that transfers one file at a time and does not return until it is
done.
The multi interface, on the other hand, allows your program to transfer
multi handle with \fIcurl_multi_init(3)\fP and add all those easy handles to
that multi handle with \fIcurl_multi_add_handle(3)\fP.
-When you've added the handles you have for the moment (you can still add new
+When you have added the handles you have for the moment (you can still add new
ones at any time), you start the transfers by calling
\fIcurl_multi_perform(3)\fP.
\fIcurl_multi_fdset(3)\fP, that fills in a set of fd_set variables for you
with the particular file descriptors libcurl uses for the moment.
-When you then call select(), it'll return when one of the file handles signal
+When you then call select(), it will 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 long timeouts on select() before you call
The DNS cache is shared between handles within a multi handle, making
subsequent name resolving faster, and the connection pool that is kept to
better allow persistent connections and connection re-use is also shared. If
-you're using the easy interface, you can still share these between specific
+you are using the easy interface, you can still share these between specific
easy handles by using the share interface, see \fIlibcurl-share(3)\fP.
Some things are never shared automatically, not within multi handles, like for
Extracted parts are not URL decoded unless the user also asks for it with the
CURLU_URLDECODE flag set in the fourth bitmask argument.
-Remember to free the returned string with \fIcurl_free(3)\fP when you're done
+Remember to free the returned string with \fIcurl_free(3)\fP when you are done
with it!
.SH "SET PARTS"
A user set individual URL parts, either after having parsed a full URL or
and developers to learn about libcurl and how to use it.
Run 'curl-config --libs' to get the (additional) linker options you need to
-link with the particular version of libcurl you've installed. See the
+link with the particular version of libcurl you have installed. See the
\fIcurl-config(1)\fP man page for further details.
Unix-like operating system that ship libcurl as part of their distributions
-often don't provide the curl-config tool, but simply install the library and
+often do not provide the curl-config tool, but simply install the library and
headers in the common path for this purpose.
Many Linux and similar systems use pkg-config to provide build and link
libcurl will \fBalways\fP attempt to use persistent connections. Whenever you
use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl
will attempt to use an existing connection to do the transfer, and if none
-exists it'll open a new one that will be subject for re-use on a possible
+exists it will open a new one that will be subject for re-use on a possible
following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
To allow libcurl to take full advantage of persistent connections, you should
If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all
the possibly open connections held by libcurl will be closed and forgotten.
-When you've created a multi handle and are using the multi interface, the
+When you have created a multi handle and are using the multi interface, the
connection pool is instead kept in the multi handle so closing and creating
new easy handles to do transfers will not affect them. Instead all added easy
handles can take advantage of the single shared pool.
You can call both of these multiple times, as long as all calls meet
these requirements and the number of calls to each is the same.
-It isn't actually required that the functions be called at the beginning
-and end of the program -- that's just usually the easiest way to do it.
+It is not actually required that the functions be called at the beginning
+and end of the program -- that is just usually the easiest way to do it.
It \fIis\fP required that the functions be called when no other thread
in the program is running.
These global constant functions are \fInot thread safe\fP, so you must
not call them when any other thread in the program is running. It
-isn't good enough that no other thread is using libcurl at the time,
+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 can't
+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,
-your code doesn't know about other parts of the program -- it doesn't
-know whether they use libcurl or not. And its code doesn't necessarily
+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
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
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's OK
+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).
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 hasn't been done
+\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
automatically when the program exits.
This failsafe feature exists mainly for backward compatibility because
-there was a time when the global functions didn't exist. Because it
+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.
\fICURLOPT_CONNECT_ONLY(3)\fP, which skips the transfer phase.
\fICURLINFO_ACTIVESOCKET(3)\fP was added as a replacement for
-\fICURLINFO_LASTSOCKET(3)\fP since that one isn't working on all platforms.
+\fICURLINFO_LASTSOCKET(3)\fP since that one is not working on all platforms.
.SH PROTOCOLS
All
.SH EXAMPLE
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO,
struct curl_certinfo **chainp);
.SH DESCRIPTION
-Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to
+Pass a pointer to a 'struct curl_certinfo *' and you will get it set to point to
a struct that holds a number of linked lists with info about the certificate
chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the request was
made. The struct reports how many certs it found and then you can extract info
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONDITION_UNMET, long *unmet);
.SH DESCRIPTION
Pass a pointer to a long to receive the number 1 if the condition provided in
-the previous request didn't match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas,
-if this returns a 1 you know that the reason you didn't get data in return is
-because it didn't fulfill the condition. The long this argument points to will
+the previous request did not match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas,
+if this returns a 1 you know that the reason you did not get data in return is
+because it did not fulfill the condition. The long this argument points to will
get a zero stored if the condition instead was met. This can also return 1 if
the server responded with a 304 HTTP status code, for example after sending a
custom "If-Match-*" header.
.SH DESCRIPTION
Pass a pointer to a double to receive the content-length of the download. This
is the value read from the Content-Length: field. Since 7.19.4, this returns
--1 if the size isn't known.
+-1 if the size is not known.
\fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP is a newer replacement that returns a more
sensible variable type.
.SH DESCRIPTION
Pass a pointer to a \fIcurl_off_t\fP to receive the content-length of the
download. This is the value read from the Content-Length: field. Stores -1 if
-the size isn't known.
+the size is not known.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
double *content_length);
.SH DESCRIPTION
Pass a pointer to a double to receive the specified size of the upload. Since
-7.19.4, this returns -1 if the size isn't known.
+7.19.4, this returns -1 if the size is not known.
\fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP is a newer replacement that returns a
more sensible variable type.
curl_off_t *content_length);
.SH DESCRIPTION
Pass a pointer to a \fIcurl_off_t\fP to receive the specified size of the
-upload. Stores -1 if the size isn't known.
+upload. Stores -1 if the size is not known.
.SH PROTOCOLS
All
.SH EXAMPLE
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the content-type of the downloaded
object. This is the value read from the Content-Type: field. If you get NULL,
-it means that the server didn't send a valid Content-Type header or that the
-protocol used doesn't support this.
+it means that the server did not send a valid Content-Type header or that the
+protocol used does not support this.
The \fBct\fP pointer will be NULL or pointing to private memory you MUST NOT
free it - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
struct curl_slist **cookies);
.SH DESCRIPTION
Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all
-cookies curl knows (expired ones, too). Don't forget to call
+cookies curl knows (expired ones, too). do not forget to call
\fIcurl_slist_free_all(3)\fP on the list after it has been used. If there are
no cookies (cookies for the handle have not been enabled or simply none have
been received) 'struct curl_slist *' will be set to point to NULL.
printf("%s\\n", each->data);
each = each->next;
}
- /* we must free these cookies when we're done */
+ /* we must free these cookies when we are done */
curl_slist_free_all(cookies);
}
}
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 not be
+In cases when you have 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
.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 not be the same
+In cases when you have 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
Pass a pointer to a long to receive the remote time of the retrieved document
(in number of seconds since 1 jan 1970 in the GMT/UTC time zone). If you get
-1, it can be because of many reasons (it might be unknown, the server might
-hide it or the server doesn't support the command that tells document time
+hide it or the server does not support the command that tells document time
etc) and the time of the document is unknown.
You must tell libcurl to collect this information before the transfer is made,
Pass a pointer to a curl_off_t to receive the remote time of the retrieved
document (in number of seconds since 1 jan 1970 in the GMT/UTC time zone). If
you get -1, it can be because of many reasons (it might be unknown, the server
-might hide it or the server doesn't support the command that tells document
+might hide it or the server does not support the command that tells document
time etc) and the time of the document is unknown.
You must ask libcurl to collect this information before the transfer is made,
Pass a pointer to a long to receive the version used in the last http
connection. The returned value will be CURL_HTTP_VERSION_1_0,
CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_3 or 0 if the
-version can't be determined.
+version cannot be determined.
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
- long sockfd; /* doesn't work on win64! */
+ long sockfd; /* does not work on win64! */
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Do not do the transfer - only connect to host */
.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
-handy if you think using the built-in libcurl redirect logic isn't good enough
+handy if you think using the built-in libcurl redirect logic is not good enough
for you but you would still prefer to avoid implementing all the magic of
figuring out the new URL.
While the HTTP header might contain a fixed date string, the
\fICURLINFO_RETRY_AFTER(3)\fP will always return number of seconds to wait -
-or zero if there was no header or the header couldn't be parsed.
+or zero if there was no header or the header could not be parsed.
.SH DEFAULT
Returns zero delay if there was no header.
.SH PROTOCOLS
OpenSSL crypto-engines supported. Note that engines are normally implemented
in separate dynamic libraries. Hence not all the returned engines may be
available at run-time. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP
-on the list pointer once you're done with it, as libcurl will not free the
+on the list pointer once you are done with it, as libcurl will not free the
data for you.
.SH PROTOCOLS
All TLS based ones.
If you are using OpenSSL or wolfSSL then \fICURLOPT_SSL_CTX_FUNCTION(3)\fP can
be used to set a certificate verification callback in the CTX. That is safer
-than using this option to poll for certificate changes and doesn't suffer from
+than using this option to poll for certificate changes and does not suffer from
any of the problems above. There is currently no way in libcurl to set a
verification callback for the other SSL backends.
"name:value" string that will be freed when this callback returns.
.IP curl_pushheader_byname
Returns the value for the given header name (or NULL). This is a shortcut so
-that the application doesn't have to loop through all headers to find the one
+that the application does not have to loop through all headers to find the one
it is interested in. The data pointed will be freed when this callback
returns. If more than one header field use the same name, this returns only
the first one.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPT_ENCODING, char *enc);
.SH DESCRIPTION
-Pass a char * argument specifying what encoding you'd like.
+Pass a char * argument specifying what encoding you would like.
Sets the contents of the Accept-Encoding: header sent in an HTTP request, and
enables decoding of a response when a Content-Encoding: header is received.
.SH AVAILABILITY
This option was called CURLOPT_ENCODING before 7.21.6
-The specific libcurl you're using must have been built with zlib to be able to
+The specific libcurl you are using must have been built with zlib to be able to
decompress gzip and deflate responses, with the brotli library to
decompress brotli responses and with the zstd library to decompress zstd
responses.
.SH NOTES
This option overrides the other auth types you might have set in CURL_HTTPAUTH
which should be highlighted as this makes this auth method special.
-This method can't be combined with other auth types.
+This method cannot be combined with other auth types.
.SH "SEE ALSO"
.BR CURLOPT_HEADEROPT "(3), " CURLOPT_HTTPHEADER "(3), "
}
.fi
.SH AVAILABILITY
-For the SSL engines that don't support certificate files the CURLOPT_CAINFO
+For the SSL engines that do not support certificate files the CURLOPT_CAINFO
option is ignored. Schannel support added in libcurl 7.60.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
network encoding. It is used when commands or ASCII data are received over
the network.
-If you set a callback pointer to NULL, or don't set it at all, the built-in
+If you set a callback pointer to NULL, or do not set it at all, the built-in
libcurl iconv functions will be used. If HAVE_ICONV was not defined when
libcurl was built, and no callback has been established, conversion will
return the CURLE_CONV_REQD error code.
\fBCURLOPT_CONV_FROM_UTF8_FUNCTION\fP converts to host encoding from UTF8
encoding. It is required only for SSL processing.
-If you set a callback pointer to NULL, or don't set it at all, the built-in
+If you set a callback pointer to NULL, or do not set it at all, the built-in
libcurl iconv functions will be used. If HAVE_ICONV was not defined when
libcurl was built, and no callback has been established, conversion will
return the CURLE_CONV_REQD error code.
network encoding. It is used when commands or ASCII data are sent over the
network.
-If you set a callback pointer to NULL, or don't set it at all, the built-in
+If you set a callback pointer to NULL, or do not set it at all, the built-in
libcurl iconv functions will be used. If HAVE_ICONV was not defined when
libcurl was built, and no callback has been established, conversion will
return the CURLE_CONV_REQD error code.
The cookies set by this option are separate from the internal cookie storage
held by the cookie engine and will not be modified by it. If you enable the
-cookie engine and either you've imported a cookie of the same name (e.g. 'foo')
+cookie engine and either you have imported a cookie of the same name (e.g. 'foo')
or the server has set one, it will have no effect on the cookies you set here.
A request to the server will send both the 'foo' held by the cookie engine and
the 'foo' held by this option. To set a cookie that is instead held by the
This option only \fBreads\fP cookies. To make libcurl write cookies to file,
see \fICURLOPT_COOKIEJAR(3)\fP.
-If you use the Set-Cookie file format and don't specify a domain then the
+If you use the Set-Cookie file format and do not specify a domain then the
cookie is not sent since the domain will never match. To address this, set a
domain in Set-Cookie line (doing that will include sub-domains) or preferably:
use the Netscape format.
stdout. Using this option also enables cookies for this session, so if you for
example follow a location it will make matching cookies get sent accordingly.
-Note that libcurl doesn't read any cookies from the cookie jar. If you want to
+Note that libcurl does not read any cookies from the cookie jar. If you want to
read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP.
-If the cookie jar file can't be created or written to (when the
+If the cookie jar file cannot be created or written to (when the
\fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an
error for this. Using \fICURLOPT_VERBOSE(3)\fP or
\fICURLOPT_DEBUGFUNCTION(3)\fP will get a warning to display, but that is the
cookie engine. This adds that single cookie to the internal cookie store.
Exercise caution if you are using this option and multiple transfers may occur.
-If you use the Set-Cookie format and don't specify a domain then the cookie is
+If you use the Set-Cookie format and do not specify a domain then the cookie is
sent for any domain (even after redirects are followed) and cannot be modified
by a server-set cookie. If a server sets a cookie of the same name (or maybe
-you've imported one) then both will be sent on a future transfer to that
+you have imported one) then both will be sent on a future transfer to that
server, likely not what you intended. To address these issues set a domain in
Set-Cookie (doing that will include sub-domains) or use the Netscape format as
shown in EXAMPLE.
before a transfer is performed. Cookies in the list that have the same
hostname, path and name as in my_cookie are skipped. That is because
libcurl has already imported my_cookie and it's considered a "live"
-cookie. A live cookie won't be replaced by one read from a file.
+cookie. A live cookie will not be replaced by one read from a file.
*/
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); /* import */
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
- /* new "session", don't load session cookies */
+ /* new "session", do not load session cookies */
curl_easy_setopt(curl, CURLOPT_COOKIESESSION, 1L);
/* get the (non session) cookies from this file */
Pass a pointer to a null-terminated string as parameter.
When you change the request method by setting \fICURLOPT_CUSTOMREQUEST(3)\fP
-to something, you don't actually change how libcurl behaves or acts in regards
+to something, you do not actually change how libcurl behaves or acts in regards
to the particular request method, it will only change the actual string sent
in the request.
include subdirectories and symbolic links.
Setting this option to 1 also implies a directory listing even if the URL
-doesn't end with a slash, which otherwise is necessary.
+does not end with a slash, which otherwise is necessary.
Do NOT use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it
will effectively break that feature then.
caching, or set to -1 to make the cached entries remain forever. By default,
libcurl caches this info for 60 seconds.
-The name resolve functions of various libc implementations don't re-read name
+The name resolve functions of various libc implementations do not re-read name
server information unless explicitly told so (for example, by calling
\fIres_init(3)\fP). This may cause libcurl to keep using the older server even
if DHCP has updated the server info, and this may look like a DNS cache issue
to the casual libcurl-app user.
-Note that DNS entries have a "TTL" property but libcurl doesn't use that. This
+Note that DNS entries have a "TTL" property but libcurl does not use that. This
DNS cache timeout is entirely speculative that a name will resolve to the same
address for a certain small amount of time into the future.
.SH DEFAULT
.SH DESCRIPTION
Pass a char * as parameter. Set the name of the network interface that the DNS
resolver should bind to. This must be an interface name (not an address). Set
-this option to NULL to use the default setting (don't bind to a specific
+this option to NULL to use the default setting (do not bind to a specific
interface).
The application does not have to keep the string around after setting this
.SH DESCRIPTION
Set the local IPv4 \fIaddress\fP that the resolver should bind to. The
argument should be of type char * and contain a single numerical IPv4 address
-as a string. Set this option to NULL to use the default setting (don't bind
+as a string. Set this option to NULL to use the default setting (do not bind
to a specific IP address).
The application does not have to keep the string around after setting this
.SH DESCRIPTION
Set the local IPv6 \fIaddress\fP that the resolver should bind to. The
argument should be of type char * and contain a single IPv6 address as a
-string. Set this option to NULL to use the default setting (don't bind to a
+string. Set this option to NULL to use the default setting (do not bind to a
specific IP address).
The application does not have to keep the string around after setting this
This option tells curl to verify the authenticity of the DoH (DNS-over-HTTPS)
server's certificate. A value of 1 means curl verifies; 0 (zero) means it
-doesn't.
+does not.
This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYPEER(3)\fP and
only affects requests to the DoH server.
Authenticating the certificate is not enough to be sure about the server. You
typically also want to ensure that the server is the server you mean to be
talking to. Use \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP for that. The check
-that the host name in the certificate is valid for the host name you're
+that the host name in the certificate is valid for the host name you are
connecting to is done independently of the
\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP option.
must be URL-encoded in the following format: "https://host:port/path". It MUST
specify a HTTPS URL.
-libcurl doesn't validate the syntax or use this variable until the transfer is
+libcurl does not validate the syntax or use this variable until the transfer is
issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will
still return \fICURLE_OK\fP.
A set \fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback is not inherited.
.SH DEFAULT
-NULL - there is no default DoH URL. If this option isn't set, libcurl will use
+NULL - there is no default DoH URL. If this option is not set, libcurl will use
the default name resolver.
.SH PROTOCOLS
All
Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
heap space.
-Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so
+Note that \fIcurl_easy_setopt(3)\fP will not actually parse the given string so
given a bad DoH URL, curl will not detect a problem until it tries to resolve
a name with it.
.SH "SEE ALSO"
impact performance.
Related functionality is \fICURLOPT_FORBID_REUSE(3)\fP which makes sure the
-connection is closed after use so that it won't be re-used.
+connection is closed after use so that it will not be re-used.
Set \fIfresh\fP to 0 to have libcurl attempt re-using an existing connection
(default behavior).
address. The string may be a plain IP address, a host name, a network
interface name (under Unix) or just a '-' symbol to let the library use your
system's default IP address. Default FTP operations are passive, and thus
-won't use PORT.
+will not use PORT.
The address can be followed by a ':' to specify a port, optionally followed by
a '-' to specify a port range. If the port specified is 0, the operating
changes working directory.
For SFTP requests, libcurl will attempt to create the remote directory if it
-can't obtain a handle to the target-location. The creation will fail if a file
+cannot obtain a handle to the target-location. The creation will fail if a file
of the same name as the directory to create already exists or lack of
permissions prevents creation.
Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to
retry the CWD command again if the subsequent MKD command fails. This is
-especially useful if you're doing many simultaneous connections against the
+especially useful if you are doing many simultaneous connections against the
same server and they all have this option enabled, as then CWD may first fail
but then another connection does MKD before this connection and thus MKD fails
but trying CWD works!
Pass a long telling libcurl which \fImethod\fP to use to reach a file on a
FTP(S) server.
-This option exists because some server implementations aren't compliant to
+This option exists because some server implementations are not compliant to
what the standards say should work.
The argument should be one of the following alternatives:
channel communication will be unencrypted. This allows NAT routers to follow
the FTP transaction. Pass a long using one of the values below
.IP CURLFTPSSL_CCC_NONE
-Don't attempt to use CCC.
+do not attempt to use CCC.
.IP CURLFTPSSL_CCC_PASSIVE
Do not initiate the shutdown, but wait for the server to do it. Do not send a
reply.
\fICURLOPT_HEADERDATA(3)\fP option.
This callback function must return the number of bytes actually taken care of.
-If that amount differs from the amount passed in to your function, it'll signal
+If that amount differs from the amount passed in to your function, it will signal
an error to the library. This will cause the transfer to get aborted and the
libcurl function in progress will return \fICURLE_WRITE_ERROR\fP.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADDATA, void *pointer);
.SH DESCRIPTION
Data \fIpointer\fP to pass to the HSTS read function. If you use the
-\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you'll get as
+\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you will get as
input in the 3rd argument to the callback.
-This option doesn't enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
+This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL
error. Returning \fICURLSTS_FAIL\fP will stop the transfer from being
performed and make \fICURLE_ABORTED_BY_CALLBACK\fP get returned.
-This option doesn't enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
+This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL - no callback.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEDATA, void *pointer);
.SH DESCRIPTION
Data \fIpointer\fP to pass to the HSTS write function. If you use the
-\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you'll get as
+\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you will get as
input in the 4th argument to the callback.
-This option doesn't enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
+This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL
be called again (for another host) or \fICURLSTS_DONE\fP if there's nothing
more to do. It can also return \fICURLSTS_FAIL\fP to signal error.
-This option doesn't enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
+This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL - no callback.
Note that the HTTP version is just a request. libcurl will still prioritize to
re-use an existing connection so it might then re-use a connection using a
-HTTP version you haven't asked for.
+HTTP version you have not asked for.
.IP CURL_HTTP_VERSION_NONE
-We don't care about what version the library uses. libcurl will use whatever
+We do not care about what version the library uses. libcurl will use whatever
it thinks fit.
.IP CURL_HTTP_VERSION_1_0
Enforce HTTP 1.0 requests.
.IP CURL_HTTP_VERSION_1_1
Enforce HTTP 1.1 requests.
.IP CURL_HTTP_VERSION_2_0
-Attempt HTTP 2 requests. libcurl will fall back to HTTP 1.1 if HTTP 2 can't be
+Attempt HTTP 2 requests. libcurl will fall back to HTTP 1.1 if HTTP 2 cannot be
negotiated with the server. (Added in 7.33.0)
The alias \fICURL_HTTP_VERSION_2\fP was added in 7.43.0 to better reflect the
actual protocol name.
.IP CURL_HTTP_VERSION_2TLS
Attempt HTTP 2 over TLS (HTTPS) only. libcurl will fall back to HTTP 1.1 if
-HTTP 2 can't be negotiated with the HTTPS server. For clear text HTTP servers,
+HTTP 2 cannot be negotiated with the HTTPS server. For clear text HTTP servers,
libcurl will use 1.1. (Added in 7.47.0)
.IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE
Issue non-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade. It requires
.IP CURL_HTTP_VERSION_3
(Added in 7.66.0) Setting this value will make libcurl attempt to use HTTP/3
directly to server given in the URL. Note that this cannot gracefully
-downgrade to earlier HTTP version if the server doesn't support HTTP/3.
+downgrade to earlier HTTP version if the server does not support HTTP/3.
For more reliably upgrading to HTTP/3, set the preferred version to something
lower and let the server announce its HTTP/3 support via Alt-Svc:. See
shown above.
This callback function gets called by libcurl when something special
-I/O-related needs to be done that the library can't do by itself. For now,
+I/O-related needs to be done that the library cannot do by itself. For now,
rewinding the read data stream is the only action it can request. The
rewinding of the read data stream may be necessary when doing an HTTP PUT or
POST with a multi-pass authentication method.
Pass a char * as parameter. Set the kerberos security level for FTP; this also
enables kerberos awareness. This is a string that should match one of the
following: \&'clear', \&'safe', \&'confidential' or \&'private'. If the
-string is set but doesn't match one of these, 'private' will be used. Set the
+string is set but does not match one of these, 'private' will be used. Set the
string to NULL to disable kerberos support for FTP.
The application does not have to keep the string around after setting this
.SH DESCRIPTION
Pass a long. The set \fIamount\fP will be the maximum number of simultaneously
open persistent connections that libcurl may cache in the pool associated with
-this handle. The default is 5, and there isn't much point in changing this
+this handle. The default is 5, and there is not much point in changing this
value unless you are perfectly aware of how this works and changes libcurl's
behavior. This concerns connections using any of the protocols that support
persistent connections.
If you set \fImaxspeed\fP to a value lower than \fICURLOPT_BUFFERSIZE(3)\fP,
libcurl might download faster than the set limit initially.
-This option doesn't affect transfer speeds done with FILE:// URLs.
+This option does not affect transfer speeds done with FILE:// URLs.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
\fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP, libcurl might "shoot over" the limit on
its first send and still send off a full buffer.
-This option doesn't affect transfer speeds done with FILE:// URLs.
+This option does not affect transfer speeds done with FILE:// URLs.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
the options controlled by this parameter.
Only machine name, user name and password are taken into account (init macros
-and similar things aren't supported).
+and similar things are not supported).
libcurl does not verify that the file has the correct properties set (as the
standard Unix ftp client does). It should only be readable by user.
"example.com,::1,localhost"
IPv6 numerical addresses are compared as strings, so they will only match if
-the representations are the same: "::1" is the same as "::0:1" but they don't
+the representations are the same: "::1" is the same as "::0:1" but they do not
match.
The application does not have to keep the string around after setting this
If you do not have the server's public key file you can extract it from the
server's certificate.
.nf
-# retrieve the server's certificate if you don't already have it
+# retrieve the server's certificate if you do not already have it
#
# be sure to examine the certificate to see if it is what you expected
#
# Windows-specific:
# - Use NUL instead of /dev/null.
# - OpenSSL may wait for input instead of disconnecting. Hit enter.
-# - If you don't have sed, then just copy the certificate into a file:
+# - If you do not have sed, then just copy the certificate into a file:
# Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
#
openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem
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 work well over proxy.
+All except file://. Note that some protocols do not work well over proxy.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually
get called.
.SH DEFAULT
-By default, libcurl has an internal progress meter. That's rarely wanted by
+By default, libcurl has an internal progress meter. That is rarely wanted by
users.
.SH PROTOCOLS
All
When you tell the library to use an HTTP proxy, libcurl will transparently
convert operations to HTTP even if you specify an FTP URL etc. This may have
an impact on what other features of the library you can use, such as
-\fICURLOPT_QUOTE(3)\fP and similar FTP specifics that don't work unless you
+\fICURLOPT_QUOTE(3)\fP and similar FTP specifics that do not work unless you
tunnel through the HTTP proxy. Such tunneling is activated with
\fICURLOPT_HTTPPROXYTUNNEL(3)\fP.
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 work well over proxy.
+All except file://. Note that some protocols do not work well over proxy.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
specified in the proxy string \fICURLOPT_PROXY(3)\fP or uses 443 for https
proxies and 1080 for all others as default.
-While this accepts a 'long', the port number is 16 bit so it can't be larger
+While this accepts a 'long', the port number is 16 bit so it cannot be larger
than 65535.
.SH DEFAULT
0, not specified which makes it use the default port
.SH AVAILABILITY
Added in 7.52.0
-For TLS backends that don't support certificate files, the
+For TLS backends that do not support certificate files, the
\fICURLOPT_PROXY_CAINFO(3)\fP option is ignored. Refer to
https://curl.se/docs/ssl-compared.html
.SH RETURN VALUE
If you do not have the https proxy server's public key file you can extract it
from the https proxy server's certificate.
.nf
-# retrieve the server's certificate if you don't already have it
+# retrieve the server's certificate if you do not already have it
#
# be sure to examine the certificate to see if it is what you expected
#
# Windows-specific:
# - Use NUL instead of /dev/null.
# - OpenSSL may wait for input instead of disconnecting. Hit enter.
-# - If you don't have sed, then just copy the certificate into a file:
+# - If you do not have sed, then just copy the certificate into a file:
# Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
#
openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem
set when you compile OpenSSL.
For NSS, valid examples of cipher lists include \fBrsa_rc4_128_md5\fP,
-\fBrsa_aes_128_sha\fP, etc. With NSS you don't add/remove ciphers. If one uses
+\fBrsa_aes_128_sha\fP, etc. With NSS you do not add/remove ciphers. If one uses
this option then all known ciphers are disabled and only those passed in are
enabled.
For WolfSSL, valid examples of cipher lists include \fBECDHE-RSA-RC4-SHA\fP,
\fBAES256-SHA:AES256-SHA256\fP, etc.
-You'll find more details about cipher lists on this URL:
+you will find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
behaviors. Available bits:
.IP CURLSSLOPT_ALLOW_BEAST
Tells libcurl to not attempt to use any workarounds for a security flaw in the
-SSL3 and TLS1.0 protocols. If this option isn't used or this bit is set to 0,
+SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0,
the SSL layer libcurl uses may use a work-around for this flaw although it
might cause interoperability problems with some (older) SSL
implementations. WARNING: avoiding this work-around lessens the security, and
Tells libcurl to disable certificate revocation checks for those SSL backends
where such behavior is present. This option is only supported for Schannel
(the native Windows SSL library), with an exception in the case of Windows'
-Untrusted Publishers block list which it seems can't be bypassed. (Added in
+Untrusted Publishers block list which it seems cannot be bypassed. (Added in
7.44.0)
.IP CURLSSLOPT_NO_PARTIALCHAIN
Tells libcurl to not accept "partial" certificate chains, which it otherwise
Pass a long as parameter set to 1L to enable or 0L to disable.
This option tells curl to verifies the authenticity of the HTTPS proxy's
-certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't.
+certificate. A value of 1 means curl verifies; 0 (zero) means it does not.
-This is the proxy version of \fICURLOPT_SSL_VERIFYPEER(3)\fP that's used for
+This is the proxy version of \fICURLOPT_SSL_VERIFYPEER(3)\fP that is used for
ordinary HTTPS servers.
When negotiating a TLS or SSL connection, the server sends a certificate
Authenticating the certificate is not enough to be sure about the server. You
typically also want to ensure that the server is the server you mean to be
talking to. Use \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP for that. The check
-that the host name in the certificate is valid for the host name you're
+that the host name in the certificate is valid for the host name you are
connecting to is done independently of the
\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option.
syntactically correct, it consists of one or more cipher suite strings
separated by colons.
-You'll find more details about cipher lists on this URL:
+you will find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
/* Set the size of the file to upload */
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize);
- /* Now run off and do what you've been told! */
+ /* Now run off and do what you have been told! */
curl_easy_perform(curl);
}
.fi
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READDATA, void *pointer);
.SH DESCRIPTION
Data \fIpointer\fP to pass to the file read function. If you use the
-\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you'll get as
+\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you will get as
input in the 4th argument to the callback.
-If you don't specify a read callback but instead rely on the default internal
+If you do not specify a read callback but instead rely on the default internal
read function, this data must be a valid readable FILE * (cast to 'void *').
-If you're using libcurl as a win32 DLL, you \fBMUST\fP use a
+If you are using libcurl as a win32 DLL, you \fBMUST\fP use a
\fICURLOPT_READFUNCTION(3)\fP if you set this option or you will experience
crashes.
.SH DEFAULT
end-of-file to the library and cause it to stop the current transfer.
If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
-server expected it, like when you've said you will upload N bytes and you
+server expected it, like when you have said you will upload N bytes and you
upload less than N bytes), you may experience that the server "hangs" waiting
-for the rest of the data that won't come.
+for the rest of the data that will not come.
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
that the callback wants, or it will be considered the final packet by the
server end and the transfer will end there.
-If you set this callback pointer to NULL, or don't set it at all, the default
+If you set this callback pointer to NULL, or do not set it at all, the default
internal read function will be used. It is doing an fread() on the FILE *
userdata set with \fICURLOPT_READDATA(3)\fP.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKDATA, void *pointer);
.SH DESCRIPTION
Data \fIpointer\fP to pass to the seek callback function. If you use the
-\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you'll get as
+\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you will get as
input.
.SH DEFAULT
-If you don't set this, NULL is passed to the callback.
+If you do not set this, NULL is passed to the callback.
.SH PROTOCOLS
HTTP, FTP, SFTP
.SH EXAMPLE
/* These are the return codes for the seek callbacks */
#define CURL_SEEKFUNC_OK 0
#define CURL_SEEKFUNC_FAIL 1 /* fail the entire transfer */
-#define CURL_SEEKFUNC_CANTSEEK 2 /* tell libcurl seeking can't be done, so
+#define CURL_SEEKFUNC_CANTSEEK 2 /* tell libcurl seeking cannot be done, so
libcurl might try other means instead */
int seek_callback(void *userp, curl_off_t offset, int origin);
If you add a share that is set to share cookies, your easy handle will use
that cookie cache and get the cookie engine enabled. If you unshare an object
-that was using cookies (or change to another object that doesn't share
+that was using cookies (or change to another object that does not share
cookies), the easy handle will get its cookie engine disabled.
Data that the share object is not set to share will be dealt with the usual
\fICURLSOCKTYPE_IPCXN\fP for actively created connections or since 7.28.0
\fICURLSOCKTYPE_ACCEPT\fP for FTP when the connection was setup with PORT/EPSV
-(in earlier versions these sockets weren't passed to this callback).
+(in earlier versions these sockets were not passed to this callback).
Future versions of libcurl may support more purposes. libcurl passes the newly
created socket descriptor to the callback in the \fIcurlfd\fP parameter so
.SH DESCRIPTION
Pass a char * pointing to a string containing a Base64-encoded SHA256
hash of the remote host's public key.
-The transfer will fail if the given hash doesn't match the hash the
+The transfer will fail if the given hash does not match the hash the
remote host provides.
.SH DEFAULT
CURLKHSTAT_FINE_ADD_TO_FILE,
CURLKHSTAT_FINE,
CURLKHSTAT_REJECT, /* reject the connection, return an error */
- CURLKHSTAT_DEFER, /* do not accept it, but we can't answer right
+ CURLKHSTAT_DEFER, /* do not accept it, but we cannot answer right
now so this causes a CURLE_DEFER error but
otherwise the connection will be left intact
etc */
.IP CURLKHSTAT_FINE_REPLACE
The new host+key is accepted and libcurl will replace the old host+key into
the known_hosts file before continuing with the connection. This will also
-add the new host+key combo to the known_host pool kept in memory if it wasn't
+add the new host+key combo to the known_host pool kept in memory if it was not
already present there. The adding of data to the file is done by completely
replacing the file with a new copy, so the permissions of the file must allow
this. (Added in 7.73.0)
.IP CURLKHSTAT_FINE_ADD_TO_FILE
The host+key is accepted and libcurl will append it to the known_hosts file
before continuing with the connection. This will also add the host+key combo
-to the known_host pool kept in memory if it wasn't already present there. The
+to the known_host pool kept in memory if it was not already present there. The
adding of data to the file is done by completely replacing the file with a new
copy, so the permissions of the file must allow this.
.IP CURLKHSTAT_FINE
The host+key is accepted libcurl will continue with the connection. This will
-also add the host+key combo to the known_host pool kept in memory if it wasn't
+also add the host+key combo to the known_host pool kept in memory if it was not
already present there.
.IP CURLKHSTAT_REJECT
The host+key is rejected. libcurl will deny the connection to continue and it
set when you compile OpenSSL.
For NSS, valid examples of cipher lists include \fBrsa_rc4_128_md5\fP,
-\fBrsa_aes_128_sha\fP, etc. With NSS you don't add/remove ciphers. If one uses
+\fBrsa_aes_128_sha\fP, etc. With NSS you do not add/remove ciphers. If one uses
this option then all known ciphers are disabled and only those passed in are
enabled.
For WolfSSL, valid examples of cipher lists include \fBECDHE-RSA-RC4-SHA\fP,
\fBAES256-SHA:AES256-SHA256\fP, etc.
-You'll find more details about cipher lists on this URL:
+you will find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_DATA, void *pointer);
.SH DESCRIPTION
Data \fIpointer\fP to pass to the ssl context callback set by the option
-\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you'll get as third
+\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you will get as third
parameter.
.SH DEFAULT
NULL
behaviors. Available bits:
.IP CURLSSLOPT_ALLOW_BEAST
Tells libcurl to not attempt to use any workarounds for a security flaw in the
-SSL3 and TLS1.0 protocols. If this option isn't used or this bit is set to 0,
+SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0,
the SSL layer libcurl uses may use a work-around for this flaw although it
might cause interoperability problems with some (older) SSL
implementations. WARNING: avoiding this work-around lessens the security, and
Tells libcurl to disable certificate revocation checks for those SSL backends
where such behavior is present. This option is only supported for Schannel
(the native Windows SSL library), with an exception in the case of Windows'
-Untrusted Publishers block list which it seems can't be bypassed. (Added in
+Untrusted Publishers block list which it seems cannot be bypassed. (Added in
7.44.0)
.IP CURLSSLOPT_NO_PARTIALCHAIN
Tells libcurl to not accept "partial" certificate chains, which it otherwise
Pass a long as parameter to enable or disable.
This option determines whether curl verifies the authenticity of the peer's
-certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't.
+certificate. A value of 1 means curl verifies; 0 (zero) means it does not.
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. Curl verifies whether the certificate is authentic,
Authenticating the certificate is not enough to be sure about the server. You
typically also want to ensure that the server is the server you mean to be
talking to. Use \fICURLOPT_SSL_VERIFYHOST(3)\fP for that. The check that the
-host name in the certificate is valid for the host name you're connecting to
+host name in the certificate is valid for the host name you are connecting to
is done independently of the \fICURLOPT_SSL_VERIFYPEER(3)\fP option.
WARNING: disabling verification of the certificate allows bad guys to
suites to use for the TLS 1.3 connection. The list must be syntactically
correct, it consists of one or more cipher suite strings separated by colons.
-You'll find more details about cipher lists on this URL:
+you will find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
The application does not have to keep the string around after setting this
option.
-This feature relies in TLS SRP which doesn't work with TLS 1.3.
+This feature relies in TLS SRP which does not work with TLS 1.3.
.SH DEFAULT
NULL
.SH PROTOCOLS
The application does not have to keep the string around after setting this
option.
-TLS SRP doesn't work with TLS 1.3.
+TLS SRP does not work with TLS 1.3.
.SH DEFAULT
blank
.SH PROTOCOLS
The application does not have to keep the string around after setting this
option.
-This feature relies in TLS SRP which doesn't work with TLS 1.3.
+This feature relies in TLS SRP which does not work with TLS 1.3.
.SH DEFAULT
NULL
.SH PROTOCOLS
/* Set the size of the file to upload */
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize);
- /* Now run off and do what you've been told! */
+ /* Now run off and do what you have been told! */
curl_easy_perform(curl);
}
.fi
16 kilobytes.
Since curl 7.61.1 the upload buffer is allocated on-demand - so if the handle
-isn't used for upload, this buffer will not be allocated at all.
+is not used for upload, this buffer will not be allocated at all.
DO NOT set this option on a handle that is currently used for an active
transfer as that may lead to unintended consequences.
For a greater explanation of the format please see RFC3986.
-libcurl doesn't validate the syntax or use this variable until the transfer is
+libcurl does not validate the syntax or use this variable until the transfer is
issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will
still return \fICURLE_OK\fP.
If libcurl is built without IDN support, the server name is used exactly as
specified when passed to the name resolver functions.
.SH DEFAULT
-There is no default URL. If this option isn't set, no transfer can be
+There is no default URL. If this option is not set, no transfer can be
performed.
.SH SECURITY CONCERNS
Applications may at times find it convenient to allow users to specify URLs
Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
heap space.
-Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so
+Note that \fIcurl_easy_setopt(3)\fP will not actually parse the given string so
given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or
similar is called.
.SH "SEE ALSO"
When using Kerberos V5 authentication with a Windows based server, you should
include the domain name in order for the server to successfully obtain a
-Kerberos Ticket. If you don't then the initial part of the authentication
+Kerberos Ticket. If you do not then the initial part of the authentication
handshake may fail.
When using NTLM, the user name can be specified simply as the user name
When using Kerberos V5 authentication with a Windows based server, you should
specify the user name part with the domain name in order for the server to
-successfully obtain a Kerberos Ticket. If you don't then the initial part of
+successfully obtain a Kerberos Ticket. If you do not then the initial part of
the authentication handshake may fail.
When using NTLM, the user name can be specified simply as the user name
This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc.
.IP CURLUSESSL_NONE
-Don't attempt to use SSL.
+do not attempt to use SSL.
.IP CURLUSESSL_TRY
Try using SSL, proceed as normal otherwise.
.IP CURLUSESSL_CONTROL
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer);
.SH DESCRIPTION
A data \fIpointer\fP to pass to the write callback. If you use the
-\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you'll get in that
-callback's 4th argument. If you don't use a write callback, you must make
+\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you will get in that
+callback's 4th argument. If you do not use a write callback, you must make
\fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl will pass this to
\fIfwrite(3)\fP when writing data.
The internal \fICURLOPT_WRITEFUNCTION(3)\fP will write the data to the FILE *
-given with this option, or to stdout if this option hasn't been set.
+given with this option, or to stdout if this option has not been set.
-If you're using libcurl as a win32 DLL, you \fBMUST\fP use a
+If you are using libcurl as a win32 DLL, you \fBMUST\fP use a
\fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you will experience
crashes.
.SH DEFAULT
Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option.
Your callback should return the number of bytes actually taken care of. If
-that amount differs from the amount passed to your callback function, it'll
+that amount differs from the amount passed to your callback function, it will
signal an error condition to the library. This will cause the transfer to get
aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
your callback. The internal default function will write the data to the FILE *
given with \fICURLOPT_WRITEDATA(3)\fP.
-This option doesn't enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
+This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
libcurl will use 'fwrite' as a callback by default.
\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually
get called.
.SH DEFAULT
-By default, libcurl has an internal progress meter. That's rarely wanted by
+By default, libcurl has an internal progress meter. That is rarely wanted by
users.
.SH PROTOCOLS
All
projects / thirdparty / curl.git / commitdiff
