UNLOZE/sourcemod
9
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Backed out updated libcurl.

Browse Source
This commit is contained in:
Asher Baker
2013-03-18 00:55:59 +00:00
parent 9b65900df0
commit e84f6e4afd
1511 changed files with 161513 additions and 213368 deletions
Download Patch File Download Diff File Expand all files Collapse all files
extensions/curl/curl-src/docs/FAQ
+138 -396
View File
@@ -1,3 +1,4 @@
Updated: Sep 24, 2008 (http://curl.haxx.se/docs/faq.html)
_ _ ____ _
___| | | | _ \| |
/ __| | | | |_) | |
@@ -18,9 +19,6 @@ FAQ
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.12 I have a problem who can I chat with?
1.13 curl's ECCN number?
1.14 How do I submit my patch?
2. Install Related Problems
2.1 configure doesn't find OpenSSL even when it is installed
@@ -28,14 +26,14 @@ FAQ
2.1.2 only the libssl lib is missing
2.2 Does curl work/build with other SSL libraries?
2.3 Where can I find a copy of LIBEAY32.DLL?
2.4 Does curl support SOCKS (RFC 1928) ?
2.4 Does curl support Socks (RFC 1928) ?
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.4 How do I tell curl to run custom FTP commands?
3.5 How can I disable the Accept: */* header?
3.5 How can I disable the Pragma: nocache header?
3.6 Does curl support ASP, XML, XHTML or HTML version Y?
3.7 Can I use curl to delete/rename a file through FTP?
3.8 How do I tell curl to follow HTTP redirects?
@@ -44,15 +42,11 @@ FAQ
3.11 How do I POST with a different Content-Type?
3.12 Why do FTP specific features over HTTP proxy fail?
3.13 Why does my single/double quotes fail?
3.14 Does curl support Javascript or PAC (automated proxy config)?
3.14 Does curl support javascript or pac (automated proxy config)?
3.15 Can I do recursive fetches with curl?
3.16 What certificates do I need when I use SSL?
3.17 How do I list the root dir of an FTP server?
3.18 Can I use curl to send a POST/PUT and not wait for a response?
3.19 How do I get HTTP from a host using a specific IP address?
3.20 How to SFTP from my user's home directory?
3.21 Protocol xxx not supported or disabled in libcurl
3.22 curl -X gives me HTTP problems
4. Running Problems
4.1 Problems connecting to SSL servers.
@@ -77,9 +71,6 @@ FAQ
4.14 Redirects work in browser but not with curl!
4.15 FTPS doesn't 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?
5. libcurl Issues
5.1 Is libcurl thread-safe?
@@ -89,16 +80,13 @@ FAQ
5.5 Does CURLOPT_WRITEDATA and CURLOPT_READDATA work on win32 ?
5.6 What about Keep-Alive or persistent connections?
5.7 Link errors when building libcurl on Windows!
5.8 libcurl.so.X: open failed: No such file or directory
5.8 libcurl.so.3: open failed: No such file or directory
5.9 How does libcurl resolve host names?
5.10 How do I prevent libcurl from writing the response to stdout?
5.11 How do I make libcurl not receive the whole HTTP response?
5.12 Can I make libcurl fake or hide my real IP address?
5.13 How do I stop an ongoing transfer?
5.14 Using C++ non-static functions for callbacks?
5.15 How do I get an FTP directory listing?
5.16 I want a different time-out!
5.17 Can I write a server with libcurl?
6. License Issues
6.1 I have a GPL program, can I use the libcurl library?
@@ -107,11 +95,11 @@ FAQ
6.4 I have a program that uses LGPL libraries, can I use libcurl?
6.5 Can I modify curl/libcurl for my program and keep the changes secret?
6.6 Can you please change the curl/libcurl license to XXXX?
6.7 What are my obligations when using libcurl in my commercial apps?
6.7 What are my obligations when using libcurl in my commerical apps?
7. PHP/CURL Issues
7.1 What is PHP/CURL?
7.2 Who wrote PHP/CURL?
7.2 Who write PHP/CURL?
7.3 Can I perform multiple requests using the same handle?
==============================================================================
@@ -130,19 +118,16 @@ FAQ
libcurl
A free and easy-to-use client-side URL transfer library, supporting DICT,
FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3,
POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP.
libcurl supports HTTPS certificates, HTTP POST, HTTP PUT, FTP uploading,
kerberos, HTTP form based upload, proxies, cookies, user+password
authentication, file transfer resume, http proxy tunneling and more!
A free and easy-to-use client-side URL transfer library, supporting FTP,
FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE and LDAP. libcurl
supports HTTPS certificates, HTTP POST, HTTP PUT, FTP uploading, kerberos,
HTTP form based upload, proxies, cookies, user+password authentication,
file transfer resume, http proxy tunneling and more!
libcurl is highly portable, it builds and works identically on numerous
platforms, including Solaris, NetBSD, FreeBSD, OpenBSD, Darwin, HPUX,
IRIX, AIX, Tru64, Linux, UnixWare, HURD, Windows, Amiga, OS/2, BeOS, Mac
OS X, Ultrix, QNX, OpenVMS, RISC OS, Novell NetWare, DOS, Symbian, OSF,
Android, Minix, IBM TPF and more...
IRIX, AIX, Tru64, Linux, UnixWare, HURD, Windows, Amiga, OS/2, BeOs, Mac
OS X, Ultrix, QNX, OpenVMS, RISC OS, Novell NetWare, DOS and more...
libcurl is free, thread-safe, IPv6 compatible, feature rich, well
supported and fast.
@@ -151,8 +136,9 @@ FAQ
A command line tool for getting or sending files using URL syntax.
Since curl uses libcurl, curl supports the same wide range of common
Internet protocols that libcurl does.
Since curl uses libcurl, it supports a range of common Internet protocols,
currently including HTTP, HTTPS, FTP, FTPS, SCP, SFTP, TFTP, LDAP, DICT,
TELNET and FILE.
We pronounce curl and cURL with an initial k sound: [kurl].
@@ -239,16 +225,13 @@ FAQ
1.6 What do you get for making curl?
Project cURL is entirely free and open. No person gets paid for developing
(lib)curl on full or even part time. We do this voluntarily on our spare
time. Occasionally companies pay individual developers to work on curl, but
that's up to each company and developer. It is not controlled by nor
supervised in any way by the project.
(lib)curl. We do this voluntarily on our spare time.
We still get help from companies. Haxx provides web site, bandwidth, mailing
lists etc and sourceforge.net hosts project services we take advantage from,
like the bug tracker. Also again, some companies have sponsored certain
parts of the development in the past and I hope some will continue to do so
in the future.
We get some help from companies. Contactor Data hosts the curl web site,
Haxx owns the curl web site's domain and sourceforge.net hosts project
services we take advantage from, like the bug tracker. Also, some companies
have sponsored certain parts of the development in the past and I hope some
will continue to do so in the future.
If you want to support our project, consider a donation or a banner-program
or even better: by helping us coding, documenting, testing etc.
@@ -308,10 +291,34 @@ FAQ
We don't know how many users that downloaded or installed curl and then
never use it.
In May 2012 Daniel did a counting game and came up with a number that may
be completely wrong or somewhat accurate. 300 million!
Some facts to use as input to the math:
See http://daniel.haxx.se/blog/2012/05/16/300m-users/
curl packages are downloaded from the curl.haxx.se and mirrors over a
million times per year. curl is installed by default with most Linux
distributions. curl is installed by default with Mac OS X. curl and libcurl
as used by numerous applications that include libcurl binaries in their
distribution packages (like Adobe Acrobat Reader and Google Earth).
More than 80 known named companies use curl in commercial environments and
products. More than 100 known named open source projects depend on
(lib)curl.
In a poll on the curl web site mid-2005, more than 50% of the 300+ answers
estimated a user base of one million users or more.
In March 2005, the "Linux Counter project" estimated a total Linux user base
of some 29 millions, while Netcraft detected some 4 million "active" Linux
based web servers. A guess is that a fair amount of these Linux
installations have curl installed.
All this taken together, there is no doubt that there are millions of
(lib)curl users.
http://curl.haxx.se/docs/companies.html
http://curl.haxx.se/docs/programs.html
http://curl.haxx.se/libcurl/using/apps.html
http://counter.li.org/estimates.php
http://news.netcraft.com/archives/2005/03/14/fedora_makes_rapid_progress.html
1.11 Why don't you update ca-bundle.crt
@@ -336,47 +343,6 @@ FAQ
Firefox (by running 'make ca-bundle), or by using our online service setup
for this purpose: http://curl.haxx.se/docs/caextract.html
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 irc.freenode.net. If you're polite and nice, chances are big
that you can get -- or provide -- help instantly.
1.13 curl's ECCN number?
The US government restricts exports of software that contains or uses
cryptography. When doing so, the Export Control Classification Number (ECCN)
is used to identify the level of export control etc.
ASF gives a good explanation at http://www.apache.org/dev/crypto.html
We believe curl's number might be ECCN 5D002, another possibility is
5D992. It seems necessary to write them, asking to confirm.
Comprehensible explanations of the meaning of such numbers and how to
obtain them (resp.) are here
http://www.bis.doc.gov/licensing/exportingbasics.htm
http://www.bis.doc.gov/licensing/do_i_needaneccn.html
An incomprehensible description of the two numbers above is here
http://www.access.gpo.gov/bis/ear/pdf/ccl5-pt2.pdf
1.14 How do I submit my patch?
When you have made a patch or a change of whatever sort, and want to submit
that to the project, there are a few different ways we prefer:
o send a patch to the curl-library mailing list. We're many subscribers
there and there are lots of people who can review patches, comment on them
and "receive" them properly.
o if your patch changes or fixes a bug, you can also opt to submit a bug
report in the bug tracker and attach your patch there. There are less
people involved there.
Lots of more details are found in the CONTRIBUTE and INTERNALS docs.
2. Install Related Problems
@@ -419,15 +385,10 @@ FAQ
2.2 Does curl work/build with other SSL libraries?
Curl has been written to use a generic SSL function layer internally, and
that SSL functionality can then be provided by one out of many different SSL
backends.
curl can be built to use one of the following SSL alternatives: OpenSSL,
GnuTLS, yassl, NSS, PolarSSL, axTLS, Secure Transport (native iOS/OS X),
schannel (native Windows) or qssl (native IBM i). They all have their pros
and cons, and we try to maintain a comparison of them here:
http://curl.haxx.se/docs/ssl-compared.html
Curl has been written to use OpenSSL, GnuTLS, yassl or NSS, although there
should not be many problems using a different library. If anyone does "port"
curl to use a different SSL library, we are of course very interested in
getting the patch!
2.3 Where can I find a copy of LIBEAY32.DLL?
@@ -438,7 +399,7 @@ FAQ
accurate and up-to-date pointers to recent OpenSSL DLLs and other binary
packages.
2.4 Does curl support SOCKS (RFC 1928) ?
2.4 Does curl support Socks (RFC 1928) ?
Yes, SOCKS 4 and 5 are supported.
@@ -448,25 +409,22 @@ FAQ
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
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
the configure script fails to find them, curl is simply built without SSL
support.
it means that the configure script couldn't find all libs and include files
it 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/or include files.
Also, check out the other paragraph in this FAQ labelled "configure doesn't
Also, check out the other paragraph in this FAQ labeled "configure doesn't
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?
@@ -488,16 +446,15 @@ FAQ
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
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.
Since curl is used for file transfers, you don't use curl to just perform
FTP commands without transferring anything. Therefore you must always specify
a URL to transfer to/from even when doing custom FTP commands.
3.5 How can I disable the Accept: */* header?
3.5 How can I disable the Pragma: nocache header?
You can change all internally generated headers by adding a replacement with
the -H/--header option. By adding a header with empty contents you safely
disable that one. Use -H "Accept:" to disable that specific header.
disable that one. Use -H "Pragma:" to disable that specific header.
3.6 Does curl support ASP, XML, XHTML or HTML version Y?
@@ -541,19 +498,12 @@ FAQ
install and use them, in the libcurl section of the curl web site:
http://curl.haxx.se/libcurl/
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
about bindings on the curl-library list too, but be prepared that people on
that list may not know anything about bindings.
In October 2009, there were interfaces available for the following
languages: Ada95, Basic, C, C++, Ch, Cocoa, D, Dylan, Eiffel, Euphoria,
Ferite, Gambas, glib/GTK+, Haskell, ILE/RPG, Java, Lisp, Lua, Mono, .NET,
Object-Pascal, O'Caml, Pascal, Perl, PHP, PostgreSQL, Python, R, Rexx, Ruby,
Scheme, S-Lang, Smalltalk, SP-Forth, SPL, Tcl, Visual Basic, Visual FoxPro,
Q, wxwidgets and XBLite. By the time you read this, additional ones may have
appeared!
In February 2007, there are interfaces available for the following
languages: Ada95, Basic, C, C++, Ch, Cocoa, D, Dylan, Euphoria, Ferite,
Gambas, glib/GTK+, Java, Lisp, Lua, Mono, .NET, Object-Pascal, O'Caml,
Pascal, Perl, PHP, PostgreSQL, Python, R, Rexx, Ruby, Scheme, S-Lang,
Smalltalk, SPL, Tcl, Visual Basic, Q, wxwidgets and XBLite. By the time you
read this, additional ones may have appeared!
3.10 What about SOAP, WebDAV, XML-RPC or similar protocols over HTTP?
@@ -607,27 +557,27 @@ FAQ
Remember that curl works and runs on more operating systems than most single
individuals have ever tried.
3.14 Does curl support Javascript or PAC (automated proxy config)?
3.14 Does curl support javascript or pac (automated proxy config)?
Many web pages do magic stuff using embedded Javascript. Curl and libcurl
Many web pages do magic stuff using embedded javascript. Curl and libcurl
have no built-in support for that, so it will be treated just like any other
contents.
.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,
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.
Some workarounds usually suggested to overcome this Javascript dependency:
Some work-arounds usually suggested to overcome this javascript dependency:
- Depending on the Javascript complexity, write up a script that
- Depending on the javascript complexity, write up a script that
translates it to another language and execute that.
- Read the Javascript code and rewrite the same logic in another language.
- Read the javascript code and rewrite the same logic in another language.
- Implement a Javascript interpreter, people have successfully used the
Mozilla Javascript engine in the past.
- Implement a javascript interpreter, people have successfully used the
Mozilla javascript engine in the past.
- Ask your admins to stop this, for a static proxy setup or similar.
@@ -649,9 +599,6 @@ FAQ
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.
A client certificate is always used together with a private key, and the
private key has a pass phrase that protects it.
- Server certificate. The server you communicate with has a server
certificate. You can and should verify this certificate to make sure that
you are truly talking to the real server and not a server impersonating
@@ -659,9 +606,8 @@ FAQ
- Certificate Authority certificate ("CA cert"). You often have several CA
certs in a CA cert bundle that can be used to verify a server certificate
that was signed by one of the authorities in the bundle. curl does not
come with a CA cert bundle but most curl installs provide one. You can
also override the default.
that was signed by one of the authorities in the bundle. curl comes with a
default CA cert bundle. You can override the default.
The server certificate verification process is made by using a Certificate
Authority certificate ("CA cert") that was used to sign the server
@@ -687,84 +633,11 @@ FAQ
curl ftp://ftp.sunet.se//tmp/
3.18 Can I use curl to send a POST/PUT and not wait for a response?
No.
But you could easily write your own program using libcurl to do such stunts.
3.19 How do I get HTTP from a host using a specific IP address?
For example, you may be trying out a web site installation that isn't 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.
Set a custom Host: header that identifies the server name you want to reach
but use the target IP address in the URL:
curl --header "Host: www.example.com" http://127.0.0.1/
You can also opt to add faked host name entries to curl with the --resolve
option. That has the added benefit that things like redirects will also work
properly. The above operation would instead be done as:
curl --resolve www.example.com:80:127.0.0.1 http://www.example.com/
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
directory, you get the actual root directory.
To specify a file in your user's home directory, you need to use the correct
URL syntax which for sftp might look similar to:
curl -O -u user:password sftp://example.com/~/file.txt
and for SCP it is just a different protocol prefix:
curl -O -u user:password scp://example.com/~/file.txt
3.21 Protocol xxx not supported or disabled in libcurl
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
a particular protocol is not supported (ie 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
be disabled or not supported.
Note that this error will also occur if you pass a wrongly spelled protocol
part as in "htpt://example.com" or as in the less evident case if you prefix
the protocol part with a space as in " http://example.com/".
3.22 curl -X gives me HTTP problems
In normal circumstances, -X should hardly ever be used.
By default you use curl without explicitly saying which request method to
use when the URL identifies a HTTP transfer. If you just pass in a URL like
"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
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]".
It is thus pointless to do "curl -XGET [URL]" as GET would be used
anyway. In the same vein it is pointless to do "curl -X POST -d data
[URL]"... But you can make a fun and somewhat rare request that sends a
request-body in a GET request with something like "curl -X GET -d data
[URL]"
Note that -X doesn't change curl's behavior. It only modifies the actual
string sent in the request.
Accordingly, by using -XPOST on a command line that for example would follow
a 303 redirect, you will effectively prevent curl from behaving
correctly. Be aware.
4. Running Problems
@@ -785,22 +658,21 @@ FAQ
4.2 Why do I get problems when I use & or % in the URL?
In general unix shells, the & symbol is treated specially and when used, it
In general unix shells, the & letter is treated special and when used, it
runs the specified command in the background. To safely send the & as a part
of a URL, you should quote the entire URL by using single (') or double (")
quotes around it. Similar problems can also occur on some shells with other
characters, including ?*!$~(){}<>\|;`. When in doubt, quote the URL.
quotes around it.
An example that would invoke a remote CGI that uses &-symbols could be:
An example that would invoke a remote CGI that uses &-letters could be:
curl 'http://www.altavista.com/cgi-bin/query?text=yes&q=curl'
In Windows, the standard DOS shell treats the %-symbol specially and you
need to use TWO %-symbols for each single one you want to use in the URL.
In Windows, the standard DOS shell treats the %-letter specially and you
need to use TWO %-letters for each single one you want to use in the URL.
Also note that if you want the literal %-symbol to be part of the data you
Also note that if you want the literal %-letter to be part of the data you
pass in a POST using -d/--data you must encode it as '%25' (which then also
needs the %-symbol doubled on Windows machines).
needs the %-letter doubled on Windows machines).
4.3 How can I use {, }, [ or ] to specify multiple URLs?
@@ -842,7 +714,7 @@ FAQ
4.5.3 "403 Forbidden"
The server understood the request, but is refusing to fulfil it.
The server understood the request, but is refusing to fulfill it.
Authorization will not help and the request SHOULD NOT be repeated.
4.5.4 "404 Not Found"
@@ -913,8 +785,10 @@ FAQ
4.9 Curl can't authenticate to the server that requires NTLM?
NTLM support requires OpenSSL, GnuTLS, NSS, Secure Transport, or Microsoft
Windows libraries at build-time to provide this functionality.
This is supported in curl 7.10.6 or later. No earlier curl version knows
of this magic. Later versions require the OpenSSL or Microsoft Windows
libraries to provide this functionality. Using GnuTLS or NSS libraries will
not provide NTLM authentication functionality in curl.
NTLM is a Microsoft proprietary protocol. Proprietary formats are evil. You
should not use such ones.
@@ -974,7 +848,7 @@ FAQ
- Meta tags. You can write a HTML tag that will cause the browser to
redirect to another given URL after a certain time.
- Javascript. You can write a Javascript program embedded in a HTML page
- Javascript. You can write a javascript program embeded in a HTML page
that redirects the browser to another given URL.
There is no way to make curl follow these redirects. You must either
@@ -1010,75 +884,6 @@ FAQ
You can disable libcurl's use of the Expect: header the same way you disable
any header, using -H / CURLOPT_HTTPHEADER, or by forcing it to use HTTP 1.0.
4.17 Non-functional connect timeouts
In most Windows setups having a timeout longer than 21 seconds make no
difference, as it will only send 3 TCP SYN packets and no more. The second
packet sent three seconds after the first and the third six seconds after
the second. No more than three packets are sent, no matter how long the
timeout is set.
See option TcpMaxConnectRetransmissions on this page:
http://support.microsoft.com/?scid=kb%3Ben-us%3B175523&x=6&y=7
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.
4.18 file:// URLs containing drive letters (Windows, NetWare)
When using cURL to try to download a local file, one might use a URL
in this format:
file://D:/blah.txt
You'll find that even if D:\blah.txt does exist, cURL returns a 'file
not found' error.
According to RFC 1738 (http://www.faqs.org/rfcs/rfc1738.html),
file:// URLs must contain a host component, but it is ignored by
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.
To fix this problem, use file:// URLs with *three* leading slashes:
file:///D:/blah.txt
Alternatively, if it makes more sense, specify 'localhost' as the host
component:
file://localhost/D:/blah.txt
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?
Unplugging the 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
delayed. Eventually, the physical break will be fixed or the data will be
re-routed around the physical problem.
In such cases, the TCP/IP stack is responsible for detecting when the
network connection is irrevocably lost. Since with some protocols it is
perfectly legal for the client wait indefinitely for data, the stack may
never report a problem, and even when it does, it can take up to 20 minutes
for it to detect an issue. The curl option --keepalive-time enables
keep-alive support in the TCP/IP stack which makes it periodically probe the
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
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
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.
5. libcurl Issues
5.1 Is libcurl thread-safe?
@@ -1092,7 +897,7 @@ FAQ
If you use a OpenSSL-powered libcurl in a multi-threaded environment, you
need to provide one or two locking functions:
http://www.openssl.org/docs/crypto/threads.html
http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION
If you use a GnuTLS-powered libcurl in a multi-threaded environment, you
need to provide locking function(s) for libgcrypt (which is used by GnuTLS
@@ -1167,11 +972,6 @@ FAQ
libcurl will reuse connections for all transfers that are made using the
same libcurl handle.
When you use the easy interface, the connection cache is kept within the
easy handle. If you instead use the multi interface, the connection cache
will be kept within the multi handle and will be shared among all the easy
handles that are used within the same multi handle.
5.7 Link errors when building libcurl on Windows!
You need to make sure that your project, and all the libraries (both static
@@ -1184,30 +984,27 @@ FAQ
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
add CURL_STATICLIB in the "Preprocessor Definitions" section.
dynamic import symbols. 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 the import libraries below. These are the
libraries produced by the various lib/Makefile.* files:
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
the import libraries below. These are the libraries produced by the various
lib/Makefile.* files:
Target: static lib. import lib for libcurl*.dll.
-----------------------------------------------------------
MingW: libcurl.a libcurldll.a
MSVC (release): libcurl.lib libcurl_imp.lib
MSVC (debug): libcurld.lib libcurld_imp.lib
Borland: libcurl.lib libcurl_imp.lib
Target: static lib. import lib for libcurl*.dll.
-----------------------------------------------------------
MingW: libcurl.a libcurldll.a
MSVC (release): libcurl.lib libcurl_imp.lib
MSVC (debug): libcurld.lib libcurld_imp.lib
Borland: libcurl.lib libcurl_imp.lib
5.8 libcurl.so.X: open failed: No such file or directory
5.8 libcurl.so.3: 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
find the shared library named libcurl.so.X. (Where X is the number of the
current libcurl ABI, typically 3 or 4).
find the shared library named libcurl.so.3.
You need to make sure that ld.so finds libcurl.so.X. You can do that
You need to make sure that ld.so finds libcurl.so.3. You can do that
multiple ways, and it differs somewhat between different operating systems,
but they are usually:
@@ -1232,20 +1029,21 @@ FAQ
- The non-ipv6 resolver that can use one out of four host name resolve calls
(depending on what your system supports):
A - gethostbyname()
B - gethostbyname_r() with 3 arguments
C - gethostbyname_r() with 5 arguments
D - gethostbyname_r() with 6 arguments
A - gethostbyname()
B - gethostbyname_r() with 3 arguments
C - gethostbyname_r() with 5 arguments
D - gethostbyname_r() with 6 arguments
- The ipv6-resolver that uses getaddrinfo()
- The c-ares based name resolver that uses the c-ares library for resolves.
Using this offers asynchronous name resolves.
Using this offers asynchronous name resolves but it currently has no IPv6
support.
- The threaded resolver (default option on Windows). It uses:
- The Windows threaded resolver. It use:
A - gethostbyname() on plain ipv4 hosts
B - getaddrinfo() on ipv6-enabled hosts
A - gethostbyname() on plain ipv4 windows hosts
B - getaddrinfo() on ipv6-enabled windows hosts
Also note that libcurl never resolves or reverse-lookups addresses given as
pure numbers, such as 127.0.0.1 or ::1.
@@ -1277,17 +1075,16 @@ FAQ
5.13 How do I stop an ongoing transfer?
With the easy interface you make sure to return the correct error code from
one of the callbacks, but none of them are instant. There is no function you
can call from another thread or similar that will stop it immediately.
Instead, you need to make sure that one of the callbacks you use returns an
appropriate value that will stop the transfer. Suitable callbacks that you
can do this with include the progress callback, the read callback and the
write callback.
There are several ways, but none of them are instant. There is no function
you can call from another thread or similar that will stop it immediately.
Instead you need to make sure that one of the callbacks you use return an
appropriate value that will stop the transfer.
If you're 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.
Suitable callbacks that you can do this with include the progress callback,
the read callback and the write callback.
If you're using the multi interface, you also stop a transfer by removing
the particular easy handle from the multi stack.
5.14 Using C++ non-static functions for callbacks?
@@ -1297,64 +1094,16 @@ FAQ
member function that is passed a pointer to the class:
// f is the pointer to your object.
static YourClass::func(void *buffer, size_t sz, size_t n, void *f)
static YourClass::staticFunction(void *buffer, size_t sz, size_t n, void *f)
{
// Call non-static member function.
static_cast<YourClass*>(f)->nonStaticFunction();
}
// This is how you pass pointer to the static function:
curl_easy_setopt(hcurl, CURLOPT_WRITEFUNCTION, YourClass:func);
curl_easy_setopt(hcurl, CURLOPT_WRITEFUNCTION, YourClass:staticFunction);
curl_easy_setopt(hcurl, CURLOPT_WRITEDATA, this);
5.15 How do I get an FTP directory listing?
If you end the FTP URL you request with a slash, libcurl will provide you
with a directory listing of that given directory. You can also set
CURLOPT_CUSTOMREQUEST to alter what exact listing command libcurl would use
to list the files.
The follow-up question that tend to follow the previous one, is how a
program is supposed to parse the directory listing. How does it know what's
a file and what's a dir and what's a symlink etc. The harsh reality is that
FTP provides no such fine and easy-to-parse output. The output format FTP
servers respond to LIST commands are entirely at the server's own liking and
the NLST output doesn't reveal any types and in many cases don't 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.
The application thus needs to parse the LIST output. One such existing
list parser is available at http://cr.yp.to/ftpparse.html Versions of
libcurl since 7.21.0 also provide the ability to specify a wildcard to
download multiple files from one FTP directory.
5.16 I want a different time-out!
Time and time again users realize that CURLOPT_TIMEOUT and
CURLOPT_CONNECTIMEOUT are not sufficiently advanced or flexible to cover all
the various use cases and scenarios applications end up with.
libcurl offers many more ways to time-out operations. A common alternative
is to use the CURLOPT_LOW_SPEED_LIMIT and CURLOPT_LOW_SPEED_TIME options to
specify the lowest possible speed to accept before to consider the transfer
timed out.
The most flexible way is by writing your own time-out logic and using
CURLOPT_PROGRESSFUNCTION (perhaps in combination with other callbacks) and
use that to figure out exactly when the right condition is met when the
transfer should get stopped.
5.17 Can I write a server with libcurl?
No. libcurl offers no functions or building blocks to build any kind of
internet protocol server. libcurl is only a client-side library. For server
libraries, you need to continue your search elsewhere but there exist many
good open source ones out there for most protocols you could possibly want a
server for. And there are really good stand-alone ones that have been tested
and proven for many years. There's no need for you to reinvent them!
6. License Issues
Curl and libcurl are released under a MIT/X derivate license. The license is
@@ -1363,10 +1112,7 @@ FAQ
this section was much enhanced by Bjorn Reese.)
We are not lawyers and this is not legal advice. You should probably consult
one if you want true and accurate legal insights without our prejudice. Note
especially that this section concerns the libcurl license only; compiling in
features of libcurl that depend on other libraries (e.g. OpenSSL) may affect
the licensing obligations of your application.
one if you want true and accurate legal insights without our prejudice.
6.1 I have a GPL program, can I use the libcurl library?
@@ -1412,7 +1158,7 @@ FAQ
libraries that use it. It should be possible for everyone to use libcurl or
curl in their projects, no matter what license they already have in use.
6.7 What are my obligations when using libcurl in my commercial apps?
6.7 What are my obligations when using libcurl in my commerical apps?
Next to none. All you need to adhere to is the MIT-style license (stated in
the COPYING file) which basically says you have to include the copyright
@@ -1424,16 +1170,12 @@ FAQ
You do not have to reveal or make public any changes to the libcurl source
code.
You do not have to broadcast to the world that you are using libcurl within
You do not have to reveal or make public that you are using libcurl within
your app.
All we ask is that you disclose "the copyright notice and this permission
notice" somewhere. Most probably like in the documentation or in the section
where other third party dependencies already are mentioned and acknowledged.
As can be seen here: http://curl.haxx.se/docs/companies.html and elsewhere,
more and more companies are discovering the power of libcurl and take
advantage of it even in commercial environments.
As can be seen here: http://curl.haxx.se/docs/companies.html and
elsewhere, more and more companies are dicovering the power
of libcurl and take advantage of it even in commercial environments.
7. PHP/CURL Issues
@@ -1449,7 +1191,7 @@ FAQ
CURL (often using all caps) or sometimes ext/curl, but both cause much
confusion to users which in turn gives us a higher question load.
7.2 Who wrote PHP/CURL?
7.2 Who write PHP/CURL?
PHP/CURL is a module that comes with the regular PHP package. It depends and
uses libcurl, so you need to have libcurl installed properly first before