diff options
Diffstat (limited to 'docs/FAQ')
| -rw-r--r-- | docs/FAQ | 304 |
1 files changed, 197 insertions, 107 deletions
@@ -1,4 +1,3 @@ -Updated: October 6, 2010 (http://curl.haxx.se/docs/faq.html) _ _ ____ _ ___| | | | _ \| | / __| | | | |_) | | @@ -36,7 +35,7 @@ FAQ 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 Pragma: nocache header? + 3.5 How can I disable the Accept: */* 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? @@ -51,6 +50,9 @@ FAQ 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. @@ -95,6 +97,8 @@ FAQ 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,7 +111,7 @@ FAQ 7. PHP/CURL Issues 7.1 What is PHP/CURL? - 7.2 Who write PHP/CURL? + 7.2 Who wrote PHP/CURL? 7.3 Can I perform multiple requests using the same handle? ============================================================================== @@ -136,7 +140,7 @@ FAQ 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 + 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... @@ -241,10 +245,10 @@ FAQ supervised in any way by the project. 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. + lists etc, sourceforge.net hosts project services we take advantage from, + like the bug tracker and github hosts the primary git repository. 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. If you want to support our project, consider a donation or a banner-program or even better: by helping us coding, documenting, testing etc. @@ -304,49 +308,17 @@ FAQ We don't know how many users that downloaded or installed curl and then never use it. - Some facts to use as input to the math: + In May 2012 Daniel did a counting game and came up with a number that may + be completely wrong or somewhat accurate. Over 500 million! - 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 a hundred known named companies use curl in commercial - environments and products and more than a hundred 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. - - The Debian project maintains statistics on packages installed by people - who have voluntarily run their package counting application. In mid-2010, - libcurl3 was installed on over 55000 such systems (62% of reporting systems) - and was one of the 320 most popular installed packages (out of about 107000 - possible packages). - - 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 - http://qa.debian.org/popcon.php?package=curl + See http://daniel.haxx.se/blog/2012/05/16/300m-users/ 1.11 Why don't you update ca-bundle.crt - The ca-bundle.crt file that used to be bundled with curl was very outdated - (it being last modified year 2000 should tell) and must be replaced with a - much more modern and up-to-date version by anyone who wants to verify peers - anyway. It is no longer provided, the last curl release that shipped it was - curl 7.18.0. + The ca cert bundle that used to shipped with curl was very outdated and must + be replaced with an up-to-date version by anyone who wants to verify + peers. It is no longer provided by curl. The last curl release ever that + shipped a ca cert bundle was curl 7.18.0. In the cURL project we've decided not to attempt to keep this file updated (or even present anymore) since deciding what to add to a ca cert bundle is @@ -446,19 +418,24 @@ FAQ 2.2 Does curl work/build with other SSL libraries? - Curl has been written to use OpenSSL, GnuTLS, yassl, NSS or PolarSSL, - 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! + 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 2.3 Where can I find a copy of LIBEAY32.DLL? That is an OpenSSL binary built for Windows. - Curl uses OpenSSL to do the SSL stuff. The LIBEAY32.DLL is what curl needs - on a windows machine to do https://. Check out the curl web site to find - accurate and up-to-date pointers to recent OpenSSL DLLs and other binary - packages. + Curl can be built with OpenSSL to do the SSL stuff. The LIBEAY32.DLL is then + what curl needs on a windows machine to do https:// etc. Check out the curl + web site to find accurate and up-to-date pointers to recent OpenSSL DLLs and + other binary packages. 2.4 Does curl support SOCKS (RFC 1928) ? @@ -470,9 +447,13 @@ 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 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. + 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. 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 @@ -485,15 +466,14 @@ FAQ 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? You can't simply use -F or -d at your choice. The web server that will - receive your post assumes one of the formats. If the form you're trying to - "fake" sets the type to '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 + receive your post expects one of the formats. If the form you're 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 @@ -507,22 +487,23 @@ 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 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. + 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. - 3.5 How can I disable the Pragma: nocache header? + 3.5 How can I disable the Accept: */* 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 "Pragma:" to disable that specific header. + disable that one. Use -H "Accept:" to disable that specific header. 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 - 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 language that generated the page. + 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 + language that generated the page. See also item 3.14 regarding javascript. @@ -559,6 +540,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, @@ -715,6 +702,68 @@ FAQ 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 (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 + 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 @@ -792,7 +841,7 @@ FAQ 4.5.3 "403 Forbidden" - The server understood the request, but is refusing to fulfill it. + The server understood the request, but is refusing to fulfil it. Authorization will not help and the request SHOULD NOT be repeated. 4.5.4 "404 Not Found" @@ -863,8 +912,8 @@ FAQ 4.9 Curl can't authenticate to the server that requires NTLM? - NTLM support requires OpenSSL, GnuTLS, NSS or Microsoft Windows libraries at - build-time to provide this functionality. + NTLM support requires OpenSSL, GnuTLS, 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. @@ -1006,11 +1055,11 @@ FAQ 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 + 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 delayed. Eventually, the physical break will be fixed or the data will be - re-routed around the physical problem. + re-routed around the physical problem through another path. In such cases, the TCP/IP stack is responsible for detecting when the network connection is irrevocably lost. Since with some protocols it is @@ -1028,6 +1077,12 @@ FAQ 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. + A libcurl-using application running in a known physical environment (e.g. + an embedded device with only a single network connection) may want to act + immediately if its lone network connection goes down. That can be achieved + by having the application monitor the network connection on its own using an + OS-specific mechanism, then signalling libcurl to abort (see also item 5.13). + 5. libcurl Issues @@ -1037,7 +1092,9 @@ FAQ We have written the libcurl code specifically adjusted for multi-threaded programs. libcurl will use thread-safe functions instead of non-safe ones if - your system has such. + your system has such. Note that you must never share the same handle in + multiple threads. + If you use a OpenSSL-powered libcurl in a multi-threaded environment, you need to provide one or two locking functions: @@ -1117,6 +1174,11 @@ 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 @@ -1138,13 +1200,12 @@ FAQ 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 @@ -1178,21 +1239,20 @@ 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 but it currently has no IPv6 - support. + Using this offers asynchronous name resolves. - The threaded resolver (default option on Windows). It uses: - A - gethostbyname() on plain ipv4 hosts - B - getaddrinfo() on ipv6-enabled hosts + A - gethostbyname() on plain ipv4 hosts + B - getaddrinfo() on ipv6-enabled hosts Also note that libcurl never resolves or reverse-lookups addresses given as pure numbers, such as 127.0.0.1 or ::1. @@ -1224,16 +1284,17 @@ FAQ 5.13 How do I stop an ongoing transfer? - 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. - - Suitable callbacks that you can do this with include the progress callback, - the read callback and the write callback. + 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. - If you're using the multi interface, you also stop a transfer by removing - the particular easy handle from the multi stack. + 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. 5.14 Using C++ non-static functions for callbacks? @@ -1243,14 +1304,14 @@ FAQ member function that is passed a pointer to the class: // f is the pointer to your object. - static YourClass::staticFunction(void *buffer, size_t sz, size_t n, void *f) + static YourClass::func(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:staticFunction); + curl_easy_setopt(hcurl, CURLOPT_WRITEFUNCTION, YourClass:func); curl_easy_setopt(hcurl, CURLOPT_WRITEDATA, this); 5.15 How do I get an FTP directory listing? @@ -1275,6 +1336,31 @@ FAQ 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 @@ -1345,12 +1431,16 @@ FAQ You do not have to reveal or make public any changes to the libcurl source code. - You do not have to reveal or make public that you are using libcurl within + You do not have to broadcast to the world that you are using libcurl within your app. - 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. + 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. 7. PHP/CURL Issues @@ -1366,7 +1456,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 write PHP/CURL? + 7.2 Who wrote 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 |