123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113 |
- Updated: November 2, 2005 (http://curl.haxx.se/docs/faq.html)
- _ _ ____ _
- ___| | | | _ \| |
- / __| | | | |_) | |
- | (__| |_| | _ <| |___
- \___|\___/|_| \_\_____|
- FAQ
- 1. Philosophy
- 1.1 What is cURL?
- 1.2 What is libcurl?
- 1.3 What is curl not?
- 1.4 When will you make curl do XXXX ?
- 1.5 Who makes curl?
- 1.6 What do you get for making curl?
- 1.7 What about CURL from curl.com?
- 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?
- 2. Install Related Problems
- 2.1 configure doesn't find OpenSSL even when it is installed
- 2.1.1 native linker doesn't find OpenSSL
- 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) ?
- 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 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?
- 3.9 How do I use curl in my favorite programming language?
- 3.10 What about SOAP, WebDAV, XML-RPC or similar protocols over HTTP?
- 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.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?
- 4. Running Problems
- 4.1 Problems connecting to SSL servers.
- 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.5 Why do I get return code XXX from a HTTP server?
- 4.5.1 "400 Bad Request"
- 4.5.2 "401 Unauthorized"
- 4.5.3 "403 Forbidden"
- 4.5.4 "404 Not Found"
- 4.5.5 "405 Method Not Allowed"
- 4.5.6 "301 Moved Permanently"
- 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.11 Why does 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!
- 5. libcurl Issues
- 5.1 Is libcurl thread-safe?
- 5.2 How can I receive all data into a large memory chunk?
- 5.3 How do I fetch multiple files with libcurl?
- 5.4 Does libcurl do Winsock initing on win32 systems?
- 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.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?
- 6. License Issues
- 6.1 I have a GPL program, can I use the libcurl library?
- 6.2 I have a closed-source program, can I use the libcurl library?
- 6.3 I have a BSD licensed program, can I use the libcurl library?
- 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 commerical apps?
- 7. PHP/CURL Issues
- 7.1 What is PHP/CURL?
- 7.2 Who write PHP/CURL?
- 7.3 Can I perform multiple requests using the same handle?
- ==============================================================================
- 1. Philosophy
- 1.1 What is cURL?
- cURL is the name of the project. The name is a play on 'Client for URLs',
- originally with URL spelled in uppercase to make it obvious it deals with
- URLs. The fact it can also be pronounced 'see URL' also helped, it works as
- an abbreviation for "Client URL Request Library" or why not the recursive
- version: "Curl URL Request Library".
- The cURL project produces two products:
- libcurl
- A free and easy-to-use client-side URL transfer library, supporting FTP,
- FTPS, HTTP, HTTPS, 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 and more...
- libcurl is free, thread-safe, IPv6 compatible, feature rich, well
- supported and fast.
- curl
- A command line tool for getting or sending files using URL syntax.
- Since curl uses libcurl, it supports a range of common Internet protocols,
- currently including HTTP, HTTPS, FTP, FTPS, LDAP, DICT, TELNET and FILE.
- We pronounce curl and cURL with an initial k sound: [kurl].
- There are numerous sub-projects and related projects that also use the word
- curl in the project names in various combinations, but you should take
- notice that this FAQ is directed at the command-line tool named curl (and
- libcurl the library), and may therefore not be valid for other curl-related
- projects. (There is however a small section for the PHP/CURL in this FAQ.)
- 1.2 What is libcurl?
- libcurl is a reliable and portable library which provides you with an easy
- interface to a range of common Internet protocols.
- You can use libcurl for free in your application, be it open source,
- commercial or closed-source.
- libcurl is most probably the most portable, most powerful and most often
- used C-based multi-platform file transfer library on this planet - be it
- open source or commercial.
- 1.3 What is curl not?
- Curl is *not* a wget clone. That is a common misconception. Never, during
- curl's development, have we intended curl to replace wget or compete on its
- market. Curl is targeted at single-shot file transfers.
- Curl is not a web site mirroring program. If you want to use curl to mirror
- something: fine, go ahead and write a script that wraps around curl to make
- it reality (like curlmirror.pl does).
- Curl is not an FTP site mirroring program. Sure, get and send FTP with curl
- but if you want systematic and sequential behavior you should write a
- script (or write a new program that interfaces libcurl) and do it.
- Curl is not a PHP tool, even though it works perfectly well when used from
- or with PHP (when using the PHP/CURL module).
- Curl is not a single-OS program. Curl exists, compiles, builds and runs
- under a wide range of operating systems, including all modern Unixes (and a
- bunch of older ones too), Windows, Amiga, BeOS, OS/2, OS X, QNX etc.
- 1.4 When will you make curl do XXXX ?
- We love suggestions of what to change in order to make curl and libcurl
- better. We do however believe in a few rules when it comes to the future of
- curl:
- * Curl -- the command line tool -- is to remain a non-graphical command line
- tool. If you want GUIs or fancy scripting capabilities, you should look
- for another tool that uses libcurl.
- * We do not add things to curl that other small and available tools already
- do very fine at the side. Curl's output is fine to pipe into another
- program or redirect to another file for the next program to interpret.
- * We focus on protocol related issues and improvements. If you wanna do more
- magic with the supported protocols than curl currently does, chances are
- big we will agree. If you wanna add more protocols, we may very well
- agree.
- * If you want someone else to make all the work while you wait for us to
- implement it for you, that is not a very friendly attitude. We spend a
- considerable time already on maintaining and developing curl. In order to
- get more out of us, you should consider trading in some of your time and
- efforts in return.
- * If you write the code, chances are bigger that it will get into curl
- faster.
- 1.5 Who makes curl?
- curl and libcurl are not made by any single individual. Daniel Stenberg is
- project leader and main developer, but other persons' submissions are
- important and crucial. Anyone can contribute and post their changes and
- improvements and have them inserted in the main sources (of course on the
- condition that developers agree on that the fixes are good).
- The full list of the more than 450 contributors is found in the docs/THANKS
- file.
- curl is developed by a community, with Daniel at the wheel.
- 1.6 What do you get for making curl?
- Project cURL is entirely free and open. No person gets paid for developing
- (lib)curl. We do this voluntarily on our spare time.
- 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.
- 1.7 What about CURL from curl.com?
- During the summer 2001, curl.com was busy advertising their client-side
- programming language for the web, named CURL.
- We are in no way associated with curl.com or their CURL programming
- language.
- Our project name curl has been in effective use since 1998. We were not the
- first computer related project to use the name "curl" and do not claim any
- first-hand rights to the name.
- We recognize that we will be living in parallel with curl.com and wish them
- every success.
- 1.8 I have a problem who do I mail?
- Please do not mail any single individual unless you really need to. Keep
- curl-related questions on a suitable mailing list. All available mailing
- lists are listed in the MANUAL document and online at
- http://curl.haxx.se/mail/
- Keeping curl-related questions and discussions on mailing lists allows
- others to join in and help, to share their ideas, contribute their
- suggestions and spread their wisdom. Keeping discussions on public mailing
- lists also allows for others to learn from this (both current and future
- users thanks to the web based archives of the mailing lists), thus saving us
- from having to repeat ourselves even more. Thanks for respecting this.
- If you have found or simply suspect a security problem in curl or libcurl,
- mail curl-security at haxx.se (closed list of receivers, mails are not
- disclosed) and tell. Then we can produce a fix in a timely manner before the
- flaw is announced to the world, thus lessen the impact the problem will have
- on existing users.
- 1.9 Where do I buy commercial support for curl?
- curl is fully open source. It means you can hire any skilled engineer to fix
- your curl-related problems.
- We list available alternatives on the curl web site:
- http://curl.haxx.se/support.html
- 1.10 How many are using curl?
- It is impossible to tell.
- We don't 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
- fact using it.
- 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:
- curl packages have been downloaded from the curl.haxx.se site well over a
- million times. 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 40 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.
- 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
- 2. Install Related Problems
- 2.1 configure doesn't find OpenSSL even when it is installed
- This may be because of several reasons.
- 2.1.1 native linker doesn't find openssl
- Affected platforms:
- Solaris (native cc compiler)
- HPUX (native cc compiler)
- SGI IRIX (native cc compiler)
- SCO UNIX (native cc compiler)
- When configuring curl, I specify --with-ssl. OpenSSL is installed in
- /usr/local/ssl Configure reports SSL in /usr/local/ssl, but fails to find
- CRYPTO_lock in -lcrypto
- Cause: The cc for this test places the -L/usr/local/ssl/lib AFTER
- -lcrypto, so ld can't find the library. This is due to a bug in the GNU
- autoconf tool.
- Workaround: Specifying "LDFLAGS=-L/usr/local/ssl/lib" in front of
- ./configure places the -L/usr/local/ssl/lib early enough in the command
- line to make things work
- Solution submitted by: Bob Allison <allisonb@users.sourceforge.net>
- 2.1.2 only the libssl lib is missing
- If all include files and the libcrypto lib is present, with only the
- libssl being missing according to configure, this is mostly likely because
- a few functions are left out from the libssl.
- If the function names missing include RSA or RSAREF you can be certain
- that this is because libssl requires the RSA and RSAREF libs to build.
- See the INSTALL file section that explains how to add those libs to
- configure. Make sure that you remove the config.cache file before you
- rerun configure with the new flags.
- 2.2 Does curl work/build with other SSL libraries?
- Curl has been written to use OpenSSL or GnuTLS, 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?
- 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.
- 2.4 Does curl support Socks (RFC 1928) ?
- Yes, SOCKS5 is supported.
- 3. Usage problems
- 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.
- 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 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?
- 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
- 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
- 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.
- 3.4 How do I tell curl to run custom FTP commands?
- 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.
- 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 "Pragma:" 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.
- See also item 3.14 regarding javascript.
- 3.7 Can I use curl to delete/rename a file through FTP?
- Yes. You specify custom FTP commands with -Q/--quote.
- One example would be to delete a file after you have downloaded it:
- curl -O ftp://download.com/coolfile -Q '-DELE coolfile'
- 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
- -L/--location option. As in:
- curl -L http://redirector.com
- Not all redirects are HTTP ones, see 4.14
- 3.9 How do I use curl in my favorite programming language?
- There exist many language interfaces/bindings for curl that integrates it
- better with various languages. If you are fluid in a script language, you
- may very well opt to use such an interface instead of using the command line
- tool.
- Find out more about which languages that support curl directly, and how to
- install and use them, in the libcurl section of the curl web site:
- http://curl.haxx.se/libcurl/
- In February 2003, there are interfaces available for the following
- languages: Basic, C, C++, Cocoa, Dylan, Euphoria, Java, Lua, Object-Pascal,
- Pascal, Perl, PHP, PostgreSQL, Python, Rexx, Ruby, Scheme and Tcl. By the
- time you read this, additional ones may have appeared!
- 3.10 What about SOAP, WebDAV, XML-RPC or similar protocols over HTTP?
- Curl adheres to the HTTP spec, which basically means you can play with *any*
- protocol that is built on top of HTTP. Protocols such as SOAP, WEBDAV and
- 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 fine and you'd just use the proper
- library options to do the same.
- 3.11 How do I POST with a different Content-Type?
- You can always replace the internally generated headers with -H/--header.
- To make a simple HTTP POST with text/xml as content-type, do something like:
- curl -d "datatopost" -H "Content-Type: text/xml" [URL]
- 3.12 Why do FTP specific features over HTTP proxy fail?
- 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
- etc.
- There is one exception to this rule, and that is if you can "tunnel through"
- the given HTTP proxy. Proxy tunneling is enabled with a special option (-p)
- and is generally not available as proxy admins usually disable tunneling to
- other ports than 443 (which is used for HTTPS access through proxies).
- 3.13 Why does my single/double quotes fail?
- To specify a command line option that includes spaces, you might need to
- put the entire option within quotes. Like in:
- curl -d " with spaces " url.com
- or perhaps
- curl -d ' with spaces ' url.com
- 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.
- Please study the documentation for your particular environment. Examples in
- the curl docs will use a mix of both these ones as shown above. You must
- adjust them to work in your environment.
- 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)?
- 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,
- it can't support .pac proxy configuration either.
- Some work-arounds usually suggested to overcome this javascript dependency:
- - 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.
- - 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.
- 3.15 Can I do recursive fetches with curl?
- No. curl itself has no code that performs recursive operations, such as
- those performed by wget and similar tools.
- There exist wrapper scripts with that functionality (for example the
- curlmirror perl script), and you can write programs based on libcurl to do
- it, but the command line tool curl itself cannot.
- 3.16 What certificates do I need when I use SSL?
- There are three different kinds of "certificates" to keep track of when we
- talk about using SSL-based protocols (HTTPS or FTPS) using curl or libcurl.
- - Client certificate. The server you communicate 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.
- - 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
- it.
- - 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 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
- certificate. Server certificate verification is enabled by default in curl
- and libcurl and is often the reason for problems as explained in FAQ entry
- 4.12 and the SSLCERTS document
- (http://curl.haxx.se/docs/sslcerts.html). Server certificates that are
- "self-signed" or otherwise signed by a CA that you do not have a CA cert
- for, cannot be verified. If the verification during a connect fails, you
- are refused access. You then need to explicitly disable the verification
- to connect to the server.
- 3.17 How do I list the root dir of an FTP server?
- There are two ways. The way defined in the RFC is to use an encoded slash
- in the first path part. List the "/tmp" dir like this:
- curl ftp://ftp.sunet.se/%2ftmp/
- or the not-quite-kosher-but-more-readable way, by simply starting the path
- section of the URL with a slash:
- 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.
- 4. Running Problems
- 4.1 Problems connecting to SSL servers.
- It took a very long time before we could sort out why curl had problems to
- connect to certain SSL servers when using SSLeay or OpenSSL v0.9+. The
- error sometimes showed up similar to:
- 16570:error:1407D071:SSL routines:SSL2_READ:bad mac decode:s2_pkt.c:233:
- It turned out to be because many older SSL servers don't deal with SSLv3
- requests properly. To correct this problem, tell curl to select SSLv2 from
- the command line (-2/--sslv2).
- There have also been examples where the remote server didn't like the SSLv2
- request and instead you had to force curl to use SSLv3 with -3/--sslv3.
- 4.2 Why do I get problems when I use & or % in the URL?
- 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.
- 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 %-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 %-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 %-letter doubled on Windows machines).
- 4.3 How can I use {, }, [ or ] to specify multiple URLs?
- Because those letters have a special meaning to the shell, and to be used in
- a URL specified to curl you must quote them.
- An example that downloads two URLs (sequentially) would do:
- curl '{curl,www}.haxx.se'
- To be able to use those letters as actual parts of the URL (without using
- them for the curl URL "globbing" system), use the -g/--globoff option:
- curl -g 'www.site.com/weirdname[].html'
- 4.4 Why do I get downloaded data even though the web page doesn't exist?
- Curl asks remote servers for the page you specify. If the page doesn't 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
- 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.
- 4.5 Why do I get return code XXX from a HTTP server?
- RFC2616 clearly explains the return codes. This is a short transcript. Go
- read the RFC for exact details:
- 4.5.1 "400 Bad Request"
- The request could not be understood by the server due to malformed
- syntax. The client SHOULD NOT repeat the request without modifications.
- 4.5.2 "401 Unauthorized"
- The request requires user authentication.
- 4.5.3 "403 Forbidden"
- 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"
- The server has not found anything matching the Request-URI. No indication
- is given of whether the condition is temporary or permanent.
- 4.5.5 "405 Method Not Allowed"
- The method specified in the Request-Line is not allowed for the resource
- identified by the Request-URI. The response MUST include an Allow header
- containing a list of valid methods for the requested resource.
- 4.5.6 "301 Moved Permanently"
- If you get this return code and an HTML output similar to this:
- <H1>Moved Permanently</H1> The document has moved <A
- HREF="http://same_url_now_with_a_trailing_slash/">here</A>.
- it might be because you request a directory URL but without the trailing
- slash. Try the same operation again _with_ the trailing URL, or use the
- -L/--location option to follow the redirection.
- 4.6 Can you tell me what error code 142 means?
- All curl error codes are described at the end of the man page, in the
- section called "EXIT CODES".
- Error codes that are larger than the highest documented error code means
- that curl has exited due to a crash. This is a serious error, and we
- appreciate a detailed bug report from you that describes how we could go
- ahead and repeat this!
- 4.7 How do I keep user names and passwords secret in Curl command lines?
- 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
- 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.
- 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
- at least hide them from being read by human eyes, but that is not what
- anyone would call security.
- Also note that regular HTTP (using Basic authentication) and FTP passwords
- are sent in clear across the network. All it takes for anyone to fetch them
- is to listen on the network. Eavesdropping is very easy. Use more secure
- authentication methods (like Digest, Negotiate or even NTLM) or consider the
- SSL-based alternatives HTTPS and FTPS.
- 4.8 I found a bug!
- 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
- 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?
- This is supported in curl 7.10.6 or later. No earlier curl version knows
- of this magic.
- 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!
- 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
- anything about.
- 4.11 Why does my HTTP range requests return the full document?
- Because the range may not be supported by the server, or the server may
- choose to ignore it and return the full document anyway.
- 4.12 Why do I get "certificate verify failed" ?
- You invoke curl 7.10 or later to communicate on a https:// URL and get an
- error back looking something similar to this:
- curl: (35) SSL: error:14090086:SSL routines:
- SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
- Then it means that curl couldn't verify that the server's certificate was
- good. Curl verifies the certificate using the CA cert bundle that comes with
- the curl installation.
- To disable the verification (which makes it act like curl did before 7.10),
- use -k. This does however enable man-in-the-middle attacks.
- If you get this failure but are having a CA cert bundle installed and used,
- the server's certificate is not signed by one of the CA's in the bundle. It
- might for example be self-signed. You then correct this problem by obtaining
- a valid CA cert for the server. Or again, decrease the security by disabling
- this check.
- Details are also in the SSLCERTS file in the release archives, found online
- here: http://curl.haxx.se/docs/sslcerts.html
- 4.13 Why is curl -R on Windows one hour off?
- During daylight savings time, when -R is used, curl will set a time that
- appears one hour off. This happens due to a flaw in how Windows stores and
- uses file modification times and it is not easily worked around. For details
- on this problem, read this: http://www.codeproject.com/datetime/dstbugs.asp
- 4.14 Redirects work in browser but not with curl!
- curl supports HTTP redirects fine (see item 3.8). Browsers generally support
- at least two other ways to perform directs that curl does not:
- - 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 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
- manually figure out what the page is set to do, or you write a script that
- parses the results and fetches the new URL.
- 5. libcurl Issues
- 5.1 Is libcurl thread-safe?
- Yes.
- 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.
- 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#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
- for the crypto functions).
- http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html
- 5.2 How can I receive all data into a large memory chunk?
- [ See also the examples/getinmemory.c source ]
- You are in full control of the callback function that gets called every time
- there is data received from the remote server. You can make that callback do
- whatever you want. You do not have to write the received data to a file.
- One solution to this problem could be to have a pointer to a struct that you
- pass to the callback function. You set the pointer using the
- CURLOPT_WRITEDATA option. Then that pointer will be passed to the callback
- instead of a FILE * to a file:
- /* imaginary struct */
- struct MemoryStruct {
- char *memory;
- size_t size;
- };
- /* imaginary callback function */
- size_t
- WriteMemoryCallback(void *ptr, size_t size, size_t nmemb, void *data)
- {
- size_t realsize = size * nmemb;
- struct MemoryStruct *mem = (struct MemoryStruct *)data;
- mem->memory = (char *)realloc(mem->memory, mem->size + realsize + 1);
- if (mem->memory) {
- memcpy(&(mem->memory[mem->size]), ptr, realsize);
- mem->size += realsize;
- mem->memory[mem->size] = 0;
- }
- return realsize;
- }
- 5.3 How do I fetch multiple files with libcurl?
- 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
- will enable libcurl to use persistent connections.
- 5.4 Does libcurl do Winsock initialization on win32 systems?
- Yes, if told to in the curl_global_init() call.
- 5.5 Does CURLOPT_WRITEDATA and CURLOPT_READDATA work on win32 ?
- Yes, but you cannot open a FILE * and pass the pointer to a DLL and have
- that DLL use the FILE * (as the DLL and the client application cannot access
- each others' variable memory areas). If you set CURLOPT_WRITEDATA you must
- also use CURLOPT_WRITEFUNCTION as well to set a function that writes the
- file, even if that simply writes the data to the specified FILE *.
- Similarly, if you use CURLOPT_READDATA you must also specify
- CURLOPT_READFUNCTION.
- (Provided by Joel DeYoung and Bob Schader)
- 5.6 What about Keep-Alive or persistent connections?
- curl and libcurl have excellent support for persistent connections when
- transferring several files from the same server. Curl will attempt to reuse
- connections for all URLs specified on the same command line/config file, and
- libcurl will reuse connections for all transfers that are made using the
- same libcurl handle.
- 5.7 Link errors when building libcurl on Windows!
- You need to make sure that your project, and all the libraries (both static
- and dynamic) that it links against, are compiled/linked against the same run
- time library.
- This is determined by the /MD, /ML, /MT (and their corresponding /M?d)
- options to the command line compiler. /MD (linking against MSVCRT dll) seems
- to be the most commonly used option.
- (Provided by Andrew Francis)
- 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 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
- 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.3.
- 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:
- * Add an option to the linker command line that specify the hard-coded path
- the run-time linker should check for the lib (usually -R)
- * 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
- put the dir (like Linux's /etc/ld.so.conf)
- 'man ld.so' and 'man ld' will tell you more details
- 5.9 How does libcurl resolve host names?
- libcurl supports a large a number of different name resolve functions. One
- of them is picked at build-time and will be used unconditionally. Thus, if
- you want to change name resolver function you must rebuild libcurl and tell
- it to use a different function.
- - 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
- - 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.
- - The Windows threaded resolver. It use:
- 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.
- 5.10 How do I prevent libcurl from writing the response to stdout?
- libcurl provides a default built-in write function that writes received data
- to stdout. Set the CURLOPT_WRITEFUNCTION to receive the data, or possibly
- set CURLOPT_WRITEDATA to a different FILE * handle.
- 5.11 How do I make libcurl not receive the whole HTTP response?
- You make the write callback (or progress callback) return an error and
- libcurl will then abort the transfer.
- 5.12 Can I make libcurl fake or hide my real IP address?
- No. libcurl operates on a higher level than so. Besides, faking IP address
- would imply sending IP packages with a made-up source address, and then you
- normally get a problem with intercepting the packages sent back as they
- would then not be routed to you!
- If you use a proxy to access remote sites, the sites will not see your local
- IP address but instead the address of the proxy.
- Also note that on many networks NATs or other IP-munging techniques are used
- that makes you see and use a different IP address locally than what the
- remote server will see you coming from.
- 6. License Issues
- Curl and libcurl are released under a MIT/X derivate license. The license is
- very liberal and should not impose a problem for your project. This section
- is just a brief summary for the cases we get the most questions. (Parts of
- this section was much enhanced by Bjorn Reese.)
- 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.
- 6.1 I have a GPL program, can I use the libcurl library?
- Yes!
- Since libcurl may be distributed under the MIT/X derivate license, it can be
- used together with GPL in any software.
- 6.2 I have a closed-source program, can I use the libcurl library?
- Yes!
- libcurl does not put any restrictions on the program that uses the library.
- 6.3 I have a BSD licensed program, can I use the libcurl library?
- Yes!
- libcurl does not put any restrictions on the program that uses the library.
- 6.4 I have a program that uses LGPL libraries, can I use libcurl?
- Yes!
- The LGPL license doesn't clash with other licenses.
- 6.5 Can I modify curl/libcurl for my program and keep the changes secret?
- Yes!
- The MIT/X derivate license practically allows you to do almost anything with
- the sources, on the condition that the copyright texts in the sources are
- left intact.
- 6.6 Can you please change the curl/libcurl license to XXXX?
- No.
- We have carefully picked this license after years of development and
- discussions and a large amount of people have contributed with source code
- knowing that this is the license we use. This license puts the restrictions
- we want on curl/libcurl and it does not spread to other programs or
- 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 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
- notice in "all copies" and that you may not use the copyright holder's name
- when promoting your software.
- You do not have to release any of your source code.
- 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
- your app.
- 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
- 7.1 What is PHP/CURL?
- The module for PHP that makes it possible for PHP programs to access curl-
- functions from within PHP.
- In the cURL project we call this module PHP/CURL to differentiate it from
- curl the command line tool and libcurl the library. The PHP team however
- does not refer to it like this (for unknown reasons). They call it plain
- CURL (often using all caps) which causes much confusion to users which in
- turn gives us a higher question load.
- 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
- PHP/CURL can be used. PHP/CURL is written by Sterling Hughes.
- 7.3 Can I perform multiple requests using the same handle?
- Yes - at least in PHP version 4.3.8 and later (this has been known to not
- work in earlier versions, but the exact version when it started to work is
- unknown to me).
- After a transfer, you just set new options in the handle and make another
- transfer. This will make libcurl to re-use the same connection if it can.
|