diff options
Diffstat (limited to 'docs')
272 files changed, 12180 insertions, 3444 deletions
diff --git a/docs/BINDINGS b/docs/BINDINGS index 5cf07fecd..466c36bd0 100644 --- a/docs/BINDINGS +++ b/docs/BINDINGS @@ -6,14 +6,14 @@ libcurl bindings -Creative people have written bindings or interfaces for various environments -and programming languages. Using one of these allows you to take advantage of -curl powers from within your favourite language or system. + Creative people have written bindings or interfaces for various environments + and programming languages. Using one of these allows you to take advantage of + curl powers from within your favourite language or system. -This is a list of all known interfaces as of this writing. + This is a list of all known interfaces as of this writing. -The bindings listed below are not part of the curl/libcurl distribution -archives, but must be downloaded and installed separately. + The bindings listed below are not part of the curl/libcurl distribution + archives, but must be downloaded and installed separately. Ada95 @@ -41,7 +41,10 @@ Ch Cocoa - Written by Dan Wood + BBHTTP: written by Bruno de Carvalho + https://github.com/brunodecarvalho/BBHTTP + + curlhandle: Written by Dan Wood http://curlhandle.sourceforge.net/ D @@ -55,6 +58,7 @@ Dylan http://dylanlibs.sourceforge.net/ Eiffel + Written by Eiffel Software http://curl.haxx.se/libcurl/eiffel/ @@ -81,6 +85,11 @@ glib/GTK+ Written by Richard Atterer http://atterer.net/glibcurl/ +Guile: + + Written by Michael L. Gran + http://www.lonelycactus.com/guile-curl.html + Haskell Written by Galois, Inc @@ -91,6 +100,11 @@ Java Maintained by [blank] http://curl.haxx.se/libcurl/java/ +Julia + + Written by Paul Howe + https://github.com/forio/Curl.jl + Lisp Written by Liam Healy @@ -6,39 +6,56 @@ BUGS + 1. Bugs + 1.1 There are still bugs + 1.2 Where to report + 1.3 What to report + 1.4 libcurl problems + 1.5 Who will fix the problems + 1.6 How to get a stack trace + 1.7 Bugs in libcurl bindings + +============================================================================== + +1.1 There are still bugs + Curl and libcurl have grown substantially since the beginning. At the time - of writing (July 2007), there are about 47000 lines of source code, and by - the time you read this it has probably grown even more. + of writing (January 2013), there are about 83,000 lines of source code, and + by the time you read this it has probably grown even more. Of course there are lots of bugs left. And lots of misfeatures. To help us make curl the stable and solid product we want it to be, we need bug reports and bug fixes. -WHERE TO REPORT +1.2 Where to report If you can't fix a bug yourself and submit a fix for it, try to report an as detailed report as possible to a curl mailing list to allow one of us to - have a go at a solution. You should also post your bug/problem at curl's bug - tracking system over at + have a go at a solution. You can optionally also post your bug/problem at + curl's bug tracking system over at - http://sourceforge.net/bugs/?group_id=976 + https://sourceforge.net/p/curl/bugs/ - (but please read the sections below first before doing that) + Please read the rest of this document below first before doing that! Also, + you need to login to your sourceforge account before being able to submit a + bug report (necessary evil done to avoid spam). If you feel you need to ask around first, find a suitable mailing list and post there. The lists are available on http://curl.haxx.se/mail/ -WHAT TO REPORT +1.3 What to report When reporting a bug, you should include all information that will help us understand what's wrong, what you expected to happen and how to repeat the bad behavior. You therefore need to tell us: - - your operating system's name and version number (uname -a under a unix - is fine) + - your operating system's name and version number + - what version of curl you're using (curl -V is fine) + - versions of the used libraries that libcurl is built to use + - what URL you were working with (if possible), at least which protocol and anything and everything else you think matters. Tell us what you @@ -59,7 +76,48 @@ WHAT TO REPORT The address and how to subscribe to the mailing lists are detailed in the MANUAL file. -HOW TO GET A STACK TRACE +1.4 libcurl problems + + First, post all libcurl problems on the curl-library mailing list. + + When you've written your own application with libcurl to perform transfers, + it is even more important to be specific and detailed when reporting bugs. + + Tell us the libcurl version and your operating system. Tell us the name and + version of all relevant sub-components like for example the SSL library + you're using and what name resolving your libcurl uses. If you use SFTP or + SCP, the libssh2 version is relevant etc. + + Showing us a real source code example repeating your problem is the best way + to get our attention and it will greatly increase our chances to understand + your problem and to work on a fix (if we agree it truly is a problem). + + Lots of problems that appear to be libcurl problems are actually just abuses + of the libcurl API or other malfunctions in your applications. It is advised + that you run your problematic program using a memory debug tool like + valgrind or similar before you post memory-related or "crashing" problems to + us. + +1.5 Who will fix the problems + + If the problems or bugs you describe are considered to be bugs, we want to + have the problems fixed. + + There are no developers in the curl project that are paid to work on bugs. + All developers that take on reported bugs do this on a voluntary basis. We + do it out of an ambition to keep curl and libcurl excellent products and out + of pride. + + But please do not assume that you can just lump over something to us and it + will then magically be fixed after some given time. Most often we need + feedback and help to understand what you've experienced and how to repeat a + problem. Then we may only be able to assist YOU to debug the problem and to + track down the proper fix. + + We get reports from many people every month and each report can take a + considerable amount of time to really go to the bottom with. + +1.6 How to get a stack trace First, you must make sure that you compile all sources with -g and that you don't 'strip' the final executable. Try to avoid optimizing the code as @@ -79,3 +137,12 @@ HOW TO GET A STACK TRACE crashed. Include the stack trace with your detailed bug report. It'll help a lot. +1.7 Bugs in libcurl bindings + + There will of course pop up bugs in libcurl bindings. You should then + primarily approach the team that works on that particular binding and see + what you can do to help them fix the problem. + + If you suspect that the problem exists in the underlying libcurl, then + please convert your program over to plain C and follow the steps outlined + above. diff --git a/docs/CONTRIBUTE b/docs/CONTRIBUTE index db03c42a1..75e7ebbb9 100644 --- a/docs/CONTRIBUTE +++ b/docs/CONTRIBUTE @@ -34,6 +34,7 @@ 3.3 How To Make a Patch without git 3.4 How to get your changes into the main sources 3.5 Write good commit messages + 3.6 Please don't send pull requests ============================================================================== @@ -78,9 +79,9 @@ 1.3 What To Read Source code, the man pages, the INTERNALS document, TODO, KNOWN_BUGS, the - most recent CHANGES. Just lurking on the libcurl mailing list is gonna give - you a lot of insights on what's going on right now. Asking there is a good - idea too. + most recent CHANGES. Just lurking on the curl-library mailing list is gonna + give you a lot of insights on what's going on right now. Asking there is a + good idea too. 2. cURL Coding Standards @@ -97,12 +98,12 @@ 2.2 Indenting - Please try using the same indenting levels and bracing method as all the - other code already does. It makes the source code a lot easier to follow if - all of it is written using the same style. We don't ask you to like it, we - just ask you to follow the tradition! ;-) This mainly means: 2-level indents, - using spaces only (no tabs) and having the opening brace ({) on the same line - as the if() or while(). + Use the same indenting levels and bracing method as all the other code + already does. It makes the source code easier to follow if all of it is + written using the same style. We don't ask you to like it, we just ask you to + follow the tradition! ;-) This mainly means: 2-level indents, using spaces + only (no tabs) and having the opening brace ({) on the same line as the if() + or while(). Also note that we use if() and while() with no space before the parenthesis. @@ -150,6 +151,9 @@ description exactly what they correct so that all patches can be selectively applied by the maintainer or other interested parties. + Also, separate patches enable bisecting much better when we track problems in + the future. + 2.9 Patch Against Recent Sources Please try to get the latest available sources to make your patches @@ -177,6 +181,10 @@ test case that verifies that it works as documented. If every submitter also posts a few test cases, it won't end up as a heavy burden on a single person! + If you don't have test cases or perhaps you have done something that is very + hard to write tests for, do explain exactly how you have otherwise tested and + verified your changes. + 3. Pushing Out Your Changes 3.1 Write Access to git Repository @@ -189,7 +197,7 @@ 3.2 How To Make a Patch with git - You need to first checkout the respository: + You need to first checkout the repository: git clone git://github.com/bagder/curl.git @@ -211,7 +219,7 @@ commit. Now send those patches off to the curl-library list. You can of course opt to - do that with the 'get send-email' command. + do that with the 'git send-email' command. 3.3 How To Make a Patch without git @@ -233,47 +241,70 @@ For unix-like operating systems: - http://www.gnu.org/software/patch/patch.html - http://www.gnu.org/directory/diffutils.html + http://www.gnu.org/software/patch/patch.html + http://www.gnu.org/directory/diffutils.html For Windows: - http://gnuwin32.sourceforge.net/packages/patch.htm - http://gnuwin32.sourceforge.net/packages/diffutils.htm + http://gnuwin32.sourceforge.net/packages/patch.htm + http://gnuwin32.sourceforge.net/packages/diffutils.htm 3.4 How to get your changes into the main sources - 1. Submit your patch to the curl-library mailing list + Submit your patch to the curl-library mailing list. - 2. Make the patch against as recent sources as possible. + Make the patch against as recent sources as possible. - 3. Make sure your patch adheres to the source indent and coding style of - already existing source code. Failing to do so just adds more work for me. + Make sure your patch adheres to the source indent and coding style of already + existing source code. Failing to do so just adds more work for me. - 4. Respond to replies on the list about the patch and answer questions and/or - fix nits/flaws. This is very important. I will take lack of replies as a - sign that you're not very anxious to get your patch accepted and I tend to - simply drop such patches from my TODO list. + Respond to replies on the list about the patch and answer questions and/or + fix nits/flaws. This is very important. I will take lack of replies as a sign + that you're not very anxious to get your patch accepted and I tend to simply + drop such patches from my TODO list. - 5. If you've followed the above mentioned paragraphs and your patch still - hasn't been incorporated after some weeks, consider resubmitting it to the - list. + If you've followed the above paragraphs and your patch still hasn't been + incorporated after some weeks, consider resubmitting it to the list. 3.5 Write good commit messages - A short guide to how to do fine commit messages in the curl project. + A short guide to how to do fine commit messages in the curl project. + + ---- start ---- + [area]: [short line describing the main effect] + + [separate the above single line from the rest with an empty line] + + [full description, no wider than 72 columns that describe as much as + possible as to why this change is made, and possibly what things + it fixes and everything else that is related] + ---- stop ---- + + Don't forget to use commit --author="" if you commit someone else's work, + and make sure that you have your own user and email setup correctly in git + before you commit + +3.6 Please don't send pull requests + + With git (and especially github) it is easy and tempting to send a pull + request to one or more people in the curl project to have changes merged this + way instead of mailing patches to the curl-library mailing list. + + We don't like that. We want them mailed for these reasons: - ---- start ---- - [area]: [short line describing the main effect] + - Peer review. Anyone and everyone on the list can review, comment and + improve on the patch. Pull requests limit this ability. - [separate the above single line from the rest with an empty line] + - Anyone can merge the patch into their own trees for testing and those who + have push rights can push it to the main repo. It doesn't have to be anyone + the patch author knows beforehand. - [full description, no wider than 72 columns that describe as much as - possible as to why this change is made, and possibly what things - it fixes and everything else that is related] - ---- stop ---- + - Commit messages can be tweaked and changed if merged locally instead of + using github. Merges directly on github requires the changes to be perfect + already, which they seldom are. - Don't forget to use commit --author="" if you commit someone else's work, - and make sure that you have your own user and email setup correctly in git - before you commit + - Merges on github prevents rebases and even enforces --no-ff which is a git + style we don't otherwise use in the project + However: once patches have been reviewed and deemed fine on list they are + perfectly OK to be pulled from a published git tree. @@ -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 diff --git a/docs/FEATURES b/docs/FEATURES index 32589e1d3..14d7e78dd 100644 --- a/docs/FEATURES +++ b/docs/FEATURES @@ -13,27 +13,29 @@ curl tool - multiple file upload on a single command line - custom maximum transfer rate - redirectable stderr + - metalink support (*13) -libcurl supports +libcurl - full URL syntax with no length limit - custom maximum download time - custom least download speed acceptable - custom output result after completion - guesses protocol from host name unless specified - uses .netrc - - progress bar/time specs while downloading + - progress bar with time statistics while downloading - "standard" proxy environment variables support - compiles on win32 (reported builds on 40+ operating systems) - selectable network interface for outgoing traffic - IPv6 support on unix and Windows - - persistant connections + - persistent connections - socks5 support - - supports user name + password in proxy environment variables + - supports user name and password in proxy environment variables - operations through proxy "tunnel" (using CONNECT) - - supports large files (>2GB and >4GB) both upload/download - - replacable memory functions (malloc, free, realloc, etc) + - support for large files (>2GB and >4GB) during upload and download + - replaceable memory functions (malloc, free, realloc, etc) - asynchronous name resolving (*6) - both a push and a pull style interface + - international domain names (*11) HTTP - HTTP/1.1 compliant (optionally uses 1.0) @@ -43,7 +45,7 @@ HTTP - POST - Pipelining - multipart formpost (RFC1867-style) - - authentication: Basic, Digest, NTLM(*9), GSS-Negotiate/Negotiate(*3) and + - authentication: Basic, Digest, NTLM (*9), GSS-Negotiate/Negotiate (*3) and SPNEGO (*4) to server and proxy - resume (both GET and PUT) - follow redirects @@ -60,7 +62,8 @@ HTTP - via http-proxy - retrieve file modification date - Content-Encoding support for deflate and gzip - - "Transfer-Encoding: chunked" support for "uploads" + - "Transfer-Encoding: chunked" support in uploads + - data compression (*12) HTTPS (*1) - (all the HTTP features) @@ -68,12 +71,13 @@ HTTPS (*1) - verify server certificate - via http-proxy - select desired encryption - - force usage of a specific SSL version (SSLv2(*7), SSLv3 or TLSv1) + - force usage of a specific SSL version (SSLv2 (*7), SSLv3 (*10) or TLSv1) FTP - download - authentication - - kerberos4 (*5), kerberos5 (*3) + - kerberos4 (*5) + - kerberos5 (*3) - active/passive using PORT, EPRT, PASV or EPSV - single file size information (compare to HTTP HEAD) - 'type=' URL support @@ -93,7 +97,7 @@ FTP FTPS (*1) - implicit ftps:// support that use SSL on both connections - - explicit "AUTH TSL" and "AUTH SSL" usage to "upgrade" plain ftp:// + - explicit "AUTH TLS" and "AUTH SSL" usage to "upgrade" plain ftp:// connection to use SSL for both or one of the connections SCP (*8) @@ -104,7 +108,8 @@ SFTP (*8) - with custom commands sent before/after the transfer TFTP - - download / upload + - download + - upload TELNET - connection negotiation @@ -119,18 +124,73 @@ DICT FILE - URL support - - "uploads" + - upload - resume +SMTP + - authentication: Plain, Login, CRAM-MD5, Digest-MD5 and NTLM (*9) + - send e-mails + - mail from support + - mail size support + - mail auth support for trusted server-to-server relaying + - multiple recipients + - via http-proxy + +SMTPS (*1) + - implicit smtps:// support + - explicit "STARTTLS" usage to "upgrade" plain smtp:// connections to use SSL + - via http-proxy + +POP3 + - authentication: Clear Text, APOP and SASL + - SASL based authentication: Plain, Login, CRAM-MD5, Digest-MD5 and + NTLM (*9) + - list e-mails + - retrieve e-mails + - enhanced command support for: CAPA, DELE, TOP, STAT, UIDL and NOOP via + custom requests + - via http-proxy + +POP3S (*1) + - implicit pop3s:// support + - explicit "STLS" usage to "upgrade" plain pop3:// connections to use SSL + - via http-proxy + +IMAP + - authentication: Clear Text and SASL + - SASL based authentication: Plain, Login, CRAM-MD5, Digest-MD5 and + NTLM (*9) + - list the folders of a mailbox + - select a mailbox with support for verifing the UIDVALIDITY + - fetch e-mails with support for specifing the UID and SECTION + - upload e-mails via the append command + - enhanced command support for: EXAMINE, CREATE, DELETE, RENAME, STATUS, + STORE, COPY and UID via custom requests + - via http-proxy + +IMAPS (*1) + - implicit imaps:// support + - explicit "STARTTLS" usage to "upgrade" plain imap:// connections to use SSL + - via http-proxy + FOOTNOTES ========= - *1 = requires OpenSSL, GnuTLS, NSS, yassl or PolarSSL + *1 = requires OpenSSL, GnuTLS, NSS, yassl, axTLS, PolarSSL, schannel (native + Windows), Secure Transport (native iOS/OS X) or qssl (native IBM i) *2 = requires OpenLDAP - *3 = requires a GSSAPI-compliant library, such as Heimdal or similar. + *3 = requires a GSSAPI-compliant library, such as Heimdal or similar *4 = requires FBopenssl - *5 = requires a krb4 library, such as the MIT one or similar. + *5 = requires a krb4 library, such as the MIT one or similar *6 = requires c-ares - *7 = requires OpenSSL or NSS, as GnuTLS only supports SSLv3 and TLSv1 + *7 = requires OpenSSL, NSS, qssl, schannel or Secure Transport; GnuTLS, for + example, only supports SSLv3 and TLSv1 *8 = requires libssh2 - *9 = requires OpenSSL, GnuTLS, NSS or yassl + *9 = requires OpenSSL, GnuTLS, NSS, yassl, Secure Transport or SSPI (native + Windows) + *10 = requires any of the SSL libraries in (*1) above other than axTLS, which + does not support SSLv3 + *11 = requires libidn or Windows + *12 = requires libz + *13 = requires libmetalink, and either an Apple or Microsoft operating + system, or OpenSSL, or GnuTLS, or NSS diff --git a/docs/HISTORY b/docs/HISTORY index e04fb53df..3c140999e 100644 --- a/docs/HISTORY +++ b/docs/HISTORY @@ -7,19 +7,19 @@ How cURL Became Like This -In the second half of 1997, Daniel Stenberg came up with the idea to make +Towards the end of 1996, Daniel Stenberg came up with the idea to make currency-exchange calculations available to Internet Relay Chat (IRC) users. All the necessary data are published on the Web; he just needed to automate their retrieval. Daniel simply adopted an existing command-line open-source tool, httpget, that -Brazilian Rafael Sagula had written. After a few minor adjustments, it did -just what he needed. +Brazilian Rafael Sagula had written and recently release version 0.1 of. After +a few minor adjustments, it did just what he needed. HttpGet 1.0 was released +on April 8th 1997 with brand new HTTP proxy support. -Soon, he found currencies on a GOPHER site, so support for that had to go in, -and not before long FTP download support was added as well. The name of the -project was changed to urlget to better fit what it actually did now, since -the http-only days were already passed. +We soon found and fixed support for getting currencies over GOPHER. Once FTP +download support was added, the name of the project was changed and urlget 2.0 +was released in August 1997. The http-only days were already passed. The project slowly grew bigger. When upload capabilities were added and the name once again was misleading, a second name change was made and on March 20, diff --git a/docs/HTTP-COOKIES b/docs/HTTP-COOKIES new file mode 100644 index 000000000..818e161ee --- /dev/null +++ b/docs/HTTP-COOKIES @@ -0,0 +1,123 @@ +Updated: July 3, 2012 (http://curl.haxx.se/docs/http-cookies.html) + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + + +HTTP Cookies + + 1. HTTP Cookies + 1.1 Cookie overview + 1.2 Cookies saved to disk + 1.3 Cookies with curl the command line tool + 1.4 Cookies with libcurl + 1.5 Cookies with javascript + +============================================================================== + +1. HTTP Cookies + + 1.1 Cookie overview + + HTTP cookies are pieces of 'name=contents' snippets that a server tells the + client to hold and then the client sends back those the server on subsequent + requests to the same domains/paths for which the cookies were set. + + Cookies are either "session cookies" which typically are forgotten when the + session is over which is often translated to equal when browser quits, or + the cookies aren't session cookies they have expiration dates after which + the client will throw them away. + + Cookies are set to the client with the Set-Cookie: header and are sent to + servers with the Cookie: header. + + For a very long time, the only spec explaining how to use cookies was the + original Netscape spec from 1994: http://curl.haxx.se/rfc/cookie_spec.html + + In 2011, RFC6265 (http://www.ietf.org/rfc/rfc6265.txt) was finally published + and details how cookies work within HTTP. + + 1.2 Cookies saved to disk + + Netscape once created a file format for storing cookies on disk so that they + would survive browser restarts. curl adopted that file format to allow + sharing the cookies with browsers, only to see browsers move away from that + format. Modern browsers no longer use it, while curl still does. + + The netscape cookie file format stores one cookie per physical line in the + file with a bunch of associated meta data, each field separated with + TAB. That file is called the cookiejar in curl terminology. + + When libcurl saves a cookiejar, it creates a file header of its own in which + there is a URL mention that will link to the web version of this document. + + 1.3 Cookies with curl the command line tool + + curl has a full cookie "engine" built in. If you just activate it, you can + have curl receive and send cookies exactly as mandated in the specs. + + Command line options: + + -b, --cookie + + tell curl a file to read cookies from and start the cookie engine, or if + it isn't a file it will pass on the given string. -b name=var works and so + does -b cookiefile. + + -j, --junk-session-cookies + + when used in combination with -b, it will skip all "session cookies" on + load so as to appear to start a new cookie session. + + -c, --cookie-jar + + tell curl to start the cookie engine and write cookies to the given file + after the request(s) + + 1.4 Cookies with libcurl + + libcurl offers several ways to enable and interface the cookie engine. These + options are the ones provided by the native API. libcurl bindings may offer + access to them using other means. + + CURLOPT_COOKIE + + Is used when you want to specify the exact contents of a cookie header to + send to the server. + + CURLOPT_COOKIEFILE + + Tell libcurl to activate the cookie engine, and to read the initial set of + cookies from the given file. Read-only. + + CURLOPT_COOKIEJAR + + Tell libcurl to activate the cookie engine, and when the easy handle is + closed save all known cookies to the given cookiejar file. Write-only. + + CURLOPT_COOKIELIST + + Provide detailed information about a single cookie to add to the internal + storage of cookies. Pass in the cookie as a HTTP header with all the + details set, or pass in a line from a netscape cookie file. This option + can also be used to flush the cookies etc. + + CURLINFO_COOKIELIST + + Extract cookie information from the internal cookie storage as a linked + list. + + 1.5 Cookies with javascript + + These days a lot of the web is built up by javascript. The webbrowser loads + complete programs that render the page you see. These javascript programs + can also set and access cookies. + + Since curl and libcurl are plain HTTP clients without any knowledge of or + capability to handle javascript, such cookies will not be detected or used. + + Often, if you want to mimic what a browser does on such web sites, you can + record web browser HTTP traffic when using such a site and then repeat the + cookie operations using curl or libcurl. diff --git a/docs/INSTALL b/docs/INSTALL index 9a5844fc2..4140359da 100644 --- a/docs/INSTALL +++ b/docs/INSTALL @@ -14,6 +14,12 @@ Installing Binary Packages binary package. This document describes how to compile, build and install curl and libcurl from source code. +Building from git +================= + + If you get your code off a git repository, see the GIT-INFO file in the + root directory for specific instructions on how to proceed. + UNIX ==== A normal unix installation is made in three or four steps (after you've @@ -129,18 +135,18 @@ UNIX default. But if you want to alter it, you can select how to deal with each individual library. - To build with GnuTLS support instead of OpenSSL for SSL/TLS, note that - you need to use both --without-ssl and --with-gnutls. + To build with GnuTLS for SSL/TLS, use both --without-ssl and + --with-gnutls. - To build with yassl support instead of OpenSSL or GnuTLS, you must build - yassl with its OpenSSL emulation enabled and point to that directory root - with configure --with-ssl. + To build with Cyassl for SSL/TLS, use both --without-ssl and + --with-cyassl. - To build with NSS support instead of OpenSSL for SSL/TLS, note that - you need to use both --without-ssl and --with-nss. + To build with NSS for SSL/TLS, use both --without-ssl and --with-nss. - To build with PolarSSL support instead of OpenSSL for SSL/TLS, note that - you need to use both --without-ssl and --with-polarssl. + To build with PolarSSL for SSL/TLS, use both --without-ssl and + --with-polarssl. + + To build with axTLS for SSL/TLS, use both --without-ssl and --with-axtls. To get GSSAPI support, build with --with-gssapi and have the MIT or Heimdal Kerberos 5 packages installed. @@ -148,6 +154,9 @@ UNIX To get support for SCP and SFTP, build with --with-libssh2 and have libssh2 0.16 or later installed. + To get Metalink support, build with --with-libmetalink and have the + libmetalink packages installed. + SPECIAL CASES ------------- Some versions of uClibc require configuring with CPPFLAGS=-D_GNU_SOURCE=1 @@ -188,6 +197,9 @@ Win32 first to rebuild every single library your app uses as well as your app using the debug multithreaded dynamic C runtime. + If you get linkage errors read section 5.7 of the FAQ document. + + MingW32 ------- @@ -208,9 +220,9 @@ Win32 adjust as necessary. It is also possible to override these paths with environment variables, for example: - set ZLIB_PATH=c:\zlib-1.2.3 - set OPENSSL_PATH=c:\openssl-0.9.8k - set LIBSSH2_PATH=c:\libssh2-1.1 + set ZLIB_PATH=c:\zlib-1.2.8 + set OPENSSL_PATH=c:\openssl-0.9.8y + set LIBSSH2_PATH=c:\libssh2-1.4.3 ATTENTION: if you want to build with libssh2 support you have to use latest version 0.17 - previous versions will NOT work with 7.17.0 and later! @@ -229,7 +241,7 @@ Win32 If you want to enable LDAPS support then set LDAPS=1. - - optional MingW32-built OpenlDAP SDK available from: + - optional MingW32-built OpenLDAP SDK available from: http://www.gknw.net/mirror/openldap/ - optional recent Novell CLDAP SDK available from: http://developer.novell.com/ndk/cldap.htm @@ -311,7 +323,7 @@ Win32 documentation on how to compile zlib. Define the ZLIB_PATH environment variable to the location of zlib.h and zlib.lib, for example: - set ZLIB_PATH=c:\zlib-1.2.3 + set ZLIB_PATH=c:\zlib-1.2.8 Then run 'nmake vc-zlib' in curl's root directory. @@ -325,7 +337,7 @@ Win32 Before running nmake define the OPENSSL_PATH environment variable with the root/base directory of OpenSSL, for example: - set OPENSSL_PATH=c:\openssl-0.9.8k + set OPENSSL_PATH=c:\openssl-0.9.8y Then run 'nmake vc-ssl' or 'nmake vc-ssl-dll' in curl's root directory. 'nmake vc-ssl' will create a libcurl static and dynamic @@ -347,7 +359,7 @@ Win32 source distribution archive to allow proper building of the two included projects, the libcurl library and the curl tool. - 1) Open the vc6curl.dsw workspace with MSVC6's IDE. + 1) Open the vs/vc6/vc6curl.dsw workspace with MSVC6's IDE. 2) Select 'Build' from top menu. 3) Select 'Batch Build' from dropdown menu. 4) Make sure that the eight project configurations are 'checked'. @@ -355,12 +367,12 @@ Win32 6) Once the eight project configurations are built you are done. Dynamic and static libcurl libraries are built in debug and release flavours, - and can be located each one in its own subdirectory, DLL-Debug, DLL-Release, - LIB-Debug and LIB-Release, all of them below the 'lib' subdirectory. + and can be located each one in its own subdirectory, dll-debug, dll-release, + lib-debug and lib-release, all of them below the 'vs/vc6/lib' subdirectory. In the same way four curl executables are created, each using its respective library. The resulting curl executables are located in its own subdirectory, - DLL-Debug, DLL-Release, LIB-Debug and LIB-Release, below the 'src' subdir. + dll-debug, dll-release, lib-debug and lib-release, below 'vs/vc6/src' subdir. These reference VC++ 6.0 configurations are generated using the dynamic CRT. @@ -374,30 +386,49 @@ Win32 Borland C++ compiler --------------------- - compile openssl + Ensure that your build environment is properly set up to use the compiler + and associated tools. PATH environment variable must include the path to + bin subdirectory of your compiler installation, eg: c:\Borland\BCC55\bin + + It is advisable to set environment variable BCCDIR to the base path of + the compiler installation. + + set BCCDIR=c:\Borland\BCC55 + + In order to build a plain vanilla version of curl and libcurl run the + following command from curl's root directory: + + make borland + + To build curl and libcurl with zlib and OpenSSL support set environment + variables ZLIB_PATH and OPENSSL_PATH to the base subdirectories of the + already built zlib and OpenSSL libraries and from curl's root directory + run command: + + make borland-ssl-zlib + + libcurl library will be built in 'lib' subdirectory while curl tool + is built in 'src' subdirectory. In order to use libcurl library it is + advisable to modify compiler's configuration file bcc32.cfg located + in c:\Borland\BCC55\bin to reflect the location of libraries include + paths for example the '-I' line could result in something like: - Make sure you include the paths to curl/include and openssl/inc32 in - your bcc32.cnf file + -I"c:\Borland\BCC55\include;c:\curl\include;c:\openssl\inc32" - eg : -I"c:\Bcc55\include;c:\path_curl\include;c:\path_openssl\inc32" + bcc3.cfg '-L' line could also be modified to reflect the location of + of libcurl library resulting for example: - Check to make sure that all of the sources listed in lib/Makefile.b32 - are present in the /path_to_curl/lib directory. (Check the src - directory for missing ones.) + -L"c:\Borland\BCC55\lib;c:\curl\lib;c:\openssl\out32" - Make sure the environment variable "BCCDIR" is set to the install - location for the compiler eg : c:\Borland\BCC55 + In order to build sample program 'simple.c' from the docs\examples + subdirectory run following command from mentioned subdirectory: - command line: - make -f /path_to_curl/lib/Makefile-ssl.b32 + bcc32 simple.c libcurl.lib cw32mt.lib - compile simplessl.c with appropriate links + In order to build sample program simplessl.c an SSL enabled libcurl + is required, as well as the OpenSSL libeay32.lib and ssleay32.lib + libraries. - c:\curl\docs\examples\> bcc32 -L c:\path_to_curl\lib\libcurl.lib - -L c:\borland\bcc55\lib\psdk\ws2_32.lib - -L c:\openssl\out32\libeay32.lib - -L c:\openssl\out32\ssleay32.lib - simplessl.c OTHER MSVC IDEs --------------- @@ -433,12 +464,40 @@ Win32 possibilities: - Modify lib/config-win32.h - - Modify lib/setup.h + - Modify lib/curl_setup.h - Modify lib/Makefile.vc6 - Add defines to Project/Settings/C/C++/General/Preprocessor Definitions in the vc6libcurl.dsw/vc6libcurl.dsp Visual C++ 6 IDE project. + Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds + -------------------------------------------------------------------- + + In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack + it is necessary to make definition of preprocessor symbol USE_LWIPSOCK + visible to libcurl and curl compilation processes. To set this definition + you have the following alternatives: + + - Modify lib/config-win32.h and src/config-win32.h + - Modify lib/Makefile.vc6 + - Add definition to Project/Settings/C/C++/General/Preprocessor Definitions + in the vc6libcurl.dsw/vc6libcurl.dsp Visual C++ 6 IDE project. + + Once that libcurl has been built with BSD-style lwIP TCP/IP stack support, + in order to use it with your program it is mandatory that your program + includes lwIP header file <lwip/opt.h> (or another lwIP header that includes + this) before including any libcurl header. Your program does not need the + USE_LWIPSOCK preprocessor definition which is for libcurl internals only. + + Compilation has been verified with lwIP 1.4.0 and contrib-1.4.0 from: + + http://download.savannah.gnu.org/releases/lwip/lwip-1.4.0.zip + http://download.savannah.gnu.org/releases/lwip/contrib-1.4.0.zip + + This BSD-style lwIP TCP/IP stack support must be considered experimental + given that it has been verified that lwIP 1.4.0 still needs some polish, + and libcurl might yet need some additional adjustment, caveat emptor. + Important static libcurl usage note ----------------------------------- @@ -447,6 +506,38 @@ Win32 dynamic import symbols. +Apple iOS and Mac OS X +====================== + On recent Apple operating systems, curl can be built to use Apple's + SSL/TLS implementation, Secure Transport, instead of OpenSSL. To build with + Secure Transport for SSL/TLS, use the configure option --with-darwinssl. (It + is not necessary to use the option --without-ssl.) This feature requires iOS + 5.0 or later, or OS X 10.5 ("Leopard") or later. + + When Secure Transport is in use, the curl options --cacert and --capath and + their libcurl equivalents, will be ignored, because Secure Transport uses + the certificates stored in the Keychain to evaluate whether or not to trust + the server. This, of course, includes the root certificates that ship with + the OS. The --cert and --engine options, and their libcurl equivalents, are + currently unimplemented in curl with Secure Transport. + + For OS X users: In OS X 10.8 ("Mountain Lion"), Apple made a major + overhaul to the Secure Transport API that, among other things, added + support for the newer TLS 1.1 and 1.2 protocols. To get curl to support + TLS 1.1 and 1.2, you must build curl on Mountain Lion or later, or by + using the equivalent SDK. If you set the MACOSX_DEPLOYMENT_TARGET + environmental variable to an earlier version of OS X prior to building curl, + then curl will use the new Secure Transport API on Mountain Lion and later, + and fall back on the older API when the same curl binary is executed on + older cats. For example, running these commands in curl's directory in the + shell will build the code such that it will run on cats as old as OS X 10.6 + ("Snow Leopard") (using bash): + + export MACOSX_DEPLOYMENT_TARGET="10.6" + ./configure --with-darwinssl + make + + IBM OS/2 ======== Building under OS/2 is not much different from building under unix. @@ -484,7 +575,7 @@ VMS Curl seems to work with FTP & HTTP other protocols are not tested. (the perl http/ftp testing server supplied as testing too cannot work on VMS because vms has no concept of fork(). [ I tried to give it a whack, but - thats of no use. + that's of no use. SSL stuff has not been ported. @@ -617,7 +708,7 @@ NetWare you can find precompiled packages at: http://www.gknw.net/development/ossl/netware/ for CLIB-based builds OpenSSL 0.9.8h or later is required - earlier versions - dont support buildunf with CLIB BSD sockets. + don't support building with CLIB BSD sockets. - optional SSH2 sources (version 0.17 or later); Set a search path to your compiler, linker and tools; on Linux make @@ -638,7 +729,7 @@ NetWare Builds automatically created 8 times a day from current git are here: http://www.gknw.net/mirror/curl/autobuilds/ the status of these builds can be viewed at the autobuild table: - http://curl.haxx.se/auto/ + http://curl.haxx.se/dev/builds.html eCos @@ -784,7 +875,44 @@ VxWorks Android ======= - See the build notes in the Android.mk file. + Method using the static makefile: + - see the build notes in the packages/Android/Android.mk file. + + Method using a configure cross-compile (tested with Android NDK r7c, r8): + - prepare the toolchain of the Android NDK for standalone use; this can + be done by invoking the script: + ./build/tools/make-standalone-toolchain.sh + which creates a usual cross-compile toolchain. Lets assume that you put + this toolchain below /opt then invoke configure with something like: + export PATH=/opt/arm-linux-androideabi-4.4.3/bin:$PATH + ./configure --host=arm-linux-androideabi [more configure options] + make + - if you want to compile directly from our GIT repo you might run into + this issue with older automake stuff: + checking host system type... + Invalid configuration `arm-linux-androideabi': + system `androideabi' not recognized + configure: error: /bin/sh ./config.sub arm-linux-androideabi failed + this issue can be fixed with using more recent versions of config.sub + and config.guess which can be obtained here: + http://git.savannah.gnu.org/gitweb/?p=config.git;a=tree + you need to replace your system-own versions which usually can be + found in your automake folder: + find /usr -name config.sub + + Wrapper for pkg-config + - In order to make proper use of pkg-config so that configure is able to + find all dependencies you should create a wrapper script for pkg-config; + file /opt/arm-linux-androideabi-4.4.3/bin/arm-linux-androideabi-pkg-config: + + #!/bin/sh + SYSROOT=$(dirname ${0%/*})/sysroot + export PKG_CONFIG_DIR= + export PKG_CONFIG_LIBDIR=${SYSROOT}/usr/local/lib/pkgconfig:${SYSROOT}/usr/share/pkgconfig + export PKG_CONFIG_SYSROOT_DIR=${SYSROOT} + exec pkg-config "$@" + + also create a copy or symlink with name arm-unknown-linux-androideabi-pkg-config. CROSS COMPILE @@ -871,8 +999,9 @@ REDUCING SIZE The GNU compiler and linker have a number of options that can reduce the size of the libcurl dynamic libraries on some platforms even further. Specify them by providing appropriate CFLAGS and LDFLAGS variables on the - configure command-line: - CFLAGS="-ffunction-sections -fdata-sections" \ + configure command-line, e.g. + CFLAGS="-Os -ffunction-sections -fdata-sections \ + -fno-unwind-tables -fno-asynchronous-unwind-tables" \ LDFLAGS="-Wl,-s -Wl,-Bsymbolic -Wl,--gc-sections" Be sure also to strip debugging symbols from your binaries after @@ -882,9 +1011,9 @@ REDUCING SIZE .comment section). Using these techniques it is possible to create a basic HTTP-only shared - libcurl library for i386 Linux platforms that is only 98 KiB in size, and - an FTP-only library that is 94 KiB in size (as of libcurl version 7.20.0, - using gcc 4.3.3). + libcurl library for i386 Linux platforms that is only 106 KiB in size, and + an FTP-only library that is 108 KiB in size (as of libcurl version 7.27.0, + using gcc 4.6.3). You may find that statically linking libcurl to your application will result in a lower total size than dynamically linking. @@ -916,9 +1045,9 @@ PORTS - Alpha OpenVMS V7.1-1H2 - Alpha Tru64 v5.0 5.1 - AVR32 Linux - - ARM Android 1.5, 2.1 + - ARM Android 1.5, 2.1, 2.3, 3.2, 4.x - ARM INTEGRITY - - ARM iPhone OS + - ARM iOS - Cell Linux - Cell Cell OS - HP-PA HP-UX 9.X 10.X 11.X @@ -956,6 +1085,7 @@ PORTS - i386 HURD - i386 Haiku OS - i386 Linux 1.3, 2.0, 2.2, 2.3, 2.4, 2.6 + - i386 Mac OS X - i386 MINIX 3.1 - i386 NetBSD - i386 Novell NetWare @@ -980,17 +1110,22 @@ PORTS Useful URLs =========== -c-ares http://daniel.haxx.se/projects/c-ares/license.html -GNU GSS http://www.gnu.org/software/gss/ -GnuTLS http://www.gnu.org/software/gnutls/ -Heimdal http://www.pdc.kth.se/heimdal/ -libidn http://www.gnu.org/software/libidn/ -libssh2 http://www.libssh2.org -MingW http://www.mingw.org +axTLS http://axtls.sourceforge.net/ +c-ares http://c-ares.haxx.se/ +GNU GSS http://www.gnu.org/software/gss/ +GnuTLS http://www.gnu.org/software/gnutls/ +Heimdal http://www.pdc.kth.se/heimdal/ +libidn http://www.gnu.org/software/libidn/ +libmetalink https://launchpad.net/libmetalink/ +libssh2 http://www.libssh2.org/ MIT Kerberos http://web.mit.edu/kerberos/www/dist/ -NSS http://www.mozilla.org/projects/security/pki/nss/ -OpenLDAP http://www.openldap.org -OpenSSL http://www.openssl.org -PolarSSL http://polarssl.org -yassl http://www.yassl.com/ -Zlib http://www.gzip.org/zlib/ +NSS http://www.mozilla.org/projects/security/pki/nss/ +OpenLDAP http://www.openldap.org/ +OpenSSL http://www.openssl.org/ +PolarSSL http://polarssl.org/ +yassl http://www.yassl.com/ +Zlib http://www.zlib.net/ + +MingW http://www.mingw.org/ +MinGW-w64 http://mingw-w64.sourceforge.net/ +OpenWatcom http://www.openwatcom.org/ diff --git a/docs/INSTALL.devcpp b/docs/INSTALL.devcpp index 7f58e4b0e..46d1836af 100644 --- a/docs/INSTALL.devcpp +++ b/docs/INSTALL.devcpp @@ -26,7 +26,7 @@ exists for a Unix/linux command line environments. This is of little help when it comes to Windows O/S. Secondly the help that does exist for the Windows O/S focused around mingw -thru a command line argument environment. +through a command line argument environment. You may ask "Why is this a problem?" diff --git a/docs/INTERNALS b/docs/INTERNALS index 9d0bdbaa1..66e11a46b 100644 --- a/docs/INTERNALS +++ b/docs/INTERNALS @@ -15,7 +15,7 @@ INTERNALS GIT === All changes to the sources are committed to the git repository as soon as - they're somewhat verified to work. Changes shall be commited as independently + they're somewhat verified to work. Changes shall be committed as independently as possible so that individual changes can be easier spotted and tracked afterwards. @@ -39,22 +39,20 @@ Portability libssh2 0.16 c-ares 1.6.0 libidn 0.4.1 - *yassl 1.4.0 (http://curl.haxx.se/mail/lib-2008-02/0093.html) + cyassl 2.0.0 openldap 2.0 MIT krb5 lib 1.2.4 - qsossl V5R2M0 - NSS 3.11.x + qsossl V5R3M0 + NSS 3.12.x + axTLS 1.2.7 Heimdal ? - * = only partly functional, but that's due to bugs in the third party lib, not - because of libcurl code - On systems where configure runs, we aim at working on them all - if they have a suitable C compiler. On systems that don't run configure, we strive to keep curl running fine on: Windows 98 - AS/400 V5R2M0 + AS/400 V5R3M0 Symbian 9.1 Windows CE ? TPF ? @@ -67,7 +65,7 @@ Portability GNU Autoconf 2.57 GNU Automake 1.7 (we currently avoid 1.10 due to Solaris-related bugs) GNU M4 1.4 - perl 4 + perl 5.004 roffit 0.5 groff ? (any version that supports "groff -Tps -man [in] [out]") ps2pdf (gs) ? @@ -90,7 +88,7 @@ Windows vs Unix do it etc there might be reasons for applications to alter that behaviour. 3. The file descriptors for network communication and file operations are - not easily interchangable as in unix. + not easily interchangeable as in unix. We avoid this by not trying any funny tricks on file descriptors. @@ -103,9 +101,9 @@ Windows vs Unix Inside the source code, We make an effort to avoid '#ifdef [Your OS]'. All conditionals that deal with features *should* instead be in the format '#ifdef HAVE_THAT_WEIRD_FUNCTION'. Since Windows can't run configure scripts, - we maintain two curl_config-win32.h files (one in lib/ and one in src/) that - are supposed to look exactly as a curl_config.h file would have looked like on - a Windows machine! + we maintain a curl_config-win32.h file in lib directory that is supposed to + look exactly as a curl_config.h file would have looked like on a Windows + machine! Generally speaking: always remember that this will be compiled on dozens of operating systems. Don't walk on the edge. @@ -113,6 +111,9 @@ Windows vs Unix Library ======= + (See LIBCURL-STRUCTS for a separate document describing all major internal + structs and their purposes.) + There are plenty of entry points to the library, namely each publicly defined function that libcurl offers to applications. All of those functions are rather small and easy-to-follow. All the ones prefixed with 'curl_easy' are @@ -137,16 +138,18 @@ Library options is documented in the man page. This function mainly sets things in the 'SessionHandle' struct. - curl_easy_perform() does a whole lot of things: + curl_easy_perform() is just a wrapper function that makes use of the multi + API. It basically curl_multi_init(), curl_multi_add_handle(), + curl_multi_wait(), and curl_multi_perform() until the transfer is done and + then returns. - It starts off in the lib/easy.c file by calling Curl_perform() and the main - work then continues in lib/url.c. The flow continues with a call to - Curl_connect() to connect to the remote site. + Some of the most important key functions in url.c are called from multi.c + when certain key steps are to be made in the transfer operation. o Curl_connect() - ... analyzes the URL, it separates the different components and connects to - the remote host. This may involve using a proxy and/or using SSL. The + Analyzes the URL, it separates the different components and connects to the + remote host. This may involve using a proxy and/or using SSL. The Curl_resolv() function in lib/hostip.c is used for looking up host names (it does then use the proper underlying method, which may vary between platforms and builds). @@ -162,10 +165,7 @@ Library o Curl_do() Curl_do() makes sure the proper protocol-specific function is called. The - functions are named after the protocols they handle. Curl_ftp(), - Curl_http(), Curl_dict(), etc. They all reside in their respective files - (ftp.c, http.c and dict.c). HTTPS is handled by Curl_http() and FTPS by - Curl_ftp(). + functions are named after the protocols they handle. The protocol-specific functions of course deal with protocol-specific negotiations and setup. They have access to the Curl_sendf() (from @@ -182,12 +182,11 @@ Library Some time during the DO function, the Curl_setup_transfer() function must be called with some basic info about the upcoming transfer: what socket(s) - to read/write and the expected file tranfer sizes (if known). + to read/write and the expected file transfer sizes (if known). - o Transfer() + o Curl_readwrite() - Curl_perform() then calls Transfer() in lib/transfer.c that performs the - entire file transfer. + Called during the transfer of the actual protocol payload. During transfer, the progress functions in lib/progress.c are called at a frequent interval (or at the user's choice, a specified callback might get @@ -209,33 +208,11 @@ Library used. This function is only used when we are certain that no more transfers is going to be made on the connection. It can be also closed by force, or it can be called to make sure that libcurl doesn't keep too many - connections alive at the same time (there's a default amount of 5 but that - can be changed with the CURLOPT_MAXCONNECTS option). + connections alive at the same time. This function cleans up all resources that are associated with a single connection. - Curl_perform() is the function that does the main "connect - do - transfer - - done" loop. It loops if there's a Location: to follow. - - When completed, the curl_easy_cleanup() should be called to free up used - resources. It runs Curl_disconnect() on all open connectons. - - A quick roundup on internal function sequences (many of these call - protocol-specific function-pointers): - - curl_connect - connects to a remote site and does initial connect fluff - This also checks for an existing connection to the requested site and uses - that one if it is possible. - - curl_do - starts a transfer - curl_transfer() - transfers data - curl_done - ends a transfer - - curl_disconnect - disconnects from a remote site. This is called when the - disconnect is really requested, which doesn't necessarily have to be - exactly after curl_done in case we want to keep the connection open for - a while. HTTP(S) @@ -249,16 +226,16 @@ Library HTTPS uses in almost every means the same procedure as HTTP, with only two exceptions: the connect procedure is different and the function used to read or write from the socket is different, although the latter fact is hidden in - the source by the use of curl_read() for reading and curl_write() for writing + the source by the use of Curl_read() for reading and Curl_write() for writing data to the remote server. http_chunks.c contains functions that understands HTTP 1.1 chunked transfer encoding. - An interesting detail with the HTTP(S) request, is the add_buffer() series of - functions we use. They append data to one single buffer, and when the - building is done the entire request is sent off in one single write. This is - done this way to overcome problems with flawed firewalls and lame servers. + An interesting detail with the HTTP(S) request, is the Curl_add_buffer() + series of functions we use. They append data to one single buffer, and when + the building is done the entire request is sent off in one single write. This + is done this way to overcome problems with flawed firewalls and lame servers. FTP @@ -284,14 +261,14 @@ Library LDAP - Everything LDAP is in lib/ldap.c. + Everything LDAP is in lib/ldap.c and lib/openldap.c GENERAL URL encoding and decoding, called escaping and unescaping in the source code, is found in lib/escape.c. - While transfering data in Transfer() a few functions might get used. + While transferring data in Transfer() a few functions might get used. curl_getdate() in lib/parsedate.c is for HTTP date comparisons (and more). lib/getenv.c offers curl_getenv() which is for reading environment variables @@ -303,7 +280,7 @@ Library lib/netrc.c holds the .netrc parser lib/timeval.c features replacement functions for systems that don't have - gettimeofday() and a few support functions for timeval convertions. + gettimeofday() and a few support functions for timeval conversions. A function named curl_version() that returns the full curl version string is found in lib/version.c. @@ -318,46 +295,38 @@ Persistent Connections hold connection-oriented data. It is meant to hold the root data as well as all the options etc that the library-user may choose. o The 'SessionHandle' struct holds the "connection cache" (an array of - pointers to 'connectdata' structs). There's one connectdata struct - allocated for each connection that libcurl knows about. Note that when you - use the multi interface, the multi handle will hold the connection cache - and not the particular easy handle. This of course to allow all easy handles - in a multi stack to be able to share and re-use connections. + pointers to 'connectdata' structs). o This enables the 'curl handle' to be reused on subsequent transfers. - o When we are about to perform a transfer with curl_easy_perform(), we first - check for an already existing connection in the cache that we can use, - otherwise we create a new one and add to the cache. If the cache is full - already when we add a new connection, we close one of the present ones. We - select which one to close dependent on the close policy that may have been - previously set. - o When the transfer operation is complete, we try to leave the connection - open. Particular options may tell us not to, and protocols may signal - closure on connections and then we don't keep it open of course. + o When libcurl is told to perform a transfer, it first checks for an already + existing connection in the cache that we can use. Otherwise it creates a + new one and adds that the cache. If the cache is full already when a new + conncetion is added added, it will first close the oldest unused one. + o When the transfer operation is complete, the connection is left + open. Particular options may tell libcurl not to, and protocols may signal + closure on connections and then they won't be kept open of course. o When curl_easy_cleanup() is called, we close all still opened connections, unless of course the multi interface "owns" the connections. - You do realize that the curl handle must be re-used in order for the - persistent connections to work. + The curl handle must be re-used in order for the persistent connections to + work. multi interface/non-blocking ============================ - We make an effort to provide a non-blocking interface to the library, the - multi interface. To make that interface work as good as possible, no - low-level functions within libcurl must be written to work in a blocking - manner. + The multi interface is a non-blocking interface to the library. To make that + interface work as good as possible, no low-level functions within libcurl + must be written to work in a blocking manner. (There are still a few spots + violating this rule.) One of the primary reasons we introduced c-ares support was to allow the name resolve phase to be perfectly non-blocking as well. - The ultimate goal is to provide the easy interface simply by wrapping the - multi interface functions and thus treat everything internally as the multi - interface is the single interface we have. - - The FTP and the SFTP/SCP protocols are thus perfect examples of how we adapt - and adjust the code to allow non-blocking operations even on multi-stage - protocols. The DICT, LDAP and TELNET are crappy examples and they are subject - for rewrite in the future to better fit the libcurl protocol family. + The FTP and the SFTP/SCP protocols are examples of how we adapt and adjust + the code to allow non-blocking operations even on multi-stage command- + response protocols. They are built around state machines that return when + they would otherwise block waiting for data. The DICT, LDAP and TELNET + protocols are crappy examples and they are subject for rewrite in the future + to better fit the libcurl protocol family. SSL libraries ============= @@ -379,7 +348,9 @@ Library Symbols All symbols used internally in libcurl must use a 'Curl_' prefix if they're used in more than a single file. Single-file symbols must be made static. Public ("exported") symbols must use a 'curl_' prefix. (There are exceptions, - but they are to be changed to follow this pattern in future versions.) + but they are to be changed to follow this pattern in future versions.) Public + API functions are marked with CURL_EXTERN in the public header files so that + all others can be hidden on platforms where this is possible. Return Codes and Informationals =============================== @@ -406,12 +377,12 @@ API/ABI Client ====== - main() resides in src/main.c together with most of the client code. + main() resides in src/tool_main.c. - src/hugehelp.c is automatically generated by the mkhelp.pl perl script to - display the complete "manual" and the src/urlglob.c file holds the functions - used for the URL-"globbing" support. Globbing in the sense that the {} and [] - expansion stuff is there. + src/tool_hugehelp.c is automatically generated by the mkhelp.pl perl script + to display the complete "manual" and the src/tool_urlglob.c file holds the + functions used for the URL-"globbing" support. Globbing in the sense that the + {} and [] expansion stuff is there. The client mostly messes around to setup its 'config' struct properly, then it calls the curl_easy_*() functions of the library and when it gets back @@ -423,8 +394,8 @@ Client curl_easy_getinfo() function to extract useful information from the curl session. - Recent versions may loop and do all this several times if many URLs were - specified on the command line or config file. + It may loop and do all this several times if many URLs were specified on the + command line or config file. Memory Debugging ================ @@ -458,31 +429,43 @@ Memory Debugging Test Suite ========== - Since November 2000, a test suite has evolved. It is placed in its own - subdirectory directly off the root in the curl archive tree, and it contains - a bunch of scripts and a lot of test case data. + The test suite is placed in its own subdirectory directly off the root in the + curl archive tree, and it contains a bunch of scripts and a lot of test case + data. - The main test script is runtests.pl that will invoke the two servers + The main test script is runtests.pl that will invoke test servers like httpserver.pl and ftpserver.pl before all the test cases are performed. The test suite currently only runs on unix-like platforms. - You'll find a complete description of the test case data files in the - tests/README file. + You'll find a description of the test suite in the tests/README file, and the + test case data files in the tests/FILEFORMAT file. The test suite automatically detects if curl was built with the memory - debugging enabled, and if it was it will detect memory leaks too. + debugging enabled, and if it was it will detect memory leaks, too. Building Releases ================= There's no magic to this. When you consider everything stable enough to be - released, run the 'maketgz' script (using 'make distcheck' will give you a - pretty good view on the status of the current sources). maketgz prompts for - version number of the client and the library before it creates a release - archive. maketgz uses 'make dist' for the actual archive building, why you - need to fill in the Makefile.am files properly for which files that should - be included in the release archives. - - NOTE: you need to have curl checked out from git to be able to do a proper + released, do this: + + 1. Tag the source code accordingly. + + 2. run the 'maketgz' script (using 'make distcheck' will give you a pretty + good view on the status of the current sources). maketgz requires a + version number and creates the release archive. maketgz uses 'make dist' + for the actual archive building, why you need to fill in the Makefile.am + files properly for which files that should be included in the release + archives. + + 3. When that's complete, sign the output files. + + 4. Upload + + 5. Update web site and changelog on site + + 6. Send announcement to the mailing lists + + NOTE: you must have curl checked out from git to be able to do a proper release build. The release tarballs do not have everything setup in order to do releases properly. diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index 96478917d..7bd6e6e32 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -3,20 +3,57 @@ join in and help us correct one or more of these! Also be sure to check the changelog of the current development status, as one or more of these problems may have been fixed since this was written! +83. curl is unable to load non-default openssl engines, because openssl isn't + initialized properly. This seems to require OpenSSL_config() or + CONF_modules_load_file() to be used by libcurl but the first seems to not + work and we've gotten not reports from tests with the latter. Possibly we + need to discuss with OpenSSL developers how this is supposed to be done. We + need users with actual external openssl engines for testing to work on this. + http://curl.haxx.se/bug/view.cgi?id=1208 + +82. When building with the Windows Borland compiler, it fails because the + "tlib" tool doesn't support hyphens (minus signs) in file names and we have + such in the build. + http://curl.haxx.se/bug/view.cgi?id=1222 + +81. When using -J (with -O), automaticly resumed downloading together with "-C + -" fails. Without -J the same command line works! This happens because the + resume logic is worked out before the target file name (and thus its + pre-transfer size) has been figured out! + http://curl.haxx.se/bug/view.cgi?id=1169 + +80. Curl doesn't recognize certificates in DER format in keychain, but it + works with PEM. + http://curl.haxx.se/bug/view.cgi?id=3439999 + +79. SMTP. When sending data to multiple recipients, curl will abort and return + failure if one of the recipients indicate failure (on the "RCPT TO" + command). Ordinary mail programs would proceed and still send to the ones + that can receive data. This is subject for change in the future. + http://curl.haxx.se/bug/view.cgi?id=3438362 + +78. curl and libcurl don't always signal the client properly when "sending" + zero bytes files - it makes for example the command line client not creating + any file at all. Like when using FTP. + http://curl.haxx.se/bug/view.cgi?id=3438362 + +77. CURLOPT_FORBID_REUSE on a handle prevents NTLM from working since it + "abuses" the underlying connection re-use system and if connections are + forced to close they break the NTLM support. + 76. The SOCKET type in Win64 is 64 bits large (and thus so is curl_socket_t on that platform), and long is only 32 bits. It makes it impossible for curl_easy_getinfo() to return a socket properly with the CURLINFO_LASTSOCKET option as for all other operating systems. -75. NTLM authentication involving unicode user name or password. +75. NTLM authentication involving unicode user name or password only works + properly if built with UNICODE defined together with the schannel/winssl + backend. The original problem was mentioned in: http://curl.haxx.se/mail/lib-2009-10/0024.html http://curl.haxx.se/bug/view.cgi?id=2944325 -74. The HTTP spec allows headers to be merged and become comma-separated - instead of being repeated several times. This also include Authenticate: and - Proxy-Authenticate: headers and while this hardly every happens in real life - it will confuse libcurl which does not properly support it for all headers - - like those Authenticate headers. + The schannel version verified to work as mentioned in + http://curl.haxx.se/mail/lib-2012-07/0073.html 73. if a connection is made to a FTP server but the server then just never sends the 220 response or otherwise is dead slow, libcurl will not @@ -67,13 +104,6 @@ may have been fixed since this was written! CURLOPT_FAILONERROR with FTP to detect if a file exists or not, but it is not working: http://curl.haxx.se/mail/lib-2008-07/0295.html -57. On VMS-Alpha: When using an http-file-upload the file is not sent to the - Server with the correct content-length. Sending a file with 511 or less - bytes, content-length 512 is used. Sending a file with 513 - 1023 bytes, - content-length 1024 is used. Files with a length of a multiple of 512 Bytes - show the correct content-length. Only these files work for upload. - http://curl.haxx.se/bug/view.cgi?id=2057858 - 56. When libcurl sends CURLOPT_POSTQUOTE commands when connected to a SFTP server using the multi interface, the commands are not being sent correctly and instead the connection is "cancelled" (the operation is considered done) @@ -116,13 +146,6 @@ may have been fixed since this was written! 38. Kumar Swamy Bhatt's problem in ftp/ssl "LIST" operation: http://curl.haxx.se/mail/lib-2007-01/0103.html -37. Having more than one connection to the same host when doing NTLM - authentication (with performs multiple "passes" and authenticates a - connection rather than a HTTP request), and particularly when using the - multi interface, there's a risk that libcurl will re-use a wrong connection - when doing the different passes in the NTLM negotiation and thus fail to - negotiate (in seemingly mysterious ways). - 35. Both SOCKS5 and SOCKS4 proxy connections are done blocking, which is very bad when used with the multi interface. @@ -152,19 +175,12 @@ may have been fixed since this was written! to what winhttp does. See http://curl.haxx.se/bug/view.cgi?id=1281867 23. SOCKS-related problems: - A) libcurl doesn't support SOCKS for IPv6. B) libcurl doesn't support FTPS over a SOCKS proxy. E) libcurl doesn't support active FTP over a SOCKS proxy We probably have even more bugs and lack of features when a SOCKS proxy is used. -22. Sending files to a FTP server using curl on VMS, might lead to curl - complaining on "unaligned file size" on completion. The problem is related - to VMS file structures and the perceived file sizes stat() returns. A - possible fix would involve sending a "STRU VMS" command. - http://curl.haxx.se/bug/view.cgi?id=1156287 - 21. FTP ASCII transfers do not follow RFC959. They don't convert the data accordingly (not for sending nor for receiving). RFC 959 section 3.1.1.1 clearly describes how this should be done: diff --git a/docs/LIBCURL-STRUCTS b/docs/LIBCURL-STRUCTS new file mode 100644 index 000000000..20f2d3410 --- /dev/null +++ b/docs/LIBCURL-STRUCTS @@ -0,0 +1,245 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + +Structs in libcurl + +This document should cover 7.32.0 pretty accurately, but will make sense even +for older and later versions as things don't change drastically that often. + + 1. The main structs in libcurl + 1.1 SessionHandle + 1.2 connectdata + 1.3 Curl_multi + 1.4 Curl_handler + 1.5 conncache + 1.6 Curl_share + 1.7 CookieInfo + +============================================================================== + +1. The main structs in libcurl + + 1.1 SessionHandle + + The SessionHandle handle struct is the one returned to the outside in the + external API as a "CURL *". This is usually known as an easy handle in API + documentations and examples. + + Information and state that is related to the actual connection is in the + 'connectdata' struct. When a transfer is about to be made, libcurl will + either create a new connection or re-use an existing one. The particular + connectdata that is used by this handle is pointed out by + SessionHandle->easy_conn. + + Data and information that regard this particular single transfer is put in + the SingleRequest sub-struct. + + When the SessionHandle struct is added to a multi handle, as it must be in + order to do any transfer, the ->multi member will point to the Curl_multi + struct it belongs to. The ->prev and ->next members will then be used by the + multi code to keep a linked list of SessionHandle structs that are added to + that same multi handle. libcurl always uses multi so ->multi *will* point to + a Curl_multi when a transfer is in progress. + + ->mstate is the multi state of this particular SessionHandle. When + multi_runsingle() is called, it will act on this handle according to which + state it is in. The mstate is also what tells which sockets to return for a + speicific SessionHandle when curl_multi_fdset() is called etc. + + The libcurl source code generally use the name 'data' for the variable that + points to the SessionHandle. + + + 1.2 connectdata + + A general idea in libcurl is to keep connections around in a connection + "cache" after they have been used in case they will be used again and then + re-use an existing one instead of creating a new as it creates a significant + performance boost. + + Each 'connectdata' identifies a single physical conncetion to a server. If + the connection can't be kept alive, the connection will be closed after use + and then this struct can be removed from the cache and freed. + + Thus, the same SessionHandle can be used multiple times and each time select + another connectdata struct to use for the connection. Keep this in mind, as + it is then important to consider if options or choices are based on the + connection or the SessionHandle. + + Functions in libcurl will assume that connectdata->data points to the + SessionHandle that uses this connection. + + As a special complexity, some protocols supported by libcurl require a + special disconnect procedure that is more than just shutting down the + socket. It can involve sending one or more commands to the server before + doing so. Since connections are kept in the connection cache after use, the + original SessionHandle may no longer be around when the time comes to shut + down a particular connection. For this purpose, libcurl holds a special + dummy 'closure_handle' SessionHandle in the Curl_multi struct to + + FTP uses two TCP connections for a typical transfer but it keeps both in + this single struct and thus can be considered a single connection for most + internal concerns. + + The libcurl source code generally use the name 'conn' for the variable that + points to the connectdata. + + + 1.3 Curl_multi + + Internally, the easy interface is implemented as a wrapper around multi + interface functions. This makes everything multi interface. + + Curl_multi is the multi handle struct exposed as "CURLM *" in external APIs. + + This struct holds a list of SessionHandle structs that have been added to + this handle with curl_multi_add_handle(). The start of the list is ->easyp + and ->num_easy is a counter of added SessionHandles. + + ->msglist is a linked list of messages to send back when + curl_multi_info_read() is called. Basically a node is added to that list + when an individual SessionHandle's transfer has completed. + + ->hostcache points to the name cache. It is a hash table for looking up name + to IP. The nodes have a limited life time in there and this cache is meant + to reduce the time for when the same name is wanted within a short period of + time. + + ->timetree points to a tree of SessionHandles, sorted by the remaining time + until it should be checked - normally some sort of timeout. Each + SessionHandle has one node in the tree. + + ->sockhash is a hash table to allow fast lookups of socket descriptor to + which SessionHandle that uses that descriptor. This is necessary for the + multi_socket API. + + ->conn_cache points to the connection cache. It keeps track of all + connections that are kept after use. The cache has a maximum size. + + ->closure_handle is described in the 'connectdata' section. + + The libcurl source code generally use the name 'multi' for the variable that + points to the Curl_multi struct. + + + 1.4 Curl_handler + + Each unique protocol that is supported by libcurl needs to provide at least + one Curl_handler struct. It defines what the protocol is called and what + functions the main code should call to deal with protocol specific issues. + In general, there's a source file named [protocol].c in which there's a + "struct Curl_handler Curl_handler_[protocol]" declared. In url.c there's + then the main array with all individual Curl_handler structs pointed to from + a single array which is scanned through when a URL is given to libcurl to + work with. + + ->scheme is the URL scheme name, usually spelled out in uppercase. That's + "HTTP" or "FTP" etc. SSL versions of the protcol need its own Curl_handler + setup so HTTPS separate from HTTP. + + ->setup_connection is called to allow the protocol code to allocate protocol + specific data that then gets associated with that SessionHandle for the rest + of this transfer. It gets freed again at the end of the transfer. It will be + called before the 'connectdata' for the transfer has been selected/created. + Most protocols will allocate its private 'struct [PROTOCOL]' here and assign + SessionHandle->req.protop to point to it. + + ->connect_it allows a protocol to do some specific actions after the TCP + connect is done, that can still be considered part of the connection phase. + + Some protocols will alter the connectdata->recv[] and connectdata->send[] + function pointers in this function. + + ->connecting is similarly a function that keeps getting called as long as the + protocol considers itself still in the connecting phase. + + ->do_it is the function called to issue the transfer request. What we call + the DO action internally. If the DO is not enough and things need to be kept + getting done for the entier DO sequence to complete, ->doing is then usually + also provided. Each protocol that needs to do multiple commands or similar + for do/doing need to implement their own state machines (see SCP, SFTP, + FTP). Some protocols (only FTP and only due to historical reasons) has a + separate piece of the DO state called DO_MORE. + + ->doing keeps getting called while issudeing the transfer request command(s) + + ->done gets called when the transfer is complete and DONE. That's after the + main data has been transferred. + + ->do_more gets called doring the DO_MORE state. The FTP protocol uses this + state when setting up the second connection. + + ->proto_getsock + ->doing_getsock + ->domore_getsock + ->perform_getsock + Functions that return socket information. Which socket(s) to wait for which + action(s) during the particular multi state. + + ->disconnect is called immediately before the TCP connection is shutdown. + + ->readwrite gets called during transfer to allow the protocol to do extra + reads/writes + + ->defport is the default report TCP or UDP port this protocol uses + + ->protocol is one or more bits in the CURLPROTO_* set. The SSL versions have + their "base" protocol set and then the SSL variation. Like "HTTP|HTTPS". + + ->flags is a bitmask with additional information about the protocol that will + make it get treated differently by the generic engine: + + PROTOPT_SSL - will make it connect and negotiate SSL + + PROTOPT_DUAL - this protocol uses two connections + + PROTOPT_CLOSEACTION - this protocol has actions to do before closing the + connection. This flag is no longer used by code, yet still set for a bunch + protocol handlers. + + PROTOPT_DIRLOCK - "direction lock". The SSH protocols set this bit to + limit which "direction" of socket actions that the main engine will + concern itself about. + + PROTOPT_NONETWORK - a protocol that doesn't use network (read file:) + + PROTOPT_NEEDSPWD - this protocol needs a password and will use a default + one unless one is provided + + PROTOPT_NOURLQUERY - this protocol can't handle a query part on the URL + (?foo=bar) + + + 1.5 conncache + + Is a hash table with connections for later re-use. Each SessionHandle has + a pointer to its connection cache. Each multi handle sets up a connection + cache that all added SessionHandles share by default. + + + 1.6 Curl_share + + The libcurl share API allocates a Curl_share struct, exposed to the external + API as "CURLSH *". + + The idea is that the struct can have a set of own versions of caches and + pools and then by providing this struct in the CURLOPT_SHARE option, those + specific SessionHandles will use the caches/pools that this share handle + holds. + + Then individual SessionHandle structs can be made to share specific things + that they otherwise wouldn't, such as cookies. + + The Curl_share struct can currently hold cookies, DNS cache and the SSL + session cache. + + + 1.7 CookieInfo + + This is the main cookie struct. It holds all known cookies and related + information. Each SessionHandle has its own private CookieInfo even when + they are added to a multi handle. They can be made to share cookies by using + the share API. diff --git a/docs/LICENSE-MIXING b/docs/LICENSE-MIXING index 3db1a3d7f..f596546da 100644 --- a/docs/LICENSE-MIXING +++ b/docs/LICENSE-MIXING @@ -55,6 +55,10 @@ NSS http://www.mozilla.org/projects/security/pki/nss/ grant you different permissions and impose different obligations. You should select the license that best meets your needs. +axTLS http://axtls.sourceforge.net/ + + (May be used for SSL/TLS support) Uses a Modified BSD-style license. + c-ares http://daniel.haxx.se/projects/c-ares/license.html (Used for asynchronous name resolves) Uses an MIT license that is very diff --git a/docs/MAIL-ETIQUETTE b/docs/MAIL-ETIQUETTE new file mode 100644 index 000000000..ae1821a89 --- /dev/null +++ b/docs/MAIL-ETIQUETTE @@ -0,0 +1,228 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + +MAIL ETIQUETTE + + 1. About the lists + 1.1 Mailing Lists + 1.2 Netiquette + 1.3 Do Not Mail a Single Individual + 1.4 Subscription Required + 1.5 Moderation of new posters + 1.6 Handling trolls and spam + 1.7 How to unsubscribe + + 2. Sending mail + 2.1 Reply or New Mail + 2.2 Reply to the List + 2.3 Use a Sensible Subject + 2.4 Do Not Top-Post + 2.5 HTML is not for mails + 2.6 Quoting + 2.7 Digest + 2.8 Please Tell Us How You Solved The Problem! + +============================================================================== + +1. About the lists + + 1.1 Mailing Lists + + The mailing lists we have are all listed and described at + http://curl.haxx.se/mail/ + + Each mailing list is targeted to a specific set of users and subjects, + please use the one or the ones that suit you the most. + + Each mailing list have hundreds up to thousands of readers, meaning that + each mail sent will be received and read by a very large amount of people. + People from various cultures, regions, religions and continents. + + 1.2 Netiquette + + Netiquette is a common name for how to behave on the internet. Of course, in + each particular group and subculture there will be differences in what is + acceptable and what is considered good manners. + + This document outlines what we in the cURL project considers to be good + etiquette, and primarily this focus on how to behave on and how to use our + mailing lists. + + 1.3 Do Not Mail a Single Individual + + Many people send one question to one person. One person gets many mails, and + there is only one person who can give you a reply. The question may be + something that other people are also wanting to ask. These other people have + no way to read the reply, but to ask the one person the question. The one + person consequently gets overloaded with mail. + + If you really want to contact an individual and perhaps pay for his or her + services, by all means go ahead, but if it's just another curl question, + take it to a suitable list instead. + + 1.4 Subscription Required + + All curl mailing lists require that you are subscribed to allow a mail to go + through to all the subscribers. + + If you post without being subscribed (or from a different mail address than + the one you are subscribed with), your mail will simply be silently + discarded. You have to subscribe first, then post. + + The reason for this unfortunate and strict subscription policy is of course + to stop spam from pestering the lists. + + 1.5 Moderation of new posters + + Several of the curl mailing lists automatically make all posts from new + subscribers require moderation. This means that after you've subscribed and + send your first mail to a list, that mail will not be let through to the + list until a mailing list administrator has verified that it is OK and + permits it to get posted. + + Once a first post has been made that proves the sender is actually talking + about curl-related subjects, the moderation "flag" will be switched off and + future posts will go through without being moderated. + + The reason for this moderation policy is that we do suffer from spammers who + actually subscribe and send spam to our lists. + + 1.6 Handling trolls and spam + + Despite our good intentions and hard work to keep spam off the lists and to + maintain a friendly and positive atmosphere, there will be times when spam + and or trolls get through. + + Troll - "someone who posts inflammatory, extraneous, or off-topic messages + in an online community" + + Spam - "use of electronic messaging systems to send unsolicited bulk + messages" + + No matter what, we NEVER EVER respond to trolls or spammers on the list. If + you believe the list admin should do something particular, contact him/her + off-list. The subject will be taken care of as good as possible to prevent + repeated offences, but responding on the list to such messages never lead to + anything good and only puts the light even more on the offender: which was + the entire purpose of it getting to the list in the first place. + + Don't feed the trolls! + + 1.7 How to unsubscribe + + You unsubscribe the same way you subscribed in the first place. You go to + the page for the particular mailing list you're subscribed to and you enter + your email address and password and press the unsubscribe button. + + Also, this information is included in the headers of every mail that is sent + out to all curl related mailing lists and there's footer in each mail that + links to the "admin" page on which you can unsubscribe and change other + options. + + You NEVER EVER email the mailing list requesting someone else to get you off + the list. + + +2. Sending mail + + 2.1 Reply or New Mail + + Please do not reply to an existing message as a short-cut to post a message + to the lists. + + Many mail programs and web archivers use information within mails to keep + them together as "threads", as collections of posts that discuss a certain + subject. If you don't intend to reply on the same or similar subject, don't + just hit reply on an existing mail and change subject, create a new mail. + + 2.2 Reply to the List + + When replying to a message from the list, make sure that you do "group + reply" or "reply to all", and not just reply to the author of the single + mail you reply to. + + We're actively discouraging replying back to the single person by setting + the Reply-To: field in outgoing mails back to the mailing list address, + making it harder for people to mail the author only by mistake. + + 2.3 Use a Sensible Subject + + Please use a subject of the mail that makes sense and that is related to the + contents of your mail. It makes it a lot easier to find your mail afterwards + and it makes it easier to track mail threads and topics. + + 2.4 Do Not Top-Post + + If you reply to a message, don't use top-posting. Top-posting is when you + write the new text at the top of a mail and you insert the previous quoted + mail conversation below. It forces users to read the mail in a backwards + order to properly understand it. + + This is why top posting is so bad: + + A: Because it messes up the order in which people normally read + text. + Q: Why is top-posting such a bad thing? + A: Top-posting. + Q: What is the most annoying thing in e-mail? + + Apart from the screwed up read order (especially when mixed together in a + thread when someone responds using the mandated bottom-posting style), it + also makes it impossible to quote only parts of the original mail. + + When you reply to a mail. You let the mail client insert the previous mail + quoted. Then you put the cursor on the first line of the mail and you move + down through the mail, deleting all parts of the quotes that don't add + context for your comments. When you want to add a comment you do so, inline, + right after the quotes that relate to your comment. Then you continue + downwards again. + + When most of the quotes have been removed and you've added your own words, + you're done! + + 2.5 HTML is not for mails + + Please switch off those HTML encoded messages. You can mail all those funny + mails to your friends. We speak plain text mails. + + 2.6 Quoting + + Quote as little as possible. Just enough to provide the context you cannot + leave out. A lengthy description can be found here: + + http://www.netmeister.org/news/learn2quote.html + + 2.7 Digest + + We allow subscribers to subscribe to the "digest" version of the mailing + lists. A digest is a collection of mails lumped together in one single mail. + + Should you decide to reply to a mail sent out as a digest, there are two + things you MUST consider if you really really cannot subscribe normally + instead: + + Cut off all mails and chatter that is not related to the mail you want to + reply to. + + Change the subject name to something sensible and related to the subject, + preferably even the actual subject of the single mail you wanted to reply to + + 2.8 Please Tell Us How You Solved The Problem! + + Many people mail questions to the list, people spend some of their time and + make an effort in providing good answers to these questions. + + If you are the one who asks, please consider responding once more in case + one of the hints was what solved your problems. The guys who write answers + feel good to know that they provided a good answer and that you fixed the + problem. Far too often, the person who asked the question is never heard of + again, and we never get to know if he/she is gone because the problem was + solved or perhaps because the problem was unsolvable! + + Getting the solution posted also helps other users that experience the same + problem(s). They get to see (possibly in the web archives) that the + suggested fixes actually has helped at least one person. + diff --git a/docs/MANUAL b/docs/MANUAL index d7085b7f6..4ad2e135e 100644 --- a/docs/MANUAL +++ b/docs/MANUAL @@ -19,7 +19,7 @@ SIMPLE USAGE curl http://www.weirdserver.com:8000/ - Get a list of a directory of an FTP site: + Get a directory listing of an FTP site: curl ftp://cool.haxx.se/ @@ -54,7 +54,7 @@ SIMPLE USAGE DOWNLOAD TO A FILE - Get a web page and store in a local file: + Get a web page and store in a local file with a specific name: curl -o thatpage.html http://www.netscape.com/ @@ -113,9 +113,10 @@ USING PASSWORDS ones out of the ones that the server accepts for the given URL, by using --anyauth. - NOTE! Since HTTP URLs don't support user and password, you can't use that - style when using Curl via a proxy. You _must_ use the -u style fetch - during such circumstances. + NOTE! According to the URL specification, HTTP URLs can not contain a user + and password, so that style will not work when using curl via a proxy, even + though curl allows it at other times. When using a proxy, you _must_ use + the -u style for user and password. HTTPS @@ -123,11 +124,17 @@ USING PASSWORDS PROXY - Get an ftp file using a proxy named my-proxy that uses port 888: + curl supports both HTTP and SOCKS proxy servers, with optional authentication. + It does not have special support for FTP proxy servers since there are no + standards for those, but it can still be made to work with many of them. You + can also use both HTTP and SOCKS proxies to transfer files to and from FTP + servers. + + Get an ftp file using an HTTP proxy named my-proxy that uses port 888: curl -x my-proxy:888 ftp://ftp.leachsite.com/README - Get a file from a HTTP server that requires user and password, using the + Get a file from an HTTP server that requires user and password, using the same proxy as above: curl -u user:passwd -x my-proxy:888 http://www.get.this/ @@ -146,12 +153,26 @@ PROXY curl also supports SOCKS4 and SOCKS5 proxies with --socks4 and --socks5. - See also the environment variables Curl support that offer further proxy + See also the environment variables Curl supports that offer further proxy control. + Most FTP proxy servers are set up to appear as a normal FTP server from the + client's perspective, with special commands to select the remote FTP server. + curl supports the -u, -Q and --ftp-account options that can be used to + set up transfers through many FTP proxies. For example, a file can be + uploaded to a remote FTP server using a Blue Coat FTP proxy with the + options: + + curl -u "Remote-FTP-Username@remote.ftp.server Proxy-Username:Remote-Pass" \ + --ftp-account Proxy-Password --upload-file local-file \ + ftp://my-ftp.proxy.server:21/remote/upload/path/ + + See the manual for your FTP proxy to determine the form it expects to set up + transfers, and curl's -v option to see exactly what curl is sending. + RANGES - With HTTP 1.1 byte-ranges were introduced. Using this, a client can request + HTTP 1.1 introduced byte-ranges. Using this, a client can request to get only one or more subparts of a specified document. Curl supports this with the -r flag. @@ -182,8 +203,8 @@ UPLOADING curl -T uploadfile -u user:passwd ftp://ftp.upload.com/myfile - Upload a local file to the remote site, and use the local file name remote - too: + Upload a local file to the remote site, and use the local file name at the remote + site too: curl -T uploadfile -u user:passwd ftp://ftp.upload.com/ @@ -199,14 +220,14 @@ UPLOADING HTTP - Upload all data on stdin to a specified http site: + Upload all data on stdin to a specified HTTP site: curl -T - http://www.upload.com/myfile - Note that the http server must have been configured to accept PUT before + Note that the HTTP server must have been configured to accept PUT before this can be done successfully. - For other ways to do http data upload, see the POST section below. + For other ways to do HTTP data upload, see the POST section below. VERBOSE / DEBUG @@ -269,7 +290,7 @@ POST (HTTP) The 'variable' names are the names set with "name=" in the <input> tags, and the data is the contents you want to fill in for the inputs. The data *must* be properly URL encoded. That means you replace space with + and that you - write weird letters with %XX where XX is the hexadecimal representation of + replace weird letters with %XX where XX is the hexadecimal representation of the letter's ASCII code. Example: @@ -308,7 +329,7 @@ POST (HTTP) If the content-type is not specified, curl will try to guess from the file extension (it only knows a few), or use the previously specified type (from an earlier file if several files are specified in a list) or else it will - using the default type 'text/plain'. + use the default type 'application/octet-stream'. Emulate a fill-in form with -F. Let's say you fill in three fields in a form. One field is a file name which to post, one field is your name and one @@ -341,8 +362,8 @@ POST (HTTP) REFERRER - A HTTP request has the option to include information about which address - that referred to actual page. Curl allows you to specify the + An HTTP request has the option to include information about which address + referred it to the actual page. Curl allows you to specify the referrer to be used on the command line. It is especially useful to fool or trick stupid servers or CGI scripts that rely on that information being available or contain certain data. @@ -353,7 +374,7 @@ REFERRER USER AGENT - A HTTP request has the option to include information about the browser + An HTTP request has the option to include information about the browser that generated the request. Curl allows it to be specified on the command line. It is especially useful to fool or trick stupid servers or CGI scripts that only accept certain browsers. @@ -593,21 +614,21 @@ SFTP and SCP and PATH NAMES FTP and firewalls The FTP protocol requires one of the involved parties to open a second - connection as soon as data is about to get transfered. There are two ways to + connection as soon as data is about to get transferred. There are two ways to do this. The default way for curl is to issue the PASV command which causes the server to open another port and await another connection performed by the - client. This is good if the client is behind a firewall that don't allow + client. This is good if the client is behind a firewall that doesn't allow incoming connections. curl ftp.download.com - If the server for example, is behind a firewall that don't allow connections - on other ports than 21 (or if it just doesn't support the PASV command), the + If the server, for example, is behind a firewall that doesn't allow connections + on ports other than 21 (or if it just doesn't support the PASV command), the other way to do it is to use the PORT command and instruct the server to - connect to the client on the given (as parameters to the PORT command) IP - number and port. + connect to the client on the given IP number and port (as parameters to the + PORT command). The -P flag to curl supports a few different options. Your machine may have several IP-addresses and/or network interfaces and curl allows you to select @@ -665,8 +686,8 @@ HTTPS If you neglect to specify the password on the command line, you will be prompted for the correct password before any data can be received. - Many older SSL-servers have problems with SSLv3 or TLS, that newer versions - of OpenSSL etc is using, therefore it is sometimes useful to specify what + Many older SSL-servers have problems with SSLv3 or TLS, which newer versions + of OpenSSL etc use, therefore it is sometimes useful to specify what SSL-version curl should use. Use -3, -2 or -1 to specify that exact SSL version to use (for SSLv3, SSLv2 or TLSv1 respectively): @@ -675,14 +696,13 @@ HTTPS Otherwise, curl will first attempt to use v3 and then v2. To use OpenSSL to convert your favourite browser's certificate into a PEM - formatted one that curl can use, do something like this (assuming netscape, - but IE is likely to work similarly): + formatted one that curl can use, do something like this: - You start with hitting the 'security' menu button in netscape. + In Netscape, you start with hitting the 'Security' menu button. Select 'certificates->yours' and then pick a certificate in the list - Press the 'export' button + Press the 'Export' button enter your PIN code for the certs @@ -693,11 +713,21 @@ HTTPS # ./apps/openssl pkcs12 -in [file you saved] -clcerts -out [PEMfile] + In Firefox, select Options, then Advanced, then the Encryption tab, + View Certificates. This opens the Certificate Manager, where you can + Export. Be sure to select PEM for the Save as type. + + In Internet Explorer, select Internet Options, then the Content tab, then + Certificates. Then you can Export, and depending on the format you may + need to convert to PEM. + + In Chrome, select Settings, then Show Advanced Settings. Under HTTPS/SSL + select Manage Certificates. RESUMING FILE TRANSFERS To continue a file transfer where it was previously aborted, curl supports - resume on http(s) downloads as well as ftp uploads and downloads. + resume on HTTP(S) downloads as well as FTP uploads and downloads. Continue downloading a document: @@ -711,7 +741,7 @@ RESUMING FILE TRANSFERS curl -C - -o file http://www.server.com/ - (*1) = This requires that the ftp server supports the non-standard command + (*1) = This requires that the FTP server supports the non-standard command SIZE. If it doesn't, curl will say so. (*2) = This requires that the web server supports at least HTTP/1.1. If it @@ -720,7 +750,7 @@ RESUMING FILE TRANSFERS TIME CONDITIONS HTTP allows a client to specify a time condition for the document it - requests. It is If-Modified-Since or If-Unmodified-Since. Curl allow you to + requests. It is If-Modified-Since or If-Unmodified-Since. Curl allows you to specify them with the -z/--time-cond flag. For example, you can easily make a download that only gets performed if the @@ -768,7 +798,7 @@ LDAP and offer ldap:// support. LDAP is a complex thing and writing an LDAP query is not an easy task. I do - advice you to dig up the syntax description for that elsewhere. Two places + advise you to dig up the syntax description for that elsewhere. Two places that might suit you are: Netscape's "Netscape Directory SDK 3.0 for C Programmer's Guide Chapter 10: @@ -777,7 +807,7 @@ LDAP RFC 2255, "The LDAP URL Format" http://curl.haxx.se/rfc/rfc2255.txt - To show you an example, this is now I can get all people from my local LDAP + To show you an example, this is how I can get all people from my local LDAP server that has a certain sub-domain in their email address: curl -B "ldap://ldap.frontec.se/o=frontec??sub?mail=*sth.frontec.se" @@ -811,15 +841,15 @@ ENVIRONMENT VARIABLES NETRC Unix introduced the .netrc concept a long time ago. It is a way for a user - to specify name and password for commonly visited ftp sites in a file so + to specify name and password for commonly visited FTP sites in a file so that you don't have to type them in each time you visit those sites. You realize this is a big security risk if someone else gets hold of your passwords, so therefore most unix programs won't read this file unless it is only readable by yourself (curl doesn't care though). - Curl supports .netrc files if told so (using the -n/--netrc and - --netrc-optional options). This is not restricted to only ftp, - but curl can use it for all protocols where authentication is used. + Curl supports .netrc files if told to (using the -n/--netrc and + --netrc-optional options). This is not restricted to just FTP, + so curl can use it for all protocols where authentication is used. A very simple .netrc file could look something like: @@ -840,7 +870,7 @@ KERBEROS FTP TRANSFER Curl supports kerberos4 and kerberos5/GSSAPI for FTP transfers. You need the kerberos package installed and used at curl build time for it to be - used. + available. First, get the krb-ticket the normal way, like with the kinit/kauth tool. Then use curl in way similar to: @@ -875,7 +905,7 @@ TELNET - NEW_ENV=<var,val> Sets an environment variable. - NOTE: the telnet protocol does not specify any way to login with a specified + NOTE: The telnet protocol does not specify any way to login with a specified user and password so curl can't do that automatically. To do that, you need to track when the login prompt is received and send the username and password accordingly. @@ -894,7 +924,7 @@ PERSISTENT CONNECTIONS Note that curl cannot use persistent connections for transfers that are used in subsequence curl invokes. Try to stuff as many URLs as possible on the same command line if they are using the same host, as that'll make the - transfers faster. If you use a http proxy for file transfers, practically + transfers faster. If you use an HTTP proxy for file transfers, practically all transfers will be persistent. MULTIPLE TRANSFERS WITH A SINGLE COMMAND LINE @@ -935,6 +965,28 @@ IPv6 IPv6 addresses provided other than in URLs (e.g. to the --proxy, --interface or --ftp-port options) should not be URL encoded. +METALINK + + Curl supports Metalink (both version 3 and 4 (RFC 5854) are supported), a way + to list multiple URIs and hashes for a file. Curl will make use of the mirrors + listed within for failover if there are errors (such as the file or server not + being available). It will also verify the hash of the file after the download + completes. The Metalink file itself is downloaded and processed in memory and + not stored in the local file system. + + Example to use a remote Metalink file: + + curl --metalink http://www.example.com/example.metalink + + To use a Metalink file in the local file system, use FILE protocol (file://): + + curl --metalink file://example.metalink + + Please note that if FILE protocol is disabled, there is no way to use a local + Metalink file at the time of this writing. Also note that if --metalink and + --include are used together, --include will be ignored. This is because including + headers in the response will break Metalink parser and if the headers are included + in the file described in Metalink file, hash check will fail. MAILING LISTS diff --git a/docs/Makefile.am b/docs/Makefile.am index 316b4f4f0..8466a6c29 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,11 +1,31 @@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| # +# Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. # +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### AUTOMAKE_OPTIONS = foreign no-dependencies man_MANS = curl.1 curl-config.1 -GENHTMLPAGES = curl.html curl-config.html -PDFPAGES = curl.pdf curl-config.pdf +noinst_man_MANS = mk-ca-bundle.1 +GENHTMLPAGES = curl.html curl-config.html mk-ca-bundle.html +PDFPAGES = curl.pdf curl-config.pdf mk-ca-bundle.pdf HTMLPAGES = $(GENHTMLPAGES) index.html @@ -16,7 +36,8 @@ CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES) EXTRA_DIST = MANUAL BUGS CONTRIBUTE FAQ FEATURES INTERNALS SSLCERTS \ README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS VERSIONS \ KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY INSTALL \ - $(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA INSTALL.devcpp + $(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA INSTALL.devcpp \ + MAIL-ETIQUETTE HTTP-COOKIES LIBCURL-STRUCTS MAN2HTML= roffit < $< >$@ diff --git a/docs/Makefile.in b/docs/Makefile.in index 3cc2e3b81..43a37299f 100644 --- a/docs/Makefile.in +++ b/docs/Makefile.in @@ -1,8 +1,8 @@ -# Makefile.in generated by automake 1.9.6 from Makefile.am. +# Makefile.in generated by automake 1.13.3 from Makefile.am. # @configure_input@ -# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -# 2003, 2004, 2005 Free Software Foundation, Inc. +# Copyright (C) 1994-2013 Free Software Foundation, Inc. + # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. @@ -14,17 +14,78 @@ @SET_MAKE@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| # +# Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. # -srcdir = @srcdir@ -top_srcdir = @top_srcdir@ +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### VPATH = @srcdir@ +am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)' +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) pkgdatadir = $(datadir)/@PACKAGE@ -pkglibdir = $(libdir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ -top_builddir = .. +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd -INSTALL = @INSTALL@ install_sh_DATA = $(install_sh) -c -m 644 install_sh_PROGRAM = $(install_sh) -c install_sh_SCRIPT = $(install_sh) -c @@ -39,64 +100,165 @@ POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ subdir = docs -DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in INSTALL \ - THANKS TODO +DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am \ + $(top_srcdir)/mkinstalldirs INSTALL THANKS TODO ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/curl-compilers.m4 \ $(top_srcdir)/m4/curl-confopts.m4 \ $(top_srcdir)/m4/curl-functions.m4 \ + $(top_srcdir)/m4/curl-openssl.m4 \ $(top_srcdir)/m4/curl-override.m4 \ - $(top_srcdir)/m4/curl-reentrant.m4 \ - $(top_srcdir)/m4/curl-system.m4 $(top_srcdir)/m4/libtool.m4 \ + $(top_srcdir)/m4/curl-reentrant.m4 $(top_srcdir)/m4/libtool.m4 \ $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \ $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \ - $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac + $(top_srcdir)/m4/xc-am-iface.m4 \ + $(top_srcdir)/m4/xc-cc-check.m4 \ + $(top_srcdir)/m4/xc-lt-iface.m4 \ + $(top_srcdir)/m4/xc-translit.m4 \ + $(top_srcdir)/m4/xc-val-flgs.m4 \ + $(top_srcdir)/m4/zz40-xc-ovr.m4 \ + $(top_srcdir)/m4/zz50-xc-ovr.m4 \ + $(top_srcdir)/m4/zz60-xc-ovr.m4 $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs CONFIG_HEADER = $(top_builddir)/lib/curl_config.h \ - $(top_builddir)/src/curl_config.h \ $(top_builddir)/include/curl/curlbuild.h CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = depcomp = am__depfiles_maybe = SOURCES = DIST_SOURCES = -RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \ - html-recursive info-recursive install-data-recursive \ - install-exec-recursive install-info-recursive \ - install-recursive installcheck-recursive installdirs-recursive \ - pdf-recursive ps-recursive uninstall-info-recursive \ - uninstall-recursive +RECURSIVE_TARGETS = all-recursive check-recursive cscopelist-recursive \ + ctags-recursive dvi-recursive html-recursive info-recursive \ + install-data-recursive install-dvi-recursive \ + install-exec-recursive install-html-recursive \ + install-info-recursive install-pdf-recursive \ + install-ps-recursive install-recursive installcheck-recursive \ + installdirs-recursive pdf-recursive ps-recursive \ + tags-recursive uninstall-recursive +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } man1dir = $(mandir)/man1 am__installdirs = "$(DESTDIR)$(man1dir)" MANS = $(man_MANS) +RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \ + distclean-recursive maintainer-clean-recursive +am__recursive_targets = \ + $(RECURSIVE_TARGETS) \ + $(RECURSIVE_CLEAN_TARGETS) \ + $(am__extra_recursive_targets) +AM_RECURSIVE_TARGETS = $(am__recursive_targets:-recursive=) TAGS CTAGS \ + distdir +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +# Read a list of newline-separated strings from the standard input, +# and print each of them once, without duplicates. Input order is +# *not* preserved. +am__uniquify_input = $(AWK) '\ + BEGIN { nonempty = 0; } \ + { items[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in items) print i; }; } \ +' +# Make sure the list of sources is unique. This is necessary because, +# e.g., the same source file might be shared among _SOURCES variables +# for different programs/libraries. +am__define_uniq_tagged_files = \ + list='$(am__tagged_files)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | $(am__uniquify_input)` ETAGS = etags CTAGS = ctags DIST_SUBDIRS = $(SUBDIRS) DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +am__relativize = \ + dir0=`pwd`; \ + sed_first='s,^\([^/]*\)/.*$$,\1,'; \ + sed_rest='s,^[^/]*/*,,'; \ + sed_last='s,^.*/\([^/]*\)$$,\1,'; \ + sed_butlast='s,/*[^/]*$$,,'; \ + while test -n "$$dir1"; do \ + first=`echo "$$dir1" | sed -e "$$sed_first"`; \ + if test "$$first" != "."; then \ + if test "$$first" = ".."; then \ + dir2=`echo "$$dir0" | sed -e "$$sed_last"`/"$$dir2"; \ + dir0=`echo "$$dir0" | sed -e "$$sed_butlast"`; \ + else \ + first2=`echo "$$dir2" | sed -e "$$sed_first"`; \ + if test "$$first2" = "$$first"; then \ + dir2=`echo "$$dir2" | sed -e "$$sed_rest"`; \ + else \ + dir2="../$$dir2"; \ + fi; \ + dir0="$$dir0"/"$$first"; \ + fi; \ + fi; \ + dir1=`echo "$$dir1" | sed -e "$$sed_rest"`; \ + done; \ + reldir="$$dir2" ACLOCAL = @ACLOCAL@ -AMDEP_FALSE = @AMDEP_FALSE@ -AMDEP_TRUE = @AMDEP_TRUE@ AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ AR = @AR@ AS = @AS@ AUTOCONF = @AUTOCONF@ AUTOHEADER = @AUTOHEADER@ AUTOMAKE = @AUTOMAKE@ AWK = @AWK@ -BUILD_LIBHOSTNAME_FALSE = @BUILD_LIBHOSTNAME_FALSE@ -BUILD_LIBHOSTNAME_TRUE = @BUILD_LIBHOSTNAME_TRUE@ +BLANK_AT_MAKETIME = @BLANK_AT_MAKETIME@ CC = @CC@ CCDEPMODE = @CCDEPMODE@ CFLAGS = @CFLAGS@ +CFLAG_CURL_SYMBOL_HIDING = @CFLAG_CURL_SYMBOL_HIDING@ CONFIGURE_OPTIONS = @CONFIGURE_OPTIONS@ CPP = @CPP@ CPPFLAGS = @CPPFLAGS@ -CROSSCOMPILING_FALSE = @CROSSCOMPILING_FALSE@ -CROSSCOMPILING_TRUE = @CROSSCOMPILING_TRUE@ -CURLDEBUG_FALSE = @CURLDEBUG_FALSE@ -CURLDEBUG_TRUE = @CURLDEBUG_TRUE@ +CPPFLAG_CURL_STATICLIB = @CPPFLAG_CURL_STATICLIB@ +CURLVERSION = @CURLVERSION@ CURL_CA_BUNDLE = @CURL_CA_BUNDLE@ CURL_CFLAG_EXTRAS = @CURL_CFLAG_EXTRAS@ CURL_DISABLE_DICT = @CURL_DISABLE_DICT@ @@ -113,7 +275,8 @@ CURL_DISABLE_RTSP = @CURL_DISABLE_RTSP@ CURL_DISABLE_SMTP = @CURL_DISABLE_SMTP@ CURL_DISABLE_TELNET = @CURL_DISABLE_TELNET@ CURL_DISABLE_TFTP = @CURL_DISABLE_TFTP@ -CURL_LIBS = @CURL_LIBS@ +CURL_LT_SHLIB_VERSIONED_FLAVOUR = @CURL_LT_SHLIB_VERSIONED_FLAVOUR@ +CURL_NETWORK_AND_TIME_LIBS = @CURL_NETWORK_AND_TIME_LIBS@ CURL_NETWORK_LIBS = @CURL_NETWORK_LIBS@ CYGPATH_W = @CYGPATH_W@ DEFS = @DEFS@ @@ -126,15 +289,17 @@ ECHO_N = @ECHO_N@ ECHO_T = @ECHO_T@ EGREP = @EGREP@ ENABLE_SHARED = @ENABLE_SHARED@ +ENABLE_STATIC = @ENABLE_STATIC@ EXEEXT = @EXEEXT@ FGREP = @FGREP@ GREP = @GREP@ +HAVE_GNUTLS_SRP = @HAVE_GNUTLS_SRP@ HAVE_LDAP_SSL = @HAVE_LDAP_SSL@ HAVE_LIBZ = @HAVE_LIBZ@ -HAVE_LIBZ_FALSE = @HAVE_LIBZ_FALSE@ -HAVE_LIBZ_TRUE = @HAVE_LIBZ_TRUE@ -HAVE_PK11_CREATEGENERICOBJECT = @HAVE_PK11_CREATEGENERICOBJECT@ +HAVE_NSS_INITCONTEXT = @HAVE_NSS_INITCONTEXT@ +HAVE_SSLEAY_SRP = @HAVE_SSLEAY_SRP@ IDN_ENABLED = @IDN_ENABLED@ +INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_SCRIPT = @INSTALL_SCRIPT@ @@ -144,6 +309,9 @@ KRB4_ENABLED = @KRB4_ENABLED@ LD = @LD@ LDFLAGS = @LDFLAGS@ LIBCURL_LIBS = @LIBCURL_LIBS@ +LIBMETALINK_CPPFLAGS = @LIBMETALINK_CPPFLAGS@ +LIBMETALINK_LDFLAGS = @LIBMETALINK_LDFLAGS@ +LIBMETALINK_LIBS = @LIBMETALINK_LIBS@ LIBOBJS = @LIBOBJS@ LIBS = @LIBS@ LIBTOOL = @LIBTOOL@ @@ -151,16 +319,12 @@ LIPO = @LIPO@ LN_S = @LN_S@ LTLIBOBJS = @LTLIBOBJS@ MAINT = @MAINT@ -MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@ -MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@ MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ MANOPT = @MANOPT@ -MIMPURE_FALSE = @MIMPURE_FALSE@ -MIMPURE_TRUE = @MIMPURE_TRUE@ +MKDIR_P = @MKDIR_P@ NM = @NM@ NMEDIT = @NMEDIT@ -NO_UNDEFINED_FALSE = @NO_UNDEFINED_FALSE@ -NO_UNDEFINED_TRUE = @NO_UNDEFINED_TRUE@ NROFF = @NROFF@ OBJDUMP = @OBJDUMP@ OBJEXT = @OBJEXT@ @@ -173,7 +337,6 @@ PACKAGE_STRING = @PACKAGE_STRING@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ -PATH = @PATH@ PATH_SEPARATOR = @PATH_SEPARATOR@ PERL = @PERL@ PKGADD_NAME = @PKGADD_NAME@ @@ -186,34 +349,34 @@ REQUIRE_LIB_DEPS = @REQUIRE_LIB_DEPS@ SED = @SED@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ -SONAME_BUMP_FALSE = @SONAME_BUMP_FALSE@ -SONAME_BUMP_TRUE = @SONAME_BUMP_TRUE@ SSL_ENABLED = @SSL_ENABLED@ -STATICLIB_FALSE = @STATICLIB_FALSE@ -STATICLIB_TRUE = @STATICLIB_TRUE@ STRIP = @STRIP@ SUPPORT_FEATURES = @SUPPORT_FEATURES@ SUPPORT_PROTOCOLS = @SUPPORT_PROTOCOLS@ -TEST_SERVER_LIBS = @TEST_SERVER_LIBS@ USE_ARES = @USE_ARES@ -USE_EMBEDDED_ARES_FALSE = @USE_EMBEDDED_ARES_FALSE@ -USE_EMBEDDED_ARES_TRUE = @USE_EMBEDDED_ARES_TRUE@ +USE_AXTLS = @USE_AXTLS@ +USE_CYASSL = @USE_CYASSL@ +USE_DARWINSSL = @USE_DARWINSSL@ USE_GNUTLS = @USE_GNUTLS@ +USE_GNUTLS_NETTLE = @USE_GNUTLS_NETTLE@ USE_LIBRTMP = @USE_LIBRTMP@ USE_LIBSSH2 = @USE_LIBSSH2@ -USE_MANUAL_FALSE = @USE_MANUAL_FALSE@ -USE_MANUAL_TRUE = @USE_MANUAL_TRUE@ USE_NSS = @USE_NSS@ USE_OPENLDAP = @USE_OPENLDAP@ USE_POLARSSL = @USE_POLARSSL@ +USE_SCHANNEL = @USE_SCHANNEL@ USE_SSLEAY = @USE_SSLEAY@ USE_WINDOWS_SSPI = @USE_WINDOWS_SSPI@ VERSION = @VERSION@ VERSIONNUM = @VERSIONNUM@ +ZLIB_LIBS = @ZLIB_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ ac_ct_CC = @ac_ct_CC@ ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ -am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ -am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ am__include = @am__include@ am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ @@ -225,6 +388,7 @@ build_alias = @build_alias@ build_cpu = @build_cpu@ build_os = @build_os@ build_vendor = @build_vendor@ +builddir = @builddir@ datadir = @datadir@ datarootdir = @datarootdir@ docdir = @docdir@ @@ -244,7 +408,6 @@ libexecdir = @libexecdir@ libext = @libext@ localedir = @localedir@ localstatedir = @localstatedir@ -lt_ECHO = @lt_ECHO@ mandir = @mandir@ mkdir_p = @mkdir_p@ oldincludedir = @oldincludedir@ @@ -254,20 +417,26 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ subdirs = @subdirs@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ AUTOMAKE_OPTIONS = foreign no-dependencies man_MANS = curl.1 curl-config.1 -GENHTMLPAGES = curl.html curl-config.html -PDFPAGES = curl.pdf curl-config.pdf +noinst_man_MANS = mk-ca-bundle.1 +GENHTMLPAGES = curl.html curl-config.html mk-ca-bundle.html +PDFPAGES = curl.pdf curl-config.pdf mk-ca-bundle.pdf HTMLPAGES = $(GENHTMLPAGES) index.html SUBDIRS = examples libcurl CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES) EXTRA_DIST = MANUAL BUGS CONTRIBUTE FAQ FEATURES INTERNALS SSLCERTS \ README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS VERSIONS \ KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY INSTALL \ - $(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA INSTALL.devcpp + $(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA INSTALL.devcpp \ + MAIL-ETIQUETTE HTTP-COOKIES LIBCURL-STRUCTS MAN2HTML = roffit < $< >$@ SUFFIXES = .1 .html .pdf @@ -279,14 +448,14 @@ $(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__confi @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ - && exit 0; \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ exit 1;; \ esac; \ done; \ - echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/Makefile'; \ - cd $(top_srcdir) && \ - $(AUTOMAKE) --foreign docs/Makefile + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign docs/Makefile .PRECIOUS: Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status @case '$?' in \ @@ -304,79 +473,77 @@ $(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh $(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): mostlyclean-libtool: -rm -f *.lo clean-libtool: -rm -rf .libs _libs - -distclean-libtool: - -rm -f libtool -uninstall-info-am: -install-man1: $(man1_MANS) $(man_MANS) +install-man1: $(man_MANS) @$(NORMAL_INSTALL) - test -z "$(man1dir)" || $(mkdir_p) "$(DESTDIR)$(man1dir)" - @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.1*) list="$$list $$i" ;; \ - esac; \ + @list1=''; \ + list2='$(man_MANS)'; \ + test -n "$(man1dir)" \ + && test -n "`echo $$list1$$list2`" \ + || exit 0; \ + echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \ + { for i in $$list1; do echo "$$i"; done; \ + if test -n "$$list2"; then \ + for i in $$list2; do echo "$$i"; done \ + | sed -n '/\.1[a-z]*$$/p'; \ + fi; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \ + fi; \ done; \ - for i in $$list; do \ - if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ - else file=$$i; fi; \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 1*) ;; \ - *) ext='1' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ - $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst"; \ - done + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \ + done; } + uninstall-man1: @$(NORMAL_UNINSTALL) - @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.1*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 1*) ;; \ - *) ext='1' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \ - rm -f "$(DESTDIR)$(man1dir)/$$inst"; \ - done + @list=''; test -n "$(man1dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.1[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir) # This directory's subdirectories are mostly independent; you can cd -# into them and run `make' without going through this Makefile. -# To change the values of `make' variables: instead of editing Makefiles, -# (1) if the variable is set in `config.status', edit `config.status' -# (which will cause the Makefiles to be regenerated when you run `make'); -# (2) otherwise, pass the desired values on the `make' command line. -$(RECURSIVE_TARGETS): - @failcom='exit 1'; \ - for f in x $$MAKEFLAGS; do \ - case $$f in \ - *=* | --[!k]*);; \ - *k*) failcom='fail=yes';; \ - esac; \ - done; \ +# into them and run 'make' without going through this Makefile. +# To change the values of 'make' variables: instead of editing Makefiles, +# (1) if the variable is set in 'config.status', edit 'config.status' +# (which will cause the Makefiles to be regenerated when you run 'make'); +# (2) otherwise, pass the desired values on the 'make' command line. +$(am__recursive_targets): + @fail=; \ + if $(am__make_keepgoing); then \ + failcom='fail=yes'; \ + else \ + failcom='exit 1'; \ + fi; \ dot_seen=no; \ target=`echo $@ | sed s/-recursive//`; \ - list='$(SUBDIRS)'; for subdir in $$list; do \ + case "$@" in \ + distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \ + *) list='$(SUBDIRS)' ;; \ + esac; \ + for subdir in $$list; do \ echo "Making $$target in $$subdir"; \ if test "$$subdir" = "."; then \ dot_seen=yes; \ @@ -384,66 +551,20 @@ $(RECURSIVE_TARGETS): else \ local_target="$$target"; \ fi; \ - (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ + ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ || eval $$failcom; \ done; \ if test "$$dot_seen" = "no"; then \ $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \ fi; test -z "$$fail" -mostlyclean-recursive clean-recursive distclean-recursive \ -maintainer-clean-recursive: - @failcom='exit 1'; \ - for f in x $$MAKEFLAGS; do \ - case $$f in \ - *=* | --[!k]*);; \ - *k*) failcom='fail=yes';; \ - esac; \ - done; \ - dot_seen=no; \ - case "$@" in \ - distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \ - *) list='$(SUBDIRS)' ;; \ - esac; \ - rev=''; for subdir in $$list; do \ - if test "$$subdir" = "."; then :; else \ - rev="$$subdir $$rev"; \ - fi; \ - done; \ - rev="$$rev ."; \ - target=`echo $@ | sed s/-recursive//`; \ - for subdir in $$rev; do \ - echo "Making $$target in $$subdir"; \ - if test "$$subdir" = "."; then \ - local_target="$$target-am"; \ - else \ - local_target="$$target"; \ - fi; \ - (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ - || eval $$failcom; \ - done && test -z "$$fail" -tags-recursive: - list='$(SUBDIRS)'; for subdir in $$list; do \ - test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) tags); \ - done -ctags-recursive: - list='$(SUBDIRS)'; for subdir in $$list; do \ - test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) ctags); \ - done +ID: $(am__tagged_files) + $(am__define_uniq_tagged_files); mkid -fID $$unique +tags: tags-recursive +TAGS: tags -ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES) - list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ - unique=`for i in $$list; do \ - if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ - done | \ - $(AWK) ' { files[$$0] = 1; } \ - END { for (i in files) print i; }'`; \ - mkid -fID $$unique -tags: TAGS - -TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ - $(TAGS_FILES) $(LISP) - tags=; \ +tags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) + set x; \ here=`pwd`; \ if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \ include_option=--etags-include; \ @@ -455,81 +576,104 @@ TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ list='$(SUBDIRS)'; for subdir in $$list; do \ if test "$$subdir" = .; then :; else \ test ! -f $$subdir/TAGS || \ - tags="$$tags $$include_option=$$here/$$subdir/TAGS"; \ + set "$$@" "$$include_option=$$here/$$subdir/TAGS"; \ fi; \ done; \ - list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ - unique=`for i in $$list; do \ - if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ - done | \ - $(AWK) ' { files[$$0] = 1; } \ - END { for (i in files) print i; }'`; \ - if test -z "$(ETAGS_ARGS)$$tags$$unique"; then :; else \ + $(am__define_uniq_tagged_files); \ + shift; \ + if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \ test -n "$$unique" || unique=$$empty_fix; \ - $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ - $$tags $$unique; \ + if test $$# -gt 0; then \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + "$$@" $$unique; \ + else \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + $$unique; \ + fi; \ fi -ctags: CTAGS -CTAGS: ctags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ - $(TAGS_FILES) $(LISP) - tags=; \ - here=`pwd`; \ - list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ - unique=`for i in $$list; do \ - if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ - done | \ - $(AWK) ' { files[$$0] = 1; } \ - END { for (i in files) print i; }'`; \ - test -z "$(CTAGS_ARGS)$$tags$$unique" \ +ctags: ctags-recursive + +CTAGS: ctags +ctags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) + $(am__define_uniq_tagged_files); \ + test -z "$(CTAGS_ARGS)$$unique" \ || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ - $$tags $$unique + $$unique GTAGS: here=`$(am__cd) $(top_builddir) && pwd` \ - && cd $(top_srcdir) \ - && gtags -i $(GTAGS_ARGS) $$here + && $(am__cd) $(top_srcdir) \ + && gtags -i $(GTAGS_ARGS) "$$here" +cscopelist: cscopelist-recursive + +cscopelist-am: $(am__tagged_files) + list='$(am__tagged_files)'; \ + case "$(srcdir)" in \ + [\\/]* | ?:[\\/]*) sdir="$(srcdir)" ;; \ + *) sdir=$(subdir)/$(srcdir) ;; \ + esac; \ + for i in $$list; do \ + if test -f "$$i"; then \ + echo "$(subdir)/$$i"; \ + else \ + echo "$$sdir/$$i"; \ + fi; \ + done >> $(top_builddir)/cscope.files distclean-tags: -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags distdir: $(DISTFILES) - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ - list='$(DISTFILES)'; for file in $$list; do \ - case $$file in \ - $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ - $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ - esac; \ + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ - dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ - if test "$$dir" != "$$file" && test "$$dir" != "."; then \ - dir="/$$dir"; \ - $(mkdir_p) "$(distdir)$$dir"; \ - else \ - dir=''; \ - fi; \ if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ - cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ fi; \ - cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ else \ - test -f $(distdir)/$$file \ - || cp -p $$d/$$file $(distdir)/$$file \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ || exit 1; \ fi; \ done - list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ + @list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ if test "$$subdir" = .; then :; else \ - test -d "$(distdir)/$$subdir" \ - || $(mkdir_p) "$(distdir)/$$subdir" \ - || exit 1; \ - distdir=`$(am__cd) $(distdir) && pwd`; \ - top_distdir=`$(am__cd) $(top_distdir) && pwd`; \ - (cd $$subdir && \ + $(am__make_dryrun) \ + || test -d "$(distdir)/$$subdir" \ + || $(MKDIR_P) "$(distdir)/$$subdir" \ + || exit 1; \ + dir1=$$subdir; dir2="$(distdir)/$$subdir"; \ + $(am__relativize); \ + new_distdir=$$reldir; \ + dir1=$$subdir; dir2="$(top_distdir)"; \ + $(am__relativize); \ + new_top_distdir=$$reldir; \ + echo " (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) top_distdir="$$new_top_distdir" distdir="$$new_distdir" \\"; \ + echo " am__remove_distdir=: am__skip_length_check=: am__skip_mode_fix=: distdir)"; \ + ($(am__cd) $$subdir && \ $(MAKE) $(AM_MAKEFLAGS) \ - top_distdir="$$top_distdir" \ - distdir="$$distdir/$$subdir" \ + top_distdir="$$new_top_distdir" \ + distdir="$$new_distdir" \ + am__remove_distdir=: \ + am__skip_length_check=: \ + am__skip_mode_fix=: \ distdir) \ || exit 1; \ fi; \ @@ -540,7 +684,7 @@ all-am: Makefile $(MANS) installdirs: installdirs-recursive installdirs-am: for dir in "$(DESTDIR)$(man1dir)"; do \ - test -z "$$dir" || $(mkdir_p) "$$dir"; \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ done install: install-recursive install-exec: install-exec-recursive @@ -552,10 +696,15 @@ install-am: all-am installcheck: installcheck-recursive install-strip: - $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ - install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ - `test -z '$(STRIP)' || \ - echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi mostlyclean-generic: clean-generic: @@ -563,6 +712,7 @@ clean-generic: distclean-generic: -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @@ -573,25 +723,44 @@ clean-am: clean-generic clean-libtool mostlyclean-am distclean: distclean-recursive -rm -f Makefile -distclean-am: clean-am distclean-generic distclean-libtool \ - distclean-tags +distclean-am: clean-am distclean-generic distclean-tags dvi: dvi-recursive dvi-am: +html-am: + info: info-recursive info-am: install-data-am: install-man +install-dvi: install-dvi-recursive + +install-dvi-am: + install-exec-am: +install-html: install-html-recursive + +install-html-am: + install-info: install-info-recursive +install-info-am: + install-man: install-man1 +install-pdf: install-pdf-recursive + +install-pdf-am: + +install-ps: install-ps-recursive + +install-ps-am: + installcheck-am: maintainer-clean: maintainer-clean-recursive @@ -608,25 +777,25 @@ ps: ps-recursive ps-am: -uninstall-am: uninstall-info-am uninstall-man - -uninstall-info: uninstall-info-recursive +uninstall-am: uninstall-man uninstall-man: uninstall-man1 -.PHONY: $(RECURSIVE_TARGETS) CTAGS GTAGS all all-am check check-am \ - clean clean-generic clean-libtool clean-recursive ctags \ - ctags-recursive distclean distclean-generic distclean-libtool \ - distclean-recursive distclean-tags distdir dvi dvi-am html \ - html-am info info-am install install-am install-data \ - install-data-am install-exec install-exec-am install-info \ - install-info-am install-man install-man1 install-strip \ - installcheck installcheck-am installdirs installdirs-am \ - maintainer-clean maintainer-clean-generic \ - maintainer-clean-recursive mostlyclean mostlyclean-generic \ - mostlyclean-libtool mostlyclean-recursive pdf pdf-am ps ps-am \ - tags tags-recursive uninstall uninstall-am uninstall-info-am \ - uninstall-man uninstall-man1 +.MAKE: $(am__recursive_targets) install-am install-strip + +.PHONY: $(am__recursive_targets) CTAGS GTAGS TAGS all all-am check \ + check-am clean clean-generic clean-libtool cscopelist-am ctags \ + ctags-am distclean distclean-generic distclean-libtool \ + distclean-tags distdir dvi dvi-am html html-am info info-am \ + install install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-man1 install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs installdirs-am maintainer-clean \ + maintainer-clean-generic mostlyclean mostlyclean-generic \ + mostlyclean-libtool pdf pdf-am ps ps-am tags tags-am uninstall \ + uninstall-am uninstall-man uninstall-man1 html: $(HTMLPAGES) @@ -644,6 +813,7 @@ pdf: $(PDFPAGES) ps2pdf $$foo.ps $@; \ rm $$foo.ps; \ echo "converted $< to $@") + # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: diff --git a/docs/SSLCERTS b/docs/SSLCERTS index 0d1414cea..e6b05c3e3 100644 --- a/docs/SSLCERTS +++ b/docs/SSLCERTS @@ -1,6 +1,12 @@ Peer SSL Certificate Verification ================================= +(NOTE: If libcurl was built with Schannel or Secure Transport support, then +this does not apply to you. Scroll down for details on how the OS-native +engines handle SSL certificates. If you're not sure, then run "curl -V" and +read the results. If the version string says "WinSSL" in it, then it was built +with Schannel support.) + libcurl performs peer SSL certificate verification by default. This is done by using CA cert bundle that the SSL library can use to make sure the peer's server certificate is valid. @@ -93,24 +99,40 @@ server. Peer SSL Certificate Verification with NSS ========================================== -If libcurl is build with NSS support then depending on the OS distribution it -is probably required to take some additional steps to use the system-wide CA -cert db. RedHat ships with an additional module libnsspem.so which enables NSS -to read the OpenSSL PEM CA bundle. With OpenSuSE this lib is missing, and NSS -can only work with its own internal formats. Also NSS got a new database -format: -https://wiki.mozilla.org/NSS_Shared_DB -Starting with version 7.19.7 libcurl will check for the NSS version it runs, -and add automatically the 'sql:' prefix to the certdb directory (either the +If libcurl was built with NSS support, then depending on the OS distribution, +it is probably required to take some additional steps to use the system-wide CA +cert db. RedHat ships with an additional module, libnsspem.so, which enables +NSS to read the OpenSSL PEM CA bundle. This library is missing in OpenSuSE, and +without it, NSS can only work with its own internal formats. NSS also has a new +database format: https://wiki.mozilla.org/NSS_Shared_DB + +Starting with version 7.19.7, libcurl will check for the NSS version it runs, +and automatically add the 'sql:' prefix to the certdb directory (either the hardcoded default /etc/pki/nssdb or the directory configured with SSL_DIR -environment variable) if a version 3.12.0 or later is detected. -To check which certdb format your distribution provides examine the default -certdb location /etc/pki/nssdb; the new certdb format can be identified by +environment variable) if version 3.12.0 or later is detected. To check which +ertdb format your distribution provides, examine the default +certdb location: /etc/pki/nssdb; the new certdb format can be identified by the filenames cert9.db, key4.db, pkcs11.txt; filenames of older versions are cert8.db, key3.db, modsec.db. -Usually these cert databases are empty; but NSS also has built-in CAs which are -provided through a shared library libnssckbi.so; if you want to use these -built-in CAs then create a symlink to libnssckbi.so in /etc/pki/nssdb: -ln -s /usr/lib[64]/libnssckbi.so /etc/pki/nssdb/libnssckbi.so +Usually these cert databases are empty, but NSS also has built-in CAs which are +provided through a shared library, libnssckbi.so; if you want to use these +built-in CAs, then create a symlink to libnssckbi.so in /etc/pki/nssdb: +ln -s /usr/lib[64]/libnssckbi.so /etc/pki/nssdb/libnssckbi.so + Peer SSL Certificate Verification with Schannel and Secure Transport + ==================================================================== + +If libcurl was built with Schannel (Microsoft's TLS/SSL engine) or Secure +Transport (Apple's TLS/SSL engine) support, then libcurl will still perform +peer certificate verification, but instead of using a CA cert bundle, it will +use the certificates that are built into the OS. These are the same +certificates that appear in the Internet Options control panel (under Windows) +or Keychain Access application (under OS X). Any custom security rules for +certificates will be honored. + +Schannel will run CRL checks on certificates unless peer verification is +disabled. Secure Transport on iOS will run OCSP checks on certificates unless +peer verification is disabled. Secure Transport on OS X will run either OCSP +or CRL checks on certificates if those features are enabled, and this behavior +can be adjusted in the preferences of Keychain Access. diff --git a/docs/THANKS b/docs/THANKS index edcd513ec..693139bf7 100644 --- a/docs/THANKS +++ b/docs/THANKS @@ -5,23 +5,34 @@ If you have contributed but are missing here, please let us know! Aaron Oneal +Aaron Orenstein Adam D. Moss Adam Light Adam Piggott +Adam Tkac Adrian Schuur +Adriano Meirelles +Ajit Dhumale +Aki Koskinen Akos Pasztory Alan Pinstein Albert Chin-A-Young Albert Choy Ale Vesely +Alejandro Alvarez Aleksandar Milivojevic +Aleksey Tulinov +Alessandro Ghedini Alessandro Vesely Alex Bligh Alex Fishman +Alex Gruz Alex Neblett Alex Suykov +Alex Vinnik Alex aka WindEagle Alexander Beedie +Alexander Klauer Alexander Kourakos Alexander Krasnostavsky Alexander Lazic @@ -29,68 +40,95 @@ Alexander Zhuravlev Alexey Borzov Alexey Pesternikov Alexey Simak +Alexey Zakhlestin Alexis Carvalho +Alfred Gebert Allen Pulsifer Amol Pattekar +Amr Shahin Anatoli Tubman Anders Gustafsson +Anders Havn Andi Jahja Andre Guibert de Bruet Andreas Damm Andreas Faerber Andreas Farber +Andreas Malzahn Andreas Ntaflos Andreas Olsson Andreas Rieke Andreas Schuldei Andreas Wurf Andrei Benea +Andrei Cipu Andres Garcia Andrew Benham Andrew Biggs Andrew Bushnell Andrew Francis Andrew Fuller +Andrew Kurushin Andrew Moise Andrew Wansink Andrew de los Reyes -Andrés García +Andrii Moiseiev +Andrés GarcÃa Andy Cedilnik Andy Serpa Andy Tsouladze Angus Mackay Anthony Bryan +Anthony G. Basile Antoine Calando +Anton Bychkov Anton Kalmykov +Anton Malov +Anton Yabchinskiy Arkadiusz Miskiewicz Armel Asselin +Arnaud Compan Arnaud Ebalard +Arthur Murray Arve Knudsen Ates Goral Augustus Saunders Avery Fay Axel Tillequin +Balaji Parasuram Balint Szilakszi Bart Whiteley Bas Mevissen Ben Darnell Ben Greear Ben Madsen +Ben Noordhuis Ben Van Hof +Ben Winslow Benbuck Nason Benjamin Gerard +Benjamin Gilbert +Benjamin Johnson Bernard Leak +Bernhard Reutner-Fischer Bertrand Demiddelaer Bill Egert Bill Hoffman +Bill Middlecamp +Bjoern Sikora Bjorn Augustsson Bjorn Reese -Björn Stenberg +Björn Stenberg +Blaise Potard +Bob Relyea Bob Richmond Bob Schader Bogdan Nicula Brad Burdick +Brad Hards +Brad King Bradford Bruce +Brandon Wang Brendan Jurd Brent Beardsley Brian Akins @@ -100,14 +138,18 @@ Brian R Duffy Brian Ulm Brock Noland Bruce Mitchener +Bruno de Carvalho Bryan Henderson Bryan Kemp +Byrial Jensen Cameron Kaiser Camille Moncelier Caolan McNamara Carsten Lange Casey O'Donnell +Cedric Deltheil Chad Monroe +Chandrakant Bagul Charles Kerr Chih-Chung Chang Chris "Bob Bob" @@ -118,19 +160,25 @@ Chris Flerackers Chris Gaukroger Chris Maltby Chris Mumford +Chris Smowton +Christian Grothoff +Christian Hägele Christian Krause Christian Kurz Christian Robottom Reis Christian Schmitz Christian Vogt +Christian Weisgerber Christophe Demory Christophe Legry Christopher Conroy Christopher Palow Christopher R. Palmer +Christopher Stone Ciprian Badescu Claes Jakobsson Clarence Gardner +Clemens Gruber Clifford Wolf Cody Jones Colin Hogben @@ -142,8 +190,12 @@ Craig A West Craig Davison Craig Markwardt Cris Bailiff +Cristian RodrÃguez Curt Bogmine Cyrill Osterwalder +Cédric Deltheil +Dag Ekengren +Dagobert Michelsen Damien Adant Dan Becker Dan C @@ -156,19 +208,23 @@ Dan Zitter Daniel Black Daniel Cater Daniel Egger -Daniel Fandrich Daniel Johnson +Daniel Mentz Daniel Steinberg Daniel Stenberg +Daniel Theron Daniel at touchtunes Darryl House +Darshan Mody Dave Dribin Dave Halbakken Dave Hamilton Dave May +Dave Reisner Dave Vasilevsky David Bau David Binderman +David Blaikie David Byron David Cohen David Eriksson @@ -185,6 +241,7 @@ David Odin David Phillips David Rosenstrauch David Shaw +David Strauss David Tarendash David Thiel David Wright @@ -199,6 +256,7 @@ Dimitris Sarris Dinar Dirk Eddelbuettel Dirk Manske +Dmitri Shubin Dmitriy Sergeyev Dmitry Bartsevich Dmitry Kurochkin @@ -207,6 +265,7 @@ Dmitry Rechkin Dolbneff A.V Domenico Andreoli Dominick Meglio +Dominique Leuenberger Doug Kaufman Doug Porter Douglas E. Wegscheid @@ -215,6 +274,7 @@ Douglas R. Horner Douglas Steinwand Dov Murik Duane Cathey +Duncan Duncan Mac-Vicar Prett Dustin Boswell Dylan Ellicott @@ -223,7 +283,11 @@ Early Ehlinger Ebenezer Ikonne Edin Kadribasic Eduard Bloch +Edward Rudd +Edward Sheldrake +Eelco Dolstra Eetu Ojanen +Eldar Zaitov Ellis Pritchard Emanuele Bovisio Emil Romanus @@ -231,21 +295,26 @@ Emiliano Ida Enrico Scholz Enrik Berkhan Eric Cooper +Eric Hu Eric Landes Eric Lavigne Eric Melville Eric Mertens Eric Rautman +Eric S. Raymond Eric Thelin Eric Vergnaud Eric Wong Eric Young Erick Nuwendam +Erik Johansson Erwan Legrand Erwin Authried Eugene Kotlyarov Evan Jordan +Evgeny Turnaev Eygene Ryabinkin +Fabian Hiernaux Fabian Keil Fabrizio Ammollo Fedor Karpelevitch @@ -258,11 +327,16 @@ Frank Keeney Frank McGeough Frank Meier Frank Ticheler +Frank Van Uffelen +FrantiÅ¡ek KuÄera Fred Machado Fred New Fred Noz Frederic Lepied +Fredrik Thulin Gabriel Kuri +Gabriel Sjoberg +Garrett Holmstrom Gary Maxwell Gautam Kachroo Gautam Mani @@ -274,7 +348,8 @@ Georg Lippitsch Georg Wicherski Gerd v. Egidy Gerhard Herre -Gerrit Bruchhäuser +Gerrit Bruchhäuser +Ghennadi Procopciuc Giancarlo Formicuccia Giaslas Georgios Gil Weber @@ -286,6 +361,7 @@ Giuseppe Attardi Giuseppe D'Ambrosio Glen Nakamura Glen Scott +Gokhan Sengun Grant Erickson Greg Hewgill Greg Morse @@ -294,12 +370,14 @@ Greg Zavertnik Grigory Entin Guenole Bescon Guenter Knauf +Guido Berhoerster Guillaume Arluison Gustaf Hui Gwenole Beauchesne -Götz Babin-Ebell +Götz Babin-Ebell Hamish Mackenzie Hang Kin Lau +Hang Su Hanno Kranzhoff Hans Steegers Hans-Jurgen May @@ -307,12 +385,18 @@ Hardeep Singh Harshal Pradhan Hauke Duden Heikki Korpela +Heinrich Ko Hendrik Visage Henrik Storner +Henry Ludemann +Herve Amblard Hidemoto Nakada +Ho-chi Chen Hoi-Ho Chan +Hongli Lai Howard Chu Hzhijun +Ian D Allen Ian Ford Ian Gulliver Ian Lynagh @@ -328,6 +412,7 @@ Immanuel Gregoire Ingmar Runge Ingo Ralf Blum Ingo Wilken +Ishan SinghLevett Jack Zhang Jacky Lam Jacob Meuser @@ -344,10 +429,16 @@ James MacMillan Jamie Lokier Jamie Newton Jamie Wilkinson +Jan Ehrhardt +Jan Koen Annot Jan Kunder +Jan Schaumann Jan Van Boghout +Jared Jennings Jared Lundell Jari Sundell +Jason Glasgow +Jason Liu Jason McDonald Jason S. Priebe Jay Austin @@ -358,7 +449,9 @@ Jean-Claude Chauve Jean-Francois Bertrand Jean-Louis Lemaire Jean-Marc Ranger +Jean-Noel Rouvignac Jean-Philippe Barrette-LaPierre +Jeff Connelly Jeff Johnson Jeff Lawson Jeff Phillips @@ -366,31 +459,44 @@ Jeff Pohlmeyer Jeff Weber Jeffrey Pohlmeyer Jeremy Friesner +Jeremy Huddleston Jerome Muffat-Meridol Jerome Vouillon +Jerry Wu Jes Badwal Jesper Jensen Jesse Noller +Jie He Jim Drash Jim Freeman +Jim Hollinger Jim Meyering +Jiri Hruska +Jiri Jaburek Jocelyn Jaubert Joe Halpin Joe Malicki +Joe Mason Joel Chen Jofell Gallardo Johan Anderson Johan Nilsson Johan van Selst +Johannes Bauer +John Bradshaw John Crow John Dennis John E. Malmberg +John Gardiner Myers John Janssen +John Joseph Bachir John Kelly John Lask John Lightsey +John Marino John McGowan John P. McCaskey +John Suprock John Wilkinson John-Mark Bell Johnny Luong @@ -400,30 +506,39 @@ Jon Sargeant Jon Travis Jon Turner Jonas Forsman +Jonas Schnelli Jonatan Lander Jonathan Hseu +Jonathan Nieder Jongki Suwandi Jose Kahan Josef Wolf Josh Kapell Joshua Kwan +Josue Andrade Gomes +Juan Barreto Juan F. Codagnone -Juan Ignacio Hervás +Juan Ignacio Hervás Judson Bishop Juergen Wilke Jukka Pihl Julian Noble +Julian Taylor Julien Chaffraix +Julien Royer Jun-ichiro itojun Hagino Jurij Smakov Justin Fletcher -Jörg Mueller-Tolk -Jörn Hartroth +Justin Karneges +Jörg Mueller-Tolk +Jörn Hartroth +Kai Engert Kai Sommerfeld Kai-Uwe Rommel Kalle Vahlman Kamil Dudka Kang-Jin Lee +Karl M Karl Moerder Karol Pietrzak Kaspar Brand @@ -443,21 +558,25 @@ Kevin Lussier Kevin Reed Kevin Roth Kim Rinnewitz +Kim Vandry Kimmo Kinnunen Kjell Ericson Kjetil Jacobsen Klevtsov Vadim +Konstantin Isakov Kris Kennaway Krishnendu Majumdar Krister Johansen Kristian Gunstone -Kristian Köhntopp +Kristian Köhntopp Kyle Sallee Lachlan O'Dea Larry Campbell Larry Fahnoe +Lars Buitinck Lars Gustafsson Lars J. Aas +Lars Johannesen Lars Nilsson Lars Torben Wilson Lau Hang Kin @@ -468,36 +587,53 @@ Len Krause Lenaic Lefever Lenny Rachitsky Liam Healy +Lijo Antony Linas Vepstas Ling Thio Linus Nielsen Feltzing Lisa Xu Liza Alenchery +LluÃs Batlle i Rossell Loic Dachary Loren Kirkby Luca Altea Luca Alteas Lucas Adamski +Ludovico Cavedon Lukasz Czekierda +Luke Amery Luke Call Luong Dinh Dung Maciej Karpiuk Maciej W. Rozycki +Mamoru Tasaka +Mandy Wu Manfred Schwarb +Manuel Massing Marc Boucher +Marc Doughty +Marc Hoersken Marc Kleine-Budde +Marcel Raad +Marcel Roelofs Marcelo Juchem +Marcin Adamski Marcin Konicki Marco G. Salvagno Marco Maggi +Marcus Sundberg Marcus Webster Mario Schroeder +Mark Brand Mark Butler Mark Davies Mark Eichin Mark Incley Mark Karpeles Mark Lentczner +Mark Salisbury +Mark Snelling +Mark Tully Markus Duft Markus Koetter Markus Moeller @@ -507,6 +643,8 @@ Martin C. Martin Martin Drasar Martin Hager Martin Hedenfalk +Martin Jansen +Martin Lemke Martin Skinner Martin Storsjo Marty Kuhrt @@ -516,40 +654,51 @@ Massimo Callegari Mateusz Loskot Mathias Axelsson Mats Lidell +Matt Arsenault Matt Kraai Matt Veenstra Matt Witherspoon Matt Wixson +Matteo Rocco Matthew Blain Matthew Clarke +Matthias Bolte Maurice Barnum Mauro Iorio Max Katsev Maxim Ivanov Maxim Perenesenko +Maxim Prohorov +Maxime Larocque +Mehmet Bozkurt Mekonikum Mettgut Jamalla Michael Benedict Michael Calmer Michael Cronenworth Michael Curtis +Michael Day Michael Goffioul Michael Jahn Michael Jerris Michael Mealling +Michael Mueller Michael Smith Michael Stillwell Michael Wallner Michal Bonino Michal Gorny +Michal Kowalczyk Michal Marek Michele Bini +Miguel Angel Mihai Ionescu Mikael Johansson Mikael Sennerholm Mike Bytnar Mike Crowe Mike Dobbs +Mike Giancola Mike Hommey Mike Power Mike Protts @@ -559,25 +708,31 @@ Mitz Wark Mohamed Lrhazi Mohun Biswas Moonesamy +Myk Taylor +Nach M. S. Nathan Coulter Nathan O'Sullivan Nathanael Nerode +Naveen Chandran Naveen Noel +Neil Bowers Neil Dunbar Neil Spring Nic Roets +Nicholas Maniscalco Nick Gimbrone Nick Humfrey Nick Zitzmann Nico Baggus Nicolas Berloquin Nicolas Croiset -Nicolas François +Nicolas François Niels van Tongeren Nikita Schmidt Nikitinskit Dmitriy Niklas Angebrand Nikolai Kondrashov +Nikos Mavrogiannopoulos Ning Dong Nir Soffer Nis Jorgensen @@ -585,17 +740,28 @@ Nodak Sodak Norbert Frese Norbert Novotny Ofer +Olaf Flebbe Olaf Stueben -Olaf Stüben +Olaf Stüben +Oliver Gondža +Olivier Berger Oren Tirosh +Ori Avtalion +Oscar Koeroo +Oscar Norlander P R Schaffner +Paolo Piacentini Pascal Terjan +Pasha Kuznetsov Pat Ray +Patrice Guerin +Patricia Muscalu Patrick Bihan-Faou Patrick Monnerat Patrick Scott Patrick Smith Patrik Thunstrom +Pau Garcia i Quiles Paul Harrington Paul Howarth Paul Marquis @@ -607,11 +773,14 @@ Pavel Orehov Pavel Raiskup Pawel A. Gajda Pawel Kierski +Pedro Larroy Pedro Neves Pete Su Peter Bray Peter Forret +Peter Gal Peter Heuchert +Peter Hjalmarsson Peter Korsgaard Peter Lamberg Peter O'Gorman @@ -627,6 +796,7 @@ Phil Blundell Phil Karn Phil Lisiecki Phil Pellouchoud +Philip Craig Philip Gladstone Philip Langdale Philippe Hameau @@ -634,16 +804,21 @@ Philippe Raoult Philippe Vaucher Pierre Pierre Brico +Pierre Chapuis Pierre Joye +Pierre Ynard Pooyan McSporran Pramod Sharma Puneet Pawaia Quagmire Quanah Gibson-Mount +Quinn Slack Rafa Muyo Rafael Sagula Rainer Canavan +Rainer Jung Rainer Koenig +Rajesh Naganathan Ralf S. Engelschall Ralph Beckmann Ralph Mitchell @@ -656,9 +831,11 @@ Reinout van Schouwen Renato Botelho Renaud Chaillat Renaud Duhaut +Renaud Guillard Rene Bernhardt Rene Rebe Reuven Wachtfogel +Reza Arbab Ricardo Cadime Rich Gray Rich Rauenzahn @@ -668,51 +845,70 @@ Richard Bramante Richard Clayton Richard Cooper Richard Gorton +Richard Michael Richard Prescott +Richard Silverman Rick Jones Rick Richardson Rob Crittenden Rob Jones Rob Stanzel +Rob Ward Robert A. Monat +Robert B. Harris Robert D. Young Robert Foreman Robert Iakobashvili Robert Olson +Robert Schumann Robert Weaver +Robert Wruck Robin Cornelius Robin Johnson Robin Kay Robson Braga Araujo Rodney Simmons +Rodrigo Silva Roland Blom Roland Krikava Roland Zimmermann Rolland Dudemaine Roman Koifman +Roman Mamedov Ron Zapp Rosimildo da Silva Roy Shan Rune Kleveland Ruslan Gazizov +Rutger Hofman Ryan Chan Ryan Nelson +Ryan Schmidt S. Moonesamy -Salvador Dávila +Salvador Dávila Salvatore Sorrentino +Sam Deane Sam Listopad Sampo Kellomaki -Samuel Díaz García +Samuel DÃaz GarcÃa Samuel Listopad +Samuel Thibault Sander Gates Sandor Feldi +Santhana Todatry +Saqib Ali +Sara Golemon +Saran Neti Saul good +Scott Bailey Scott Barrett Scott Cantor Scott Davis Scott McCreary +Sebastian Rasmussen Sebastien Willemijns Senthil Raja Velu +Sergei Nikulov Sergio Ballestrero Seshubabu Pasam Sh Diao @@ -732,9 +928,12 @@ Spacen Jasset Spiridonoff A.V Stadler Stephan Stan van de Burgt +Stanislav Ivochkin Stefan Esser Stefan Krause +Stefan Neis Stefan Teleman +Stefan Tomanek Stefan Ulrich Stephan Bergmann Stephen Collyer @@ -742,6 +941,8 @@ Stephen Kick Stephen More Sterling Hughes Steve Green +Steve H Truong +Steve Holme Steve Lhomme Steve Little Steve Marx @@ -749,18 +950,23 @@ Steve Oliphant Steve Roskowski Steven Bazyl Steven G. Johnson +Steven Gu Steven M. Schweda +Steven Parkes Stoned Elipot Sven Anders Sven Neuhaus Sven Wegener -Sébastien Willemijns +Sébastien Willemijns T. Bharath T. Yamada +Taneli Vahakangas Tanguy Fautre +Tatsuhiro Tsujikawa Temprimus Thomas J. Moore Thomas Klausner +Thomas L. Shinnick Thomas Lopatic Thomas Schwinge Thomas Tonino @@ -769,25 +975,36 @@ Tim Baker Tim Bartley Tim Chen Tim Costello +Tim Harder +Tim Heckman Tim Newsome Tim Sneddon -Tobias Rundström +Timo Sirainen +Tinus van den Berg +Tobias Rundström Toby Peterson +Todd A Ouska Todd Kulesza +Todd Ouska Todd Vierling Tom Benoist Tom Donovan +Tom Grace Tom Lee Tom Mattison Tom Moers Tom Mueller Tom Regner +Tom Wright Tom Zerucha +Tomas Mlcoch Tomas Pospisek Tomas Szepe Tomasz Lacki +Tommie Gannert Tommy Tam Ton Voon +Toni Moreno Toon Verwaest Tor Arntsen Torsten Foertsch @@ -797,7 +1014,8 @@ Traian Nicolescu Troels Walsted Hansen Troy Engel Tupone Alfredo -Ulf Härnhammar +Ulf Härnhammar +Ulrich Doehner Ulrich Zadow Venkat Akella Victor Snezhko @@ -807,25 +1025,37 @@ Vincent Bronner Vincent Le Normand Vincent Penquerc'h Vincent Sanders +Vincent Torri Vlad Grachov Vlad Ureche +Vladimir Grishchenko Vladimir Lazarenko Vojtech Janota Vojtech Minarik +Vsevolod Novikov Walter J. Mack +Ward Willats Wayne Haigh Werner Koch Wesley Laxton Wesley Miaw Wez Furlong Wilfredo Sanchez +Willem Sparreboom Wojciech Zwiefka +Wouter Van Rooy +Wu Yongzheng Xavier Bouchoux +Yamada Yasuharu Yang Tse Yarram Sunil Yehoshua Hershberg +Yukihiro Kawada Yuriy Sosov +Yves Arrouye Yves Lejeune +Zdenek Pavlas +Zekun Ni Zmey Petroff Zvi Har'El nk @@ -12,16 +12,16 @@ All bugs documented in the KNOWN_BUGS document are subject for fixing! 1. libcurl - 1.1 Zero-copy interface 1.2 More data sharing 1.3 struct lifreq 1.4 signal-based resolver timeouts + 1.5 get rid of PATH_MAX + 1.6 Happy Eyeball dual stack connect + 1.7 Modified buffer size approach 2. libcurl - multi interface 2.1 More non-blocking - 2.2 Remove easy interface internally - 2.3 Avoid having to remove/readd handles - 2.4 Fix HTTP Pipelining for PUT + 2.2 Fix HTTP Pipelining for PUT 3. Documentation 3.1 More and better @@ -38,6 +38,7 @@ 5.1 Better persistency for HTTP 1.0 5.2 support FF3 sqlite cookie files 5.3 Rearrange request header order + 5.4 HTTP2/SPDY 6. TELNET 6.1 ditch stdin @@ -45,71 +46,84 @@ 6.3 feature negotiation debug data 6.4 send data in chunks - 7. SSL - 7.1 Disable specific versions - 7.2 Provide mutex locking API - 7.3 Evaluate SSL patches - 7.4 Cache OpenSSL contexts - 7.5 Export session ids - 7.6 Provide callback for cert verification - 7.7 Support other SSL libraries - 7.8 Support SRP on the TLS layer - 7.9 improve configure --with-ssl - - 8. GnuTLS - 8.1 SSL engine stuff - 8.2 SRP - 8.3 check connection - 8.4 non-gcrypt - - 9. Other protocols - - 10. New protocols - 10.1 RSYNC - - 11. Client - 11.1 sync - 11.2 glob posts - 11.3 prevent file overwriting - 11.4 simultaneous parallel transfers - 11.5 provide formpost headers - 11.6 url-specific options - 11.7 metalink support - 11.8 warning when setting an option - - 12. Build - 12.1 roffit - - 13. Test suite - 13.1 SSL tunnel - 13.2 nicer lacking perl message - 13.3 more protocols supported - 13.4 more platforms supported - - 14. Next SONAME bump - 14.1 http-style HEAD output for ftp - 14.2 combine error codes - 14.3 extend CURLOPT_SOCKOPTFUNCTION prototype - - 15. Next major release - 15.1 cleanup return codes - 15.2 remove obsolete defines - 15.3 size_t - 15.4 remove several functions - 15.5 remove CURLOPT_FAILONERROR - 15.6 remove CURLOPT_DNS_USE_GLOBAL_CACHE - 15.7 remove progress meter from libcurl + 7. SMTP + 7.1 Pipelining + 7.2 Graceful base64 decoding failure + 7.3 Enhanced capability support + + 8. POP3 + 8.1 Pipelining + 8.2 Graceful base64 decoding failure + 8.3 Enhanced capability support + + 9. IMAP + 9.1 Graceful base64 decoding failure + 9.2 Enhanced capability support + + 10. LDAP + 10.1 SASL based authentication mechanisms + + 11. New protocols + 11.1 RSYNC + + 12. SSL + 12.1 Disable specific versions + 12.2 Provide mutex locking API + 12.3 Evaluate SSL patches + 12.4 Cache OpenSSL contexts + 12.5 Export session ids + 12.6 Provide callback for cert verification + 12.7 Support other SSL libraries + 12.8 improve configure --with-ssl + 12.9 Support DANE + + 13. GnuTLS + 13.1 SSL engine stuff + 13.2 check connection + + 14. SASL + 14.1 Other authentication mechanisms + + 15. Client + 15.1 sync + 15.2 glob posts + 15.3 prevent file overwriting + 15.4 simultaneous parallel transfers + 15.5 provide formpost headers + 15.6 url-specific options + 15.7 warning when setting an option + 15.8 IPv6 addresses with globbing + + 16. Build + 16.1 roffit + + 17. Test suite + 17.1 SSL tunnel + 17.2 nicer lacking perl message + 17.3 more protocols supported + 17.4 more platforms supported + + 18. Next SONAME bump + 18.1 http-style HEAD output for ftp + 18.2 combine error codes + 18.3 extend CURLOPT_SOCKOPTFUNCTION prototype + + 19. Next major release + 19.1 cleanup return codes + 19.2 remove obsolete defines + 19.3 size_t + 19.4 remove several functions + 19.5 remove CURLOPT_FAILONERROR + 19.6 remove CURLOPT_DNS_USE_GLOBAL_CACHE + 19.7 remove progress meter from libcurl + 19.8 remove 'curl_httppost' from public + 19.9 have form functions use CURL handle argument + 19.10 Add CURLOPT_MAIL_CLIENT option ============================================================================== 1. libcurl -1.1 Zero-copy interface - - Introduce another callback interface for upload/download that makes one less - copy of data and thus a faster operation. - [http://curl.haxx.se/dev/no_copy_callbacks.txt] - 1.2 More data sharing curl_share_* functions already exist and work, and they can be extended to @@ -134,6 +148,49 @@ Also, alarm() provides timeout resolution only to the nearest second. alarm ought to be replaced by setitimer on systems that support it. +1.5 get rid of PATH_MAX + + Having code use and rely on PATH_MAX is not nice: + http://insanecoding.blogspot.com/2007/11/pathmax-simply-isnt.html + + Currently the SSH based code uses it a bit, but to remove PATH_MAX from there + we need libssh2 to properly tell us when we pass in a too small buffer and + its current API (as of libssh2 1.2.7) doesn't. + +1.6 Happy Eyeball dual stack connect + + In order to make alternative technologies not suffer when transitioning, like + when introducing IPv6 as an alternative to IPv4 and there are more than one + option existing simultaneously there are reasons to reconsider internal + choices. + + To make libcurl do blazing fast IPv6 in a dual-stack configuration, this needs + to be addressed: + + http://tools.ietf.org/html/rfc6555 + +1.7 Modified buffer size approach + + Current libcurl allocates a fixed 16K size buffer for download and an + additional 16K for upload. They are always unconditionally part of the easy + handle. If CRLF translations are requested, an additional 32K "scratch + buffer" is allocated. A total of 64K transfer buffers in the worst case. + + First, while the handles are not actually in use these buffers could be freed + so that lingering handles just kept in queues or whatever waste less memory. + + Secondly, SFTP is a protocol that needs to handle many ~30K blocks at once + since each need to be individually acked and therefore libssh2 must be + allowed to send (or receive) many separate ones in parallel to achieve high + transfer speeds. A current libcurl build with a 16K buffer makes that + impossible, but one with a 512K buffer will reach MUCH faster transfers. But + allocating 512K unconditionally for all buffers just in case they would like + to do fast SFTP transfers at some point is not a good solution either. + + Dynamically allocate buffer size depending on protocol in use in combination + with freeing it after each individual transfer? Other suggestions? + + 2. libcurl - multi interface 2.1 More non-blocking @@ -143,7 +200,6 @@ - Name resolves on non-windows unless c-ares is used - NSS SSL connections - - Active FTP connections - HTTP proxy CONNECT operations - SOCKS proxy handshakes - file:// transfers @@ -151,33 +207,7 @@ - The "DONE" operation (post transfer protocol-specific actions) for the protocols SFTP, SMTP, FTP. Fixing Curl_done() for this is a worthy task. -2.2 Remove easy interface internally - - Make curl_easy_perform() a wrapper-function that simply creates a multi - handle, adds the easy handle to it, runs curl_multi_perform() until the - transfer is done, then detach the easy handle, destroy the multi handle and - return the easy handle's return code. This will thus make everything - internally use and assume the multi interface. The select()-loop should use - curl_multi_socket(). - -2.3 Avoid having to remove/readd handles - - curl_multi_handle_control() - this can control the easy handle (while) added - to a multi handle in various ways: - - o RESTART, unconditionally restart this easy handle's transfer from the - start, re-init the state - - o RESTART_COMPLETED, restart this easy handle's transfer but only if the - existing transfer has already completed and it is in a "finished state". - - o STOP, just stop this transfer and consider it completed - - o PAUSE? - - o RESUME? - -2.4 Fix HTTP Pipelining for PUT +2.2 Fix HTTP Pipelining for PUT HTTP Pipelining can be a way to greatly enhance performance for multiple serial requests and currently libcurl only supports that for HEAD and GET @@ -252,6 +282,24 @@ headers use a default value so only headers that need to be moved have to be specified. +5.4 HTTP2/SPDY + + The first drafts for HTTP2 have been published + (http://tools.ietf.org/html/draft-ietf-httpbis-http2-03) and is so far based + on SPDY (http://www.chromium.org/spdy) designs and experiences. Chances are + it will end up in that style. Chrome and Firefox already support SPDY and + lots of web services do. + + It would make sense to implement SPDY support now and later transition into + or add HTTP2 support as well. + + We should base or HTTP2/SPDY work on a 3rd party library for the protocol + fiddling. The Spindy library (http://spindly.haxx.se/) was an attempt to make + such a library with an API suitable for use by libcurl but that effort has + more or less stalled. spdylay (https://github.com/tatsuhiro-t/spdylay) may + be a better option, either used directly or wrapped with a more spindly-like + API. + 6. TELNET @@ -277,25 +325,92 @@ to provide the data to send. use, but inefficient for any other. Sent data should be sent in larger chunks. -7. SSL +7. SMTP + +7.1 Pipelining + + Add support for pipelining emails. + +7.2 Graceful base64 decoding failure + + Rather than shutting down the session and returning an error when the + decoding of a base64 encoded authentication response fails, we should + gracefully shutdown the authentication process by sending a * response to the + server as per RFC4954. + +7.3 Enhanced capability support + + Add the ability, for an application that uses libcurl, to obtain the list of + capabilities returned from the EHLO command. + +8. POP3 + +8.1 Pipelining + + Add support for pipelining commands. + +8.2 Graceful base64 decoding failure + + Rather than shutting down the session and returning an error when the + decoding of a base64 encoded authentication response fails, we should + gracefully shutdown the authentication process by sending a * response to the + server as per RFC5034. + +8.3 Enhanced capability support + + Add the ability, for an application that uses libcurl, to obtain the list of + capabilities returned from the CAPA command. + +9. IMAP -7.1 Disable specific versions +9.1 Graceful base64 decoding failure + + Rather than shutting down the session and returning an error when the + decoding of a base64 encoded authentication response fails, we should + gracefully shutdown the authentication process by sending a * response to the + server as per RFC3501. + +9.2 Enhanced capability support + + Add the ability, for an application that uses libcurl, to obtain the list of + capabilities returned from the CAPABILITY command. + +10. LDAP + +10.1 SASL based authentication mechanisms + + Currently the LDAP module only supports ldap_simple_bind_s() in order to bind + to an LDAP server. However, this function sends username and password details + using the simple authentication mechanism (as clear text). However, it should + be possible to use ldap_bind_s() instead specifing the security context + information ourselves. + +11. New protocols + +11.1 RSYNC + + There's no RFC for the protocol or an URI/URL format. An implementation + should most probably use an existing rsync library, such as librsync. + +12. SSL + +12.1 Disable specific versions Provide an option that allows for disabling specific SSL versions, such as SSLv2 http://curl.haxx.se/bug/feature.cgi?id=1767276 -7.2 Provide mutex locking API +12.2 Provide mutex locking API Provide a libcurl API for setting mutex callbacks in the underlying SSL library, so that the same application code can use mutex-locking independently of OpenSSL or GnutTLS being used. -7.3 Evaluate SSL patches +12.3 Evaluate SSL patches Evaluate/apply Gertjan van Wingerde's SSL patches: http://curl.haxx.se/mail/lib-2004-03/0087.html -7.4 Cache OpenSSL contexts +12.4 Cache OpenSSL contexts "Look at SSL cafile - quick traces look to me like these are done on every request as well, when they should only be necessary once per ssl context (or @@ -305,7 +420,7 @@ to provide the data to send. style connections are re-used. It will make us use slightly more memory but it will libcurl do less creations and deletions of SSL contexts. -7.5 Export session ids +12.5 Export session ids Add an interface to libcurl that enables "session IDs" to get exported/imported. Cris Bailiff said: "OpenSSL has functions which can @@ -313,67 +428,54 @@ to provide the data to send. the state from such a buffer at a later date - this is used by mod_ssl for apache to implement and SSL session ID cache". -7.6 Provide callback for cert verification +12.6 Provide callback for cert verification OpenSSL supports a callback for customised verification of the peer certificate, but this doesn't seem to be exposed in the libcurl APIs. Could it be? There's so much that could be done if it were! -7.7 Support other SSL libraries +12.7 Support other SSL libraries Make curl's SSL layer capable of using other free SSL libraries. Such as MatrixSSL (http://www.matrixssl.org/). -7.8 Support SRP on the TLS layer - - Peter Sylvester's patch for SRP on the TLS layer. Awaits OpenSSL support for - this, no need to support this in libcurl before there's an OpenSSL release - that does it. - -7.9 improve configure --with-ssl +12.8 improve configure --with-ssl make the configure --with-ssl option first check for OpenSSL, then GnuTLS, then NSS... -8. GnuTLS +12.9 Support DANE -8.1 SSL engine stuff + DNS-Based Authentication of Named Entities (DANE) is a way to provide SSL + keys and certs over DNS using DNSSEC as an alternative to the CA model. + http://www.rfc-editor.org/rfc/rfc6698.txt - Is this even possible? + An initial patch was posted by Suresh Krishnaswamy on March 7th 2013 + (http://curl.haxx.se/mail/lib-2013-03/0075.html) but it was a too simple + approach. See Daniel's comments: + http://curl.haxx.se/mail/lib-2013-03/0103.html . libunbound may be the + correct library to base this development on. + +13. GnuTLS -8.2 SRP +13.1 SSL engine stuff - Work out a common method with Peter Sylvester's OpenSSL-patch for SRP on the - TLS to provide name and password. GnuTLS already supports it... + Is this even possible? -8.3 check connection +13.2 check connection Add a way to check if the connection seems to be alive, to correspond to the SSL_peak() way we use with OpenSSL. -8.4 non-gcrypt - - libcurl assumes that there are gcrypt functions available when - GnuTLS is. - - GnuTLS can be built to use libnettle instead as crypto library, - which breaks the previously mentioned assumption - - The correct fix would be to detect which crypto layer that is in use and - adapt our code to use that instead of blindly assuming gcrypt. - -9. Other protocols +14. SASL -10. New protocols +14.1 Other authentication mechanisms -10.1 RSYNC + Add support for GSSAPI to SMTP, POP3 and IMAP. - There's no RFC for protocol nor URI/URL format. An implementation should - most probably use an existing rsync library, such as librsync. +15. Client -11. Client - -11.1 sync +15.1 sync "curl --sync http://example.com/feed[1-100].rss" or "curl --sync http://example.net/{index,calendar,history}.html" @@ -382,12 +484,12 @@ to provide the data to send. remote file is newer than the local file. A Last-Modified HTTP date header should also be used to set the mod date on the downloaded file. -11.2 glob posts +15.2 glob posts Globbing support for -d and -F, as in 'curl -d "name=foo[0-9]" URL'. This is easily scripted though. -11.3 prevent file overwriting +15.3 prevent file overwriting Add an option that prevents cURL from overwriting existing local files. When used, and there already is an existing file with the target file name @@ -395,14 +497,14 @@ to provide the data to send. existing). So that index.html becomes first index.html.1 and then index.html.2 etc. -11.4 simultaneous parallel transfers +15.4 simultaneous parallel transfers The client could be told to use maximum N simultaneous parallel transfers and then just make sure that happens. It should of course not make more than one connection to the same remote host. This would require the client to use the multi interface. http://curl.haxx.se/bug/feature.cgi?id=1558595 -11.5 provide formpost headers +15.5 provide formpost headers Extending the capabilities of the multipart formposting. How about leaving the ';type=foo' syntax as it is and adding an extra tag (headers) which @@ -416,7 +518,7 @@ to provide the data to send. which should overwrite the program reasonable defaults (plain/text, 8bit...) -11.6 url-specific options +15.6 url-specific options Provide a way to make options bound to a specific URL among several on the command line. Possibly by letting ':' separate options between URLs, @@ -430,55 +532,57 @@ to provide the data to send. The example would do a POST-GET-POST combination on a single command line. -11.7 metalink support - - Add metalink support to curl (http://www.metalinker.org/). This is most useful - with simultaneous parallel transfers (11.6) but not necessary. - -11.8 warning when setting an option +15.7 warning when setting an option Display a warning when libcurl returns an error when setting an option. This can be useful to tell when support for a particular feature hasn't been compiled into the library. -12. Build +15.8 IPv6 addresses with globbing + + Currently the command line client needs to get url globbing disabled (with + -g) for it to support IPv6 numerical addresses. This is a rather silly flaw + that should be corrected. It probably involves a smarter detection of the + '[' and ']' letters. + +16. Build -12.1 roffit +16.1 roffit Consider extending 'roffit' to produce decent ASCII output, and use that - instead of (g)nroff when building src/hugehelp.c + instead of (g)nroff when building src/tool_hugehelp.c -13. Test suite +17. Test suite -13.1 SSL tunnel +17.1 SSL tunnel Make our own version of stunnel for simple port forwarding to enable HTTPS and FTP-SSL tests without the stunnel dependency, and it could allow us to provide test tools built with either OpenSSL or GnuTLS -13.2 nicer lacking perl message +17.2 nicer lacking perl message If perl wasn't found by the configure script, don't attempt to run the tests but explain something nice why it doesn't. -13.3 more protocols supported +17.3 more protocols supported Extend the test suite to include more protocols. The telnet could just do ftp or http operations (for which we have test servers). -13.4 more platforms supported +17.4 more platforms supported Make the test suite work on more platforms. OpenBSD and Mac OS. Remove fork()s and it should become even more portable. -14. Next SONAME bump +18. Next SONAME bump -14.1 http-style HEAD output for ftp +18.1 http-style HEAD output for ftp #undef CURL_FTP_HTTPSTYLE_HEAD in lib/ftp.c to remove the HTTP-style headers from being output in NOBODY requests over ftp -14.2 combine error codes +18.2 combine error codes Combine some of the error codes to remove duplicates. The original numbering should not be changed, and the old identifiers would be @@ -488,37 +592,44 @@ to provide the data to send. Candidates for removal and their replacements: CURLE_FILE_COULDNT_READ_FILE => CURLE_REMOTE_FILE_NOT_FOUND + CURLE_FTP_COULDNT_RETR_FILE => CURLE_REMOTE_FILE_NOT_FOUND + CURLE_FTP_COULDNT_USE_REST => CURLE_RANGE_ERROR + CURLE_FUNCTION_NOT_FOUND => CURLE_FAILED_INIT + CURLE_LDAP_INVALID_URL => CURLE_URL_MALFORMAT + CURLE_TFTP_NOSUCHUSER => CURLE_TFTP_ILLEGAL + CURLE_TFTP_NOTFOUND => CURLE_REMOTE_FILE_NOT_FOUND + CURLE_TFTP_PERM => CURLE_REMOTE_ACCESS_DENIED -14.3 extend CURLOPT_SOCKOPTFUNCTION prototype +18.3 extend CURLOPT_SOCKOPTFUNCTION prototype The current prototype only provides 'purpose' that tells what the connection/socket is for, but not any protocol or similar. It makes it hard for applications to differentiate on TCP vs UDP and even HTTP vs FTP and similar. -15. Next major release +10. Next major release -15.1 cleanup return codes +19.1 cleanup return codes curl_easy_cleanup() returns void, but curl_multi_cleanup() returns a CURLMcode. These should be changed to be the same. -15.2 remove obsolete defines +19.2 remove obsolete defines remove obsolete defines from curl/curl.h -15.3 size_t +19.3 size_t make several functions use size_t instead of int in their APIs -15.4 remove several functions +19.4 remove several functions remove the following functions from the public API: @@ -539,18 +650,18 @@ to provide the data to send. curl_multi_socket_all -15.5 remove CURLOPT_FAILONERROR +19.5 remove CURLOPT_FAILONERROR Remove support for CURLOPT_FAILONERROR, it has gotten too kludgy and weird internally. Let the app judge success or not for itself. -15.6 remove CURLOPT_DNS_USE_GLOBAL_CACHE +19.6 remove CURLOPT_DNS_USE_GLOBAL_CACHE Remove support for a global DNS cache. Anything global is silly, and we already offer the share interface for the same functionality but done "right". -15.7 remove progress meter from libcurl +19.7 remove progress meter from libcurl The internally provided progress meter output doesn't belong in the library. Basically no application wants it (apart from curl) but instead applications @@ -559,3 +670,31 @@ to provide the data to send. The progress callback should then be bumped as well to get proper 64bit variable types passed to it instead of doubles so that big files work correctly. + +19.8 remove 'curl_httppost' from public + + curl_formadd() was made to fill in a public struct, but the fact that the + struct is public is never really used by application for their own advantage + but instead often restricts how the form functions can or can't be modified. + + Changing them to return a private handle will benefit the implementation and + allow us much greater freedoms while still maintining a solid API and ABI. + +19.9 have form functions use CURL handle argument + + curl_formadd() and curl_formget() both currently have no CURL handle + argument, but both can use a callback that is set in the easy handle, and + thus curl_formget() with callback cannot function without first having + curl_easy_perform() (or similar) called - which is hard to grasp and a design + mistake. + +19.10 Add CURLOPT_MAIL_CLIENT option + + Rather than use the URL to specify the mail client string to present in the + HELO and EHLO commands, libcurl should support a new CURLOPT specifically for + specifing this data as the URL is non-standard and to be honest a bit of a + hack ;-) + + Please see the following thread for more information: + http://curl.haxx.se/mail/lib-2012-05/0178.html + diff --git a/docs/TheArtOfHttpScripting b/docs/TheArtOfHttpScripting index 183dd17a7..b0dab5ff2 100644 --- a/docs/TheArtOfHttpScripting +++ b/docs/TheArtOfHttpScripting @@ -1,5 +1,5 @@ Online: http://curl.haxx.se/docs/httpscripting.html -Date: May 28, 2008 +Date: Jan 19, 2011 The Art Of Scripting HTTP Requests Using Curl ============================================= @@ -38,10 +38,26 @@ Date: May 28, 2008 request a particular action, and then the server replies a few text lines before the actual requested content is sent to the client. - Using curl's option --verbose (-v as a short option) will display what kind of - commands curl sends to the server, as well as a few other informational texts. - --verbose is the single most useful option when it comes to debug or even - understand the curl<->server interaction. + The client, curl, sends a HTTP request. The request contains a method (like + GET, POST, HEAD etc), a number of request headers and sometimes a request + body. The HTTP server responds with a status line (indicating if things went + well), response headers and most often also a response body. The "body" part + is the plain data you requested, like the actual HTML or the image etc. + + 1.1 See the Protocol + + Using curl's option --verbose (-v as a short option) will display what kind + of commands curl sends to the server, as well as a few other informational + texts. + + --verbose is the single most useful option when it comes to debug or even + understand the curl<->server interaction. + + Sometimes even --verbose is not enough. Then --trace and --trace-ascii offer + even more details as they show EVERYTHING curl sends and receives. Use it + like this: + + curl --trace-ascii debugdump.txt http://www.example.com/ 2. URL @@ -61,10 +77,10 @@ Date: May 28, 2008 you get a web page returned in your terminal window. The entire HTML document that that URL holds. - All HTTP replies contain a set of headers that are normally hidden, use - curl's --include (-i) option to display them as well as the rest of the - document. You can also ask the remote server for ONLY the headers by using the - --head (-I) option (which will make curl issue a HEAD request). + All HTTP replies contain a set of response headers that are normally hidden, + use curl's --include (-i) option to display them as well as the rest of the + document. You can also ask the remote server for ONLY the headers by using + the --head (-I) option (which will make curl issue a HEAD request). 4. Forms @@ -127,7 +143,8 @@ Date: May 28, 2008 And to use curl to post this form with the same data filled in as before, we could do it like: - curl --data "birthyear=1905&press=%20OK%20" http://www.hotmail.com/when/junk.cgi + curl --data "birthyear=1905&press=%20OK%20" \ + http://www.example.com/when.cgi This kind of POST will use the Content-Type application/x-www-form-urlencoded and is the most widely used POST kind. @@ -204,7 +221,7 @@ Date: May 28, 2008 Put a file to a HTTP server with curl: - curl --upload-file uploadfile http://www.uploadhttp.com/receive.cgi + curl --upload-file uploadfile http://www.example.com/receive.cgi 6. HTTP Authentication @@ -217,7 +234,7 @@ Date: May 28, 2008 To tell curl to use a user and password for authentication: - curl --user name:password http://www.secrets.com + curl --user name:password http://www.example.com The site might require a different authentication method (check the headers returned by the server), and then --ntlm, --digest, --negotiate or even @@ -257,7 +274,7 @@ Date: May 28, 2008 Use curl to set the referer field with: - curl --referer http://curl.haxx.se http://daniel.haxx.se + curl --referer http://www.example.come http://www.example.com 8. User Agent @@ -273,13 +290,13 @@ Date: May 28, 2008 is time to set the User Agent field to fool the server into thinking you're one of those browsers. - To make curl look like Internet Explorer on a Windows 2000 box: + To make curl look like Internet Explorer 5 on a Windows 2000 box: - curl --user-agent "Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)" [URL] + curl --user-agent "Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)" [URL] - Or why not look like you're using Netscape 4.73 on a Linux (PIII) box: + Or why not look like you're using Netscape 4.73 on an old Linux box: - curl --user-agent "Mozilla/4.73 [en] (X11; U; Linux 2.2.15 i686)" [URL] + curl --user-agent "Mozilla/4.73 [en] (X11; U; Linux 2.2.15 i686)" [URL] 9. Redirects @@ -294,7 +311,7 @@ Date: May 28, 2008 To tell curl to follow a Location: - curl --location http://www.sitethatredirects.com + curl --location http://www.example.com If you use curl to POST to a site that immediately redirects you to another page, you can safely use --location (-L) and --data/--form together. Curl will @@ -321,13 +338,13 @@ Date: May 28, 2008 The simplest way to send a few cookies to the server when getting a page with curl is to add them on the command line like: - curl --cookie "name=Daniel" http://www.cookiesite.com + curl --cookie "name=Daniel" http://www.example.com Cookies are sent as common HTTP headers. This is practical as it allows curl to record cookies simply by recording headers. Record cookies with curl by using the --dump-header (-D) option like: - curl --dump-header headers_and_cookies http://www.cookiesite.com + curl --dump-header headers_and_cookies http://www.example.com (Take note that the --cookie-jar option described below is a better way to store cookies.) @@ -338,24 +355,25 @@ Date: May 28, 2008 believing you had a previous connection). To use previously stored cookies, you run curl like: - curl --cookie stored_cookies_in_file http://www.cookiesite.com + curl --cookie stored_cookies_in_file http://www.example.com Curl's "cookie engine" gets enabled when you use the --cookie option. If you only want curl to understand received cookies, use --cookie with a file that - doesn't exist. Example, if you want to let curl understand cookies from a page - and follow a location (and thus possibly send back cookies it received), you - can invoke it like: + doesn't exist. Example, if you want to let curl understand cookies from a + page and follow a location (and thus possibly send back cookies it received), + you can invoke it like: - curl --cookie nada --location http://www.cookiesite.com + curl --cookie nada --location http://www.example.com Curl has the ability to read and write cookie files that use the same file format that Netscape and Mozilla do. It is a convenient way to share cookies - between browsers and automatic scripts. The --cookie (-b) switch automatically - detects if a given file is such a cookie file and parses it, and by using the - --cookie-jar (-c) option you'll make curl write a new cookie file at the end of - an operation: + between browsers and automatic scripts. The --cookie (-b) switch + automatically detects if a given file is such a cookie file and parses it, + and by using the --cookie-jar (-c) option you'll make curl write a new cookie + file at the end of an operation: - curl --cookie cookies.txt --cookie-jar newcookies.txt http://www.cookiesite.com + curl --cookie cookies.txt --cookie-jar newcookies.txt \ + http://www.example.com 11. HTTPS @@ -371,7 +389,7 @@ Date: May 28, 2008 Curl supports encrypted fetches thanks to the freely available OpenSSL libraries. To get a page from a HTTPS server, simply run curl like: - curl https://that.secure.server.com + curl https://secure.example.com 11.1 Certificates @@ -382,7 +400,7 @@ Date: May 28, 2008 can be specified on the command line or if not, entered interactively when curl queries for it. Use a certificate with curl on a HTTPS server like: - curl --cert mycert.pem https://that.secure.server.com + curl --cert mycert.pem https://secure.example.com curl also tries to verify that the server is who it claims to be, by verifying the server's certificate against a locally stored CA cert @@ -403,17 +421,18 @@ Date: May 28, 2008 For example, you can change the POST request to a PROPFIND and send the data as "Content-Type: text/xml" (instead of the default Content-Type) like this: - curl --data "<xml>" --header "Content-Type: text/xml" --request PROPFIND url.com + curl --data "<xml>" --header "Content-Type: text/xml" \ + --request PROPFIND url.com You can delete a default header by providing one without content. Like you can ruin the request by chopping off the Host: header: - curl --header "Host:" http://mysite.com + curl --header "Host:" http://www.example.com You can add headers the same way. Your server may want a "Destination:" header, and you can add it: - curl --header "Destination: http://moo.com/nowhere" http://url.com + curl --header "Destination: http://nowhere" http://example.com 13. Web Login @@ -444,7 +463,6 @@ Date: May 28, 2008 to do a proper login POST. Remember that the contents need to be URL encoded when sent in a normal POST. - 14. Debug Many times when you run curl on a site, you'll notice that the site doesn't @@ -480,12 +498,10 @@ Date: May 28, 2008 RFC 2616 is a must to read if you want in-depth understanding of the HTTP protocol. - RFC 2396 explains the URL syntax. + RFC 3986 explains the URL syntax. RFC 2109 defines how cookies are supposed to work. RFC 1867 defines the HTTP post upload format. - http://www.openssl.org is the home of the OpenSSL project - http://curl.haxx.se is the home of the cURL project diff --git a/docs/VERSIONS b/docs/VERSIONS index 21c0d901a..0670089bd 100644 --- a/docs/VERSIONS +++ b/docs/VERSIONS @@ -11,32 +11,25 @@ Version Numbers and Releases The version numbering is always built up using the same system: - X.Y[.Z][-preN] + X.Y[.Z] Where X is main version number Y is release number Z is patch number - N is pre-release number One of these numbers will get bumped in each new release. The numbers to the right of a bumped number will be reset to zero. If Z is zero, it may not be - included in the version number. The pre release number is only included in - pre releases (they're never used in public, official, releases). + included in the version number. The main version number will get bumped when *really* big, world colliding - changes are made. The release number is bumped when big changes are - performed. The patch number is bumped when the changes are mere bugfixes and - only minor feature changes. The pre-release is a counter, to identify which - pre-release a certain release is. - - When reaching the end of a pre-release period, the version without the - pre-release part will be released as a public release. + changes are made. The release number is bumped when changes are performed or + things/features are added. The patch number is bumped when the changes are + mere bugfixes. It means that after release 1.2.3, we can release 2.0 if something really big has been made, 1.3 if not that big changes were made or 1.2.4 if mostly bugs - were fixed. Before 1.2.4 is released, we might release a 1.2.4-pre1 release - for the brave people to try before the actual release. + were fixed. Bumping, as in increasing the number with 1, is unconditionally only affecting one of the numbers (except the ones to the right of it, that may be @@ -56,12 +49,12 @@ Version Numbers and Releases #define LIBCURL_VERSION_NUM 0xXXYYZZ Where XX, YY and ZZ are the main version, release and patch numbers in - hexadecimal. All three numbers are always represented using two digits. 1.2 - would appear as "0x010200" while version 9.11.7 appears as "0x090b07". + hexadecimal. All three number fields are always represented using two digits + (eight bits each). 1.2 would appear as "0x010200" while version 9.11.7 + appears as "0x090b07". - This 6-digit hexadecimal number does not show pre-release number, and it is - always a greater number in a more recent release. It makes comparisons with - greater than and less than work. + This 6-digit hexadecimal number is always a greater number in a more recent + release. It makes comparisons with greater than and less than work. This number is also available as three separate defines: LIBCURL_VERSION_MAJOR, LIBCURL_VERSION_MINOR and LIBCURL_VERSION_PATCH. diff --git a/docs/curl-config.1 b/docs/curl-config.1 index c4f4e2b12..14a9d2ba8 100644 --- a/docs/curl-config.1 +++ b/docs/curl-config.1 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -93,7 +93,6 @@ What's the installed libcurl version? How do I build a single file with a one-line command? - $ `curl-config --cc --cflags --libs` -o example example.c - + $ `curl-config --cc --cflags` -o example example.c `curl-config --libs` .SH "SEE ALSO" .BR curl (1) diff --git a/docs/curl-config.html b/docs/curl-config.html index 3f49388c5..1563d548b 100644 --- a/docs/curl-config.html +++ b/docs/curl-config.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl-config man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -83,8 +85,7 @@ p.roffit { <p class="level0">What's the installed libcurl version? <p class="level0"> $ curl-config --version <p class="level0">How do I build a single file with a one-line command? -<p class="level0"> $ `curl-config --cc --cflags --libs` -o example example.c -<p class="level0"><a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> +<p class="level0"> $ `curl-config --cc --cflags` -o example example.c `curl-config --libs` <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><span Class="manpage">curl (1)</span> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/curl-config.pdf b/docs/curl-config.pdf Binary files differindex e159a94b4..429812f14 100644 --- a/docs/curl-config.pdf +++ b/docs/curl-config.pdf diff --git a/docs/curl.1 b/docs/curl.1 index 95614c6e4..9e1a6883b 100644 --- a/docs/curl.1 +++ b/docs/curl.1 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH curl 1 "28 November 2009" "Curl 7.20.0" "Curl Manual" +.TH curl 1 "27 July 2012" "Curl 7.27.0" "Curl Manual" .SH NAME curl \- transfer a URL .SH SYNOPSIS @@ -35,8 +35,8 @@ command is designed to work without user interaction. curl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer -resume and more. As you will see below, the number of features will make your -head spin! +resume, Metalink, and more. As you will see below, the number of features will +make your head spin! curl is powered by libcurl for all transfer-related features. See .BR libcurl (3) @@ -79,14 +79,14 @@ curl will do its best to use what you pass to it as a URL. It is not trying to validate it as a syntactically correct URL by any means but is instead \fBvery\fP liberal with what it accepts. -Curl will attempt to re-use connections for multiple file transfers, so that +curl will attempt to re-use connections for multiple file transfers, so that getting many files from the same server will not do multiple connects / handshakes. This improves speed. Of course this is only done on files specified on a single command line and cannot be used between separate curl invokes. .SH "PROGRESS METER" -curl normally displays a progress meter during operations, indicating the amount -of transferred data, transfer speeds and estimated time left, etc. +curl normally displays a progress meter during operations, indicating the +amount of transferred data, transfer speeds and estimated time left, etc. curl displays this data to the terminal by default, so if you invoke curl to do an operation and it is about to write data to the terminal, it @@ -103,24 +103,46 @@ any response data to the terminal. If you prefer a progress "bar" instead of the regular meter, \fI-#\fP is your friend. .SH OPTIONS -In general, all boolean options are enabled with --option and yet again +In general, all boolean options are enabled with --\fBoption\fP and yet again disabled with --\fBno-\fPoption. That is, you use the exact same option name but prefix it with "no-". However, in this list we mostly only list and show the --option version of them. (This concept with --no options was added in 7.19.0. Previously most options were toggled on/off on repeated use of the same command line option.) -.IP "-a/--append" +.IP "-#, --progress-bar" +Make curl display progress as a simple progress bar instead of the standard, +more informational, meter. +.IP "-0, --http1.0" +(HTTP) Forces curl to issue its requests using HTTP 1.0 instead of using its +internally preferred: HTTP 1.1. +.IP "-1, --tlsv1" +(SSL) +Forces curl to use TLS version 1 when negotiating with a remote TLS server. +.IP "-2, --sslv2" +(SSL) +Forces curl to use SSL version 2 when negotiating with a remote SSL server. +.IP "-3, --sslv3" +(SSL) +Forces curl to use SSL version 3 when negotiating with a remote SSL server. +.IP "-4, --ipv4" +If curl is capable of resolving an address to multiple IP versions (which it +is if it is IPv6-capable), this option tells curl to resolve names to IPv4 +addresses only. +.IP "-6, --ipv6" +If curl is capable of resolving an address to multiple IP versions (which it +is if it is IPv6-capable), this option tells curl to resolve names to IPv6 +addresses only. +.IP "-a, --append" (FTP/SFTP) When used in an upload, this will tell curl to append to the target file instead of overwriting it. If the file doesn't exist, it will be created. Note that this flag is ignored by some SSH servers (including OpenSSH). -.IP "-A/--user-agent <agent string>" +.IP "-A, --user-agent <agent string>" (HTTP) Specify the User-Agent string to send to the HTTP server. Some badly done CGIs fail if this field isn't set to "Mozilla/4.0". To encode blanks in the string, surround the string with single quote marks. This can also be set -with the \fI-H/--header\fP option of course. +with the \fI-H, --header\fP option of course. -If this option is set more than once, the last one will be the one that's -used. +If this option is used several times, the last one will be used. .IP "--anyauth" (HTTP) Tells curl to figure out authentication method by itself, and use the most secure one the remote site claims to support. This is done by first @@ -133,7 +155,7 @@ Note that using --anyauth is not recommended if you do uploads from stdin, since it may require data to be sent twice and then the client must be able to rewind. If the need should arise when uploading from stdin, the upload operation will fail. -.IP "-b/--cookie <name=data>" +.IP "-b, --cookie <name=data>" (HTTP) Pass the data to the HTTP server as a cookie. It is supposedly the data previously received from the server in a "Set-Cookie:" line. @@ -143,19 +165,18 @@ If no '=' symbol is used in the line, it is treated as a filename to use to read previously stored cookie lines from, which should be used in this session if they match. Using this method also activates the "cookie parser" which will make curl record incoming cookies too, which may be handy if you're using this -in combination with the \fI-L/--location\fP option. The file format of the +in combination with the \fI-L, --location\fP option. The file format of the file to read cookies from should be plain HTTP headers or the Netscape/Mozilla cookie file format. -\fBNOTE\fP that the file specified with \fI-b/--cookie\fP is only used as +\fBNOTE\fP that the file specified with \fI-b, --cookie\fP is only used as input. No cookies will be stored in the file. To store cookies, use the -\fI-c/--cookie-jar\fP option or you could even save the HTTP headers to a file -using \fI-D/--dump-header\fP! +\fI-c, --cookie-jar\fP option or you could even save the HTTP headers to a file +using \fI-D, --dump-header\fP! -If this option is set more than once, the last one will be the one that's -used. -.IP "-B/--use-ascii" -Enable ASCII transfer when using FTP or LDAP. For FTP, this can also be +If this option is used several times, the last one will be used. +.IP "-B, --use-ascii" +(FTP/LDAP) Enable ASCII transfer. For FTP, this can also be enforced by using an URL that ends with ";type=A". This option causes data sent to stdout to be in text mode for win32 systems. .IP "--basic" @@ -163,35 +184,18 @@ sent to stdout to be in text mode for win32 systems. this option is usually pointless, unless you use it to override a previously set option that sets a different authentication method (such as \fI--ntlm\fP, \fI--digest\fP, or \fI--negotiate\fP). -.IP "--ciphers <list of ciphers>" -(SSL) Specifies which ciphers to use in the connection. The list of ciphers -must specify valid ciphers. Read up on SSL cipher list details on this URL: -\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP - -NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of -NSS ciphers is in the NSSCipherSuite entry at this URL: -\fIhttp://directory.fedora.redhat.com/docs/mod_nss.html#Directives\fP - -If this option is used several times, the last one will override the others. -.IP "--compressed" -(HTTP) Request a compressed response using one of the algorithms libcurl -supports, and return the uncompressed document. If this option is used and -the server sends an unsupported encoding, curl will report an error. -.IP "--connect-timeout <seconds>" -Maximum time in seconds that you allow the connection to the server to take. -This only limits the connection phase, once curl has connected this option is -of no more use. See also the \fI-m/--max-time\fP option. +.IP "-c, --cookie-jar <file name>" +(HTTP) Specify to which file you want curl to write all cookies after a +completed operation. Curl writes all cookies previously read from a specified +file as well as all cookies received from remote server(s). If no cookies are +known, no file will be written. The file will be written using the Netscape +cookie file format. If you set the file name to a single dash, "-", the +cookies will be written to stdout. + +This command line option will activate the cookie engine that makes curl +record and use cookies. Another way to activate it is to use the \fI-b, +--cookie\fP option. -If this option is used several times, the last one will be used. -.IP "-c/--cookie-jar <file name>" -Specify to which file you want curl to write all cookies after a completed -operation. Curl writes all cookies previously read from a specified file as -well as all cookies received from remote server(s). If no cookies are known, -no file will be written. The file will be written using the Netscape cookie -file format. If you set the file name to a single dash, "-", the cookies will -be written to stdout. - -.B NOTE If the cookie jar can't be created or written to, the whole curl operation won't fail or even report an error clearly. Using -v will get a warning displayed, but that is the only visible feedback you get about this possibly @@ -199,7 +203,7 @@ lethal situation. If this option is used several times, the last specified file name will be used. -.IP "-C/--continue-at <offset>" +.IP "-C, --continue-at <offset>" Continue/Resume a previous file transfer at the given offset. The given offset is the exact number of bytes that will be skipped, counting from the beginning of the source file before it is transferred to the destination. If used with @@ -209,11 +213,33 @@ Use "-C -" to tell curl to automatically find out where/how to resume the transfer. It then uses the given output/input files to figure that out. If this option is used several times, the last one will be used. +.IP "--ciphers <list of ciphers>" +(SSL) Specifies which ciphers to use in the connection. The list of ciphers +must specify valid ciphers. Read up on SSL cipher list details on this URL: +\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP + +NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS +ciphers is in the NSSCipherSuite entry at this URL: +\fIhttp://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives\fP + +If this option is used several times, the last one will be used. +.IP "--compressed" +(HTTP) Request a compressed response using one of the algorithms curl +supports, and save the uncompressed document. If this option is used and the +server sends an unsupported encoding, curl will report an error. +.IP "--connect-timeout <seconds>" +Maximum time in seconds that you allow the connection to the server to take. +This only limits the connection phase, once curl has connected this option is +of no more use. Since 7.32.0, this option accepts decimal values, but the +actual timeout will decrease in accuracy as the specified timeout increases in +decimal precision. See also the \fI-m, --max-time\fP option. + +If this option is used several times, the last one will be used. .IP "--create-dirs" -When used in conjunction with the -o option, curl will create the necessary -local directory hierarchy as needed. This option creates the dirs mentioned -with the -o option, nothing else. If the -o file name uses no dir or if the -dirs it mentions already exist, no dir will be created. +When used in conjunction with the \fI-o\fP option, curl will create the +necessary local directory hierarchy as needed. This option creates the dirs +mentioned with the \fI-o\fP option, nothing else. If the \fI-o\fP file name +uses no dir or if the dirs it mentions already exist, no dir will be created. To create remote directories when using FTP or SFTP, try \fI--ftp-create-dirs\fP. @@ -226,14 +252,14 @@ List that may specify peer certificates that are to be considered revoked. If this option is used several times, the last one will be used. (Added in 7.19.7) -.IP "-d/--data <data>" +.IP "-d, --data <data>" (HTTP) Sends the specified data in a POST request to the HTTP server, in the same way that a browser does when a user has filled in an HTML form and presses the submit button. This will cause curl to pass the data to the server using the content-type application/x-www-form-urlencoded. Compare to -\fI-F/--form\fP. +\fI-F, --form\fP. -\fI-d/--data\fP is the same as \fI--data-ascii\fP. To post data purely binary, +\fI-d, --data\fP is the same as \fI--data-ascii\fP. To post data purely binary, you should instead use the \fI--data-binary\fP option. To URL-encode the value of a form field you may use \fI--data-urlencode\fP. @@ -247,6 +273,21 @@ read the data from, or - if you want curl to read the data from stdin. The contents of the file must already be URL-encoded. Multiple files can also be specified. Posting data from a file named 'foobar' would thus be done with \fI--data @foobar\fP. +.IP "-D, --dump-header <file>" +Write the protocol headers to the specified file. + +This option is handy to use when you want to store the headers that an HTTP +site sends to you. Cookies from the headers could then be read in a second +curl invocation by using the \fI-b, --cookie\fP option! The +\fI-c, --cookie-jar\fP option is however a better way to store cookies. + +When used in FTP, the FTP server response lines are considered being "headers" +and thus are saved there. + +If this option is used several times, the last one will be used. + +.IP "--data-ascii <data>" +See \fI-d, --data\fP. .IP "--data-binary <data>" (HTTP) This posts data exactly as specified with no extra processing whatsoever. @@ -256,7 +297,7 @@ is posted in a similar manner as \fI--data-ascii\fP does, except that newlines are preserved and conversions are never done. If this option is used several times, the ones following the first will append -data as described in \fI-d/--data\fP. +data as described in \fI-d, --data\fP. .IP "--data-urlencode <data>" (HTTP) This posts data, similar to the other --data options with the exception that this performs URL-encoding. (Added in 7.18.0) @@ -284,87 +325,95 @@ URL-encode that data and pass it on in the POST. The name part gets an equal sign appended, resulting in \fIname=urlencoded-file-content\fP. Note that the name is expected to be URL-encoded already. .RE +.IP "--delegation LEVEL" +Set \fILEVEL\fP to tell the server what it is allowed to delegate when it +comes to user credentials. Used with GSS/kerberos. +.RS +.IP "none" +Don't allow any delegation. +.IP "policy" +Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos +service ticket, which is a matter of realm policy. +.IP "always" +Unconditionally allow the server to delegate. +.RE .IP "--digest" -(HTTP) Enables HTTP Digest authentication. This is a authentication that -prevents the password from being sent over the wire in clear text. Use this in -combination with the normal \fI-u/--user\fP option to set user name and -password. See also \fI--ntlm\fP, \fI--negotiate\fP and \fI--anyauth\fP for +(HTTP) Enables HTTP Digest authentication. This is an authentication scheme +that prevents the password from being sent over the wire in clear text. Use +this in combination with the normal \fI-u, --user\fP option to set user name +and password. See also \fI--ntlm\fP, \fI--negotiate\fP and \fI--anyauth\fP for related options. -If this option is used several times, the following occurrences make no -difference. +If this option is used several times, only the first one is used. .IP "--disable-eprt" (FTP) Tell curl to disable the use of the EPRT and LPRT commands when doing active FTP transfers. Curl will normally always first attempt to use EPRT, then LPRT before using PORT, but with this option, it will use PORT right -away. EPRT and LPRT are extensions to the original FTP protocol, and may not work -on all servers, but they enable more functionality in a better way than the -traditional PORT command. +away. EPRT and LPRT are extensions to the original FTP protocol, and may not +work on all servers, but they enable more functionality in a better way than +the traditional PORT command. \fB--eprt\fP can be used to explicitly enable EPRT again and \fB--no-eprt\fP is an alias for \fB--disable-eprt\fP. Disabling EPRT only changes the active behavior. If you want to switch to -passive mode you need to not use \fI-P/--ftp-port\fP or force it with +passive mode you need to not use \fI-P, --ftp-port\fP or force it with \fI--ftp-pasv\fP. .IP "--disable-epsv" (FTP) Tell curl to disable the use of the EPSV command when doing passive FTP transfers. Curl will normally always first attempt to use EPSV before PASV, but with this option, it will not try using EPSV. -\fB--epsv\fP can be used to explicitly enable EPRT again and \fB--no-epsv\fP +\fB--epsv\fP can be used to explicitly enable EPSV again and \fB--no-epsv\fP is an alias for \fB--disable-epsv\fP. Disabling EPSV only changes the passive behavior. If you want to switch to -active mode you need to use \fI-P/--ftp-port\fP. -.IP "-D/--dump-header <file>" -Write the protocol headers to the specified file. - -This option is handy to use when you want to store the headers that a HTTP -site sends to you. Cookies from the headers could then be read in a second -curl invocation by using the \fI-b/--cookie\fP option! The \fI-c/--cookie-jar\fP -option is however a better way to store cookies. - -When used in FTP, the FTP server response lines are considered being "headers" -and thus are saved there. - -If this option is used several times, the last one will be used. -.IP "-e/--referer <URL>" +active mode you need to use \fI-P, --ftp-port\fP. +.IP "-e, --referer <URL>" (HTTP) Sends the "Referer Page" information to the HTTP server. This can also -be set with the \fI-H/--header\fP flag of course. When used with -\fI-L/--location\fP you can append ";auto" to the --referer URL to make curl +be set with the \fI-H, --header\fP flag of course. When used with +\fI-L, --location\fP you can append ";auto" to the --referer URL to make curl automatically set the previous URL when it follows a Location: header. The \&";auto" string can be used alone, even if you don't set an initial --referer. If this option is used several times, the last one will be used. +.IP "-E, --cert <certificate[:password]>" +(SSL) Tells curl to use the specified client certificate file when getting a +file with HTTPS, FTPS or another SSL-based protocol. The certificate must be +in PEM format. If the optional password isn't specified, it will be queried +for on the terminal. Note that this option assumes a \&"certificate" file that +is the private key and the private certificate concatenated! See \fI--cert\fP +and \fI--key\fP to specify them independently. + +If curl is built against the NSS SSL library then this option can tell +curl the nickname of the certificate to use within the NSS database defined +by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the +NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be +loaded. If you want to use a file from the current directory, please precede +it with "./" prefix, in order to avoid confusion with a nickname. If the +nickname contains ":", it needs to be preceded by "\\" so that it is not +recognized as password delimiter. If the nickname contains "\\", it needs to +be escaped as "\\\\" so that it is not recognized as an escape character. + +(iOS and Mac OS X only) If curl is built against Secure Transport, then the +certificate string must match the name of a certificate that's in the system or +user keychain. The private key corresponding to the certificate, and +certificate chain (if any), must also be present in the keychain. + +If this option is used several times, the last one will be used. .IP "--engine <name>" Select the OpenSSL crypto engine to use for cipher operations. Use \fI--engine list\fP to print a list of build-time supported engines. Note that not all (or none) of the engines may be available at run-time. .IP "--environment" -(RISC OS ONLY) Sets a range of environment variables, using the names the -w -option supports, to allow easier extraction of useful information after having -run curl. +(RISC OS ONLY) Sets a range of environment variables, using the names the +\fI-w\fP option supports, to allow easier extraction of useful information +after having run curl. .IP "--egd-file <file>" (SSL) Specify the path name to the Entropy Gathering Daemon socket. The socket is used to seed the random engine for SSL connections. See also the \fI--random-file\fP option. -.IP "-E/--cert <certificate[:password]>" -(SSL) Tells curl to use the specified certificate file when getting a file -with HTTPS or FTPS. The certificate must be in PEM format. If the optional -password isn't specified, it will be queried for on the terminal. Note that -this option assumes a \&"certificate" file that is the private key and the -private certificate concatenated! See \fI--cert\fP and \fI--key\fP to specify -them independently. - -If curl is built against the NSS SSL library then this option tells -curl the nickname of the certificate to use within the NSS database defined -by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the -NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be -loaded. - -If this option is used several times, the last one will be used. .IP "--cert-type <type>" (SSL) Tells curl what certificate type the provided certificate is in. PEM, DER and ENG are recognized types. If not specified, PEM is assumed. @@ -384,50 +433,101 @@ The windows version of curl will automatically look for a CA certs file named \'curl-ca-bundle.crt\', either in the same directory as curl.exe, or in the Current Working Directory, or in any folder along your PATH. -If curl is built against the NSS SSL library then this option tells -curl the nickname of the CA certificate to use within the NSS database -defined by the environment variable SSL_DIR (or by default /etc/pki/nssdb). -If the NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files -may be loaded. +If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module +(libnsspem.so) needs to be available for this option to work properly. If this option is used several times, the last one will be used. .IP "--capath <CA certificate directory>" (SSL) Tells curl to use the specified certificate directory to verify the -peer. The certificates must be in PEM format, and the directory must have been -processed using the c_rehash utility supplied with openssl. Using -\fI--capath\fP can allow curl to make SSL-connections much more efficiently -than using \fI--cacert\fP if the \fI--cacert\fP file contains many CA -certificates. - -If this option is used several times, the last one will be used. -.IP "-f/--fail" +peer. Multiple paths can be provided by separating them with ":" (e.g. +\&"path1:path2:path3"). The certificates must be in PEM format, and if curl is +built against OpenSSL, the directory must have been processed using the +c_rehash utility supplied with OpenSSL. Using \fI--capath\fP can allow +OpenSSL-powered curl to make SSL-connections much more efficiently than using +\fI--cacert\fP if the \fI--cacert\fP file contains many CA certificates. + +If this option is set, the default capath value will be ignored, and if it is +used several times, the last one will be used. +.IP "-f, --fail" (HTTP) Fail silently (no output at all) on server errors. This is mostly done to better enable scripts etc to better deal with failed attempts. In -normal cases when a HTTP server fails to deliver a document, it returns an +normal cases when an HTTP server fails to deliver a document, it returns an HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and return error 22. This method is not fail-safe and there are occasions where non-successful response codes will slip through, especially when authentication is involved (response codes 401 and 407). +.IP "-F, --form <name=content>" +(HTTP) This lets curl emulate a filled-in form in which a user has pressed the +submit button. This causes curl to POST data using the Content-Type +multipart/form-data according to RFC 2388. This enables uploading of binary +files etc. To force the 'content' part to be a file, prefix the file name +with an @ sign. To just get the content part from a file, prefix the file name +with the symbol <. The difference between @ and < is then that @ makes a file +get attached in the post as a file upload, while the < makes a text field and +just get the contents for that text field from a file. + +Example, to send your password file to the server, where +\&'password' is the name of the form-field to which /etc/passwd will be the +input: + +\fBcurl\fP -F password=@/etc/passwd www.mypasswords.com + +To read content from stdin instead of a file, use - as the filename. This goes +for both @ and < constructs. + +You can also tell curl what Content-Type to use by using 'type=', in a manner +similar to: + +\fBcurl\fP -F "web=@index.html;type=text/html" url.com + +or + +\fBcurl\fP -F "name=daniel;type=text/foo" url.com + +You can also explicitly change the name field of a file upload part by setting +filename=, like this: + +\fBcurl\fP -F "file=@localfile;filename=nameinpost" url.com + +If filename/path contains ',' or ';', it must be quoted by double-quotes like: + +\fBcurl\fP -F "file=@\\"localfile\\";filename=\\"nameinpost\\"" url.com + +or + +\fBcurl\fP -F 'file=@"localfile";filename="nameinpost"' url.com + +Note that if a filename/path is quoted by double-quotes, any double-quote +or backslash within the filename must be escaped by backslash. + +See further examples and details in the MANUAL. + +This option can be used multiple times. .IP "--ftp-account [data]" (FTP) When an FTP server asks for "account data" after user name and password has been provided, this data is sent off using the ACCT command. (Added in 7.13.0) -If this option is used twice, the second will override the previous use. +If this option is used several times, the last one will be used. +.IP "--ftp-alternative-to-user <command>" +(FTP) If authenticating with the USER and PASS commands fails, send this +command. When connecting to Tumbleweed's Secure Transport server over FTPS +using a client certificate, using "SITE AUTH" will tell the server to retrieve +the username from the certificate. (Added in 7.15.5) .IP "--ftp-create-dirs" (FTP/SFTP) When an FTP or SFTP URL/operation uses a path that doesn't currently exist on the server, the standard behavior of curl is to fail. Using this option, curl will instead attempt to create missing directories. .IP "--ftp-method [method]" -(FTP) Control what method curl should use to reach a file on a FTP(S) +(FTP) Control what method curl should use to reach a file on an FTP(S) server. The method argument should be one of the following alternatives: .RS .IP multicwd curl does a single CWD operation for each path part in the given URL. For deep -hierarchies this means very many commands. This is how RFC1738 says it should +hierarchies this means very many commands. This is how RFC 1738 says it should be done. This is the default but the slowest behavior. .IP nocwd curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full @@ -439,21 +539,16 @@ compliant than 'nocwd' but without the full penalty of 'multicwd'. .RE (Added in 7.15.1) .IP "--ftp-pasv" -(FTP) Use passive mode for the data conection. Passive is the internal default +(FTP) Use passive mode for the data connection. Passive is the internal default behavior, but using this option can be used to override a previous \fI-P/-ftp-port\fP option. (Added in 7.11.0) -If this option is used several times, the following occurrences make no -difference. Undoing an enforced passive really isn't doable but you must then -instead enforce the correct \fI-P/--ftp-port\fP again. +If this option is used several times, only the first one is used. Undoing an +enforced passive really isn't doable but you must then instead enforce the +correct \fI-P, --ftp-port\fP again. Passive mode means that curl will try the EPSV command first and then PASV, unless \fI--disable-epsv\fP is used. -.IP "--ftp-alternative-to-user <command>" -(FTP) If authenticating with the USER and PASS commands fails, send this -command. When connecting to Tumbleweed's Secure Transport server over FTPS -using a client certificate, using "SITE AUTH" will tell the server to retrieve -the username from the certificate. (Added in 7.15.5) .IP "--ftp-skip-pasv-ip" (FTP) Tell curl to not use the IP address the server suggests in its response to curl's PASV command when curl connects the data connection. Instead curl @@ -466,30 +561,12 @@ This option has no effect if PORT, EPRT or EPSV is used instead of PASV. FTP servers, mainly drftpd, require this non-standard command for directory listings as well as up and downloads in PASV mode. (Added in 7.20.x) -.IP "--ssl" -(FTP, POP3, IMAP, SMTP) Try to use SSL/TLS for the connection. Reverts to a -non-secure connection if the server doesn't support SSL/TLS. See also -\fI--ftp-ssl-control\fP and \fI--ssl-reqd\fP for different levels of -encryption required. (Added in 7.20.0) - -This option was formerly known as \fI--ftp-ssl\fP (Added in 7.11.0) and that -can still be used but will be removed in a future version. -.IP "--ftp-ssl-control" -(FTP) Require SSL/TLS for the FTP login, clear for transfer. Allows secure -authentication, but non-encrypted data transfers for efficiency. Fails the -transfer if the server doesn't support SSL/TLS. (Added in 7.16.0) -.IP "--ssl-reqd" -(FTP, POP3, IMAP, SMTP) Require SSL/TLS for the connection. Terminates the -connection if the server doesn't support SSL/TLS. (Added in 7.20.0) - -This option was formerly known as \fI--ftp-ssl-reqd\fP (added in 7.15.5) and -that can still be used but will be removed in a future version. .IP "--ftp-ssl-ccc" (FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after authenticating. The rest of the control channel communication will be unencrypted. This allows NAT routers to follow the FTP transaction. The default mode is -passive. See --ftp-ssl-ccc-mode for other modes. +passive. See \fI--ftp-ssl-ccc-mode\fP for other modes. (Added in 7.16.1) .IP "--ftp-ssl-ccc-mode [active/passive]" (FTP) Use CCC (Clear Command Channel) @@ -498,68 +575,35 @@ instead wait for the server to do it, and will not reply to the shutdown from the server. The active mode initiates the shutdown and waits for a reply from the server. (Added in 7.16.2) -.IP "-F/--form <name=content>" -(HTTP) This lets curl emulate a filled-in form in which a user has pressed the -submit button. This causes curl to POST data using the Content-Type -multipart/form-data according to RFC2388. This enables uploading of binary -files etc. To force the 'content' part to be a file, prefix the file name -with an @ sign. To just get the content part from a file, prefix the file name -with the symbol <. The difference between @ and < is then that @ makes a file -get attached in the post as a file upload, while the < makes a text field and -just get the contents for that text field from a file. - -Example, to send your password file to the server, where -\&'password' is the name of the form-field to which /etc/passwd will be the -input: - -\fBcurl\fP -F password=@/etc/passwd www.mypasswords.com - -To read the file's content from stdin instead of a file, use - where the file -name should've been. This goes for both @ and < constructs. - -You can also tell curl what Content-Type to use by using 'type=', in a manner -similar to: - -\fBcurl\fP -F "web=@index.html;type=text/html" url.com - -or - -\fBcurl\fP -F "name=daniel;type=text/foo" url.com - -You can also explicitly change the name field of a file upload part by setting -filename=, like this: - -\fBcurl\fP -F "file=@localfile;filename=nameinpost" url.com - -See further examples and details in the MANUAL. - -This option can be used multiple times. +.IP "--ftp-ssl-control" +(FTP) Require SSL/TLS for the FTP login, clear for transfer. Allows secure +authentication, but non-encrypted data transfers for efficiency. Fails the +transfer if the server doesn't support SSL/TLS. (Added in 7.16.0) +that can still be used but will be removed in a future version. .IP "--form-string <name=string>" (HTTP) Similar to \fI--form\fP except that the value string for the named parameter is used literally. Leading \&'@' and \&'<' characters, and the \&';type=' string in the value have no special meaning. Use this in preference to \fI--form\fP if there's any possibility that the string value may accidentally trigger the \&'@' or \&'<' features of \fI--form\fP. -.IP "-g/--globoff" +.IP "-g, --globoff" This option switches off the "URL globbing parser". When you set this option, you can specify URLs that contain the letters {}[] without having them being interpreted by curl itself. Note that these letters are not normal legal URL contents but they should be encoded according to the URI standard. -.IP "-G/--get" -When used, this option will make all data specified with \fI-d/--data\fP or -\fI--data-binary\fP to be used in a HTTP GET request instead of the POST +.IP "-G, --get" +When used, this option will make all data specified with \fI-d, --data\fP or +\fI--data-binary\fP to be used in an HTTP GET request instead of the POST request that otherwise would be used. The data will be appended to the URL with a '?' separator. If used in combination with -I, the POST data will instead be appended to the URL with a HEAD request. -If this option is used several times, the following occurrences make no -difference. This is because undoing a GET doesn't make sense, but you should -then instead enforce the alternative method you prefer. -.IP "-h/--help" -Usage help. -.IP "-H/--header <header>" +If this option is used several times, only the first one is used. This is +because undoing a GET doesn't make sense, but you should then instead enforce +the alternative method you prefer. +.IP "-H, --header <header>" (HTTP) Extra header to use when getting a web page. You may specify any number of extra headers. Note that if you should add a custom header that has the same name as one of the internal ones curl would use, your externally set @@ -567,29 +611,36 @@ header will be used instead of the internal one. This allows you to make even trickier stuff than curl would normally do. You should not replace internally set headers without knowing perfectly well what you're doing. Remove an internal header by giving a replacement without content on the right side of -the colon, as in: -H \&"Host:". +the colon, as in: -H \&"Host:". If you send the custom header with no-value +then its header must be terminated with a semicolon, such as \-H +\&"X-Custom-Header;" to send "X-Custom-Header:". curl will make sure that each header you add/replace is sent with the proper end-of-line marker, you should thus \fBnot\fP add that as a part of the header content: do not add newlines or carriage returns, they will only mess things up for you. -See also the \fI-A/--user-agent\fP and \fI-e/--referer\fP options. +See also the \fI-A, --user-agent\fP and \fI-e, --referer\fP options. This option can be used multiple times to add/replace/remove multiple headers. .IP "--hostpubmd5 <md5>" -Pass a string containing 32 hexadecimal digits. The string should be the 128 -bit MD5 checksum of the remote host's public key, curl will refuse the -connection with the host unless the md5sums match. This option is only for SCP -and SFTP transfers. (Added in 7.17.1) +(SCP/SFTP) Pass a string containing 32 hexadecimal digits. The string should +be the 128 bit MD5 checksum of the remote host's public key, curl will refuse +the connection with the host unless the md5sums match. (Added in 7.17.1) .IP "--ignore-content-length" (HTTP) Ignore the Content-Length header. This is particularly useful for servers running Apache 1.x, which will report incorrect Content-Length for files larger than 2 gigabytes. -.IP "-i/--include" +.IP "-i, --include" (HTTP) Include the HTTP-header in the output. The HTTP-header includes things like server-name, date of the document, HTTP-version and more... +.IP "-I, --head" +(HTTP/FTP/FILE) +Fetch the HTTP-header only! HTTP-servers feature the command HEAD +which this uses to get nothing but the header of a document. When used +on an FTP or FILE file, curl displays the file size and last modification +time only. .IP "--interface <name>" Perform an operation using a specified interface. You can enter interface name, IP address or host name. An example could look like: @@ -597,58 +648,24 @@ name, IP address or host name. An example could look like: curl --interface eth0:1 http://www.netscape.com/ If this option is used several times, the last one will be used. -.IP "-I/--head" -(HTTP/FTP/FILE) -Fetch the HTTP-header only! HTTP-servers feature the command HEAD -which this uses to get nothing but the header of a document. When used -on a FTP or FILE file, curl displays the file size and last modification -time only. -.IP "-j/--junk-session-cookies" +.IP "-j, --junk-session-cookies" (HTTP) When curl is told to read cookies from a given file, this option will make it discard all "session cookies". This will basically have the same effect as if a new session is started. Typical browsers always discard session cookies when they're closed down. -.IP "-J/--remote-header-name" -(HTTP) This option tells the -O/--remote-name option to use the server-specified -Content-Disposition filename instead of extracting a filename from the URL. -.IP "-k/--insecure" +.IP "-J, --remote-header-name" +(HTTP) This option tells the \fI-O, --remote-name\fP option to use the +server-specified Content-Disposition filename instead of extracting a filename +from the URL. +.IP "-k, --insecure" (SSL) This option explicitly allows curl to perform "insecure" SSL connections and transfers. All SSL connections are attempted to be made secure by using the CA certificate bundle installed by default. This makes all connections -considered "insecure" fail unless \fI-k/--insecure\fP is used. +considered "insecure" fail unless \fI-k, --insecure\fP is used. See this online resource for further details: \fBhttp://curl.haxx.se/docs/sslcerts.html\fP -.IP "--keepalive-time <seconds>" -This option sets the time a connection needs to remain idle before sending -keepalive probes and the time between individual keepalive probes. It is -currently effective on operating systems offering the TCP_KEEPIDLE and -TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more). This -option has no effect if \fI--no-keepalive\fP is used. (Added in 7.18.0) - -If this option is used multiple times, the last occurrence sets the amount. -.IP "--key <key>" -(SSL/SSH) Private key file name. Allows you to provide your private key in this -separate file. - -If this option is used several times, the last one will be used. -.IP "--key-type <type>" -(SSL) Private key file type. Specify which type your \fI--key\fP provided -private key is. DER, PEM, and ENG are supported. If not specified, PEM is -assumed. - -If this option is used several times, the last one will be used. -.IP "--krb <level>" -(FTP) Enable Kerberos authentication and use. The level must be entered and -should be one of 'clear', 'safe', 'confidential', or 'private'. Should you use -a level that is not one of these, 'private' will instead be used. - -This option requires a library built with kerberos4 or GSSAPI -(GSS-Negotiate) support. This is not very common. Use \fI-V/--version\fP to -see if your curl supports it. - -If this option is used several times, the last one will be used. -.IP "-K/--config <config file>" +.IP "-K, --config <config file>" Specify which config file to read curl arguments from. The config file is a text file in which command line arguments can be written which then will be used as if they were written on the actual command line. Options and their @@ -662,7 +679,7 @@ first column of a config line is a '#' character, the rest of the line will be treated as a comment. Only write one option per physical line in the config file. -Specify the filename to -K/--config as '-' to make curl read the file from +Specify the filename to -K, --config as '-' to make curl read the file from stdin. Note that to be able to specify a URL in the config file, you need to specify @@ -703,36 +720,37 @@ referer = "http://nowhereatall.com/" .fi This option can be used multiple times to load multiple config files. -.IP "--libcurl <file>" -Append this option to any ordinary curl command line, and you will get a -libcurl-using source code written to the file that does the equivalent -of what your command-line operation does! - -NOTE: this does not properly support -F and the sending of multipart -formposts, so in those cases the output program will be missing necessary -calls to \fIcurl_formadd(3)\fP, and possibly more. +.IP "--keepalive-time <seconds>" +This option sets the time a connection needs to remain idle before sending +keepalive probes and the time between individual keepalive probes. It is +currently effective on operating systems offering the TCP_KEEPIDLE and +TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more). This +option has no effect if \fI--no-keepalive\fP is used. (Added in 7.18.0) -If this option is used several times, the last given file name will be -used. (Added in 7.16.1) -.IP "--limit-rate <speed>" -Specify the maximum transfer rate you want curl to use. This feature is useful -if you have a limited pipe and you'd like your transfer not to use your entire -bandwidth. +If this option is used several times, the last one will be used. If +unspecified, the option defaults to 60 seconds. +.IP "--key <key>" +(SSL/SSH) Private key file name. Allows you to provide your private key in this +separate file. -The given speed is measured in bytes/second, unless a suffix is appended. -Appending 'k' or 'K' will count the number as kilobytes, 'm' or M' makes it -megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G. +If this option is used several times, the last one will be used. +.IP "--key-type <type>" +(SSL) Private key file type. Specify which type your \fI--key\fP provided +private key is. DER, PEM, and ENG are supported. If not specified, PEM is +assumed. -The given rate is the average speed counted during the entire transfer. It -means that curl might use higher transfer speeds in short bursts, but over -time it uses no more than the given rate. +If this option is used several times, the last one will be used. +.IP "--krb <level>" +(FTP) Enable Kerberos authentication and use. The level must be entered and +should be one of 'clear', 'safe', 'confidential', or 'private'. Should you use +a level that is not one of these, 'private' will instead be used. -If you also use the \fI-Y/--speed-limit\fP option, that option will take -precedence and might cripple the rate-limiting slightly, to help keeping the -speed-limit logic working. +This option requires a library built with kerberos4 or GSSAPI +(GSS-Negotiate) support. This is not very common. Use \fI-V, --version\fP to +see if your curl supports it. If this option is used several times, the last one will be used. -.IP "-l/--list-only" +.IP "-l, --list-only" (FTP) When listing an FTP directory, this switch forces a name-only view. Especially useful if you want to machine-parse the contents of an FTP @@ -743,16 +761,11 @@ This option causes an FTP NLST command to be sent. Some FTP servers list only files in their response to NLST; they do not include subdirectories and symbolic links. -.IP "--local-port <num>[-num]" -Set a preferred number or range of local port numbers to use for the -connection(s). Note that port numbers by nature are a scarce resource that -will be busy at times so setting this range to something too narrow might -cause unnecessary connection setup failures. (Added in 7.15.2) -.IP "-L/--location" +.IP "-L, --location" (HTTP/HTTPS) If the server reports that the requested page has moved to a different location (indicated with a Location: header and a 3XX response code), this option will make curl redo the request on the new place. If used together -with \fI-i/--include\fP or \fI-I/--head\fP, headers from all requested pages +with \fI-i, --include\fP or \fI-I, --head\fP, headers from all requested pages will be shown. When authentication is used, curl only sends its credentials to the initial host. If a redirect takes curl to a different host, it won't be able to intercept the user+password. See also \fI--location-trusted\fP on how @@ -763,17 +776,57 @@ When curl follows a redirect and the request is not a plain GET (for example POST or PUT), it will do the following request with a GET if the HTTP response was 301, 302, or 303. If the response code was any other 3xx code, curl will re-send the following request using the same unmodified method. +.IP "--libcurl <file>" +Append this option to any ordinary curl command line, and you will get a +libcurl-using C source code written to the file that does the equivalent +of what your command-line operation does! + +If this option is used several times, the last given file name will be +used. (Added in 7.16.1) +.IP "--limit-rate <speed>" +Specify the maximum transfer rate you want curl to use. This feature is useful +if you have a limited pipe and you'd like your transfer not to use your entire +bandwidth. + +The given speed is measured in bytes/second, unless a suffix is appended. +Appending 'k' or 'K' will count the number as kilobytes, 'm' or M' makes it +megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G. + +The given rate is the average speed counted during the entire transfer. It +means that curl might use higher transfer speeds in short bursts, but over +time it uses no more than the given rate. + +If you also use the \fI-Y, --speed-limit\fP option, that option will take +precedence and might cripple the rate-limiting slightly, to help keeping the +speed-limit logic working. + +If this option is used several times, the last one will be used. +.IP "--local-port <num>[-num]" +Set a preferred number or range of local port numbers to use for the +connection(s). Note that port numbers by nature are a scarce resource that +will be busy at times so setting this range to something too narrow might +cause unnecessary connection setup failures. (Added in 7.15.2) .IP "--location-trusted" -(HTTP/HTTPS) Like \fI-L/--location\fP, but will allow sending the name + +(HTTP/HTTPS) Like \fI-L, --location\fP, but will allow sending the name + password to all hosts that the site may redirect to. This may or may not introduce a security breach if the site redirects you to a site to which you'll send your authentication info (which is plaintext in the case of HTTP Basic authentication). -.IP "--mail-rcpt <address>" -(SMTP) Specify a single address that the given mail should get sent to. This -option can be used multiple times to specify many recipients. +.IP "-m, --max-time <seconds>" +Maximum time in seconds that you allow the whole operation to take. This is +useful for preventing your batch jobs from hanging for hours due to slow +networks or links going down. Since 7.32.0, this option accepts decimal +values, but the actual timeout will decrease in accuracy as the specified +timeout increases in decimal precision. See also the \fI--connect-timeout\fP +option. -(Added in 7.20.0) +If this option is used several times, the last one will be used. +.IP "--mail-auth <address>" +(SMTP) Specify a single address. This will be used to specify the +authentication address (identity) of a submitted message that is being relayed +to another server. + +(Added in 7.25.0) .IP "--mail-from <address>" (SMTP) Specify a single address that the given mail should get sent from. @@ -783,18 +836,47 @@ Specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and curl will return with exit code 63. -\fBNOTE:\fP The file size is not always known prior to download, and for such files -this option has no effect even if the file transfer ends up being larger than -this given limit. This concerns both FTP and HTTP transfers. -.IP "-m/--max-time <seconds>" -Maximum time in seconds that you allow the whole operation to take. This is -useful for preventing your batch jobs from hanging for hours due to slow -networks or links going down. See also the \fI--connect-timeout\fP option. +\fBNOTE:\fP The file size is not always known prior to download, and for such +files this option has no effect even if the file transfer ends up being larger +than this given limit. This concerns both FTP and HTTP transfers. +.IP "--mail-rcpt <address>" +(SMTP) Specify a single address that the given mail should get sent to. This +option can be used multiple times to specify many recipients. + +(Added in 7.20.0) +.IP "--max-redirs <num>" +Set maximum number of redirection-followings allowed. If \fI-L, --location\fP +is used, this option can be used to prevent curl from following redirections +\&"in absurdum". By default, the limit is set to 50 redirections. Set this +option to -1 to make it limitless. If this option is used several times, the last one will be used. -.IP "-M/--manual" -Manual. Display the huge help text. -.IP "-n/--netrc" +.IP "--metalink" +This option can tell curl to parse and process a given URI as Metalink file +(both version 3 and 4 (RFC 5854) are supported) and make use of the mirrors +listed within for failover if there are errors (such as the file or server not +being available). It will also verify the hash of the file after the download +completes. The Metalink file itself is downloaded and processed in memory and +not stored in the local file system. + +Example to use a remote Metalink file: + +\fBcurl\fP --metalink http://www.example.com/example.metalink + +To use a Metalink file in the local file system, use FILE protocol +(file://): + +\fBcurl\fP --metalink file://example.metalink + +Please note that if FILE protocol is disabled, there is no way to use +a local Metalink file at the time of this writing. Also note that if +\fI--metalink\fP and \fI--include\fP are used together, \fI--include\fP will be +ignored. This is because including headers in the response will break +Metalink parser and if the headers are included in the file described +in Metalink file, hash check will fail. + +(Added in 7.27.0, if built against the libmetalink library.) +.IP "-n, --netrc" Makes curl scan the \fI.netrc\fP (\fI_netrc\fP on Windows) file in the user's home directory for login name and password. This is typically used for FTP on UNIX. If used with HTTP, curl will enable user authentication. See @@ -811,9 +893,28 @@ to FTP to the machine host.domain.com with user name \&'myself' and password \&'secret' should look similar to: .B "machine host.domain.com login myself password secret" +.IP "-N, --no-buffer" +Disables the buffering of the output stream. In normal work situations, curl +will use a standard buffered output stream that will have the effect that it +will output the data in chunks, not necessarily exactly when the data arrives. +Using this option will disable that buffering. + +Note that this is the negated option name documented. You can thus use +\fI--buffer\fP to enforce the buffering. +.IP "--netrc-file" +This option is similar to \fI--netrc\fP, except that you provide the path +(absolute or relative) to the netrc file that Curl should use. +You can only specify one netrc file per invocation. If several +\fI--netrc-file\fP options are provided, only the \fBlast one\fP will be used. +(Added in 7.21.5) + +This option overrides any use of \fI--netrc\fP as they are mutually exclusive. +It will also abide by \fI--netrc-optional\fP if specified. + .IP "--netrc-optional" Very similar to \fI--netrc\fP, but this option makes the .netrc usage \fBoptional\fP and not mandatory as the \fI--netrc\fP option does. + .IP "--negotiate" (HTTP) Enables GSS-Negotiate authentication. The GSS-Negotiate method was designed by Microsoft and is used in their web applications. It is primarily @@ -825,23 +926,14 @@ If you want to enable Negotiate for your proxy authentication, then use \fI--proxy-negotiate\fP. This option requires a library built with GSSAPI support. This is -not very common. Use \fI-V/--version\fP to see if your version supports +not very common. Use \fI-V, --version\fP to see if your version supports GSS-Negotiate. -When using this option, you must also provide a fake -u/--user option to +When using this option, you must also provide a fake \fI-u, --user\fP option to activate the authentication code properly. Sending a '-u :' is enough as the -user name and password from the -u option aren't actually used. - -If this option is used several times, the following occurrences make no -difference. -.IP "-N/--no-buffer" -Disables the buffering of the output stream. In normal work situations, curl -will use a standard buffered output stream that will have the effect that it -will output the data in chunks, not necessarily exactly when the data arrives. -Using this option will disable that buffering. +user name and password from the \fI-u\fP option aren't actually used. -Note that this is the negated option name documented. You can thus use -\fI--buffer\fP to enforce the buffering. +If this option is used several times, only the first one is used. .IP "--no-keepalive" Disables the use of keepalive messages on the TCP connection, as by default curl enables them. @@ -876,11 +968,10 @@ If you want to enable NTLM for your proxy authentication, then use \fI--proxy-ntlm\fP. This option requires a library built with SSL support. Use -\fI-V/--version\fP to see if your curl supports NTLM. +\fI-V, --version\fP to see if your curl supports NTLM. -If this option is used several times, the following occurrences make no -difference. -.IP "-o/--output <file>" +If this option is used several times, only the first one is used. +.IP "-o, --output <file>" Write output to <file> instead of stdout. If you are using {} or [] to fetch multiple documents, you can use '#' followed by a number in the <file> specifier. That variable will be replaced with the current string for the URL @@ -897,37 +988,76 @@ You may use this option as many times as the number of URLs you have. See also the \fI--create-dirs\fP option to create the local directories dynamically. Specifying the output as '-' (a single dash) will force the output to be done to stdout. -.IP "-O/--remote-name" +.IP "-O, --remote-name" Write output to a local file named like the remote file we get. (Only the file part of the remote file is used, the path is cut off.) The remote file name to use for saving is extracted from the given URL, nothing else. +Consequentially, the file will be saved in the current working directory. If +you want the file saved in a different directory, make sure you change current +working directory before you invoke curl with the \fB-O, --remote-name\fP flag! + You may use this option as many times as the number of URLs you have. -.IP "--remote-name-all" -This option changes the default action for all given URLs to be dealt with as -if \fI-O/--remote-name\fP were used for each one. So if you want to disable -that for a specific URL after \fI--remote-name-all\fP has been used, you must -use "-o -" or \fI--no-remote-name\fP. (Added in 7.19.0) +.IP "-p, --proxytunnel" +When an HTTP proxy is used (\fI-x, --proxy\fP), this option will cause non-HTTP +protocols to attempt to tunnel through the proxy instead of merely using it to +do HTTP-like operations. The tunnel approach is made with the HTTP proxy +CONNECT request and requires that the proxy allows direct connect to the +remote port number curl wants to tunnel through to. +.IP "-P, --ftp-port <address>" +(FTP) Reverses the default initiator/listener roles when connecting with +FTP. This switch makes curl use active mode. In practice, curl then tells the +server to connect back to the client's specified address and port, while +passive mode asks the server to setup an IP address and port for it to connect +to. <address> should be one of: +.RS +.IP interface +i.e "eth0" to specify which interface's IP address you want to use (Unix only) +.IP "IP address" +i.e "192.168.10.1" to specify the exact IP address +.IP "host name" +i.e "my.host.domain" to specify the machine +.IP "-" +make curl pick the same IP address that is already used for the control +connection +.RE + +If this option is used several times, the last one will be used. Disable the +use of PORT with \fI--ftp-pasv\fP. Disable the attempt to use the EPRT command +instead of PORT by using \fI--disable-eprt\fP. EPRT is really PORT++. + +Starting in 7.19.5, you can append \&":[start]-[end]\&" to the right of the +address, to tell curl what TCP port range to use. That means you specify a +port range, from a lower to a higher number. A single number works as well, +but do note that it increases the risk of failure since the port may not be +available. .IP "--pass <phrase>" (SSL/SSH) Passphrase for the private key If this option is used several times, the last one will be used. .IP "--post301" -Tells curl to respect RFC 2616/10.3.2 and not convert POST requests into GET -requests when following a 301 redirection. The non-RFC behaviour is ubiquitous -in web browsers, so curl does the conversion by default to maintain +(HTTP) Tells curl to respect RFC 2616/10.3.2 and not convert POST requests +into GET requests when following a 301 redirection. The non-RFC behaviour is +ubiquitous in web browsers, so curl does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using \fI-L/--location\fP +a redirection. This option is meaningful only when using \fI-L, --location\fP (Added in 7.17.1) .IP "--post302" -Tells curl to respect RFC 2616/10.3.2 and not convert POST requests into GET -requests when following a 302 redirection. The non-RFC behaviour is ubiquitous -in web browsers, so curl does the conversion by default to maintain +(HTTP) Tells curl to respect RFC 2616/10.3.2 and not convert POST requests +into GET requests when following a 302 redirection. The non-RFC behaviour is +ubiquitous in web browsers, so curl does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using \fI-L/--location\fP +a redirection. This option is meaningful only when using \fI-L, --location\fP (Added in 7.19.1) +.IP "--post303" +(HTTP) Tells curl to respect RFC 2616/10.3.2 and not convert POST requests +into GET requests when following a 303 redirection. The non-RFC behaviour is +ubiquitous in web browsers, so curl does the conversion by default to maintain +consistency. However, a server may require a POST to remain a POST after such +a redirection. This option is meaningful only when using \fI-L, --location\fP +(Added in 7.26.0) .IP "--proto <protocols>" Tells curl to use the listed protocols for its initial retrieval. Protocols are evaluated left to right, are comma separated, and are each a protocol @@ -996,71 +1126,41 @@ proxy. Use \fI--ntlm\fP for enabling NTLM with a remote host. Use the specified HTTP 1.0 proxy. If the port number is not specified, it is assumed at port 1080. -The only difference between this and the HTTP proxy option (\fI-x/--proxy\fP), +The only difference between this and the HTTP proxy option (\fI-x, --proxy\fP), is that attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol instead of the default HTTP 1.1. -.IP "-p/--proxytunnel" -When an HTTP proxy is used (\fI-x/--proxy\fP), this option will cause non-HTTP -protocols to attempt to tunnel through the proxy instead of merely using it to -do HTTP-like operations. The tunnel approach is made with the HTTP proxy -CONNECT request and requires that the proxy allows direct connect to the -remote port number curl wants to tunnel through to. .IP "--pubkey <key>" (SSH) Public key file name. Allows you to provide your public key in this separate file. If this option is used several times, the last one will be used. -.IP "-P/--ftp-port <address>" -(FTP) Reverses the default initiator/listener roles when connecting with -FTP. This switch makes curl use active mode. In practice, curl then tells the -server to connect back to the client's specified address and port, while -passive mode asks the server to setup an IP address and port for it to connect -to. <address> should be one of: -.RS -.IP interface -i.e "eth0" to specify which interface's IP address you want to use (Unix only) -.IP "IP address" -i.e "192.168.10.1" to specify the exact IP address -.IP "host name" -i.e "my.host.domain" to specify the machine -.IP "-" -make curl pick the same IP address that is already used for the control -connection -.RE - -If this option is used several times, the last one will be used. Disable the -use of PORT with \fI--ftp-pasv\fP. Disable the attempt to use the EPRT command -instead of PORT by using \fI--disable-eprt\fP. EPRT is really PORT++. - -Starting in 7.19.5, you can append \&":[start]-[end]\&" to the right of the -address, to tell curl what TCP port range to use. That means you specify a -port range, from a lower to a higher number. A single number works as well, -but do note that it increases the risk of failure since the port may not be -available. .IP "-q" If used as the first parameter on the command line, the \fIcurlrc\fP config -file will not be read and used. See the \fI-K/--config\fP for details on the +file will not be read and used. See the \fI-K, --config\fP for details on the default config file search path. -.IP "-Q/--quote <command>" +.IP "-Q, --quote <command>" (FTP/SFTP) Send an arbitrary command to the remote FTP or SFTP server. Quote -commands are sent BEFORE the transfer takes place (just after the -initial PWD command in an FTP transfer, to be exact). To make commands -take place after a successful transfer, prefix them with a dash '-'. -To make commands be sent after libcurl has changed the working directory, -just before the transfer command(s), prefix the command with a '+' (this -is only supported for FTP). You may specify any number of commands. If -the server returns failure for one of the commands, the entire operation -will be aborted. You must send syntactically correct FTP commands as -RFC959 defines to FTP servers, or one of the commands listed below to -SFTP servers. This option can be used multiple times. - -SFTP is a binary protocol. Unlike for FTP, libcurl interprets SFTP quote -commands before sending them to the server. Following is the list of +commands are sent BEFORE the transfer takes place (just after the initial PWD +command in an FTP transfer, to be exact). To make commands take place after a +successful transfer, prefix them with a dash '-'. To make commands be sent +after curl has changed the working directory, just before the transfer +command(s), prefix the command with a '+' (this is only supported for +FTP). You may specify any number of commands. If the server returns failure +for one of the commands, the entire operation will be aborted. You must send +syntactically correct FTP commands as RFC 959 defines to FTP servers, or one +of the commands listed below to SFTP servers. This option can be used +multiple times. When speaking to an FTP server, prefix the command with an +asterisk (*) to make curl continue even if the command fails as by default +curl will stop at first failure. + +SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands +itself before sending them to the server. File names may be quoted +shell-style to embed spaces or special characters. Following is the list of all supported SFTP quote commands: .RS .IP "chgrp group file" -The chgrp command sets the group ID of the file named by the file operand to the -group ID specified by the group operand. The group operand is a decimal +The chgrp command sets the group ID of the file named by the file operand to +the group ID specified by the group operand. The group operand is a decimal integer group ID. .IP "chmod mode file" The chmod command modifies the file mode bits of the specified file. The @@ -1087,11 +1187,7 @@ operand, provided it is empty. .IP "symlink source_file target_file" See ln. .RE -.IP "--random-file <file>" -(SSL) Specify the path name to file containing what will be considered as -random data. The data is used to seed the random engine for SSL connections. -See also the \fI--egd-file\fP option. -.IP "-r/--range <range>" +.IP "-r, --range <range>" (HTTP/FTP/SFTP/FILE) Retrieve a byte range (i.e a partial document) from a HTTP/1.1, FTP or SFTP server or a local FILE. Ranges can be specified in a number of ways. @@ -1122,9 +1218,10 @@ specifies two separate 100-byte ranges(*)(H) (*) = NOTE that this will cause the server to reply with a multipart response! -Only digit characters (0-9) are valid in the 'start' and 'stop' fields of -the \&'start-stop' range syntax. If a non-digit character is given in the range, the server's -response will be unspecified, depending on the server's configuration. +Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the +\&'start-stop' range syntax. If a non-digit character is given in the range, +the server's response will be unspecified, depending on the server's +configuration. You should also be aware that many HTTP/1.1 servers do not have this feature enabled, so that when you attempt to get a range, you'll instead get the whole @@ -1135,13 +1232,22 @@ FTP and SFTP range downloads only support the simple 'start-stop' syntax FTP command SIZE. If this option is used several times, the last one will be used. -.IP "--raw" -When used, it disables all internal HTTP decoding of content or transfer -encodings and instead makes them passed on unaltered, raw. (Added in 7.16.2) -.IP "-R/--remote-time" -When used, this will make libcurl attempt to figure out the timestamp of the +.IP "-R, --remote-time" +When used, this will make curl attempt to figure out the timestamp of the remote file, and if that is available make the local file get that same timestamp. +.IP "--random-file <file>" +(SSL) Specify the path name to file containing what will be considered as +random data. The data is used to seed the random engine for SSL connections. +See also the \fI--egd-file\fP option. +.IP "--raw" +(HTTP) When used, it disables all internal HTTP decoding of content or transfer +encodings and instead makes them passed on unaltered, raw. (Added in 7.16.2) +.IP "--remote-name-all" +This option changes the default action for all given URLs to be dealt with as +if \fI-O, --remote-name\fP were used for each one. So if you want to disable +that for a specific URL after \fI--remote-name-all\fP has been used, you must +use "-o -" or \fI--no-remote-name\fP. (Added in 7.19.0) .IP "--resolve <host:port:address>" Provide a custom address for a specific host and port pair. Using this, you can make the curl requests(s) use a specified address and prevent the @@ -1167,7 +1273,7 @@ using \fI--retry-delay\fP you disable this exponential backoff algorithm. See also \fI--retry-max-time\fP to limit the total time allowed for retries. (Added in 7.12.3) -If this option is used multiple times, the last occurrence decide the amount. +If this option is used several times, the last one will be used. .IP "--retry-delay <seconds>" Make curl sleep this amount of time before each retry when a transfer has failed with a transient error (it changes the default backoff time algorithm @@ -1175,46 +1281,78 @@ between retries). This option is only interesting if \fI--retry\fP is also used. Setting this delay to zero will make curl use the default backoff time. (Added in 7.12.3) -If this option is used multiple times, the last occurrence determines the amount. +If this option is used several times, the last one will be used. .IP "--retry-max-time <seconds>" The retry timer is reset before the first transfer attempt. Retries will be done as usual (see \fI--retry\fP) as long as the timer hasn't reached this given limit. Notice that if the timer hasn't reached the limit, the request will be made and while performing, it may take longer than this given time -period. To limit a single request\'s maximum time, use \fI-m/--max-time\fP. +period. To limit a single request\'s maximum time, use \fI-m, --max-time\fP. Set this option to zero to not timeout retries. (Added in 7.12.3) -If this option is used multiple times, the last occurrence determines the -amount. -.IP "-s/--silent" -Silent or quiet mode. Don't show progress meter or error messages. Makes -Curl mute. -.IP "-S/--show-error" -When used with -s it makes curl show an error message if it fails. +If this option is used several times, the last one will be used. +.IP "-s, --silent" +Silent or quiet mode. Don't show progress meter or error messages. Makes Curl +mute. It will still output the data you ask for, potentially even to the +terminal/stdout unless you redirect it. +.IP "--sasl-ir" +Enable initial response in SASL authentication. +(Added in 7.31.0) +.IP "-S, --show-error" +When used with \fI-s\fP it makes curl show an error message if it fails. +.IP "--ssl" +(FTP, POP3, IMAP, SMTP) Try to use SSL/TLS for the connection. Reverts to a +non-secure connection if the server doesn't support SSL/TLS. See also +\fI--ftp-ssl-control\fP and \fI--ssl-reqd\fP for different levels of +encryption required. (Added in 7.20.0) + +This option was formerly known as \fI--ftp-ssl\fP (Added in 7.11.0). That +option name can still be used but will be removed in a future version. +.IP "--ssl-reqd" +(FTP, POP3, IMAP, SMTP) Require SSL/TLS for the connection. Terminates the +connection if the server doesn't support SSL/TLS. (Added in 7.20.0) + +This option was formerly known as \fI--ftp-ssl-reqd\fP (added in 7.15.5). That +option name can still be used but will be removed in a future version. +.IP "--ssl-allow-beast" +(SSL) This option tells curl to not work around a security flaw in the SSL3 +and TLS1.0 protocols known as BEAST. If this option isn't used, the SSL layer +may use work-arounds known to cause interoperability problems with some older +SSL implementations. WARNING: this option loosens the SSL security, and by +using this flag you ask for exactly that. (Added in 7.25.0) .IP "--socks4 <host[:port]>" Use the specified SOCKS4 proxy. If the port number is not specified, it is assumed at port 1080. (Added in 7.15.2) -This option overrides any previous use of \fI-x/--proxy\fP, as they are +This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually exclusive. +Since 7.21.7, this option is superfluous since you can specify a socks4 proxy +with \fI-x, --proxy\fP using a socks4:// protocol prefix. + If this option is used several times, the last one will be used. .IP "--socks4a <host[:port]>" Use the specified SOCKS4a proxy. If the port number is not specified, it is assumed at port 1080. (Added in 7.18.0) -This option overrides any previous use of \fI-x/--proxy\fP, as they are +This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually exclusive. +Since 7.21.7, this option is superfluous since you can specify a socks4a proxy +with \fI-x, --proxy\fP using a socks4a:// protocol prefix. + If this option is used several times, the last one will be used. .IP "--socks5-hostname <host[:port]>" Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If the port number is not specified, it is assumed at port 1080. (Added in 7.18.0) -This option overrides any previous use of \fI-x/--proxy\fP, as they are +This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually exclusive. +Since 7.21.7, this option is superfluous since you can specify a socks5 +hostname proxy with \fI-x, --proxy\fP using a socks5h:// protocol prefix. + If this option is used several times, the last one will be used. (This option was previously wrongly documented and used as --socks without the number appended.) @@ -1222,9 +1360,12 @@ appended.) Use the specified SOCKS5 proxy - but resolve the host name locally. If the port number is not specified, it is assumed at port 1080. -This option overrides any previous use of \fI-x/--proxy\fP, as they are +This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually exclusive. +Since 7.21.7, this option is superfluous since you can specify a socks5 proxy +with \fI-x, --proxy\fP using a socks5:// protocol prefix. + If this option is used several times, the last one will be used. (This option was previously wrongly documented and used as --socks without the number appended.) @@ -1234,27 +1375,21 @@ This option (as well as \fI--socks4\fP) does not work with IPV6, FTPS or LDAP. The default service name for a socks server is rcmd/server-fqdn. This option allows you to change it. -Examples: - --socks5 proxy-name \fI--socks5-gssapi-service\fP sockd would use -sockd/proxy-name - --socks5 proxy-name \fI--socks5-gssapi-service\fP sockd/real-name would use -sockd/real-name for cases where the proxy-name does not match the princpal name. - (Added in 7.19.4). +Examples: --socks5 proxy-name \fI--socks5-gssapi-service\fP sockd would use +sockd/proxy-name --socks5 proxy-name \fI--socks5-gssapi-service\fP +sockd/real-name would use sockd/real-name for cases where the proxy-name does +not match the principal name. (Added in 7.19.4). .IP "--socks5-gssapi-nec" -As part of the gssapi negotiation a protection mode is negotiated. The rfc1961 +As part of the gssapi negotiation a protection mode is negotiated. RFC 1961 says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. The option \fI--socks5-gssapi-nec\fP allows the unprotected exchange of the protection mode negotiation. (Added in 7.19.4). .IP "--stderr <file>" Redirect all writes to stderr to the specified file instead. If the file name -is a plain '-', it is instead written to stdout. This option has no point when -you're using a shell with decent redirecting capabilities. +is a plain '-', it is instead written to stdout. If this option is used several times, the last one will be used. -.IP "--tcp-nodelay" -Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for -details about this option. (Added in 7.11.2) -.IP "-t/--telnet-option <OPT=val>" +.IP "-t, --telnet-option <OPT=val>" Pass options to the telnet protocol. Supported options are: TTYPE=<term> Sets the terminal type. @@ -1262,21 +1397,13 @@ TTYPE=<term> Sets the terminal type. XDISPLOC=<X display> Sets the X display location. NEW_ENV=<var,val> Sets an environment variable. -.IP "--tftp-blksize <value>" -(TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size that -curl will try to use when tranferring data to or from a TFTP server. By -default 512 bytes will be used. - -If this option is used several times, the last one will be used. - -(Added in 7.20.0) -.IP "-T/--upload-file <file>" +.IP "-T, --upload-file <file>" This transfers the specified local file to the remote URL. If there is no file part in the specified URL, Curl will append the local file name. NOTE that you must use a trailing / on the last directory to really prove to Curl that there is no file name or curl will think that your last directory name is the remote file name to use. That will most likely cause the upload operation to fail. If -this is used on a HTTP(S) server, the PUT command will be used. +this is used on an HTTP(S) server, the PUT command will be used. Use the file name "-" (a single dash) to use stdin instead of a given file. Alternately, the file name "." (a single period) may be specified instead @@ -1293,12 +1420,41 @@ curl -T "{file1,file2}" http://www.uploadtothissite.com or even curl -T "img[1-1000].png" ftp://ftp.picturemania.com/upload/ +.IP "--tcp-nodelay" +Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for +details about this option. (Added in 7.11.2) +.IP "--tftp-blksize <value>" +(TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size that +curl will try to use when transferring data to or from a TFTP server. By +default 512 bytes will be used. + +If this option is used several times, the last one will be used. + +(Added in 7.20.0) +.IP "--tlsauthtype <authtype>" +Set TLS authentication type. Currently, the only supported option is "SRP", +for TLS-SRP (RFC 5054). If \fI--tlsuser\fP and \fI--tlspassword\fP are +specified but \fI--tlsauthtype\fP is not, then this option defaults to "SRP". +(Added in 7.21.4) +.IP "--tlsuser <user>" +Set username for use with the TLS authentication method specified with +\fI--tlsauthtype\fP. Requires that \fI--tlspassword\fP also be set. (Added in +7.21.4) +.IP "--tlspassword <password>" +Set password for use with the TLS authentication method specified with +\fI--tlsauthtype\fP. Requires that \fI--tlsuser\fP also be set. (Added in +7.21.4) +.IP "--tr-encoding" +(HTTP) Request a compressed Transfer-Encoding response using one of the +algorithms curl supports, and uncompress the data while receiving it. + +(Added in 7.21.6) .IP "--trace <file>" Enables a full trace dump of all incoming and outgoing data, including descriptive information, to the given output file. Use "-" as filename to have the output sent to stdout. -This option overrides previous uses of \fI-v/--verbose\fP or +This option overrides previous uses of \fI-v, --verbose\fP or \fI--trace-ascii\fP. If this option is used several times, the last one will be used. @@ -1311,15 +1467,15 @@ This is very similar to \fI--trace\fP, but leaves out the hex part and only shows the ASCII part of the dump. It makes smaller output that might be easier to read for untrained humans. -This option overrides previous uses of \fI-v/--verbose\fP or \fI--trace\fP. +This option overrides previous uses of \fI-v, --verbose\fP or \fI--trace\fP. If this option is used several times, the last one will be used. .IP "--trace-time" Prepends a time stamp to each trace or verbose line that curl displays. (Added in 7.14.0) -.IP "-u/--user <user:password>" +.IP "-u, --user <user:password>" Specify the user name and password to use for server authentication. Overrides -\fI-n/--netrc\fP and \fI--netrc-optional\fP. +\fI-n, --netrc\fP and \fI--netrc-optional\fP. If you just give the user name (without entering a colon) curl will prompt for a password. @@ -1329,7 +1485,7 @@ force curl to pick up the user name and password from your environment by simply specifying a single colon with this option: "-u :". If this option is used several times, the last one will be used. -.IP "-U/--proxy-user <user:password>" +.IP "-U, --proxy-user <user:password>" Specify the user name and password to use for proxy authentication. If you use an SSPI-enabled curl binary and do NTLM authentication, you can @@ -1342,14 +1498,14 @@ Specify a URL to fetch. This option is mostly handy when you want to specify URL(s) in a config file. This option may be used any number of times. To control where this URL is -written, use the \fI-o/--output\fP or the \fI-O/--remote-name\fP options. -.IP "-v/--verbose" +written, use the \fI-o, --output\fP or the \fI-O, --remote-name\fP options. +.IP "-v, --verbose" Makes the fetching more verbose/talkative. Mostly useful for debugging. A line starting with '>' means "header data" sent by curl, '<' means "header data" received by curl that is hidden in normal cases, and a line starting with '*' means additional info provided by curl. -Note that if you only want HTTP headers in the output, \fI-i/--include\fP +Note that if you only want HTTP headers in the output, \fI-i, --include\fP might be the option you're looking for. If you think this option still doesn't give you enough details, consider using @@ -1357,47 +1513,8 @@ If you think this option still doesn't give you enough details, consider using This option overrides previous uses of \fI--trace-ascii\fP or \fI--trace\fP. -Use \fI-S/--silent\fP to make curl quiet. -.IP "-V/--version" -Displays information about curl and the libcurl version it uses. - -The first line includes the full version of curl, libcurl and other 3rd party -libraries linked with the executable. - -The second line (starts with "Protocols:") shows all protocols that libcurl -reports to support. - -The third line (starts with "Features:") shows specific features libcurl -reports to offer. Available features include: -.RS -.IP "IPv6" -You can use IPv6 with this. -.IP "krb4" -Krb4 for FTP is supported. -.IP "SSL" -HTTPS and FTPS are supported. -.IP "libz" -Automatic decompression of compressed files over HTTP is supported. -.IP "NTLM" -NTLM authentication is supported. -.IP "GSS-Negotiate" -Negotiate authentication and krb5 for FTP is supported. -.IP "Debug" -This curl uses a libcurl built with Debug. This enables more error-tracking -and memory debugging etc. For curl-developers only! -.IP "AsynchDNS" -This curl uses asynchronous name resolves. -.IP "SPNEGO" -SPNEGO Negotiate authentication is supported. -.IP "Largefile" -This curl supports transfers of large files, files larger than 2GB. -.IP "IDN" -This curl supports IDN - international domain names. -.IP "SSPI" -SSPI is supported. If you use NTLM and set a blank user name, curl will -authenticate with your current user and password. -.RE -.IP "-w/--write-out <format>" +Use \fI-s, --silent\fP to make curl quiet. +.IP "-w, --write-out <format>" Defines what to display on stdout after a completed and successful operation. The format is a string that may contain plain text mixed with any number of variables. The string can be specified as "string", to get read from @@ -1414,12 +1531,21 @@ space with \\t. The %-symbol is a special symbol in the win32-environment, where all occurrences of % must be doubled when using this option. -The variables available at this point are: +The variables available are: .RS .TP 15 -.B url_effective -The URL that was fetched last. This is most meaningful if you've told curl -to follow location: headers. +.B content_type +The Content-Type of the requested document, if there was any. +.TP +.B filename_effective +The ultimate filename that curl writes out to. This is only meaningful if curl +is told to write to a file with the \fI--remote-name\fP or \fI--output\fP +option. It's most useful in combination with the \fI--remote-header-name\fP +option. (Added in 7.25.1) +.TP +.B ftp_entry_path +The initial path curl ended up in when logging on to the remote FTP +server. (Added in 7.15.4) .TP .B http_code The numerical response code that was found in the last retrieved HTTP(S) or @@ -1430,50 +1556,42 @@ same info. The numerical code that was found in the last response (from a proxy) to a curl CONNECT request. (Added in 7.12.4) .TP -.B time_total -The total time, in seconds, that the full operation lasted. The time will be -displayed with millisecond resolution. +.B local_ip +The IP address of the local end of the most recently done connection - can be +either IPv4 or IPv6 (Added in 7.29.0) .TP -.B time_namelookup -The time, in seconds, it took from the start until the name resolving was -completed. +.B local_port +The local port number of the most recently done connection (Added in 7.29.0) .TP -.B time_connect -The time, in seconds, it took from the start until the TCP connect to the -remote host (or proxy) was completed. +.B num_connects +Number of new connects made in the recent transfer. (Added in 7.12.3) .TP -.B time_appconnect -The time, in seconds, it took from the start until the SSL/SSH/etc -connect/handshake to the remote host was completed. (Added in 7.19.0) +.B num_redirects +Number of redirects that were followed in the request. (Added in 7.12.3) .TP -.B time_pretransfer -The time, in seconds, it took from the start until the file transfer was just -about to begin. This includes all pre-transfer commands and negotiations that -are specific to the particular protocol(s) involved. +.B redirect_url +When an HTTP request was made without -L to follow redirects, this variable +will show the actual URL a redirect \fIwould\fP take you to. (Added in 7.18.2) .TP -.B time_redirect -The time, in seconds, it took for all redirection steps include name lookup, -connect, pretransfer and transfer before the final transaction was -started. time_redirect shows the complete execution time for multiple -redirections. (Added in 7.12.3) +.B remote_ip +The remote IP address of the most recently done connection - can be either +IPv4 or IPv6 (Added in 7.29.0) .TP -.B time_starttransfer -The time, in seconds, it took from the start until the first byte was just about -to be transferred. This includes time_pretransfer and also the time the -server needed to calculate the result. +.B remote_port +The remote port number of the most recently done connection (Added in 7.29.0) .TP .B size_download The total amount of bytes that were downloaded. .TP -.B size_upload -The total amount of bytes that were uploaded. -.TP .B size_header The total amount of bytes of the downloaded headers. .TP .B size_request The total amount of bytes that were sent in the HTTP request. .TP +.B size_upload +The total amount of bytes that were uploaded. +.TP .B speed_download The average download speed that curl measured for the complete download. Bytes per second. @@ -1482,48 +1600,76 @@ per second. The average upload speed that curl measured for the complete upload. Bytes per second. .TP -.B content_type -The Content-Type of the requested document, if there was any. +.B ssl_verify_result +The result of the SSL peer certificate verification that was requested. 0 +means the verification was successful. (Added in 7.19.0) .TP -.B num_connects -Number of new connects made in the recent transfer. (Added in 7.12.3) +.B time_appconnect +The time, in seconds, it took from the start until the SSL/SSH/etc +connect/handshake to the remote host was completed. (Added in 7.19.0) .TP -.B num_redirects -Number of redirects that were followed in the request. (Added in 7.12.3) +.B time_connect +The time, in seconds, it took from the start until the TCP connect to the +remote host (or proxy) was completed. .TP -.B redirect_url -When a HTTP request was made without -L to follow redirects, this variable -will show the actual URL a redirect \fIwould\fP take you to. (Added in 7.18.2) +.B time_namelookup +The time, in seconds, it took from the start until the name resolving was +completed. .TP -.B ftp_entry_path -The initial path libcurl ended up in when logging on to the remote FTP -server. (Added in 7.15.4) +.B time_pretransfer +The time, in seconds, it took from the start until the file transfer was just +about to begin. This includes all pre-transfer commands and negotiations that +are specific to the particular protocol(s) involved. .TP -.B ssl_verify_result -The result of the SSL peer certificate verification that was requested. 0 -means the verification was successful. (Added in 7.19.0) +.B time_redirect +The time, in seconds, it took for all redirection steps include name lookup, +connect, pretransfer and transfer before the final transaction was +started. time_redirect shows the complete execution time for multiple +redirections. (Added in 7.12.3) +.TP +.B time_starttransfer +The time, in seconds, it took from the start until the first byte was just +about to be transferred. This includes time_pretransfer and also the time the +server needed to calculate the result. +.TP +.B time_total +The total time, in seconds, that the full operation lasted. The time will be +displayed with millisecond resolution. +.TP +.B url_effective +The URL that was fetched last. This is most meaningful if you've told curl +to follow location: headers. .RE If this option is used several times, the last one will be used. -.IP "-x/--proxy <proxyhost[:port]>" -Use the specified HTTP proxy. If the port number is not specified, it is assumed -at port 1080. +.IP "-x, --proxy <[protocol://][user:password@]proxyhost[:port]>" +Use the specified HTTP proxy. If the port number is not specified, it is +assumed at port 1080. This option overrides existing environment variables that set the proxy to use. If there's an environment variable setting a proxy, you can set proxy to \&"" to override it. -\fBNote\fP that all operations that are performed over a HTTP proxy will -transparently be converted to HTTP. It means that certain protocol specific -operations might not be available. This is not the case if you can tunnel -through the proxy, as done with the \fI-p/--proxytunnel\fP option. +All operations that are performed over an HTTP proxy will transparently be +converted to HTTP. It means that certain protocol specific operations might +not be available. This is not the case if you can tunnel through the proxy, as +one with the \fI-p, --proxytunnel\fP option. + +User and password that might be provided in the proxy string are URL decoded +by curl. This allows you to pass in special characters such as @ by using %40 +or pass in a colon with %3a. -Starting with 7.14.1, the proxy host can be specified the exact same way as -the proxy environment variables, including the protocol prefix (http://) and -the embedded user + password. +The proxy host can be specified the exact same way as the proxy environment +variables, including the protocol prefix (http://) and the embedded user + +password. + +From 7.21.7, the proxy string may be specified with a protocol:// prefix to +specify alternative proxy protocols. Use socks4://, socks4a://, socks5:// or +socks5h:// to request the specific SOCKS version to be used. No protocol +specified, http:// and all others will be treated as HTTP proxies. If this option is used several times, the last one will be used. -.IP "-X/--request <command>" +.IP "-X, --request <command>" (HTTP) Specifies a custom request method to use when communicating with the HTTP server. The specified request will be used instead of the method otherwise used (which defaults to GET). Read the HTTP 1.1 specification for @@ -1531,87 +1677,145 @@ details and explanations. Common additional HTTP requests include PUT and DELETE, but related technologies like WebDAV offers PROPFIND, COPY, MOVE and more. +Normally you don't need this option. All sorts of GET, HEAD, POST and PUT +requests are rather invoked by using dedicated command line options. + +This option only changes the actual word used in the HTTP request, it does not +alter the way curl behaves. So for example if you want to make a proper HEAD +request, using -X HEAD will not suffice. You need to use the \fI-I, --head\fP +option. + (FTP) Specifies a custom FTP command to use instead of LIST when doing file lists with FTP. If this option is used several times, the last one will be used. -.IP "-y/--speed-time <time>" + +.IP "--xattr" +When saving output to a file, this option tells curl to store certain file +metadata in extended file attributes. Currently, the URL is stored in the +xdg.origin.url attribute and, for HTTP, the content type is stored in +the mime_type attribute. If the file system does not support extended +attributes, a warning is issued. + +.IP "-y, --speed-time <time>" If a download is slower than speed-limit bytes per second during a speed-time period, the download gets aborted. If speed-time is used, the default -speed-limit will be 1 unless set with -Y. +speed-limit will be 1 unless set with \fI-Y\fP. This option controls transfers and thus will not affect slow connects etc. If this is a concern for you, try the \fI--connect-timeout\fP option. If this option is used several times, the last one will be used. -.IP "-Y/--speed-limit <speed>" +.IP "-Y, --speed-limit <speed>" If a download is slower than this given speed (in bytes per second) for -speed-time seconds it gets aborted. speed-time is set with -y and is 30 if -not set. +speed-time seconds it gets aborted. speed-time is set with \fI-y\fP and is 30 +if not set. If this option is used several times, the last one will be used. -.IP "-z/--time-cond <date expression>" +.IP "-z, --time-cond <date expression>|<file>" (HTTP/FTP) Request a file that has been modified later than the given time and -date, or one that has been modified before that time. The date expression can -be all sorts of date strings or if it doesn't match any internal ones, it -tries to get the time from a given file name instead! See the -\fIcurl_getdate(3)\fP man pages for date expression details. +date, or one that has been modified before that time. The <date expression> +can be all sorts of date strings or if it doesn't match any internal ones, it +is taken as a filename and tries to get the modification date (mtime) from +<file> instead. See the \fIcurl_getdate(3)\fP man pages for date expression +details. Start the date expression with a dash (-) to make it request for a document that is older than the given date/time, default is a document that is newer than the specified date/time. If this option is used several times, the last one will be used. -.IP "--max-redirs <num>" -Set maximum number of redirection-followings allowed. If \fI-L/--location\fP -is used, this option can be used to prevent curl from following redirections -\&"in absurdum". By default, the limit is set to 50 redirections. Set this -option to -1 to make it limitless. +.IP "-h, --help" +Usage help. +.IP "-M, --manual" +Manual. Display the huge help text. +.IP "-V, --version" +Displays information about curl and the libcurl version it uses. -If this option is used several times, the last one will be used. -.IP "-0/--http1.0" -(HTTP) Forces curl to issue its requests using HTTP 1.0 instead of using its -internally preferred: HTTP 1.1. -.IP "-1/--tlsv1" -(SSL) -Forces curl to use TLS version 1 when negotiating with a remote TLS server. -.IP "-2/--sslv2" -(SSL) -Forces curl to use SSL version 2 when negotiating with a remote SSL server. -.IP "-3/--sslv3" -(SSL) -Forces curl to use SSL version 3 when negotiating with a remote SSL server. -.IP "-4/--ipv4" -If libcurl is capable of resolving an address to multiple IP versions (which -it is if it is IPv6-capable), this option tells libcurl to resolve names to -IPv4 addresses only. -.IP "-6/--ipv6" -If libcurl is capable of resolving an address to multiple IP versions (which -it is if it is IPv6-capable), this option tells libcurl to resolve names to -IPv6 addresses only. -.IP "-#/--progress-bar" -Make curl display progress information as a progress bar instead of the -default statistics. +The first line includes the full version of curl, libcurl and other 3rd party +libraries linked with the executable. + +The second line (starts with "Protocols:") shows all protocols that libcurl +reports to support. + +The third line (starts with "Features:") shows specific features libcurl +reports to offer. Available features include: +.RS +.IP "IPv6" +You can use IPv6 with this. +.IP "krb4" +Krb4 for FTP is supported. +.IP "SSL" +HTTPS and FTPS are supported. +.IP "libz" +Automatic decompression of compressed files over HTTP is supported. +.IP "NTLM" +NTLM authentication is supported. +.IP "GSS-Negotiate" +Negotiate authentication and krb5 for FTP is supported. +.IP "Debug" +This curl uses a libcurl built with Debug. This enables more error-tracking +and memory debugging etc. For curl-developers only! +.IP "AsynchDNS" +This curl uses asynchronous name resolves. +.IP "SPNEGO" +SPNEGO Negotiate authentication is supported. +.IP "Largefile" +This curl supports transfers of large files, files larger than 2GB. +.IP "IDN" +This curl supports IDN - international domain names. +.IP "SSPI" +SSPI is supported. If you use NTLM and set a blank user name, curl will +authenticate with your current user and password. +.IP "TLS-SRP" +SRP (Secure Remote Password) authentication is supported for TLS. +.IP "Metalink" +This curl supports Metalink (both version 3 and 4 (RFC 5854)), which +describes mirrors and hashes. curl will use mirrors for failover if +there are errors (such as the file or server not being available). +.RE .SH FILES .I ~/.curlrc .RS -Default config file, see \fI-K/--config\fP for details. +Default config file, see \fI-K, --config\fP for details. .SH ENVIRONMENT The environment variables can be specified in lower case or upper case. The lower case version has precedence. http_proxy is an exception as it is only available in lower case. + +Using an environment variable to set the proxy has the same effect as using +the \fI--proxy\fP option. + .IP "http_proxy [protocol://]<host>[:port]" Sets the proxy server to use for HTTP. .IP "HTTPS_PROXY [protocol://]<host>[:port]" Sets the proxy server to use for HTTPS. -.IP "FTP_PROXY [protocol://]<host>[:port]" -Sets the proxy server to use for FTP. +.IP "[url-protocol]_PROXY [protocol://]<host>[:port]" +Sets the proxy server to use for [url-protocol], where the protocol is a +protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP, +SMTP, LDAP etc. .IP "ALL_PROXY [protocol://]<host>[:port]" Sets the proxy server to use if no protocol-specific proxy is set. .IP "NO_PROXY <comma-separated list of hosts>" list of host names that shouldn't go through any proxy. If set to a asterisk \&'*' only, it matches all hosts. +.SH "PROXY PROTOCOL PREFIXES" +Since curl version 7.21.7, the proxy string may be specified with a +protocol:// prefix to specify alternative proxy protocols. + +If no protocol is specified in the proxy string or if the string doesn't match +a supported one, the proxy will be treated as an HTTP proxy. + +The supported proxy protocol prefixes are as follows: +.IP "socks4://" +Makes it the equivalent of \fI--socks4\fP +.IP "socks4a://" +Makes it the equivalent of \fI--socks4a\fP +.IP "socks5://" +Makes it the equivalent of \fI--socks5\fP +.IP "socks5h://" +Makes it the equivalent of \fI--socks5-hostname\fP .SH EXIT CODES There are a bunch of different error codes and their corresponding error messages that may appear during bad conditions. At the time of this writing, @@ -1622,6 +1826,10 @@ Unsupported protocol. This build of curl has no support for this protocol. Failed to initialize. .IP 3 URL malformed. The syntax was not correct. +.IP 4 +A feature or option that was needed to perform the desired request was not +enabled or was explicitly disabled at build-time. To make curl able to do +this, you probably need another build of libcurl! .IP 5 Couldn't resolve proxy. The given proxy host could not be resolved. .IP 6 @@ -1654,7 +1862,7 @@ FTP quote error. A quote command returned error from the server. .IP 22 HTTP page not retrieved. The requested url was not found or returned another error with the HTTP error code being 400 or above. This return code only -appears if \fI-f/--fail\fP is used. +appears if \fI-f, --fail\fP is used. .IP 23 Write error. Curl couldn't write data to a local filesystem or similar. .IP 25 @@ -1698,11 +1906,13 @@ Interface error. A specified outgoing interface could not be used. .IP 47 Too many redirects. When following redirects, curl hit the maximum amount. .IP 48 -Unknown TELNET option specified. +Unknown option specified to libcurl. This indicates that you passed a weird +option to curl that was passed on to libcurl and rejected. Read up in the +manual! .IP 49 Malformed telnet option. .IP 51 -The peer's SSL certificate or SSH MD5 fingerprint was not ok. +The peer's SSL certificate or SSH MD5 fingerprint was not OK. .IP 52 The server didn't reply anything, which here is considered an error. .IP 53 @@ -1786,4 +1996,3 @@ ftp://ftp.sunet.se/pub/www/utilities/curl/ .SH "SEE ALSO" .BR ftp (1), .BR wget (1) - diff --git a/docs/curl.html b/docs/curl.html index fb8f4b4b1..88c7e7ec4 100644 --- a/docs/curl.html +++ b/docs/curl.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -47,9 +49,9 @@ p.roffit { <p class="level0">curl - transfer a URL <a name="SYNOPSIS"></a><h2 class="nroffsh">SYNOPSIS</h2> <p class="level0"><span Class="bold">curl [options]</span> <a class="emphasis" href="#URL">[URL...]</a> <a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> <p class="level0"><span Class="bold">curl</span> is a tool to transfer data from or to a server, using one of the supported protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP). The command is designed to work without user interaction. -<p class="level0">curl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume and more. As you will see below, the number of features will make your head spin! +<p class="level0">curl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume, Metalink, and more. As you will see below, the number of features will make your head spin! <p class="level0">curl is powered by libcurl for all transfer-related features. See <span Class="manpage">libcurl (3)</span> for details. <a name="URL"></a><h2 class="nroffsh">URL</h2> -<p class="level0">The URL syntax is protocol-dependent. You'll find a detailed description in RFC 3986. +<p class="level0">The URL syntax is protocol-dependent. You'll find a detailed description in <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>. <p class="level0">You can specify multiple URLs or parts of URLs by writing part sets within braces as in: <p class="level0"> <a href="http://site">http://site</a>.{one,two,three}.com <p class="level0">or you can get sequences of alphanumeric series by using [] as in: @@ -61,49 +63,64 @@ p.roffit { <p class="level0"> <a href="http://www.numericals.com/file">http://www.numericals.com/file</a>[1-100:10].txt <a href="http://www.letters.com/file">http://www.letters.com/file</a>[a-z:2].txt <p class="level0">If you specify URL without protocol:// prefix, curl will attempt to guess what protocol you might want. It will then default to HTTP but try other protocols based on often-used host name prefixes. For example, for host names starting with "ftp." curl will assume you want to speak FTP. <p class="level0">curl will do its best to use what you pass to it as a URL. It is not trying to validate it as a syntactically correct URL by any means but is instead <span Class="bold">very</span> liberal with what it accepts. -<p class="level0">Curl will attempt to re-use connections for multiple file transfers, so that getting many files from the same server will not do multiple connects / handshakes. This improves speed. Of course this is only done on files specified on a single command line and cannot be used between separate curl invokes. <a name="PROGRESS"></a><h2 class="nroffsh">PROGRESS METER</h2> +<p class="level0">curl will attempt to re-use connections for multiple file transfers, so that getting many files from the same server will not do multiple connects / handshakes. This improves speed. Of course this is only done on files specified on a single command line and cannot be used between separate curl invokes. <a name="PROGRESS"></a><h2 class="nroffsh">PROGRESS METER</h2> <p class="level0">curl normally displays a progress meter during operations, indicating the amount of transferred data, transfer speeds and estimated time left, etc. <p class="level0">curl displays this data to the terminal by default, so if you invoke curl to do an operation and it is about to write data to the terminal, it <span Class="emphasis">disables</span> the progress meter as otherwise it would mess up the output mixing progress meter and response data. <p class="level0">If you want a progress meter for HTTP POST or PUT requests, you need to redirect the response output to a file, using shell redirect (>), -o [file] or similar. <p class="level0">It is not the same case for FTP upload as that operation does not spit out any response data to the terminal. <p class="level0">If you prefer a progress "bar" instead of the regular meter, <a class="emphasis" href="#-">-#</a> is your friend. <a name="OPTIONS"></a><h2 class="nroffsh">OPTIONS</h2> -<p class="level0">In general, all boolean options are enabled with --option and yet again disabled with --<span Class="bold">no-</span>option. That is, you use the exact same option name but prefix it with "no-". However, in this list we mostly only list and show the --option version of them. (This concept with --no options was added in 7.19.0. Previously most options were toggled on/off on repeated use of the same command line option.) -<p class="level0"><a name="-a--append"></a><span class="nroffip">-a/--append</span> +<p class="level0">In general, all boolean options are enabled with --<span Class="bold">option</span> and yet again disabled with --<span Class="bold">no-</span>option. That is, you use the exact same option name but prefix it with "no-". However, in this list we mostly only list and show the --option version of them. (This concept with --no options was added in 7.19.0. Previously most options were toggled on/off on repeated use of the same command line option.) +<p class="level0"><a name="-"></a><span class="nroffip">-#, --progress-bar</span> +<p class="level1">Make curl display progress as a simple progress bar instead of the standard, more informational, meter. +<p class="level0"><a name="-0"></a><span class="nroffip">-0, --http1.0</span> +<p class="level1">(HTTP) Forces curl to issue its requests using HTTP 1.0 instead of using its internally preferred: HTTP 1.1. +<p class="level0"><a name="-1"></a><span class="nroffip">-1, --tlsv1</span> +<p class="level1">(SSL) Forces curl to use TLS version 1 when negotiating with a remote TLS server. +<p class="level0"><a name="-2"></a><span class="nroffip">-2, --sslv2</span> +<p class="level1">(SSL) Forces curl to use SSL version 2 when negotiating with a remote SSL server. +<p class="level0"><a name="-3"></a><span class="nroffip">-3, --sslv3</span> +<p class="level1">(SSL) Forces curl to use SSL version 3 when negotiating with a remote SSL server. +<p class="level0"><a name="-4"></a><span class="nroffip">-4, --ipv4</span> +<p class="level1">If curl is capable of resolving an address to multiple IP versions (which it is if it is IPv6-capable), this option tells curl to resolve names to IPv4 addresses only. +<p class="level0"><a name="-6"></a><span class="nroffip">-6, --ipv6</span> +<p class="level1">If curl is capable of resolving an address to multiple IP versions (which it is if it is IPv6-capable), this option tells curl to resolve names to IPv6 addresses only. +<p class="level0"><a name="-a"></a><span class="nroffip">-a, --append</span> <p class="level1">(FTP/SFTP) When used in an upload, this will tell curl to append to the target file instead of overwriting it. If the file doesn't exist, it will be created. Note that this flag is ignored by some SSH servers (including OpenSSH). -<p class="level0"><a name="-A--user-agent"></a><span class="nroffip">-A/--user-agent <agent string></span> -<p class="level1">(HTTP) Specify the User-Agent string to send to the HTTP server. Some badly done CGIs fail if this field isn't set to "Mozilla/4.0". To encode blanks in the string, surround the string with single quote marks. This can also be set with the <a class="emphasis" href="#-H--header">-H/--header</a> option of course. -<p class="level1">If this option is set more than once, the last one will be the one that's used. +<p class="level0"><a name="-A"></a><span class="nroffip">-A, --user-agent <agent string></span> +<p class="level1">(HTTP) Specify the User-Agent string to send to the HTTP server. Some badly done CGIs fail if this field isn't set to "Mozilla/4.0". To encode blanks in the string, surround the string with single quote marks. This can also be set with the <a class="emphasis" href="#-H">-H, --header</a> option of course. +<p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--anyauth"></a><span class="nroffip">--anyauth</span> <p class="level1">(HTTP) Tells curl to figure out authentication method by itself, and use the most secure one the remote site claims to support. This is done by first doing a request and checking the response-headers, thus possibly inducing an extra network round-trip. This is used instead of setting a specific authentication method, which you can do with <a class="emphasis" href="#--basic">--basic</a>, <a class="emphasis" href="#--digest">--digest</a>, <a class="emphasis" href="#--ntlm">--ntlm</a>, and <a class="emphasis" href="#--negotiate">--negotiate</a>. <p class="level1">Note that using --anyauth is not recommended if you do uploads from stdin, since it may require data to be sent twice and then the client must be able to rewind. If the need should arise when uploading from stdin, the upload operation will fail. -<p class="level0"><a name="-b--cookie"></a><span class="nroffip">-b/--cookie <name=data></span> +<p class="level0"><a name="-b"></a><span class="nroffip">-b, --cookie <name=data></span> <p class="level1">(HTTP) Pass the data to the HTTP server as a cookie. It is supposedly the data previously received from the server in a "Set-Cookie:" line. The data should be in the format "NAME1=VALUE1; NAME2=VALUE2". -<p class="level1">If no '=' symbol is used in the line, it is treated as a filename to use to read previously stored cookie lines from, which should be used in this session if they match. Using this method also activates the "cookie parser" which will make curl record incoming cookies too, which may be handy if you're using this in combination with the <a class="emphasis" href="#-L--location">-L/--location</a> option. The file format of the file to read cookies from should be plain HTTP headers or the Netscape/Mozilla cookie file format. -<p class="level1"><span Class="bold">NOTE</span> that the file specified with <a class="emphasis" href="#-b--cookie">-b/--cookie</a> is only used as input. No cookies will be stored in the file. To store cookies, use the <a class="emphasis" href="#-c--cookie-jar">-c/--cookie-jar</a> option or you could even save the HTTP headers to a file using <a class="emphasis" href="#-D--dump-header">-D/--dump-header</a>! -<p class="level1">If this option is set more than once, the last one will be the one that's used. -<p class="level0"><a name="-B--use-ascii"></a><span class="nroffip">-B/--use-ascii</span> -<p class="level1">Enable ASCII transfer when using FTP or LDAP. For FTP, this can also be enforced by using an URL that ends with ";type=A". This option causes data sent to stdout to be in text mode for win32 systems. +<p class="level1">If no '=' symbol is used in the line, it is treated as a filename to use to read previously stored cookie lines from, which should be used in this session if they match. Using this method also activates the "cookie parser" which will make curl record incoming cookies too, which may be handy if you're using this in combination with the <a class="emphasis" href="#-L">-L, --location</a> option. The file format of the file to read cookies from should be plain HTTP headers or the Netscape/Mozilla cookie file format. +<p class="level1"><span Class="bold">NOTE</span> that the file specified with <a class="emphasis" href="#-b">-b, --cookie</a> is only used as input. No cookies will be stored in the file. To store cookies, use the <a class="emphasis" href="#-c">-c, --cookie-jar</a> option or you could even save the HTTP headers to a file using <a class="emphasis" href="#-D">-D, --dump-header</a>! +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="-B"></a><span class="nroffip">-B, --use-ascii</span> +<p class="level1">(FTP/LDAP) Enable ASCII transfer. For FTP, this can also be enforced by using an URL that ends with ";type=A". This option causes data sent to stdout to be in text mode for win32 systems. <p class="level0"><a name="--basic"></a><span class="nroffip">--basic</span> <p class="level1">(HTTP) Tells curl to use HTTP Basic authentication. This is the default and this option is usually pointless, unless you use it to override a previously set option that sets a different authentication method (such as <a class="emphasis" href="#--ntlm">--ntlm</a>, <a class="emphasis" href="#--digest">--digest</a>, or <a class="emphasis" href="#--negotiate">--negotiate</a>). +<p class="level0"><a name="-c"></a><span class="nroffip">-c, --cookie-jar <file name></span> +<p class="level1">(HTTP) Specify to which file you want curl to write all cookies after a completed operation. Curl writes all cookies previously read from a specified file as well as all cookies received from remote server(s). If no cookies are known, no file will be written. The file will be written using the Netscape cookie file format. If you set the file name to a single dash, "-", the cookies will be written to stdout. +<p class="level1">This command line option will activate the cookie engine that makes curl record and use cookies. Another way to activate it is to use the <span class="emphasis">-b, --cookie</span> option. +<p class="level1">If the cookie jar can't be created or written to, the whole curl operation won't fail or even report an error clearly. Using -v will get a warning displayed, but that is the only visible feedback you get about this possibly lethal situation. +<p class="level1">If this option is used several times, the last specified file name will be used. +<p class="level0"><a name="-C"></a><span class="nroffip">-C, --continue-at <offset></span> +<p class="level1">Continue/Resume a previous file transfer at the given offset. The given offset is the exact number of bytes that will be skipped, counting from the beginning of the source file before it is transferred to the destination. If used with uploads, the FTP server command SIZE will not be used by curl. +<p class="level1">Use "-C -" to tell curl to automatically find out where/how to resume the transfer. It then uses the given output/input files to figure that out. +<p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--ciphers"></a><span class="nroffip">--ciphers <list of ciphers></span> <p class="level1">(SSL) Specifies which ciphers to use in the connection. The list of ciphers must specify valid ciphers. Read up on SSL cipher list details on this URL: <span Class="emphasis"><a href="http://www.openssl.org/docs/apps/ciphers.html">http://www.openssl.org/docs/apps/ciphers.html</a></span> -<p class="level1">NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS ciphers is in the NSSCipherSuite entry at this URL: <span Class="emphasis"><a href="http://directory.fedora.redhat.com/docs/mod_nss.html">http://directory.fedora.redhat.com/docs/mod_nss.html</a>#Directives</span> -<p class="level1">If this option is used several times, the last one will override the others. +<p class="level1">NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS ciphers is in the NSSCipherSuite entry at this URL: <span Class="emphasis"><a href="http://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html">http://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html</a>#Directives</span> +<p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--compressed"></a><span class="nroffip">--compressed</span> -<p class="level1">(HTTP) Request a compressed response using one of the algorithms libcurl supports, and return the uncompressed document. If this option is used and the server sends an unsupported encoding, curl will report an error. +<p class="level1">(HTTP) Request a compressed response using one of the algorithms curl supports, and save the uncompressed document. If this option is used and the server sends an unsupported encoding, curl will report an error. <p class="level0"><a name="--connect-timeout"></a><span class="nroffip">--connect-timeout <seconds></span> -<p class="level1">Maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once curl has connected this option is of no more use. See also the <a class="emphasis" href="#-m--max-time">-m/--max-time</a> option. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-c--cookie-jar"></a><span class="nroffip">-c/--cookie-jar <file name></span> -<p class="level1">Specify to which file you want curl to write all cookies after a completed operation. Curl writes all cookies previously read from a specified file as well as all cookies received from remote server(s). If no cookies are known, no file will be written. The file will be written using the Netscape cookie file format. If you set the file name to a single dash, "-", the cookies will be written to stdout. -<p class="level1"><span Class="bold">NOTE</span> If the cookie jar can't be created or written to, the whole curl operation won't fail or even report an error clearly. Using -v will get a warning displayed, but that is the only visible feedback you get about this possibly lethal situation. -<p class="level1">If this option is used several times, the last specified file name will be used. -<p class="level0"><a name="-C--continue-at"></a><span class="nroffip">-C/--continue-at <offset></span> -<p class="level1">Continue/Resume a previous file transfer at the given offset. The given offset is the exact number of bytes that will be skipped, counting from the beginning of the source file before it is transferred to the destination. If used with uploads, the FTP server command SIZE will not be used by curl. -<p class="level1">Use "-C -" to tell curl to automatically find out where/how to resume the transfer. It then uses the given output/input files to figure that out. +<p class="level1">Maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once curl has connected this option is of no more use. Since 7.32.0, this option accepts decimal values, but the actual timeout will decrease in accuracy as the specified timeout increases in decimal precision. See also the <a class="emphasis" href="#-m">-m, --max-time</a> option. <p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--create-dirs"></a><span class="nroffip">--create-dirs</span> -<p class="level1">When used in conjunction with the -o option, curl will create the necessary local directory hierarchy as needed. This option creates the dirs mentioned with the -o option, nothing else. If the -o file name uses no dir or if the dirs it mentions already exist, no dir will be created. +<p class="level1">When used in conjunction with the <a class="emphasis" href="#-o">-o</a> option, curl will create the necessary local directory hierarchy as needed. This option creates the dirs mentioned with the <a class="emphasis" href="#-o">-o</a> option, nothing else. If the <a class="emphasis" href="#-o">-o</a> file name uses no dir or if the dirs it mentions already exist, no dir will be created. <p class="level1">To create remote directories when using FTP or SFTP, try <a class="emphasis" href="#--ftp-create-dirs">--ftp-create-dirs</a>. <p class="level0"><a name="--crlf"></a><span class="nroffip">--crlf</span> <p class="level1">(FTP) Convert LF to CRLF in upload. Useful for MVS (OS/390). @@ -111,15 +128,23 @@ p.roffit { <p class="level1">(HTTPS/FTPS) Provide a file using PEM format with a Certificate Revocation List that may specify peer certificates that are to be considered revoked. <p class="level1">If this option is used several times, the last one will be used. <p class="level1">(Added in 7.19.7) -<p class="level0"><a name="-d--data"></a><span class="nroffip">-d/--data <data></span> -<p class="level1">(HTTP) Sends the specified data in a POST request to the HTTP server, in the same way that a browser does when a user has filled in an HTML form and presses the submit button. This will cause curl to pass the data to the server using the content-type application/x-www-form-urlencoded. Compare to <a class="emphasis" href="#-F--form">-F/--form</a>. -<p class="level1"><a class="emphasis" href="#-d--data">-d/--data</a> is the same as <span Class="emphasis">--data-ascii</span>. To post data purely binary, you should instead use the <a class="emphasis" href="#--data-binary">--data-binary</a> option. To URL-encode the value of a form field you may use <a class="emphasis" href="#--data-urlencode">--data-urlencode</a>. +<p class="level0"><a name="-d"></a><span class="nroffip">-d, --data <data></span> +<p class="level1">(HTTP) Sends the specified data in a POST request to the HTTP server, in the same way that a browser does when a user has filled in an HTML form and presses the submit button. This will cause curl to pass the data to the server using the content-type application/x-www-form-urlencoded. Compare to <a class="emphasis" href="#-F">-F, --form</a>. +<p class="level1"><a class="emphasis" href="#-d">-d, --data</a> is the same as <a class="emphasis" href="#--data-ascii">--data-ascii</a>. To post data purely binary, you should instead use the <a class="emphasis" href="#--data-binary">--data-binary</a> option. To URL-encode the value of a form field you may use <a class="emphasis" href="#--data-urlencode">--data-urlencode</a>. <p class="level1">If any of these options is used more than once on the same command line, the data pieces specified will be merged together with a separating &-symbol. Thus, using '-d name=daniel -d skill=lousy' would generate a post chunk that looks like 'name=daniel&skill=lousy'. <p class="level1">If you start the data with the letter @, the rest should be a file name to read the data from, or - if you want curl to read the data from stdin. The contents of the file must already be URL-encoded. Multiple files can also be specified. Posting data from a file named 'foobar' would thus be done with <span Class="emphasis">--data @foobar</span>. +<p class="level0"><a name="-D"></a><span class="nroffip">-D, --dump-header <file></span> +<p class="level1">Write the protocol headers to the specified file. +<p class="level1">This option is handy to use when you want to store the headers that an HTTP site sends to you. Cookies from the headers could then be read in a second curl invocation by using the <a class="emphasis" href="#-b">-b, --cookie</a> option! The <a class="emphasis" href="#-c">-c, --cookie-jar</a> option is however a better way to store cookies. +<p class="level1">When used in FTP, the FTP server response lines are considered being "headers" and thus are saved there. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level1"> +<p class="level0"><a name="--data-ascii"></a><span class="nroffip">--data-ascii <data></span> +<p class="level1">See <a class="emphasis" href="#-d">-d, --data</a>. <p class="level0"><a name="--data-binary"></a><span class="nroffip">--data-binary <data></span> <p class="level1">(HTTP) This posts data exactly as specified with no extra processing whatsoever. -<p class="level1">If you start the data with the letter @, the rest should be a filename. Data is posted in a similar manner as <span Class="emphasis">--data-ascii</span> does, except that newlines are preserved and conversions are never done. -<p class="level1">If this option is used several times, the ones following the first will append data as described in <a class="emphasis" href="#-d--data">-d/--data</a>. +<p class="level1">If you start the data with the letter @, the rest should be a filename. Data is posted in a similar manner as <a class="emphasis" href="#--data-ascii">--data-ascii</a> does, except that newlines are preserved and conversions are never done. +<p class="level1">If this option is used several times, the ones following the first will append data as described in <a class="emphasis" href="#-d">-d, --data</a>. <p class="level0"><a name="--data-urlencode"></a><span class="nroffip">--data-urlencode <data></span> <p class="level1">(HTTP) This posts data, similar to the other --data options with the exception that this performs URL-encoding. (Added in 7.18.0) <p class="level1">To be CGI-compliant, the <data> part should begin with a <span Class="emphasis">name</span> followed by a separator and a content specification. The <data> part can be passed to curl using one of the following syntaxes: @@ -135,35 +160,41 @@ p.roffit { <p class="level1"><a name="namefilename"></a><span class="nroffip">name@filename</span> <p class="level2">This will make curl load data from the given file (including any newlines), URL-encode that data and pass it on in the POST. The name part gets an equal sign appended, resulting in <span Class="emphasis">name=urlencoded-file-content</span>. Note that the name is expected to be URL-encoded already. <p class="level1"> +<p class="level0"><a name="--delegation"></a><span class="nroffip">--delegation LEVEL</span> +<p class="level1">Set <span Class="emphasis">LEVEL</span> to tell the server what it is allowed to delegate when it comes to user credentials. Used with GSS/kerberos. +<p class="level2"> +<p class="level1"><a name="none"></a><span class="nroffip">none</span> +<p class="level2">Don't allow any delegation. +<p class="level1"><a name="policy"></a><span class="nroffip">policy</span> +<p class="level2">Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos service ticket, which is a matter of realm policy. +<p class="level1"><a name="always"></a><span class="nroffip">always</span> +<p class="level2">Unconditionally allow the server to delegate. +<p class="level1"> <p class="level0"><a name="--digest"></a><span class="nroffip">--digest</span> -<p class="level1">(HTTP) Enables HTTP Digest authentication. This is a authentication that prevents the password from being sent over the wire in clear text. Use this in combination with the normal <a class="emphasis" href="#-u--user">-u/--user</a> option to set user name and password. See also <a class="emphasis" href="#--ntlm">--ntlm</a>, <a class="emphasis" href="#--negotiate">--negotiate</a> and <a class="emphasis" href="#--anyauth">--anyauth</a> for related options. -<p class="level1">If this option is used several times, the following occurrences make no difference. +<p class="level1">(HTTP) Enables HTTP Digest authentication. This is an authentication scheme that prevents the password from being sent over the wire in clear text. Use this in combination with the normal <a class="emphasis" href="#-u">-u, --user</a> option to set user name and password. See also <a class="emphasis" href="#--ntlm">--ntlm</a>, <a class="emphasis" href="#--negotiate">--negotiate</a> and <a class="emphasis" href="#--anyauth">--anyauth</a> for related options. +<p class="level1">If this option is used several times, only the first one is used. <p class="level0"><a name="--disable-eprt"></a><span class="nroffip">--disable-eprt</span> <p class="level1">(FTP) Tell curl to disable the use of the EPRT and LPRT commands when doing active FTP transfers. Curl will normally always first attempt to use EPRT, then LPRT before using PORT, but with this option, it will use PORT right away. EPRT and LPRT are extensions to the original FTP protocol, and may not work on all servers, but they enable more functionality in a better way than the traditional PORT command. <p class="level1"><span Class="bold">--eprt</span> can be used to explicitly enable EPRT again and <span Class="bold">--no-eprt</span> is an alias for <a class="bold" href="#--disable-eprt">--disable-eprt</a>. -<p class="level1">Disabling EPRT only changes the active behavior. If you want to switch to passive mode you need to not use <a class="emphasis" href="#-P--ftp-port">-P/--ftp-port</a> or force it with <a class="emphasis" href="#--ftp-pasv">--ftp-pasv</a>. +<p class="level1">Disabling EPRT only changes the active behavior. If you want to switch to passive mode you need to not use <a class="emphasis" href="#-P">-P, --ftp-port</a> or force it with <a class="emphasis" href="#--ftp-pasv">--ftp-pasv</a>. <p class="level0"><a name="--disable-epsv"></a><span class="nroffip">--disable-epsv</span> <p class="level1">(FTP) Tell curl to disable the use of the EPSV command when doing passive FTP transfers. Curl will normally always first attempt to use EPSV before PASV, but with this option, it will not try using EPSV. -<p class="level1"><span Class="bold">--epsv</span> can be used to explicitly enable EPRT again and <span Class="bold">--no-epsv</span> is an alias for <a class="bold" href="#--disable-epsv">--disable-epsv</a>. -<p class="level1">Disabling EPSV only changes the passive behavior. If you want to switch to active mode you need to use <a class="emphasis" href="#-P--ftp-port">-P/--ftp-port</a>. -<p class="level0"><a name="-D--dump-header"></a><span class="nroffip">-D/--dump-header <file></span> -<p class="level1">Write the protocol headers to the specified file. -<p class="level1">This option is handy to use when you want to store the headers that a HTTP site sends to you. Cookies from the headers could then be read in a second curl invocation by using the <a class="emphasis" href="#-b--cookie">-b/--cookie</a> option! The <a class="emphasis" href="#-c--cookie-jar">-c/--cookie-jar</a> option is however a better way to store cookies. -<p class="level1">When used in FTP, the FTP server response lines are considered being "headers" and thus are saved there. +<p class="level1"><span Class="bold">--epsv</span> can be used to explicitly enable EPSV again and <span Class="bold">--no-epsv</span> is an alias for <a class="bold" href="#--disable-epsv">--disable-epsv</a>. +<p class="level1">Disabling EPSV only changes the passive behavior. If you want to switch to active mode you need to use <a class="emphasis" href="#-P">-P, --ftp-port</a>. +<p class="level0"><a name="-e"></a><span class="nroffip">-e, --referer <URL></span> +<p class="level1">(HTTP) Sends the "Referer Page" information to the HTTP server. This can also be set with the <a class="emphasis" href="#-H">-H, --header</a> flag of course. When used with <a class="emphasis" href="#-L">-L, --location</a> you can append ";auto" to the --referer URL to make curl automatically set the previous URL when it follows a Location: header. The ";auto" string can be used alone, even if you don't set an initial --referer. <p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-e--referer"></a><span class="nroffip">-e/--referer <URL></span> -<p class="level1">(HTTP) Sends the "Referer Page" information to the HTTP server. This can also be set with the <a class="emphasis" href="#-H--header">-H/--header</a> flag of course. When used with <a class="emphasis" href="#-L--location">-L/--location</a> you can append ";auto" to the --referer URL to make curl automatically set the previous URL when it follows a Location: header. The ";auto" string can be used alone, even if you don't set an initial --referer. +<p class="level0"><a name="-E"></a><span class="nroffip">-E, --cert <certificate[:password]></span> +<p class="level1">(SSL) Tells curl to use the specified client certificate file when getting a file with HTTPS, FTPS or another SSL-based protocol. The certificate must be in PEM format. If the optional password isn't specified, it will be queried for on the terminal. Note that this option assumes a "certificate" file that is the private key and the private certificate concatenated! See <span Class="emphasis">--cert</span> and <a class="emphasis" href="#--key">--key</a> to specify them independently. +<p class="level1">If curl is built against the NSS SSL library then this option can tell curl the nickname of the certificate to use within the NSS database defined by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be loaded. If you want to use a file from the current directory, please precede it with "./" prefix, in order to avoid confusion with a nickname. If the nickname contains ":", it needs to be preceded by "\" so that it is not recognized as password delimiter. If the nickname contains "\", it needs to be escaped as "\\" so that it is not recognized as an escape character. +<p class="level1">(iOS and Mac OS X only) If curl is built against Secure Transport, then the certificate string must match the name of a certificate that's in the system or user keychain. The private key corresponding to the certificate, and certificate chain (if any), must also be present in the keychain. <p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--engine"></a><span class="nroffip">--engine <name></span> <p class="level1">Select the OpenSSL crypto engine to use for cipher operations. Use <a class="emphasis" href="#--engine">--engine list</a> to print a list of build-time supported engines. Note that not all (or none) of the engines may be available at run-time. <p class="level0"><a name="--environment"></a><span class="nroffip">--environment</span> -<p class="level1">(RISC OS ONLY) Sets a range of environment variables, using the names the -w option supports, to allow easier extraction of useful information after having run curl. +<p class="level1">(RISC OS ONLY) Sets a range of environment variables, using the names the <a class="emphasis" href="#-w">-w</a> option supports, to allow easier extraction of useful information after having run curl. <p class="level0"><a name="--egd-file"></a><span class="nroffip">--egd-file <file></span> <p class="level1">(SSL) Specify the path name to the Entropy Gathering Daemon socket. The socket is used to seed the random engine for SSL connections. See also the <a class="emphasis" href="#--random-file">--random-file</a> option. -<p class="level0"><a name="-E--cert"></a><span class="nroffip">-E/--cert <certificate[:password]></span> -<p class="level1">(SSL) Tells curl to use the specified certificate file when getting a file with HTTPS or FTPS. The certificate must be in PEM format. If the optional password isn't specified, it will be queried for on the terminal. Note that this option assumes a "certificate" file that is the private key and the private certificate concatenated! See <span Class="emphasis">--cert</span> and <a class="emphasis" href="#--key">--key</a> to specify them independently. -<p class="level1">If curl is built against the NSS SSL library then this option tells curl the nickname of the certificate to use within the NSS database defined by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be loaded. -<p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--cert-type"></a><span class="nroffip">--cert-type <type></span> <p class="level1">(SSL) Tells curl what certificate type the provided certificate is in. PEM, DER and ENG are recognized types. If not specified, PEM is assumed. <p class="level1">If this option is used several times, the last one will be used. @@ -171,115 +202,99 @@ p.roffit { <p class="level1">(SSL) Tells curl to use the specified certificate file to verify the peer. The file may contain multiple CA certificates. The certificate(s) must be in PEM format. Normally curl is built to use a default file for this, so this option is typically used to alter that default file. <p class="level1">curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is set, and uses the given path as a path to a CA cert bundle. This option overrides that variable. <p class="level1">The windows version of curl will automatically look for a CA certs file named ´curl-ca-bundle.crt´, either in the same directory as curl.exe, or in the Current Working Directory, or in any folder along your PATH. -<p class="level1">If curl is built against the NSS SSL library then this option tells curl the nickname of the CA certificate to use within the NSS database defined by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be loaded. +<p class="level1">If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module (libnsspem.so) needs to be available for this option to work properly. <p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--capath"></a><span class="nroffip">--capath <CA certificate directory></span> -<p class="level1">(SSL) Tells curl to use the specified certificate directory to verify the peer. The certificates must be in PEM format, and the directory must have been processed using the c_rehash utility supplied with openssl. Using <a class="emphasis" href="#--capath">--capath</a> can allow curl to make SSL-connections much more efficiently than using <a class="emphasis" href="#--cacert">--cacert</a> if the <a class="emphasis" href="#--cacert">--cacert</a> file contains many CA certificates. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-f--fail"></a><span class="nroffip">-f/--fail</span> -<p class="level1">(HTTP) Fail silently (no output at all) on server errors. This is mostly done to better enable scripts etc to better deal with failed attempts. In normal cases when a HTTP server fails to deliver a document, it returns an HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and return error 22. +<p class="level1">(SSL) Tells curl to use the specified certificate directory to verify the peer. Multiple paths can be provided by separating them with ":" (e.g. "path1:path2:path3"). The certificates must be in PEM format, and if curl is built against OpenSSL, the directory must have been processed using the c_rehash utility supplied with OpenSSL. Using <a class="emphasis" href="#--capath">--capath</a> can allow OpenSSL-powered curl to make SSL-connections much more efficiently than using <a class="emphasis" href="#--cacert">--cacert</a> if the <a class="emphasis" href="#--cacert">--cacert</a> file contains many CA certificates. +<p class="level1">If this option is set, the default capath value will be ignored, and if it is used several times, the last one will be used. +<p class="level0"><a name="-f"></a><span class="nroffip">-f, --fail</span> +<p class="level1">(HTTP) Fail silently (no output at all) on server errors. This is mostly done to better enable scripts etc to better deal with failed attempts. In normal cases when an HTTP server fails to deliver a document, it returns an HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and return error 22. <p class="level1">This method is not fail-safe and there are occasions where non-successful response codes will slip through, especially when authentication is involved (response codes 401 and 407). +<p class="level0"><a name="-F"></a><span class="nroffip">-F, --form <name=content></span> +<p class="level1">(HTTP) This lets curl emulate a filled-in form in which a user has pressed the submit button. This causes curl to POST data using the Content-Type multipart/form-data according to <a href="http://www.ietf.org/rfc/rfc2388.txt">RFC 2388</a>. This enables uploading of binary files etc. To force the 'content' part to be a file, prefix the file name with an @ sign. To just get the content part from a file, prefix the file name with the symbol <. The difference between @ and < is then that @ makes a file get attached in the post as a file upload, while the < makes a text field and just get the contents for that text field from a file. +<p class="level1">Example, to send your password file to the server, where 'password' is the name of the form-field to which /etc/passwd will be the input: +<p class="level1"><span Class="bold">curl</span> -F password=@/etc/passwd www.mypasswords.com +<p class="level1">To read content from stdin instead of a file, use - as the filename. This goes for both @ and < constructs. +<p class="level1">You can also tell curl what Content-Type to use by using 'type=', in a manner similar to: +<p class="level1"><span Class="bold">curl</span> -F "web=@index.html;type=text/html" url.com +<p class="level1">or +<p class="level1"><span Class="bold">curl</span> -F "name=daniel;type=text/foo" url.com +<p class="level1">You can also explicitly change the name field of a file upload part by setting filename=, like this: +<p class="level1"><span Class="bold">curl</span> -F "file=@localfile;filename=nameinpost" url.com +<p class="level1">If filename/path contains ',' or ';', it must be quoted by double-quotes like: +<p class="level1"><span Class="bold">curl</span> -F "file=@\"localfile\";filename=\"nameinpost\"" url.com +<p class="level1">or +<p class="level1"><span Class="bold">curl</span> -F 'file=@"localfile";filename="nameinpost"' url.com +<p class="level1">Note that if a filename/path is quoted by double-quotes, any double-quote or backslash within the filename must be escaped by backslash. +<p class="level1">See further examples and details in the MANUAL. +<p class="level1">This option can be used multiple times. <p class="level0"><a name="--ftp-account"></a><span class="nroffip">--ftp-account [data]</span> <p class="level1">(FTP) When an FTP server asks for "account data" after user name and password has been provided, this data is sent off using the ACCT command. (Added in 7.13.0) -<p class="level1">If this option is used twice, the second will override the previous use. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="--ftp-alternative-to-user"></a><span class="nroffip">--ftp-alternative-to-user <command></span> +<p class="level1">(FTP) If authenticating with the USER and PASS commands fails, send this command. When connecting to Tumbleweed's Secure Transport server over FTPS using a client certificate, using "SITE AUTH" will tell the server to retrieve the username from the certificate. (Added in 7.15.5) <p class="level0"><a name="--ftp-create-dirs"></a><span class="nroffip">--ftp-create-dirs</span> <p class="level1">(FTP/SFTP) When an FTP or SFTP URL/operation uses a path that doesn't currently exist on the server, the standard behavior of curl is to fail. Using this option, curl will instead attempt to create missing directories. <p class="level0"><a name="--ftp-method"></a><span class="nroffip">--ftp-method [method]</span> -<p class="level1">(FTP) Control what method curl should use to reach a file on a FTP(S) server. The method argument should be one of the following alternatives: +<p class="level1">(FTP) Control what method curl should use to reach a file on an FTP(S) server. The method argument should be one of the following alternatives: <p class="level2"> <p class="level1"><a name="multicwd"></a><span class="nroffip">multicwd</span> -<p class="level2">curl does a single CWD operation for each path part in the given URL. For deep hierarchies this means very many commands. This is how RFC1738 says it should be done. This is the default but the slowest behavior. +<p class="level2">curl does a single CWD operation for each path part in the given URL. For deep hierarchies this means very many commands. This is how <a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a> says it should be done. This is the default but the slowest behavior. <p class="level1"><a name="nocwd"></a><span class="nroffip">nocwd</span> <p class="level2">curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full path to the server for all these commands. This is the fastest behavior. <p class="level1"><a name="singlecwd"></a><span class="nroffip">singlecwd</span> <p class="level2">curl does one CWD with the full target directory and then operates on the file "normally" (like in the multicwd case). This is somewhat more standards compliant than 'nocwd' but without the full penalty of 'multicwd'. <p class="level1">(Added in 7.15.1) <p class="level0"><a name="--ftp-pasv"></a><span class="nroffip">--ftp-pasv</span> -<p class="level1">(FTP) Use passive mode for the data conection. Passive is the internal default behavior, but using this option can be used to override a previous <span Class="emphasis">-P/-ftp-port</span> option. (Added in 7.11.0) -<p class="level1">If this option is used several times, the following occurrences make no difference. Undoing an enforced passive really isn't doable but you must then instead enforce the correct <a class="emphasis" href="#-P--ftp-port">-P/--ftp-port</a> again. +<p class="level1">(FTP) Use passive mode for the data connection. Passive is the internal default behavior, but using this option can be used to override a previous <span Class="emphasis">-P/-ftp-port</span> option. (Added in 7.11.0) +<p class="level1">If this option is used several times, only the first one is used. Undoing an enforced passive really isn't doable but you must then instead enforce the correct <a class="emphasis" href="#-P">-P, --ftp-port</a> again. <p class="level1">Passive mode means that curl will try the EPSV command first and then PASV, unless <a class="emphasis" href="#--disable-epsv">--disable-epsv</a> is used. -<p class="level0"><a name="--ftp-alternative-to-user"></a><span class="nroffip">--ftp-alternative-to-user <command></span> -<p class="level1">(FTP) If authenticating with the USER and PASS commands fails, send this command. When connecting to Tumbleweed's Secure Transport server over FTPS using a client certificate, using "SITE AUTH" will tell the server to retrieve the username from the certificate. (Added in 7.15.5) <p class="level0"><a name="--ftp-skip-pasv-ip"></a><span class="nroffip">--ftp-skip-pasv-ip</span> <p class="level1">(FTP) Tell curl to not use the IP address the server suggests in its response to curl's PASV command when curl connects the data connection. Instead curl will re-use the same IP address it already uses for the control connection. (Added in 7.14.2) <p class="level1">This option has no effect if PORT, EPRT or EPSV is used instead of PASV. <p class="level0"><a name="--ftp-pret"></a><span class="nroffip">--ftp-pret</span> <p class="level1">(FTP) Tell curl to send a PRET command before PASV (and EPSV). Certain FTP servers, mainly drftpd, require this non-standard command for directory listings as well as up and downloads in PASV mode. (Added in 7.20.x) -<p class="level0"><a name="--ssl"></a><span class="nroffip">--ssl</span> -<p class="level1">(FTP, POP3, IMAP, SMTP) Try to use SSL/TLS for the connection. Reverts to a non-secure connection if the server doesn't support SSL/TLS. See also <a class="emphasis" href="#--ftp-ssl-control">--ftp-ssl-control</a> and <a class="emphasis" href="#--ssl-reqd">--ssl-reqd</a> for different levels of encryption required. (Added in 7.20.0) -<p class="level1">This option was formerly known as <span Class="emphasis">--ftp-ssl</span> (Added in 7.11.0) and that can still be used but will be removed in a future version. -<p class="level0"><a name="--ftp-ssl-control"></a><span class="nroffip">--ftp-ssl-control</span> -<p class="level1">(FTP) Require SSL/TLS for the FTP login, clear for transfer. Allows secure authentication, but non-encrypted data transfers for efficiency. Fails the transfer if the server doesn't support SSL/TLS. (Added in 7.16.0) -<p class="level0"><a name="--ssl-reqd"></a><span class="nroffip">--ssl-reqd</span> -<p class="level1">(FTP, POP3, IMAP, SMTP) Require SSL/TLS for the connection. Terminates the connection if the server doesn't support SSL/TLS. (Added in 7.20.0) -<p class="level1">This option was formerly known as <span Class="emphasis">--ftp-ssl-reqd</span> (added in 7.15.5) and that can still be used but will be removed in a future version. <p class="level0"><a name="--ftp-ssl-ccc"></a><span class="nroffip">--ftp-ssl-ccc</span> -<p class="level1">(FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after authenticating. The rest of the control channel communication will be unencrypted. This allows NAT routers to follow the FTP transaction. The default mode is passive. See --ftp-ssl-ccc-mode for other modes. (Added in 7.16.1) +<p class="level1">(FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after authenticating. The rest of the control channel communication will be unencrypted. This allows NAT routers to follow the FTP transaction. The default mode is passive. See <a class="emphasis" href="#--ftp-ssl-ccc-mode">--ftp-ssl-ccc-mode</a> for other modes. (Added in 7.16.1) <p class="level0"><a name="--ftp-ssl-ccc-mode"></a><span class="nroffip">--ftp-ssl-ccc-mode [active/passive]</span> <p class="level1">(FTP) Use CCC (Clear Command Channel) Sets the CCC mode. The passive mode will not initiate the shutdown, but instead wait for the server to do it, and will not reply to the shutdown from the server. The active mode initiates the shutdown and waits for a reply from the server. (Added in 7.16.2) -<p class="level0"><a name="-F--form"></a><span class="nroffip">-F/--form <name=content></span> -<p class="level1">(HTTP) This lets curl emulate a filled-in form in which a user has pressed the submit button. This causes curl to POST data using the Content-Type multipart/form-data according to RFC2388. This enables uploading of binary files etc. To force the 'content' part to be a file, prefix the file name with an @ sign. To just get the content part from a file, prefix the file name with the symbol <. The difference between @ and < is then that @ makes a file get attached in the post as a file upload, while the < makes a text field and just get the contents for that text field from a file. -<p class="level1">Example, to send your password file to the server, where 'password' is the name of the form-field to which /etc/passwd will be the input: -<p class="level1"><span Class="bold">curl</span> -F password=@/etc/passwd www.mypasswords.com -<p class="level1">To read the file's content from stdin instead of a file, use - where the file name should've been. This goes for both @ and < constructs. -<p class="level1">You can also tell curl what Content-Type to use by using 'type=', in a manner similar to: -<p class="level1"><span Class="bold">curl</span> -F "web=@index.html;type=text/html" url.com -<p class="level1">or -<p class="level1"><span Class="bold">curl</span> -F "name=daniel;type=text/foo" url.com -<p class="level1">You can also explicitly change the name field of a file upload part by setting filename=, like this: -<p class="level1"><span Class="bold">curl</span> -F "file=@localfile;filename=nameinpost" url.com -<p class="level1">See further examples and details in the MANUAL. -<p class="level1">This option can be used multiple times. +<p class="level0"><a name="--ftp-ssl-control"></a><span class="nroffip">--ftp-ssl-control</span> +<p class="level1">(FTP) Require SSL/TLS for the FTP login, clear for transfer. Allows secure authentication, but non-encrypted data transfers for efficiency. Fails the transfer if the server doesn't support SSL/TLS. (Added in 7.16.0) that can still be used but will be removed in a future version. <p class="level0"><a name="--form-string"></a><span class="nroffip">--form-string <name=string></span> <p class="level1">(HTTP) Similar to <span Class="emphasis">--form</span> except that the value string for the named parameter is used literally. Leading '@' and '<' characters, and the ';type=' string in the value have no special meaning. Use this in preference to <span Class="emphasis">--form</span> if there's any possibility that the string value may accidentally trigger the '@' or '<' features of <span Class="emphasis">--form</span>. -<p class="level0"><a name="-g--globoff"></a><span class="nroffip">-g/--globoff</span> +<p class="level0"><a name="-g"></a><span class="nroffip">-g, --globoff</span> <p class="level1">This option switches off the "URL globbing parser". When you set this option, you can specify URLs that contain the letters {}[] without having them being interpreted by curl itself. Note that these letters are not normal legal URL contents but they should be encoded according to the URI standard. -<p class="level0"><a name="-G--get"></a><span class="nroffip">-G/--get</span> -<p class="level1">When used, this option will make all data specified with <a class="emphasis" href="#-d--data">-d/--data</a> or <a class="emphasis" href="#--data-binary">--data-binary</a> to be used in a HTTP GET request instead of the POST request that otherwise would be used. The data will be appended to the URL with a '?' separator. +<p class="level0"><a name="-G"></a><span class="nroffip">-G, --get</span> +<p class="level1">When used, this option will make all data specified with <a class="emphasis" href="#-d">-d, --data</a> or <a class="emphasis" href="#--data-binary">--data-binary</a> to be used in an HTTP GET request instead of the POST request that otherwise would be used. The data will be appended to the URL with a '?' separator. <p class="level1">If used in combination with -I, the POST data will instead be appended to the URL with a HEAD request. -<p class="level1">If this option is used several times, the following occurrences make no difference. This is because undoing a GET doesn't make sense, but you should then instead enforce the alternative method you prefer. -<p class="level0"><a name="-h--help"></a><span class="nroffip">-h/--help</span> -<p class="level1">Usage help. -<p class="level0"><a name="-H--header"></a><span class="nroffip">-H/--header <header></span> -<p class="level1">(HTTP) Extra header to use when getting a web page. You may specify any number of extra headers. Note that if you should add a custom header that has the same name as one of the internal ones curl would use, your externally set header will be used instead of the internal one. This allows you to make even trickier stuff than curl would normally do. You should not replace internally set headers without knowing perfectly well what you're doing. Remove an internal header by giving a replacement without content on the right side of the colon, as in: -H "Host:". +<p class="level1">If this option is used several times, only the first one is used. This is because undoing a GET doesn't make sense, but you should then instead enforce the alternative method you prefer. +<p class="level0"><a name="-H"></a><span class="nroffip">-H, --header <header></span> +<p class="level1">(HTTP) Extra header to use when getting a web page. You may specify any number of extra headers. Note that if you should add a custom header that has the same name as one of the internal ones curl would use, your externally set header will be used instead of the internal one. This allows you to make even trickier stuff than curl would normally do. You should not replace internally set headers without knowing perfectly well what you're doing. Remove an internal header by giving a replacement without content on the right side of the colon, as in: -H "Host:". If you send the custom header with no-value then its header must be terminated with a semicolon, such as -H "X-Custom-Header;" to send "X-Custom-Header:". <p class="level1">curl will make sure that each header you add/replace is sent with the proper end-of-line marker, you should thus <span Class="bold">not</span> add that as a part of the header content: do not add newlines or carriage returns, they will only mess things up for you. -<p class="level1">See also the <a class="emphasis" href="#-A--user-agent">-A/--user-agent</a> and <a class="emphasis" href="#-e--referer">-e/--referer</a> options. +<p class="level1">See also the <a class="emphasis" href="#-A">-A, --user-agent</a> and <a class="emphasis" href="#-e">-e, --referer</a> options. <p class="level1">This option can be used multiple times to add/replace/remove multiple headers. <p class="level0"><a name="--hostpubmd5"></a><span class="nroffip">--hostpubmd5 <md5></span> -<p class="level1">Pass a string containing 32 hexadecimal digits. The string should be the 128 bit MD5 checksum of the remote host's public key, curl will refuse the connection with the host unless the md5sums match. This option is only for SCP and SFTP transfers. (Added in 7.17.1) +<p class="level1">(SCP/SFTP) Pass a string containing 32 hexadecimal digits. The string should be the 128 bit MD5 checksum of the remote host's public key, curl will refuse the connection with the host unless the md5sums match. (Added in 7.17.1) <p class="level0"><a name="--ignore-content-length"></a><span class="nroffip">--ignore-content-length</span> <p class="level1">(HTTP) Ignore the Content-Length header. This is particularly useful for servers running Apache 1.x, which will report incorrect Content-Length for files larger than 2 gigabytes. -<p class="level0"><a name="-i--include"></a><span class="nroffip">-i/--include</span> +<p class="level0"><a name="-i"></a><span class="nroffip">-i, --include</span> <p class="level1">(HTTP) Include the HTTP-header in the output. The HTTP-header includes things like server-name, date of the document, HTTP-version and more... +<p class="level0"><a name="-I"></a><span class="nroffip">-I, --head</span> +<p class="level1">(HTTP/FTP/FILE) Fetch the HTTP-header only! HTTP-servers feature the command HEAD which this uses to get nothing but the header of a document. When used on an FTP or FILE file, curl displays the file size and last modification time only. <p class="level0"><a name="--interface"></a><span class="nroffip">--interface <name></span> <p class="level1">Perform an operation using a specified interface. You can enter interface name, IP address or host name. An example could look like: <p class="level1"> curl --interface eth0:1 <a href="http://www.netscape.com/">http://www.netscape.com/</a> <p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-I--head"></a><span class="nroffip">-I/--head</span> -<p class="level1">(HTTP/FTP/FILE) Fetch the HTTP-header only! HTTP-servers feature the command HEAD which this uses to get nothing but the header of a document. When used on a FTP or FILE file, curl displays the file size and last modification time only. -<p class="level0"><a name="-j--junk-session-cookies"></a><span class="nroffip">-j/--junk-session-cookies</span> +<p class="level0"><a name="-j"></a><span class="nroffip">-j, --junk-session-cookies</span> <p class="level1">(HTTP) When curl is told to read cookies from a given file, this option will make it discard all "session cookies". This will basically have the same effect as if a new session is started. Typical browsers always discard session cookies when they're closed down. -<p class="level0"><a name="-J--remote-header-name"></a><span class="nroffip">-J/--remote-header-name</span> -<p class="level1">(HTTP) This option tells the -O/--remote-name option to use the server-specified Content-Disposition filename instead of extracting a filename from the URL. -<p class="level0"><a name="-k--insecure"></a><span class="nroffip">-k/--insecure</span> -<p class="level1">(SSL) This option explicitly allows curl to perform "insecure" SSL connections and transfers. All SSL connections are attempted to be made secure by using the CA certificate bundle installed by default. This makes all connections considered "insecure" fail unless <a class="emphasis" href="#-k--insecure">-k/--insecure</a> is used. +<p class="level0"><a name="-J"></a><span class="nroffip">-J, --remote-header-name</span> +<p class="level1">(HTTP) This option tells the <a class="emphasis" href="#-O">-O, --remote-name</a> option to use the server-specified Content-Disposition filename instead of extracting a filename from the URL. +<p class="level0"><a name="-k"></a><span class="nroffip">-k, --insecure</span> +<p class="level1">(SSL) This option explicitly allows curl to perform "insecure" SSL connections and transfers. All SSL connections are attempted to be made secure by using the CA certificate bundle installed by default. This makes all connections considered "insecure" fail unless <a class="emphasis" href="#-k">-k, --insecure</a> is used. <p class="level1">See this online resource for further details: <span Class="bold"><a href="http://curl.haxx.se/docs/sslcerts.html">http://curl.haxx.se/docs/sslcerts.html</a></span> -<p class="level0"><a name="--keepalive-time"></a><span class="nroffip">--keepalive-time <seconds></span> -<p class="level1">This option sets the time a connection needs to remain idle before sending keepalive probes and the time between individual keepalive probes. It is currently effective on operating systems offering the TCP_KEEPIDLE and TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more). This option has no effect if <a class="emphasis" href="#--no-keepalive">--no-keepalive</a> is used. (Added in 7.18.0) -<p class="level1">If this option is used multiple times, the last occurrence sets the amount. -<p class="level0"><a name="--key"></a><span class="nroffip">--key <key></span> -<p class="level1">(SSL/SSH) Private key file name. Allows you to provide your private key in this separate file. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="--key-type"></a><span class="nroffip">--key-type <type></span> -<p class="level1">(SSL) Private key file type. Specify which type your <a class="emphasis" href="#--key">--key</a> provided private key is. DER, PEM, and ENG are supported. If not specified, PEM is assumed. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="--krb"></a><span class="nroffip">--krb <level></span> -<p class="level1">(FTP) Enable Kerberos authentication and use. The level must be entered and should be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a level that is not one of these, 'private' will instead be used. -<p class="level1">This option requires a library built with kerberos4 or GSSAPI (GSS-Negotiate) support. This is not very common. Use <a class="emphasis" href="#-V--version">-V/--version</a> to see if your curl supports it. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-K--config"></a><span class="nroffip">-K/--config <config file></span> +<p class="level0"><a name="-K"></a><span class="nroffip">-K, --config <config file></span> <p class="level1">Specify which config file to read curl arguments from. The config file is a text file in which command line arguments can be written which then will be used as if they were written on the actual command line. Options and their parameters must be specified on the same config file line, separated by whitespace, colon, the equals sign or any combination thereof (however, the preferred separator is the equals sign). If the parameter is to contain whitespace, the parameter must be enclosed within quotes. Within double quotes, the following escape sequences are available: \\, \", \t, \n, \r and \v. A backslash preceding any other letter is ignored. If the first column of a config line is a '#' character, the rest of the line will be treated as a comment. Only write one option per physical line in the config file. -<p class="level1">Specify the filename to -K/--config as '-' to make curl read the file from stdin. +<p class="level1">Specify the filename to -K, --config as '-' to make curl read the file from stdin. <p class="level1">Note that to be able to specify a URL in the config file, you need to specify it using the <a class="emphasis" href="#--url">--url</a> option, and not by simply writing the URL on its own line. So, it could look similar to this: <p class="level1">url = "<a href="http://curl.haxx.se/docs/">http://curl.haxx.se/docs/</a>" <p class="level1">Long option names can optionally be given in the config file without the initial double dashes. @@ -301,56 +316,85 @@ p.roffit { <p class="level1"> <p class="level1">This option can be used multiple times to load multiple config files. +<p class="level0"><a name="--keepalive-time"></a><span class="nroffip">--keepalive-time <seconds></span> +<p class="level1">This option sets the time a connection needs to remain idle before sending keepalive probes and the time between individual keepalive probes. It is currently effective on operating systems offering the TCP_KEEPIDLE and TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more). This option has no effect if <a class="emphasis" href="#--no-keepalive">--no-keepalive</a> is used. (Added in 7.18.0) +<p class="level1">If this option is used several times, the last one will be used. If unspecified, the option defaults to 60 seconds. +<p class="level0"><a name="--key"></a><span class="nroffip">--key <key></span> +<p class="level1">(SSL/SSH) Private key file name. Allows you to provide your private key in this separate file. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="--key-type"></a><span class="nroffip">--key-type <type></span> +<p class="level1">(SSL) Private key file type. Specify which type your <a class="emphasis" href="#--key">--key</a> provided private key is. DER, PEM, and ENG are supported. If not specified, PEM is assumed. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="--krb"></a><span class="nroffip">--krb <level></span> +<p class="level1">(FTP) Enable Kerberos authentication and use. The level must be entered and should be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a level that is not one of these, 'private' will instead be used. +<p class="level1">This option requires a library built with kerberos4 or GSSAPI (GSS-Negotiate) support. This is not very common. Use <a class="emphasis" href="#-V">-V, --version</a> to see if your curl supports it. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="-l"></a><span class="nroffip">-l, --list-only</span> +<p class="level1">(FTP) When listing an FTP directory, this switch forces a name-only view. Especially useful if you want to machine-parse the contents of an FTP directory since the normal directory view doesn't use a standard look or format. +<p class="level1">This option causes an FTP NLST command to be sent. Some FTP servers list only files in their response to NLST; they do not include subdirectories and symbolic links. +<p class="level1"> +<p class="level0"><a name="-L"></a><span class="nroffip">-L, --location</span> +<p class="level1">(HTTP/HTTPS) If the server reports that the requested page has moved to a different location (indicated with a Location: header and a 3XX response code), this option will make curl redo the request on the new place. If used together with <a class="emphasis" href="#-i">-i, --include</a> or <a class="emphasis" href="#-I">-I, --head</a>, headers from all requested pages will be shown. When authentication is used, curl only sends its credentials to the initial host. If a redirect takes curl to a different host, it won't be able to intercept the user+password. See also <a class="emphasis" href="#--location-trusted">--location-trusted</a> on how to change this. You can limit the amount of redirects to follow by using the <a class="emphasis" href="#--max-redirs">--max-redirs</a> option. +<p class="level1">When curl follows a redirect and the request is not a plain GET (for example POST or PUT), it will do the following request with a GET if the HTTP response was 301, 302, or 303. If the response code was any other 3xx code, curl will re-send the following request using the same unmodified method. <p class="level0"><a name="--libcurl"></a><span class="nroffip">--libcurl <file></span> -<p class="level1">Append this option to any ordinary curl command line, and you will get a libcurl-using source code written to the file that does the equivalent of what your command-line operation does! -<p class="level1">NOTE: this does not properly support -F and the sending of multipart formposts, so in those cases the output program will be missing necessary calls to <span Class="emphasis">curl_formadd(3)</span>, and possibly more. +<p class="level1">Append this option to any ordinary curl command line, and you will get a libcurl-using C source code written to the file that does the equivalent of what your command-line operation does! <p class="level1">If this option is used several times, the last given file name will be used. (Added in 7.16.1) <p class="level0"><a name="--limit-rate"></a><span class="nroffip">--limit-rate <speed></span> <p class="level1">Specify the maximum transfer rate you want curl to use. This feature is useful if you have a limited pipe and you'd like your transfer not to use your entire bandwidth. <p class="level1">The given speed is measured in bytes/second, unless a suffix is appended. Appending 'k' or 'K' will count the number as kilobytes, 'm' or M' makes it megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G. <p class="level1">The given rate is the average speed counted during the entire transfer. It means that curl might use higher transfer speeds in short bursts, but over time it uses no more than the given rate. -<p class="level1">If you also use the <a class="emphasis" href="#-Y--speed-limit">-Y/--speed-limit</a> option, that option will take precedence and might cripple the rate-limiting slightly, to help keeping the speed-limit logic working. +<p class="level1">If you also use the <a class="emphasis" href="#-Y">-Y, --speed-limit</a> option, that option will take precedence and might cripple the rate-limiting slightly, to help keeping the speed-limit logic working. <p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-l--list-only"></a><span class="nroffip">-l/--list-only</span> -<p class="level1">(FTP) When listing an FTP directory, this switch forces a name-only view. Especially useful if you want to machine-parse the contents of an FTP directory since the normal directory view doesn't use a standard look or format. -<p class="level1">This option causes an FTP NLST command to be sent. Some FTP servers list only files in their response to NLST; they do not include subdirectories and symbolic links. -<p class="level1"> <p class="level0"><a name="--local-port"></a><span class="nroffip">--local-port <num>[-num]</span> <p class="level1">Set a preferred number or range of local port numbers to use for the connection(s). Note that port numbers by nature are a scarce resource that will be busy at times so setting this range to something too narrow might cause unnecessary connection setup failures. (Added in 7.15.2) -<p class="level0"><a name="-L--location"></a><span class="nroffip">-L/--location</span> -<p class="level1">(HTTP/HTTPS) If the server reports that the requested page has moved to a different location (indicated with a Location: header and a 3XX response code), this option will make curl redo the request on the new place. If used together with <a class="emphasis" href="#-i--include">-i/--include</a> or <a class="emphasis" href="#-I--head">-I/--head</a>, headers from all requested pages will be shown. When authentication is used, curl only sends its credentials to the initial host. If a redirect takes curl to a different host, it won't be able to intercept the user+password. See also <a class="emphasis" href="#--location-trusted">--location-trusted</a> on how to change this. You can limit the amount of redirects to follow by using the <a class="emphasis" href="#--max-redirs">--max-redirs</a> option. -<p class="level1">When curl follows a redirect and the request is not a plain GET (for example POST or PUT), it will do the following request with a GET if the HTTP response was 301, 302, or 303. If the response code was any other 3xx code, curl will re-send the following request using the same unmodified method. <p class="level0"><a name="--location-trusted"></a><span class="nroffip">--location-trusted</span> -<p class="level1">(HTTP/HTTPS) Like <a class="emphasis" href="#-L--location">-L/--location</a>, but will allow sending the name + password to all hosts that the site may redirect to. This may or may not introduce a security breach if the site redirects you to a site to which you'll send your authentication info (which is plaintext in the case of HTTP Basic authentication). -<p class="level0"><a name="--mail-rcpt"></a><span class="nroffip">--mail-rcpt <address></span> -<p class="level1">(SMTP) Specify a single address that the given mail should get sent to. This option can be used multiple times to specify many recipients. -<p class="level1">(Added in 7.20.0) +<p class="level1">(HTTP/HTTPS) Like <a class="emphasis" href="#-L">-L, --location</a>, but will allow sending the name + password to all hosts that the site may redirect to. This may or may not introduce a security breach if the site redirects you to a site to which you'll send your authentication info (which is plaintext in the case of HTTP Basic authentication). +<p class="level0"><a name="-m"></a><span class="nroffip">-m, --max-time <seconds></span> +<p class="level1">Maximum time in seconds that you allow the whole operation to take. This is useful for preventing your batch jobs from hanging for hours due to slow networks or links going down. Since 7.32.0, this option accepts decimal values, but the actual timeout will decrease in accuracy as the specified timeout increases in decimal precision. See also the <a class="emphasis" href="#--connect-timeout">--connect-timeout</a> option. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="--mail-auth"></a><span class="nroffip">--mail-auth <address></span> +<p class="level1">(SMTP) Specify a single address. This will be used to specify the authentication address (identity) of a submitted message that is being relayed to another server. +<p class="level1">(Added in 7.25.0) <p class="level0"><a name="--mail-from"></a><span class="nroffip">--mail-from <address></span> <p class="level1">(SMTP) Specify a single address that the given mail should get sent from. <p class="level1">(Added in 7.20.0) <p class="level0"><a name="--max-filesize"></a><span class="nroffip">--max-filesize <bytes></span> <p class="level1">Specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and curl will return with exit code 63. <p class="level1"><span Class="bold">NOTE:</span> The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. This concerns both FTP and HTTP transfers. -<p class="level0"><a name="-m--max-time"></a><span class="nroffip">-m/--max-time <seconds></span> -<p class="level1">Maximum time in seconds that you allow the whole operation to take. This is useful for preventing your batch jobs from hanging for hours due to slow networks or links going down. See also the <a class="emphasis" href="#--connect-timeout">--connect-timeout</a> option. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-M--manual"></a><span class="nroffip">-M/--manual</span> -<p class="level1">Manual. Display the huge help text. -<p class="level0"><a name="-n--netrc"></a><span class="nroffip">-n/--netrc</span> +<p class="level0"><a name="--mail-rcpt"></a><span class="nroffip">--mail-rcpt <address></span> +<p class="level1">(SMTP) Specify a single address that the given mail should get sent to. This option can be used multiple times to specify many recipients. +<p class="level1">(Added in 7.20.0) +<p class="level0"><a name="--max-redirs"></a><span class="nroffip">--max-redirs <num></span> +<p class="level1">Set maximum number of redirection-followings allowed. If <a class="emphasis" href="#-L">-L, --location</a> is used, this option can be used to prevent curl from following redirections "in absurdum". By default, the limit is set to 50 redirections. Set this option to -1 to make it limitless. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="--metalink"></a><span class="nroffip">--metalink</span> +<p class="level1">This option can tell curl to parse and process a given URI as Metalink file (both version 3 and 4 (<a href="http://www.ietf.org/rfc/rfc5854.txt">RFC 5854</a>) are supported) and make use of the mirrors listed within for failover if there are errors (such as the file or server not being available). It will also verify the hash of the file after the download completes. The Metalink file itself is downloaded and processed in memory and not stored in the local file system. +<p class="level1">Example to use a remote Metalink file: +<p class="level1"><span Class="bold">curl</span> --metalink <a href="http://www.example.com/example.metalink">http://www.example.com/example.metalink</a> +<p class="level1">To use a Metalink file in the local file system, use FILE protocol (file://): +<p class="level1"><span Class="bold">curl</span> --metalink file://example.metalink +<p class="level1">Please note that if FILE protocol is disabled, there is no way to use a local Metalink file at the time of this writing. Also note that if <a class="emphasis" href="#--metalink">--metalink</a> and <span Class="emphasis">--include</span> are used together, <span Class="emphasis">--include</span> will be ignored. This is because including headers in the response will break Metalink parser and if the headers are included in the file described in Metalink file, hash check will fail. +<p class="level1">(Added in 7.27.0, if built against the libmetalink library.) +<p class="level0"><a name="-n"></a><span class="nroffip">-n, --netrc</span> <p class="level1">Makes curl scan the <span Class="emphasis">.netrc</span> (<span Class="emphasis">_netrc</span> on Windows) file in the user's home directory for login name and password. This is typically used for FTP on UNIX. If used with HTTP, curl will enable user authentication. See <span Class="manpage">netrc(4)</span> or <span Class="manpage">ftp(1)</span> for details on the file format. Curl will not complain if that file doesn't have the right permissions (it should not be either world- or group-readable). The environment variable "HOME" is used to find the home directory. <p class="level1">A quick and very simple example of how to setup a <span Class="emphasis">.netrc</span> to allow curl to FTP to the machine host.domain.com with user name 'myself' and password 'secret' should look similar to: <p class="level1"><span Class="bold">machine host.domain.com login myself password secret</span> +<p class="level0"><a name="-N"></a><span class="nroffip">-N, --no-buffer</span> +<p class="level1">Disables the buffering of the output stream. In normal work situations, curl will use a standard buffered output stream that will have the effect that it will output the data in chunks, not necessarily exactly when the data arrives. Using this option will disable that buffering. +<p class="level1">Note that this is the negated option name documented. You can thus use <span Class="emphasis">--buffer</span> to enforce the buffering. +<p class="level0"><a name="--netrc-file"></a><span class="nroffip">--netrc-file</span> +<p class="level1">This option is similar to <span Class="emphasis">--netrc</span>, except that you provide the path (absolute or relative) to the netrc file that Curl should use. You can only specify one netrc file per invocation. If several <a class="emphasis" href="#--netrc-file">--netrc-file</a> options are provided, only the <span Class="bold">last one</span> will be used. (Added in 7.21.5) +<p class="level1">This option overrides any use of <span Class="emphasis">--netrc</span> as they are mutually exclusive. It will also abide by <a class="emphasis" href="#--netrc-optional">--netrc-optional</a> if specified. +<p class="level1"> <p class="level0"><a name="--netrc-optional"></a><span class="nroffip">--netrc-optional</span> <p class="level1">Very similar to <span Class="emphasis">--netrc</span>, but this option makes the .netrc usage <span Class="bold">optional</span> and not mandatory as the <span Class="emphasis">--netrc</span> option does. +<p class="level1"> <p class="level0"><a name="--negotiate"></a><span class="nroffip">--negotiate</span> <p class="level1">(HTTP) Enables GSS-Negotiate authentication. The GSS-Negotiate method was designed by Microsoft and is used in their web applications. It is primarily meant as a support for Kerberos5 authentication but may be also used along with another authentication method. For more information see IETF draft draft-brezak-spnego-http-04.txt. <p class="level1">If you want to enable Negotiate for your proxy authentication, then use <a class="emphasis" href="#--proxy-negotiate">--proxy-negotiate</a>. -<p class="level1">This option requires a library built with GSSAPI support. This is not very common. Use <a class="emphasis" href="#-V--version">-V/--version</a> to see if your version supports GSS-Negotiate. -<p class="level1">When using this option, you must also provide a fake -u/--user option to activate the authentication code properly. Sending a '-u :' is enough as the user name and password from the -u option aren't actually used. -<p class="level1">If this option is used several times, the following occurrences make no difference. -<p class="level0"><a name="-N--no-buffer"></a><span class="nroffip">-N/--no-buffer</span> -<p class="level1">Disables the buffering of the output stream. In normal work situations, curl will use a standard buffered output stream that will have the effect that it will output the data in chunks, not necessarily exactly when the data arrives. Using this option will disable that buffering. -<p class="level1">Note that this is the negated option name documented. You can thus use <span Class="emphasis">--buffer</span> to enforce the buffering. +<p class="level1">This option requires a library built with GSSAPI support. This is not very common. Use <a class="emphasis" href="#-V">-V, --version</a> to see if your version supports GSS-Negotiate. +<p class="level1">When using this option, you must also provide a fake <a class="emphasis" href="#-u">-u, --user</a> option to activate the authentication code properly. Sending a '-u :' is enough as the user name and password from the <a class="emphasis" href="#-u">-u</a> option aren't actually used. +<p class="level1">If this option is used several times, only the first one is used. <p class="level0"><a name="--no-keepalive"></a><span class="nroffip">--no-keepalive</span> <p class="level1">Disables the use of keepalive messages on the TCP connection, as by default curl enables them. <p class="level1">Note that this is the negated option name documented. You can thus use <span Class="emphasis">--keepalive</span> to enforce keepalive. @@ -362,28 +406,45 @@ p.roffit { <p class="level0"><a name="--ntlm"></a><span class="nroffip">--ntlm</span> <p class="level1">(HTTP) Enables NTLM authentication. The NTLM authentication method was designed by Microsoft and is used by IIS web servers. It is a proprietary protocol, reverse-engineered by clever people and implemented in curl based on their efforts. This kind of behavior should not be endorsed, you should encourage everyone who uses NTLM to switch to a public and documented authentication method instead, such as Digest. <p class="level1">If you want to enable NTLM for your proxy authentication, then use <a class="emphasis" href="#--proxy-ntlm">--proxy-ntlm</a>. -<p class="level1">This option requires a library built with SSL support. Use <a class="emphasis" href="#-V--version">-V/--version</a> to see if your curl supports NTLM. -<p class="level1">If this option is used several times, the following occurrences make no difference. -<p class="level0"><a name="-o--output"></a><span class="nroffip">-o/--output <file></span> +<p class="level1">This option requires a library built with SSL support. Use <a class="emphasis" href="#-V">-V, --version</a> to see if your curl supports NTLM. +<p class="level1">If this option is used several times, only the first one is used. +<p class="level0"><a name="-o"></a><span class="nroffip">-o, --output <file></span> <p class="level1">Write output to <file> instead of stdout. If you are using {} or [] to fetch multiple documents, you can use '#' followed by a number in the <file> specifier. That variable will be replaced with the current string for the URL being fetched. Like in: <p class="level1"> curl http://{one,two}.site.com -o "file_#1.txt" <p class="level1">or use several variables like: <p class="level1"> curl http://{site,host}.host[1-5].com -o "#1_#2" <p class="level1">You may use this option as many times as the number of URLs you have. <p class="level1">See also the <a class="emphasis" href="#--create-dirs">--create-dirs</a> option to create the local directories dynamically. Specifying the output as '-' (a single dash) will force the output to be done to stdout. -<p class="level0"><a name="-O--remote-name"></a><span class="nroffip">-O/--remote-name</span> +<p class="level0"><a name="-O"></a><span class="nroffip">-O, --remote-name</span> <p class="level1">Write output to a local file named like the remote file we get. (Only the file part of the remote file is used, the path is cut off.) <p class="level1">The remote file name to use for saving is extracted from the given URL, nothing else. +<p class="level1">Consequentially, the file will be saved in the current working directory. If you want the file saved in a different directory, make sure you change current working directory before you invoke curl with the <a class="bold" href="#-O">-O, --remote-name</a> flag! <p class="level1">You may use this option as many times as the number of URLs you have. -<p class="level0"><a name="--remote-name-all"></a><span class="nroffip">--remote-name-all</span> -<p class="level1">This option changes the default action for all given URLs to be dealt with as if <a class="emphasis" href="#-O--remote-name">-O/--remote-name</a> were used for each one. So if you want to disable that for a specific URL after <a class="emphasis" href="#--remote-name-all">--remote-name-all</a> has been used, you must use "-o -" or <span Class="emphasis">--no-remote-name</span>. (Added in 7.19.0) +<p class="level0"><a name="-p"></a><span class="nroffip">-p, --proxytunnel</span> +<p class="level1">When an HTTP proxy is used (<a class="emphasis" href="#-x">-x, --proxy</a>), this option will cause non-HTTP protocols to attempt to tunnel through the proxy instead of merely using it to do HTTP-like operations. The tunnel approach is made with the HTTP proxy CONNECT request and requires that the proxy allows direct connect to the remote port number curl wants to tunnel through to. +<p class="level0"><a name="-P"></a><span class="nroffip">-P, --ftp-port <address></span> +<p class="level1">(FTP) Reverses the default initiator/listener roles when connecting with FTP. This switch makes curl use active mode. In practice, curl then tells the server to connect back to the client's specified address and port, while passive mode asks the server to setup an IP address and port for it to connect to. <address> should be one of: +<p class="level2"> +<p class="level1"><a name="interface"></a><span class="nroffip">interface</span> +<p class="level2">i.e "eth0" to specify which interface's IP address you want to use (Unix only) +<p class="level1"><a name="IP"></a><span class="nroffip">IP address</span> +<p class="level2">i.e "192.168.10.1" to specify the exact IP address +<p class="level1"><a name="host"></a><span class="nroffip">host name</span> +<p class="level2">i.e "my.host.domain" to specify the machine +<p class="level1"><a name="-"></a><span class="nroffip">-</span> +<p class="level2">make curl pick the same IP address that is already used for the control connection +<p class="level1"> +<p class="level1">If this option is used several times, the last one will be used. Disable the use of PORT with <a class="emphasis" href="#--ftp-pasv">--ftp-pasv</a>. Disable the attempt to use the EPRT command instead of PORT by using <a class="emphasis" href="#--disable-eprt">--disable-eprt</a>. EPRT is really PORT++. +<p class="level1">Starting in 7.19.5, you can append ":[start]-[end]" to the right of the address, to tell curl what TCP port range to use. That means you specify a port range, from a lower to a higher number. A single number works as well, but do note that it increases the risk of failure since the port may not be available. <p class="level0"><a name="--pass"></a><span class="nroffip">--pass <phrase></span> <p class="level1">(SSL/SSH) Passphrase for the private key <p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--post301"></a><span class="nroffip">--post301</span> -<p class="level1">Tells curl to respect RFC 2616/10.3.2 and not convert POST requests into GET requests when following a 301 redirection. The non-RFC behaviour is ubiquitous in web browsers, so curl does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when using <a class="emphasis" href="#-L--location">-L/--location</a> (Added in 7.17.1) +<p class="level1">(HTTP) Tells curl to respect <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>/10.3.2 and not convert POST requests into GET requests when following a 301 redirection. The non-RFC behaviour is ubiquitous in web browsers, so curl does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when using <a class="emphasis" href="#-L">-L, --location</a> (Added in 7.17.1) <p class="level0"><a name="--post302"></a><span class="nroffip">--post302</span> -<p class="level1">Tells curl to respect RFC 2616/10.3.2 and not convert POST requests into GET requests when following a 302 redirection. The non-RFC behaviour is ubiquitous in web browsers, so curl does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when using <a class="emphasis" href="#-L--location">-L/--location</a> (Added in 7.19.1) +<p class="level1">(HTTP) Tells curl to respect <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>/10.3.2 and not convert POST requests into GET requests when following a 302 redirection. The non-RFC behaviour is ubiquitous in web browsers, so curl does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when using <a class="emphasis" href="#-L">-L, --location</a> (Added in 7.19.1) +<p class="level0"><a name="--post303"></a><span class="nroffip">--post303</span> +<p class="level1">(HTTP) Tells curl to respect <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>/10.3.2 and not convert POST requests into GET requests when following a 303 redirection. The non-RFC behaviour is ubiquitous in web browsers, so curl does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when using <a class="emphasis" href="#-L">-L, --location</a> (Added in 7.26.0) <p class="level0"><a name="--proto"></a><span class="nroffip">--proto <protocols></span> <p class="level1">Tells curl to use the listed protocols for its initial retrieval. Protocols are evaluated left to right, are comma separated, and are each a protocol name or 'all', optionally prefixed by zero or more modifiers. Available modifiers are: <p class="level2"> @@ -417,31 +478,15 @@ p.roffit { <p class="level1">Tells curl to use HTTP NTLM authentication when communicating with the given proxy. Use <a class="emphasis" href="#--ntlm">--ntlm</a> for enabling NTLM with a remote host. <p class="level0"><a name="--proxy10"></a><span class="nroffip">--proxy1.0 <proxyhost[:port]></span> <p class="level1">Use the specified HTTP 1.0 proxy. If the port number is not specified, it is assumed at port 1080. -<p class="level1">The only difference between this and the HTTP proxy option (<a class="emphasis" href="#-x--proxy">-x/--proxy</a>), is that attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol instead of the default HTTP 1.1. -<p class="level0"><a name="-p--proxytunnel"></a><span class="nroffip">-p/--proxytunnel</span> -<p class="level1">When an HTTP proxy is used (<a class="emphasis" href="#-x--proxy">-x/--proxy</a>), this option will cause non-HTTP protocols to attempt to tunnel through the proxy instead of merely using it to do HTTP-like operations. The tunnel approach is made with the HTTP proxy CONNECT request and requires that the proxy allows direct connect to the remote port number curl wants to tunnel through to. +<p class="level1">The only difference between this and the HTTP proxy option (<a class="emphasis" href="#-x">-x, --proxy</a>), is that attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol instead of the default HTTP 1.1. <p class="level0"><a name="--pubkey"></a><span class="nroffip">--pubkey <key></span> <p class="level1">(SSH) Public key file name. Allows you to provide your public key in this separate file. <p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-P--ftp-port"></a><span class="nroffip">-P/--ftp-port <address></span> -<p class="level1">(FTP) Reverses the default initiator/listener roles when connecting with FTP. This switch makes curl use active mode. In practice, curl then tells the server to connect back to the client's specified address and port, while passive mode asks the server to setup an IP address and port for it to connect to. <address> should be one of: -<p class="level2"> -<p class="level1"><a name="interface"></a><span class="nroffip">interface</span> -<p class="level2">i.e "eth0" to specify which interface's IP address you want to use (Unix only) -<p class="level1"><a name="IP"></a><span class="nroffip">IP address</span> -<p class="level2">i.e "192.168.10.1" to specify the exact IP address -<p class="level1"><a name="host"></a><span class="nroffip">host name</span> -<p class="level2">i.e "my.host.domain" to specify the machine -<p class="level1"><a name="-"></a><span class="nroffip">-</span> -<p class="level2">make curl pick the same IP address that is already used for the control connection -<p class="level1"> -<p class="level1">If this option is used several times, the last one will be used. Disable the use of PORT with <a class="emphasis" href="#--ftp-pasv">--ftp-pasv</a>. Disable the attempt to use the EPRT command instead of PORT by using <a class="emphasis" href="#--disable-eprt">--disable-eprt</a>. EPRT is really PORT++. -<p class="level1">Starting in 7.19.5, you can append ":[start]-[end]" to the right of the address, to tell curl what TCP port range to use. That means you specify a port range, from a lower to a higher number. A single number works as well, but do note that it increases the risk of failure since the port may not be available. <p class="level0"><a name="-q"></a><span class="nroffip">-q</span> -<p class="level1">If used as the first parameter on the command line, the <span Class="emphasis">curlrc</span> config file will not be read and used. See the <a class="emphasis" href="#-K--config">-K/--config</a> for details on the default config file search path. -<p class="level0"><a name="-Q--quote"></a><span class="nroffip">-Q/--quote <command></span> -<p class="level1">(FTP/SFTP) Send an arbitrary command to the remote FTP or SFTP server. Quote commands are sent BEFORE the transfer takes place (just after the initial PWD command in an FTP transfer, to be exact). To make commands take place after a successful transfer, prefix them with a dash '-'. To make commands be sent after libcurl has changed the working directory, just before the transfer command(s), prefix the command with a '+' (this is only supported for FTP). You may specify any number of commands. If the server returns failure for one of the commands, the entire operation will be aborted. You must send syntactically correct FTP commands as RFC959 defines to FTP servers, or one of the commands listed below to SFTP servers. This option can be used multiple times. -<p class="level1">SFTP is a binary protocol. Unlike for FTP, libcurl interprets SFTP quote commands before sending them to the server. Following is the list of all supported SFTP quote commands: +<p class="level1">If used as the first parameter on the command line, the <span Class="emphasis">curlrc</span> config file will not be read and used. See the <a class="emphasis" href="#-K">-K, --config</a> for details on the default config file search path. +<p class="level0"><a name="-Q"></a><span class="nroffip">-Q, --quote <command></span> +<p class="level1">(FTP/SFTP) Send an arbitrary command to the remote FTP or SFTP server. Quote commands are sent BEFORE the transfer takes place (just after the initial PWD command in an FTP transfer, to be exact). To make commands take place after a successful transfer, prefix them with a dash '-'. To make commands be sent after curl has changed the working directory, just before the transfer command(s), prefix the command with a '+' (this is only supported for FTP). You may specify any number of commands. If the server returns failure for one of the commands, the entire operation will be aborted. You must send syntactically correct FTP commands as <a href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</a> defines to FTP servers, or one of the commands listed below to SFTP servers. This option can be used multiple times. When speaking to an FTP server, prefix the command with an asterisk (*) to make curl continue even if the command fails as by default curl will stop at first failure. +<p class="level1">SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands itself before sending them to the server. File names may be quoted shell-style to embed spaces or special characters. Following is the list of all supported SFTP quote commands: <p class="level2"> <p class="level1"><a name="chgrp"></a><span class="nroffip">chgrp group file</span> <p class="level2">The chgrp command sets the group ID of the file named by the file operand to the group ID specified by the group operand. The group operand is a decimal integer group ID. @@ -464,9 +509,7 @@ p.roffit { <p class="level1"><a name="symlink"></a><span class="nroffip">symlink source_file target_file</span> <p class="level2">See ln. <p class="level1"> -<p class="level0"><a name="--random-file"></a><span class="nroffip">--random-file <file></span> -<p class="level1">(SSL) Specify the path name to file containing what will be considered as random data. The data is used to seed the random engine for SSL connections. See also the <a class="emphasis" href="#--egd-file">--egd-file</a> option. -<p class="level0"><a name="-r--range"></a><span class="nroffip">-r/--range <range></span> +<p class="level0"><a name="-r"></a><span class="nroffip">-r, --range <range></span> <p class="level1">(HTTP/FTP/SFTP/FILE) Retrieve a byte range (i.e a partial document) from a HTTP/1.1, FTP or SFTP server or a local FILE. Ranges can be specified in a number of ways. <p class="level2"> <p class="level2"><span Class="bold">0-499</span> specifies the first 500 bytes @@ -482,10 +525,14 @@ p.roffit { <p class="level1">You should also be aware that many HTTP/1.1 servers do not have this feature enabled, so that when you attempt to get a range, you'll instead get the whole document. <p class="level1">FTP and SFTP range downloads only support the simple 'start-stop' syntax (optionally with one of the numbers omitted). FTP use depends on the extended FTP command SIZE. <p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="-R"></a><span class="nroffip">-R, --remote-time</span> +<p class="level1">When used, this will make curl attempt to figure out the timestamp of the remote file, and if that is available make the local file get that same timestamp. +<p class="level0"><a name="--random-file"></a><span class="nroffip">--random-file <file></span> +<p class="level1">(SSL) Specify the path name to file containing what will be considered as random data. The data is used to seed the random engine for SSL connections. See also the <a class="emphasis" href="#--egd-file">--egd-file</a> option. <p class="level0"><a name="--raw"></a><span class="nroffip">--raw</span> -<p class="level1">When used, it disables all internal HTTP decoding of content or transfer encodings and instead makes them passed on unaltered, raw. (Added in 7.16.2) -<p class="level0"><a name="-R--remote-time"></a><span class="nroffip">-R/--remote-time</span> -<p class="level1">When used, this will make libcurl attempt to figure out the timestamp of the remote file, and if that is available make the local file get that same timestamp. +<p class="level1">(HTTP) When used, it disables all internal HTTP decoding of content or transfer encodings and instead makes them passed on unaltered, raw. (Added in 7.16.2) +<p class="level0"><a name="--remote-name-all"></a><span class="nroffip">--remote-name-all</span> +<p class="level1">This option changes the default action for all given URLs to be dealt with as if <a class="emphasis" href="#-O">-O, --remote-name</a> were used for each one. So if you want to disable that for a specific URL after <a class="emphasis" href="#--remote-name-all">--remote-name-all</a> has been used, you must use "-o -" or <span Class="emphasis">--no-remote-name</span>. (Added in 7.19.0) <p class="level0"><a name="--resolve"></a><span class="nroffip">--resolve <host:port:address></span> <p class="level1">Provide a custom address for a specific host and port pair. Using this, you can make the curl requests(s) use a specified address and prevent the otherwise normally resolved address to be used. Consider it a sort of /etc/hosts alternative provided on the command line. The port number should be the number used for the specific protocol the host will be used for. It means you need several entries if you want to provide address for the same host but different ports. <p class="level1">This option can be used many times to add many host names to resolve. @@ -493,90 +540,181 @@ p.roffit { <p class="level0"><a name="--retry"></a><span class="nroffip">--retry <num></span> <p class="level1">If a transient error is returned when curl tries to perform a transfer, it will retry this number of times before giving up. Setting the number to 0 makes curl do no retries (which is the default). Transient error means either: a timeout, an FTP 4xx response code or an HTTP 5xx response code. <p class="level1">When curl is about to retry a transfer, it will first wait one second and then for all forthcoming retries it will double the waiting time until it reaches 10 minutes which then will be the delay between the rest of the retries. By using <a class="emphasis" href="#--retry-delay">--retry-delay</a> you disable this exponential backoff algorithm. See also <a class="emphasis" href="#--retry-max-time">--retry-max-time</a> to limit the total time allowed for retries. (Added in 7.12.3) -<p class="level1">If this option is used multiple times, the last occurrence decide the amount. +<p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--retry-delay"></a><span class="nroffip">--retry-delay <seconds></span> <p class="level1">Make curl sleep this amount of time before each retry when a transfer has failed with a transient error (it changes the default backoff time algorithm between retries). This option is only interesting if <a class="emphasis" href="#--retry">--retry</a> is also used. Setting this delay to zero will make curl use the default backoff time. (Added in 7.12.3) -<p class="level1">If this option is used multiple times, the last occurrence determines the amount. +<p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--retry-max-time"></a><span class="nroffip">--retry-max-time <seconds></span> -<p class="level1">The retry timer is reset before the first transfer attempt. Retries will be done as usual (see <a class="emphasis" href="#--retry">--retry</a>) as long as the timer hasn't reached this given limit. Notice that if the timer hasn't reached the limit, the request will be made and while performing, it may take longer than this given time period. To limit a single request´s maximum time, use <a class="emphasis" href="#-m--max-time">-m/--max-time</a>. Set this option to zero to not timeout retries. (Added in 7.12.3) -<p class="level1">If this option is used multiple times, the last occurrence determines the amount. -<p class="level0"><a name="-s--silent"></a><span class="nroffip">-s/--silent</span> -<p class="level1">Silent or quiet mode. Don't show progress meter or error messages. Makes Curl mute. -<p class="level0"><a name="-S--show-error"></a><span class="nroffip">-S/--show-error</span> -<p class="level1">When used with -s it makes curl show an error message if it fails. +<p class="level1">The retry timer is reset before the first transfer attempt. Retries will be done as usual (see <a class="emphasis" href="#--retry">--retry</a>) as long as the timer hasn't reached this given limit. Notice that if the timer hasn't reached the limit, the request will be made and while performing, it may take longer than this given time period. To limit a single request´s maximum time, use <a class="emphasis" href="#-m">-m, --max-time</a>. Set this option to zero to not timeout retries. (Added in 7.12.3) +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="-s"></a><span class="nroffip">-s, --silent</span> +<p class="level1">Silent or quiet mode. Don't show progress meter or error messages. Makes Curl mute. It will still output the data you ask for, potentially even to the terminal/stdout unless you redirect it. +<p class="level0"><a name="--sasl-ir"></a><span class="nroffip">--sasl-ir</span> +<p class="level1">Enable initial response in SASL authentication. (Added in 7.31.0) +<p class="level0"><a name="-S"></a><span class="nroffip">-S, --show-error</span> +<p class="level1">When used with <a class="emphasis" href="#-s">-s</a> it makes curl show an error message if it fails. +<p class="level0"><a name="--ssl"></a><span class="nroffip">--ssl</span> +<p class="level1">(FTP, POP3, IMAP, SMTP) Try to use SSL/TLS for the connection. Reverts to a non-secure connection if the server doesn't support SSL/TLS. See also <a class="emphasis" href="#--ftp-ssl-control">--ftp-ssl-control</a> and <a class="emphasis" href="#--ssl-reqd">--ssl-reqd</a> for different levels of encryption required. (Added in 7.20.0) +<p class="level1">This option was formerly known as <span Class="emphasis">--ftp-ssl</span> (Added in 7.11.0). That option name can still be used but will be removed in a future version. +<p class="level0"><a name="--ssl-reqd"></a><span class="nroffip">--ssl-reqd</span> +<p class="level1">(FTP, POP3, IMAP, SMTP) Require SSL/TLS for the connection. Terminates the connection if the server doesn't support SSL/TLS. (Added in 7.20.0) +<p class="level1">This option was formerly known as <span Class="emphasis">--ftp-ssl-reqd</span> (added in 7.15.5). That option name can still be used but will be removed in a future version. +<p class="level0"><a name="--ssl-allow-beast"></a><span class="nroffip">--ssl-allow-beast</span> +<p class="level1">(SSL) This option tells curl to not work around a security flaw in the SSL3 and TLS1.0 protocols known as BEAST. If this option isn't used, the SSL layer may use work-arounds known to cause interoperability problems with some older SSL implementations. WARNING: this option loosens the SSL security, and by using this flag you ask for exactly that. (Added in 7.25.0) <p class="level0"><a name="--socks4"></a><span class="nroffip">--socks4 <host[:port]></span> <p class="level1">Use the specified SOCKS4 proxy. If the port number is not specified, it is assumed at port 1080. (Added in 7.15.2) -<p class="level1">This option overrides any previous use of <a class="emphasis" href="#-x--proxy">-x/--proxy</a>, as they are mutually exclusive. +<p class="level1">This option overrides any previous use of <a class="emphasis" href="#-x">-x, --proxy</a>, as they are mutually exclusive. +<p class="level1">Since 7.21.7, this option is superfluous since you can specify a socks4 proxy with <a class="emphasis" href="#-x">-x, --proxy</a> using a socks4:// protocol prefix. <p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--socks4a"></a><span class="nroffip">--socks4a <host[:port]></span> <p class="level1">Use the specified SOCKS4a proxy. If the port number is not specified, it is assumed at port 1080. (Added in 7.18.0) -<p class="level1">This option overrides any previous use of <a class="emphasis" href="#-x--proxy">-x/--proxy</a>, as they are mutually exclusive. +<p class="level1">This option overrides any previous use of <a class="emphasis" href="#-x">-x, --proxy</a>, as they are mutually exclusive. +<p class="level1">Since 7.21.7, this option is superfluous since you can specify a socks4a proxy with <a class="emphasis" href="#-x">-x, --proxy</a> using a socks4a:// protocol prefix. <p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--socks5-hostname"></a><span class="nroffip">--socks5-hostname <host[:port]></span> <p class="level1">Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If the port number is not specified, it is assumed at port 1080. (Added in 7.18.0) -<p class="level1">This option overrides any previous use of <a class="emphasis" href="#-x--proxy">-x/--proxy</a>, as they are mutually exclusive. +<p class="level1">This option overrides any previous use of <a class="emphasis" href="#-x">-x, --proxy</a>, as they are mutually exclusive. +<p class="level1">Since 7.21.7, this option is superfluous since you can specify a socks5 hostname proxy with <a class="emphasis" href="#-x">-x, --proxy</a> using a socks5h:// protocol prefix. <p class="level1">If this option is used several times, the last one will be used. (This option was previously wrongly documented and used as --socks without the number appended.) <p class="level0"><a name="--socks5"></a><span class="nroffip">--socks5 <host[:port]></span> <p class="level1">Use the specified SOCKS5 proxy - but resolve the host name locally. If the port number is not specified, it is assumed at port 1080. -<p class="level1">This option overrides any previous use of <a class="emphasis" href="#-x--proxy">-x/--proxy</a>, as they are mutually exclusive. +<p class="level1">This option overrides any previous use of <a class="emphasis" href="#-x">-x, --proxy</a>, as they are mutually exclusive. +<p class="level1">Since 7.21.7, this option is superfluous since you can specify a socks5 proxy with <a class="emphasis" href="#-x">-x, --proxy</a> using a socks5:// protocol prefix. <p class="level1">If this option is used several times, the last one will be used. (This option was previously wrongly documented and used as --socks without the number appended.) <p class="level1">This option (as well as <a class="emphasis" href="#--socks4">--socks4</a>) does not work with IPV6, FTPS or LDAP. <p class="level0"><a name="--socks5-gssapi-service"></a><span class="nroffip">--socks5-gssapi-service <servicename></span> <p class="level1">The default service name for a socks server is rcmd/server-fqdn. This option allows you to change it. -<p class="level1">Examples: --socks5 proxy-name <a class="emphasis" href="#--socks5-gssapi-service">--socks5-gssapi-service</a> sockd would use sockd/proxy-name --socks5 proxy-name <a class="emphasis" href="#--socks5-gssapi-service">--socks5-gssapi-service</a> sockd/real-name would use sockd/real-name for cases where the proxy-name does not match the princpal name. (Added in 7.19.4). +<p class="level1">Examples: --socks5 proxy-name <a class="emphasis" href="#--socks5-gssapi-service">--socks5-gssapi-service</a> sockd would use sockd/proxy-name --socks5 proxy-name <a class="emphasis" href="#--socks5-gssapi-service">--socks5-gssapi-service</a> sockd/real-name would use sockd/real-name for cases where the proxy-name does not match the principal name. (Added in 7.19.4). <p class="level0"><a name="--socks5-gssapi-nec"></a><span class="nroffip">--socks5-gssapi-nec</span> -<p class="level1">As part of the gssapi negotiation a protection mode is negotiated. The rfc1961 says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. The option <a class="emphasis" href="#--socks5-gssapi-nec">--socks5-gssapi-nec</a> allows the unprotected exchange of the protection mode negotiation. (Added in 7.19.4). +<p class="level1">As part of the gssapi negotiation a protection mode is negotiated. <a href="http://www.ietf.org/rfc/rfc1961.txt">RFC 1961</a> says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. The option <a class="emphasis" href="#--socks5-gssapi-nec">--socks5-gssapi-nec</a> allows the unprotected exchange of the protection mode negotiation. (Added in 7.19.4). <p class="level0"><a name="--stderr"></a><span class="nroffip">--stderr <file></span> -<p class="level1">Redirect all writes to stderr to the specified file instead. If the file name is a plain '-', it is instead written to stdout. This option has no point when you're using a shell with decent redirecting capabilities. +<p class="level1">Redirect all writes to stderr to the specified file instead. If the file name is a plain '-', it is instead written to stdout. <p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="--tcp-nodelay"></a><span class="nroffip">--tcp-nodelay</span> -<p class="level1">Turn on the TCP_NODELAY option. See the <span Class="emphasis">curl_easy_setopt(3)</span> man page for details about this option. (Added in 7.11.2) -<p class="level0"><a name="-t--telnet-option"></a><span class="nroffip">-t/--telnet-option <OPT=val></span> +<p class="level0"><a name="-t"></a><span class="nroffip">-t, --telnet-option <OPT=val></span> <p class="level1">Pass options to the telnet protocol. Supported options are: <p class="level1">TTYPE=<term> Sets the terminal type. <p class="level1">XDISPLOC=<X display> Sets the X display location. <p class="level1">NEW_ENV=<var,val> Sets an environment variable. -<p class="level0"><a name="--tftp-blksize"></a><span class="nroffip">--tftp-blksize <value></span> -<p class="level1">(TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size that curl will try to use when tranferring data to or from a TFTP server. By default 512 bytes will be used. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level1">(Added in 7.20.0) -<p class="level0"><a name="-T--upload-file"></a><span class="nroffip">-T/--upload-file <file></span> -<p class="level1">This transfers the specified local file to the remote URL. If there is no file part in the specified URL, Curl will append the local file name. NOTE that you must use a trailing / on the last directory to really prove to Curl that there is no file name or curl will think that your last directory name is the remote file name to use. That will most likely cause the upload operation to fail. If this is used on a HTTP(S) server, the PUT command will be used. +<p class="level0"><a name="-T"></a><span class="nroffip">-T, --upload-file <file></span> +<p class="level1">This transfers the specified local file to the remote URL. If there is no file part in the specified URL, Curl will append the local file name. NOTE that you must use a trailing / on the last directory to really prove to Curl that there is no file name or curl will think that your last directory name is the remote file name to use. That will most likely cause the upload operation to fail. If this is used on an HTTP(S) server, the PUT command will be used. <p class="level1">Use the file name "-" (a single dash) to use stdin instead of a given file. Alternately, the file name "." (a single period) may be specified instead of "-" to use stdin in non-blocking mode to allow reading server output while stdin is being uploaded. <p class="level1">You can specify one -T for each URL on the command line. Each -T + URL pair specifies what to upload and to where. curl also supports "globbing" of the -T argument, meaning that you can upload multiple files to a single URL by using the same URL globbing style supported in the URL, like this: <p class="level1">curl -T "{file1,file2}" <a href="http://www.uploadtothissite.com">http://www.uploadtothissite.com</a> <p class="level1">or even <p class="level1">curl -T "img[1-1000].png" <a href="ftp://ftp.picturemania.com/upload/">ftp://ftp.picturemania.com/upload/</a> +<p class="level0"><a name="--tcp-nodelay"></a><span class="nroffip">--tcp-nodelay</span> +<p class="level1">Turn on the TCP_NODELAY option. See the <span Class="emphasis">curl_easy_setopt(3)</span> man page for details about this option. (Added in 7.11.2) +<p class="level0"><a name="--tftp-blksize"></a><span class="nroffip">--tftp-blksize <value></span> +<p class="level1">(TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size that curl will try to use when transferring data to or from a TFTP server. By default 512 bytes will be used. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level1">(Added in 7.20.0) +<p class="level0"><a name="--tlsauthtype"></a><span class="nroffip">--tlsauthtype <authtype></span> +<p class="level1">Set TLS authentication type. Currently, the only supported option is "SRP", for TLS-SRP (<a href="http://www.ietf.org/rfc/rfc5054.txt">RFC 5054</a>). If <a class="emphasis" href="#--tlsuser">--tlsuser</a> and <a class="emphasis" href="#--tlspassword">--tlspassword</a> are specified but <a class="emphasis" href="#--tlsauthtype">--tlsauthtype</a> is not, then this option defaults to "SRP". (Added in 7.21.4) +<p class="level0"><a name="--tlsuser"></a><span class="nroffip">--tlsuser <user></span> +<p class="level1">Set username for use with the TLS authentication method specified with <a class="emphasis" href="#--tlsauthtype">--tlsauthtype</a>. Requires that <a class="emphasis" href="#--tlspassword">--tlspassword</a> also be set. (Added in 7.21.4) +<p class="level0"><a name="--tlspassword"></a><span class="nroffip">--tlspassword <password></span> +<p class="level1">Set password for use with the TLS authentication method specified with <a class="emphasis" href="#--tlsauthtype">--tlsauthtype</a>. Requires that <a class="emphasis" href="#--tlsuser">--tlsuser</a> also be set. (Added in 7.21.4) +<p class="level0"><a name="--tr-encoding"></a><span class="nroffip">--tr-encoding</span> +<p class="level1">(HTTP) Request a compressed Transfer-Encoding response using one of the algorithms curl supports, and uncompress the data while receiving it. +<p class="level1">(Added in 7.21.6) <p class="level0"><a name="--trace"></a><span class="nroffip">--trace <file></span> <p class="level1">Enables a full trace dump of all incoming and outgoing data, including descriptive information, to the given output file. Use "-" as filename to have the output sent to stdout. -<p class="level1">This option overrides previous uses of <a class="emphasis" href="#-v--verbose">-v/--verbose</a> or <a class="emphasis" href="#--trace-ascii">--trace-ascii</a>. +<p class="level1">This option overrides previous uses of <a class="emphasis" href="#-v">-v, --verbose</a> or <a class="emphasis" href="#--trace-ascii">--trace-ascii</a>. <p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--trace-ascii"></a><span class="nroffip">--trace-ascii <file></span> <p class="level1">Enables a full trace dump of all incoming and outgoing data, including descriptive information, to the given output file. Use "-" as filename to have the output sent to stdout. <p class="level1">This is very similar to <a class="emphasis" href="#--trace">--trace</a>, but leaves out the hex part and only shows the ASCII part of the dump. It makes smaller output that might be easier to read for untrained humans. -<p class="level1">This option overrides previous uses of <a class="emphasis" href="#-v--verbose">-v/--verbose</a> or <a class="emphasis" href="#--trace">--trace</a>. +<p class="level1">This option overrides previous uses of <a class="emphasis" href="#-v">-v, --verbose</a> or <a class="emphasis" href="#--trace">--trace</a>. <p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--trace-time"></a><span class="nroffip">--trace-time</span> <p class="level1">Prepends a time stamp to each trace or verbose line that curl displays. (Added in 7.14.0) -<p class="level0"><a name="-u--user"></a><span class="nroffip">-u/--user <user:password></span> -<p class="level1">Specify the user name and password to use for server authentication. Overrides <a class="emphasis" href="#-n--netrc">-n/--netrc</a> and <a class="emphasis" href="#--netrc-optional">--netrc-optional</a>. +<p class="level0"><a name="-u"></a><span class="nroffip">-u, --user <user:password></span> +<p class="level1">Specify the user name and password to use for server authentication. Overrides <a class="emphasis" href="#-n">-n, --netrc</a> and <a class="emphasis" href="#--netrc-optional">--netrc-optional</a>. <p class="level1">If you just give the user name (without entering a colon) curl will prompt for a password. <p class="level1">If you use an SSPI-enabled curl binary and do NTLM authentication, you can force curl to pick up the user name and password from your environment by simply specifying a single colon with this option: "-u :". <p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-U--proxy-user"></a><span class="nroffip">-U/--proxy-user <user:password></span> +<p class="level0"><a name="-U"></a><span class="nroffip">-U, --proxy-user <user:password></span> <p class="level1">Specify the user name and password to use for proxy authentication. <p class="level1">If you use an SSPI-enabled curl binary and do NTLM authentication, you can force curl to pick up the user name and password from your environment by simply specifying a single colon with this option: "-U :". <p class="level1">If this option is used several times, the last one will be used. <p class="level0"><a name="--url"></a><span class="nroffip">--url <URL></span> <p class="level1">Specify a URL to fetch. This option is mostly handy when you want to specify URL(s) in a config file. -<p class="level1">This option may be used any number of times. To control where this URL is written, use the <a class="emphasis" href="#-o--output">-o/--output</a> or the <a class="emphasis" href="#-O--remote-name">-O/--remote-name</a> options. -<p class="level0"><a name="-v--verbose"></a><span class="nroffip">-v/--verbose</span> +<p class="level1">This option may be used any number of times. To control where this URL is written, use the <a class="emphasis" href="#-o">-o, --output</a> or the <a class="emphasis" href="#-O">-O, --remote-name</a> options. +<p class="level0"><a name="-v"></a><span class="nroffip">-v, --verbose</span> <p class="level1">Makes the fetching more verbose/talkative. Mostly useful for debugging. A line starting with '>' means "header data" sent by curl, '<' means "header data" received by curl that is hidden in normal cases, and a line starting with '*' means additional info provided by curl. -<p class="level1">Note that if you only want HTTP headers in the output, <a class="emphasis" href="#-i--include">-i/--include</a> might be the option you're looking for. +<p class="level1">Note that if you only want HTTP headers in the output, <a class="emphasis" href="#-i">-i, --include</a> might be the option you're looking for. <p class="level1">If you think this option still doesn't give you enough details, consider using <a class="emphasis" href="#--trace">--trace</a> or <a class="emphasis" href="#--trace-ascii">--trace-ascii</a> instead. <p class="level1">This option overrides previous uses of <a class="emphasis" href="#--trace-ascii">--trace-ascii</a> or <a class="emphasis" href="#--trace">--trace</a>. -<p class="level1">Use <span Class="emphasis">-S/--silent</span> to make curl quiet. -<p class="level0"><a name="-V--version"></a><span class="nroffip">-V/--version</span> +<p class="level1">Use <a class="emphasis" href="#-s">-s, --silent</a> to make curl quiet. +<p class="level0"><a name="-w"></a><span class="nroffip">-w, --write-out <format></span> +<p class="level1">Defines what to display on stdout after a completed and successful operation. The format is a string that may contain plain text mixed with any number of variables. The string can be specified as "string", to get read from a particular file you specify it "@filename" and to tell curl to read the format from stdin you write "@-". +<p class="level1">The variables present in the output format will be substituted by the value or text that curl thinks fit, as described below. All variables are specified as %{variable_name} and to output a normal % you just write them as %%. You can output a newline by using \n, a carriage return with \r and a tab space with \t. +<p class="level1"><span Class="bold">NOTE:</span> The %-symbol is a special symbol in the win32-environment, where all occurrences of % must be doubled when using this option. +<p class="level1">The variables available are: +<p class="level2"> +<p class="level2"><span Class="bold">content_type</span> The Content-Type of the requested document, if there was any. +<p class="level2"><span Class="bold">filename_effective</span> The ultimate filename that curl writes out to. This is only meaningful if curl is told to write to a file with the <span Class="emphasis">--remote-name</span> or <span Class="emphasis">--output</span> option. It's most useful in combination with the <span Class="emphasis">--remote-header-name</span> option. (Added in 7.25.1) +<p class="level2"><span Class="bold">ftp_entry_path</span> The initial path curl ended up in when logging on to the remote FTP server. (Added in 7.15.4) +<p class="level2"><span Class="bold">http_code</span> The numerical response code that was found in the last retrieved HTTP(S) or FTP(s) transfer. In 7.18.2 the alias <span Class="bold">response_code</span> was added to show the same info. +<p class="level2"><span Class="bold">http_connect</span> The numerical code that was found in the last response (from a proxy) to a curl CONNECT request. (Added in 7.12.4) +<p class="level2"><span Class="bold">local_ip</span> The IP address of the local end of the most recently done connection - can be either IPv4 or IPv6 (Added in 7.29.0) +<p class="level2"><span Class="bold">local_port</span> The local port number of the most recently done connection (Added in 7.29.0) +<p class="level2"><span Class="bold">num_connects</span> Number of new connects made in the recent transfer. (Added in 7.12.3) +<p class="level2"><span Class="bold">num_redirects</span> Number of redirects that were followed in the request. (Added in 7.12.3) +<p class="level2"><span Class="bold">redirect_url</span> When an HTTP request was made without -L to follow redirects, this variable will show the actual URL a redirect <span Class="emphasis">would</span> take you to. (Added in 7.18.2) +<p class="level2"><span Class="bold">remote_ip</span> The remote IP address of the most recently done connection - can be either IPv4 or IPv6 (Added in 7.29.0) +<p class="level2"><span Class="bold">remote_port</span> The remote port number of the most recently done connection (Added in 7.29.0) +<p class="level2"><span Class="bold">size_download</span> The total amount of bytes that were downloaded. +<p class="level2"><span Class="bold">size_header</span> The total amount of bytes of the downloaded headers. +<p class="level2"><span Class="bold">size_request</span> The total amount of bytes that were sent in the HTTP request. +<p class="level2"><span Class="bold">size_upload</span> The total amount of bytes that were uploaded. +<p class="level2"><span Class="bold">speed_download</span> The average download speed that curl measured for the complete download. Bytes per second. +<p class="level2"><span Class="bold">speed_upload</span> The average upload speed that curl measured for the complete upload. Bytes per second. +<p class="level2"><span Class="bold">ssl_verify_result</span> The result of the SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.19.0) +<p class="level2"><span Class="bold">time_appconnect</span> The time, in seconds, it took from the start until the SSL/SSH/etc connect/handshake to the remote host was completed. (Added in 7.19.0) +<p class="level2"><span Class="bold">time_connect</span> The time, in seconds, it took from the start until the TCP connect to the remote host (or proxy) was completed. +<p class="level2"><span Class="bold">time_namelookup</span> The time, in seconds, it took from the start until the name resolving was completed. +<p class="level2"><span Class="bold">time_pretransfer</span> The time, in seconds, it took from the start until the file transfer was just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. +<p class="level2"><span Class="bold">time_redirect</span> The time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before the final transaction was started. time_redirect shows the complete execution time for multiple redirections. (Added in 7.12.3) +<p class="level2"><span Class="bold">time_starttransfer</span> The time, in seconds, it took from the start until the first byte was just about to be transferred. This includes time_pretransfer and also the time the server needed to calculate the result. +<p class="level2"><span Class="bold">time_total</span> The total time, in seconds, that the full operation lasted. The time will be displayed with millisecond resolution. +<p class="level2"><span Class="bold">url_effective</span> The URL that was fetched last. This is most meaningful if you've told curl to follow location: headers. +<p class="level1"> +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="-x"></a><span class="nroffip">-x, --proxy <[protocol://][user:password@]proxyhost[:port]></span> +<p class="level1">Use the specified HTTP proxy. If the port number is not specified, it is assumed at port 1080. +<p class="level1">This option overrides existing environment variables that set the proxy to use. If there's an environment variable setting a proxy, you can set proxy to "" to override it. +<p class="level1">All operations that are performed over an HTTP proxy will transparently be converted to HTTP. It means that certain protocol specific operations might not be available. This is not the case if you can tunnel through the proxy, as one with the <a class="emphasis" href="#-p">-p, --proxytunnel</a> option. +<p class="level1">User and password that might be provided in the proxy string are URL decoded by curl. This allows you to pass in special characters such as @ by using %40 or pass in a colon with %3a. +<p class="level1">The proxy host can be specified the exact same way as the proxy environment variables, including the protocol prefix (http://) and the embedded user + password. +<p class="level1">From 7.21.7, the proxy string may be specified with a protocol:// prefix to specify alternative proxy protocols. Use socks4://, socks4a://, socks5:// or socks5h:// to request the specific SOCKS version to be used. No protocol specified, http:// and all others will be treated as HTTP proxies. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="-X"></a><span class="nroffip">-X, --request <command></span> +<p class="level1">(HTTP) Specifies a custom request method to use when communicating with the HTTP server. The specified request will be used instead of the method otherwise used (which defaults to GET). Read the HTTP 1.1 specification for details and explanations. Common additional HTTP requests include PUT and DELETE, but related technologies like WebDAV offers PROPFIND, COPY, MOVE and more. +<p class="level1">Normally you don't need this option. All sorts of GET, HEAD, POST and PUT requests are rather invoked by using dedicated command line options. +<p class="level1">This option only changes the actual word used in the HTTP request, it does not alter the way curl behaves. So for example if you want to make a proper HEAD request, using -X HEAD will not suffice. You need to use the <a class="emphasis" href="#-I">-I, --head</a> option. +<p class="level1">(FTP) Specifies a custom FTP command to use instead of LIST when doing file lists with FTP. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level1"> +<p class="level0"><a name="--xattr"></a><span class="nroffip">--xattr</span> +<p class="level1">When saving output to a file, this option tells curl to store certain file metadata in extended file attributes. Currently, the URL is stored in the xdg.origin.url attribute and, for HTTP, the content type is stored in the mime_type attribute. If the file system does not support extended attributes, a warning is issued. +<p class="level1"> +<p class="level0"><a name="-y"></a><span class="nroffip">-y, --speed-time <time></span> +<p class="level1">If a download is slower than speed-limit bytes per second during a speed-time period, the download gets aborted. If speed-time is used, the default speed-limit will be 1 unless set with <a class="emphasis" href="#-Y">-Y</a>. +<p class="level1">This option controls transfers and thus will not affect slow connects etc. If this is a concern for you, try the <a class="emphasis" href="#--connect-timeout">--connect-timeout</a> option. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="-Y"></a><span class="nroffip">-Y, --speed-limit <speed></span> +<p class="level1">If a download is slower than this given speed (in bytes per second) for speed-time seconds it gets aborted. speed-time is set with <a class="emphasis" href="#-y">-y</a> and is 30 if not set. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="-z"></a><span class="nroffip">-z, --time-cond <date expression>|<file></span> +<p class="level1">(HTTP/FTP) Request a file that has been modified later than the given time and date, or one that has been modified before that time. The <date expression> can be all sorts of date strings or if it doesn't match any internal ones, it is taken as a filename and tries to get the modification date (mtime) from <file> instead. See the <span Class="emphasis">curl_getdate(3)</span> man pages for date expression details. +<p class="level1">Start the date expression with a dash (-) to make it request for a document that is older than the given date/time, default is a document that is newer than the specified date/time. +<p class="level1">If this option is used several times, the last one will be used. +<p class="level0"><a name="-h"></a><span class="nroffip">-h, --help</span> +<p class="level1">Usage help. +<p class="level0"><a name="-M"></a><span class="nroffip">-M, --manual</span> +<p class="level1">Manual. Display the huge help text. +<p class="level0"><a name="-V"></a><span class="nroffip">-V, --version</span> <p class="level1">Displays information about curl and the libcurl version it uses. <p class="level1">The first line includes the full version of curl, libcurl and other 3rd party libraries linked with the executable. <p class="level1">The second line (starts with "Protocols:") shows all protocols that libcurl reports to support. @@ -606,88 +744,37 @@ p.roffit { <p class="level2">This curl supports IDN - international domain names. <p class="level1"><a name="SSPI"></a><span class="nroffip">SSPI</span> <p class="level2">SSPI is supported. If you use NTLM and set a blank user name, curl will authenticate with your current user and password. -<p class="level1"> -<p class="level0"><a name="-w--write-out"></a><span class="nroffip">-w/--write-out <format></span> -<p class="level1">Defines what to display on stdout after a completed and successful operation. The format is a string that may contain plain text mixed with any number of variables. The string can be specified as "string", to get read from a particular file you specify it "@filename" and to tell curl to read the format from stdin you write "@-". -<p class="level1">The variables present in the output format will be substituted by the value or text that curl thinks fit, as described below. All variables are specified as %{variable_name} and to output a normal % you just write them as %%. You can output a newline by using \n, a carriage return with \r and a tab space with \t. -<p class="level1"><span Class="bold">NOTE:</span> The %-symbol is a special symbol in the win32-environment, where all occurrences of % must be doubled when using this option. -<p class="level1">The variables available at this point are: -<p class="level2"> -<p class="level2"><span Class="bold">url_effective</span> The URL that was fetched last. This is most meaningful if you've told curl to follow location: headers. -<p class="level2"><span Class="bold">http_code</span> The numerical response code that was found in the last retrieved HTTP(S) or FTP(s) transfer. In 7.18.2 the alias <span Class="bold">response_code</span> was added to show the same info. -<p class="level2"><span Class="bold">http_connect</span> The numerical code that was found in the last response (from a proxy) to a curl CONNECT request. (Added in 7.12.4) -<p class="level2"><span Class="bold">time_total</span> The total time, in seconds, that the full operation lasted. The time will be displayed with millisecond resolution. -<p class="level2"><span Class="bold">time_namelookup</span> The time, in seconds, it took from the start until the name resolving was completed. -<p class="level2"><span Class="bold">time_connect</span> The time, in seconds, it took from the start until the TCP connect to the remote host (or proxy) was completed. -<p class="level2"><span Class="bold">time_appconnect</span> The time, in seconds, it took from the start until the SSL/SSH/etc connect/handshake to the remote host was completed. (Added in 7.19.0) -<p class="level2"><span Class="bold">time_pretransfer</span> The time, in seconds, it took from the start until the file transfer was just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. -<p class="level2"><span Class="bold">time_redirect</span> The time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before the final transaction was started. time_redirect shows the complete execution time for multiple redirections. (Added in 7.12.3) -<p class="level2"><span Class="bold">time_starttransfer</span> The time, in seconds, it took from the start until the first byte was just about to be transferred. This includes time_pretransfer and also the time the server needed to calculate the result. -<p class="level2"><span Class="bold">size_download</span> The total amount of bytes that were downloaded. -<p class="level2"><span Class="bold">size_upload</span> The total amount of bytes that were uploaded. -<p class="level2"><span Class="bold">size_header</span> The total amount of bytes of the downloaded headers. -<p class="level2"><span Class="bold">size_request</span> The total amount of bytes that were sent in the HTTP request. -<p class="level2"><span Class="bold">speed_download</span> The average download speed that curl measured for the complete download. Bytes per second. -<p class="level2"><span Class="bold">speed_upload</span> The average upload speed that curl measured for the complete upload. Bytes per second. -<p class="level2"><span Class="bold">content_type</span> The Content-Type of the requested document, if there was any. -<p class="level2"><span Class="bold">num_connects</span> Number of new connects made in the recent transfer. (Added in 7.12.3) -<p class="level2"><span Class="bold">num_redirects</span> Number of redirects that were followed in the request. (Added in 7.12.3) -<p class="level2"><span Class="bold">redirect_url</span> When a HTTP request was made without -L to follow redirects, this variable will show the actual URL a redirect <span Class="emphasis">would</span> take you to. (Added in 7.18.2) -<p class="level2"><span Class="bold">ftp_entry_path</span> The initial path libcurl ended up in when logging on to the remote FTP server. (Added in 7.15.4) -<p class="level2"><span Class="bold">ssl_verify_result</span> The result of the SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.19.0) -<p class="level1"> -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-x--proxy"></a><span class="nroffip">-x/--proxy <proxyhost[:port]></span> -<p class="level1">Use the specified HTTP proxy. If the port number is not specified, it is assumed at port 1080. -<p class="level1">This option overrides existing environment variables that set the proxy to use. If there's an environment variable setting a proxy, you can set proxy to "" to override it. -<p class="level1"><span Class="bold">Note</span> that all operations that are performed over a HTTP proxy will transparently be converted to HTTP. It means that certain protocol specific operations might not be available. This is not the case if you can tunnel through the proxy, as done with the <a class="emphasis" href="#-p--proxytunnel">-p/--proxytunnel</a> option. -<p class="level1">Starting with 7.14.1, the proxy host can be specified the exact same way as the proxy environment variables, including the protocol prefix (http://) and the embedded user + password. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-X--request"></a><span class="nroffip">-X/--request <command></span> -<p class="level1">(HTTP) Specifies a custom request method to use when communicating with the HTTP server. The specified request will be used instead of the method otherwise used (which defaults to GET). Read the HTTP 1.1 specification for details and explanations. Common additional HTTP requests include PUT and DELETE, but related technologies like WebDAV offers PROPFIND, COPY, MOVE and more. -<p class="level1">(FTP) Specifies a custom FTP command to use instead of LIST when doing file lists with FTP. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-y--speed-time"></a><span class="nroffip">-y/--speed-time <time></span> -<p class="level1">If a download is slower than speed-limit bytes per second during a speed-time period, the download gets aborted. If speed-time is used, the default speed-limit will be 1 unless set with -Y. -<p class="level1">This option controls transfers and thus will not affect slow connects etc. If this is a concern for you, try the <a class="emphasis" href="#--connect-timeout">--connect-timeout</a> option. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-Y--speed-limit"></a><span class="nroffip">-Y/--speed-limit <speed></span> -<p class="level1">If a download is slower than this given speed (in bytes per second) for speed-time seconds it gets aborted. speed-time is set with -y and is 30 if not set. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-z--time-cond"></a><span class="nroffip">-z/--time-cond <date expression></span> -<p class="level1">(HTTP/FTP) Request a file that has been modified later than the given time and date, or one that has been modified before that time. The date expression can be all sorts of date strings or if it doesn't match any internal ones, it tries to get the time from a given file name instead! See the <span Class="emphasis">curl_getdate(3)</span> man pages for date expression details. -<p class="level1">Start the date expression with a dash (-) to make it request for a document that is older than the given date/time, default is a document that is newer than the specified date/time. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="--max-redirs"></a><span class="nroffip">--max-redirs <num></span> -<p class="level1">Set maximum number of redirection-followings allowed. If <a class="emphasis" href="#-L--location">-L/--location</a> is used, this option can be used to prevent curl from following redirections "in absurdum". By default, the limit is set to 50 redirections. Set this option to -1 to make it limitless. -<p class="level1">If this option is used several times, the last one will be used. -<p class="level0"><a name="-0--http10"></a><span class="nroffip">-0/--http1.0</span> -<p class="level1">(HTTP) Forces curl to issue its requests using HTTP 1.0 instead of using its internally preferred: HTTP 1.1. -<p class="level0"><a name="-1--tlsv1"></a><span class="nroffip">-1/--tlsv1</span> -<p class="level1">(SSL) Forces curl to use TLS version 1 when negotiating with a remote TLS server. -<p class="level0"><a name="-2--sslv2"></a><span class="nroffip">-2/--sslv2</span> -<p class="level1">(SSL) Forces curl to use SSL version 2 when negotiating with a remote SSL server. -<p class="level0"><a name="-3--sslv3"></a><span class="nroffip">-3/--sslv3</span> -<p class="level1">(SSL) Forces curl to use SSL version 3 when negotiating with a remote SSL server. -<p class="level0"><a name="-4--ipv4"></a><span class="nroffip">-4/--ipv4</span> -<p class="level1">If libcurl is capable of resolving an address to multiple IP versions (which it is if it is IPv6-capable), this option tells libcurl to resolve names to IPv4 addresses only. -<p class="level0"><a name="-6--ipv6"></a><span class="nroffip">-6/--ipv6</span> -<p class="level1">If libcurl is capable of resolving an address to multiple IP versions (which it is if it is IPv6-capable), this option tells libcurl to resolve names to IPv6 addresses only. -<p class="level0"><a name="---progress-bar"></a><span class="nroffip">-#/--progress-bar</span> -<p class="level1">Make curl display progress information as a progress bar instead of the default statistics. <a name="FILES"></a><h2 class="nroffsh">FILES</h2> +<p class="level1"><a name="TLS-SRP"></a><span class="nroffip">TLS-SRP</span> +<p class="level2">SRP (Secure Remote Password) authentication is supported for TLS. +<p class="level1"><a name="Metalink"></a><span class="nroffip">Metalink</span> +<p class="level2">This curl supports Metalink (both version 3 and 4 (<a href="http://www.ietf.org/rfc/rfc5854.txt">RFC 5854</a>)), which describes mirrors and hashes. curl will use mirrors for failover if there are errors (such as the file or server not being available). +<p class="level1"><a name="FILES"></a><h2 class="nroffsh">FILES</h2> <p class="level0"><span Class="emphasis">~/.curlrc</span> -<p class="level1">Default config file, see <a class="emphasis" href="#-K--config">-K/--config</a> for details. <a name="ENVIRONMENT"></a><h2 class="nroffsh">ENVIRONMENT</h2> +<p class="level1">Default config file, see <a class="emphasis" href="#-K">-K, --config</a> for details. <a name="ENVIRONMENT"></a><h2 class="nroffsh">ENVIRONMENT</h2> <p class="level0">The environment variables can be specified in lower case or upper case. The lower case version has precedence. http_proxy is an exception as it is only available in lower case. +<p class="level0">Using an environment variable to set the proxy has the same effect as using the <span Class="emphasis">--proxy</span> option. +<p class="level0"> <p class="level0"><a name="httpproxy"></a><span class="nroffip">http_proxy [protocol://]<host>[:port]</span> <p class="level1">Sets the proxy server to use for HTTP. <p class="level0"><a name="HTTPSPROXY"></a><span class="nroffip">HTTPS_PROXY [protocol://]<host>[:port]</span> <p class="level1">Sets the proxy server to use for HTTPS. -<p class="level0"><a name="FTPPROXY"></a><span class="nroffip">FTP_PROXY [protocol://]<host>[:port]</span> -<p class="level1">Sets the proxy server to use for FTP. +<p class="level0"><a name="url-protocolPROXY"></a><span class="nroffip">[url-protocol]_PROXY [protocol://]<host>[:port]</span> +<p class="level1">Sets the proxy server to use for [url-protocol], where the protocol is a protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP, SMTP, LDAP etc. <p class="level0"><a name="ALLPROXY"></a><span class="nroffip">ALL_PROXY [protocol://]<host>[:port]</span> <p class="level1">Sets the proxy server to use if no protocol-specific proxy is set. <p class="level0"><a name="NOPROXY"></a><span class="nroffip">NO_PROXY <comma-separated list of hosts></span> -<p class="level1">list of host names that shouldn't go through any proxy. If set to a asterisk '*' only, it matches all hosts. <a name="EXIT"></a><h2 class="nroffsh">EXIT CODES</h2> +<p class="level1">list of host names that shouldn't go through any proxy. If set to a asterisk '*' only, it matches all hosts. <a name="PROXY"></a><h2 class="nroffsh">PROXY PROTOCOL PREFIXES</h2> +<p class="level0">Since curl version 7.21.7, the proxy string may be specified with a protocol:// prefix to specify alternative proxy protocols. +<p class="level0">If no protocol is specified in the proxy string or if the string doesn't match a supported one, the proxy will be treated as an HTTP proxy. +<p class="level0">The supported proxy protocol prefixes are as follows: +<p class="level0"><a name="socks4"></a><span class="nroffip">socks4://</span> +<p class="level1">Makes it the equivalent of <a class="emphasis" href="#--socks4">--socks4</a> +<p class="level0"><a name="socks4a"></a><span class="nroffip">socks4a://</span> +<p class="level1">Makes it the equivalent of <a class="emphasis" href="#--socks4a">--socks4a</a> +<p class="level0"><a name="socks5"></a><span class="nroffip">socks5://</span> +<p class="level1">Makes it the equivalent of <a class="emphasis" href="#--socks5">--socks5</a> +<p class="level0"><a name="socks5h"></a><span class="nroffip">socks5h://</span> +<p class="level1">Makes it the equivalent of <a class="emphasis" href="#--socks5-hostname">--socks5-hostname</a> <a name="EXIT"></a><h2 class="nroffsh">EXIT CODES</h2> <p class="level0">There are a bunch of different error codes and their corresponding error messages that may appear during bad conditions. At the time of this writing, the exit codes are: <p class="level0"><a name="1"></a><span class="nroffip">1</span> <p class="level1">Unsupported protocol. This build of curl has no support for this protocol. @@ -695,6 +782,8 @@ p.roffit { <p class="level1">Failed to initialize. <p class="level0"><a name="3"></a><span class="nroffip">3</span> <p class="level1">URL malformed. The syntax was not correct. +<p class="level0"><a name="4"></a><span class="nroffip">4</span> +<p class="level1">A feature or option that was needed to perform the desired request was not enabled or was explicitly disabled at build-time. To make curl able to do this, you probably need another build of libcurl! <p class="level0"><a name="5"></a><span class="nroffip">5</span> <p class="level1">Couldn't resolve proxy. The given proxy host could not be resolved. <p class="level0"><a name="6"></a><span class="nroffip">6</span> @@ -722,7 +811,7 @@ p.roffit { <p class="level0"><a name="21"></a><span class="nroffip">21</span> <p class="level1">FTP quote error. A quote command returned error from the server. <p class="level0"><a name="22"></a><span class="nroffip">22</span> -<p class="level1">HTTP page not retrieved. The requested url was not found or returned another error with the HTTP error code being 400 or above. This return code only appears if <a class="emphasis" href="#-f--fail">-f/--fail</a> is used. +<p class="level1">HTTP page not retrieved. The requested url was not found or returned another error with the HTTP error code being 400 or above. This return code only appears if <a class="emphasis" href="#-f">-f, --fail</a> is used. <p class="level0"><a name="23"></a><span class="nroffip">23</span> <p class="level1">Write error. Curl couldn't write data to a local filesystem or similar. <p class="level0"><a name="25"></a><span class="nroffip">25</span> @@ -762,11 +851,11 @@ p.roffit { <p class="level0"><a name="47"></a><span class="nroffip">47</span> <p class="level1">Too many redirects. When following redirects, curl hit the maximum amount. <p class="level0"><a name="48"></a><span class="nroffip">48</span> -<p class="level1">Unknown TELNET option specified. +<p class="level1">Unknown option specified to libcurl. This indicates that you passed a weird option to curl that was passed on to libcurl and rejected. Read up in the manual! <p class="level0"><a name="49"></a><span class="nroffip">49</span> <p class="level1">Malformed telnet option. <p class="level0"><a name="51"></a><span class="nroffip">51</span> -<p class="level1">The peer's SSL certificate or SSH MD5 fingerprint was not ok. +<p class="level1">The peer's SSL certificate or SSH MD5 fingerprint was not OK. <p class="level0"><a name="52"></a><span class="nroffip">52</span> <p class="level1">The server didn't reply anything, which here is considered an error. <p class="level0"><a name="53"></a><span class="nroffip">53</span> @@ -842,7 +931,6 @@ p.roffit { <p class="level0">Daniel Stenberg is the main author, but the whole list of contributors is found in the separate THANKS file. <a name="WWW"></a><h2 class="nroffsh">WWW</h2> <p class="level0"><a href="http://curl.haxx.se">http://curl.haxx.se</a> <a name="FTP"></a><h2 class="nroffsh">FTP</h2> <p class="level0"><a href="ftp://ftp.sunet.se/pub/www/utilities/curl/">ftp://ftp.sunet.se/pub/www/utilities/curl/</a> <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> -<p class="level0"><span Class="manpage">ftp (1)</span> <span Class="manpage">wget (1)</span> -<p class="level0"><p class="roffit"> +<p class="level0"><span Class="manpage">ftp (1)</span> <span Class="manpage">wget (1)</span> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/curl.pdf b/docs/curl.pdf Binary files differindex efb5ee1f0..c81dd370d 100644 --- a/docs/curl.pdf +++ b/docs/curl.pdf diff --git a/docs/examples/10-at-a-time.c b/docs/examples/10-at-a-time.c index b215cbfd4..a85fff46f 100644 --- a/docs/examples/10-at-a-time.c +++ b/docs/examples/10-at-a-time.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Example application source code using the multi interface to download many + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example application source code using the multi interface to download many * files, but with a capped maximum amount of simultaneous transfers. * * Written by Michael Wallner diff --git a/docs/examples/Makefile.am b/docs/examples/Makefile.am index 8d92f7311..8e2bc9a83 100644 --- a/docs/examples/Makefile.am +++ b/docs/examples/Makefile.am @@ -1,10 +1,29 @@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| # +# Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. # +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### AUTOMAKE_OPTIONS = foreign nostdinc EXTRA_DIST = README Makefile.example Makefile.inc Makefile.m32 \ - makefile.dj $(COMPLICATED_EXAMPLES) + Makefile.netware makefile.dj $(COMPLICATED_EXAMPLES) # Specify our include paths here, and do it relative to $(top_srcdir) and # $(top_builddir), to ensure that these paths which belong to the library @@ -12,26 +31,33 @@ EXTRA_DIST = README Makefile.example Makefile.inc Makefile.m32 \ # might possibly already be installed in the system. # # $(top_builddir)/include/curl for generated curlbuild.h included from curl.h -# $(top_builddir)/include for generated curlbuild.h included from lib/setup.h +# $(top_builddir)/include for generated curlbuild.h inc. from lib/curl_setup.h # $(top_srcdir)/include is for libcurl's external include files -INCLUDES = -I$(top_builddir)/include/curl \ - -I$(top_builddir)/include \ - -I$(top_srcdir)/include +AM_CPPFLAGS = -I$(top_builddir)/include/curl \ + -I$(top_builddir)/include \ + -I$(top_srcdir)/include LIBDIR = $(top_builddir)/lib -if STATICLIB -# we need this define when building with a static lib on Windows -STATICCPPFLAGS = -DCURL_STATICLIB +# Avoid libcurl obsolete stuff +AM_CPPFLAGS += -DCURL_NO_OLDIES + +if USE_CPPFLAG_CURL_STATICLIB +AM_CPPFLAGS += -DCURL_STATICLIB endif -CPPFLAGS = -DCURL_NO_OLDIES $(STATICCPPFLAGS) +# Prevent LIBS from being used for all link targets +LIBS = $(BLANK_AT_MAKETIME) # Dependencies +if USE_EXPLICIT_LIB_DEPS +LDADD = $(LIBDIR)/libcurl.la @LIBCURL_LIBS@ +else LDADD = $(LIBDIR)/libcurl.la +endif # Makefile.inc provides the check_PROGRAMS and COMPLICATED_EXAMPLES defines include Makefile.inc - +all: $(check_PROGRAMS) diff --git a/docs/examples/Makefile.example b/docs/examples/Makefile.example index 29ca0d7a2..dfd117873 100644 --- a/docs/examples/Makefile.example +++ b/docs/examples/Makefile.example @@ -1,11 +1,24 @@ -############################################################################# +#*************************************************************************** # _ _ ____ _ # Project ___| | | | _ \| | # / __| | | | |_) | | # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # +# Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. # +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### # What to call the final executable TARGET = example diff --git a/docs/examples/Makefile.in b/docs/examples/Makefile.in index 1c7682225..d1deb8491 100644 --- a/docs/examples/Makefile.in +++ b/docs/examples/Makefile.in @@ -1,8 +1,8 @@ -# Makefile.in generated by automake 1.9.6 from Makefile.am. +# Makefile.in generated by automake 1.13.3 from Makefile.am. # @configure_input@ -# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -# 2003, 2004, 2005 Free Software Foundation, Inc. +# Copyright (C) 1994-2013 Free Software Foundation, Inc. + # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. @@ -14,17 +14,78 @@ @SET_MAKE@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| # +# Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. # -srcdir = @srcdir@ -top_srcdir = @top_srcdir@ +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### VPATH = @srcdir@ +am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)' +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) pkgdatadir = $(datadir)/@PACKAGE@ -pkglibdir = $(libdir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ -top_builddir = ../.. +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd -INSTALL = @INSTALL@ install_sh_DATA = $(install_sh) -c -m 644 install_sh_PROGRAM = $(install_sh) -c install_sh_SCRIPT = $(install_sh) -c @@ -38,8 +99,10 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -DIST_COMMON = README $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ - $(srcdir)/Makefile.inc +@USE_CPPFLAG_CURL_STATICLIB_TRUE@am__append_1 = -DCURL_STATICLIB +DIST_COMMON = $(srcdir)/Makefile.inc $(srcdir)/Makefile.in \ + $(srcdir)/Makefile.am $(top_srcdir)/mkinstalldirs \ + $(top_srcdir)/depcomp README check_PROGRAMS = 10-at-a-time$(EXEEXT) anyauthput$(EXEEXT) \ cookie_interface$(EXEEXT) debug$(EXEEXT) fileupload$(EXEEXT) \ fopen$(EXEEXT) ftpget$(EXEEXT) ftpgetresp$(EXEEXT) \ @@ -52,209 +115,446 @@ check_PROGRAMS = 10-at-a-time$(EXEEXT) anyauthput$(EXEEXT) \ simple$(EXEEXT) simplepost$(EXEEXT) simplessl$(EXEEXT) \ sendrecv$(EXEEXT) httpcustomheader$(EXEEXT) certinfo$(EXEEXT) \ chkspeed$(EXEEXT) ftpgetinfo$(EXEEXT) ftp-wildcard$(EXEEXT) \ - smtp-multi$(EXEEXT) + smtp-multi$(EXEEXT) simplesmtp$(EXEEXT) smtp-tls$(EXEEXT) \ + rtsp$(EXEEXT) externalsocket$(EXEEXT) resolve$(EXEEXT) \ + progressfunc$(EXEEXT) pop3s$(EXEEXT) pop3slist$(EXEEXT) \ + imap$(EXEEXT) url2file$(EXEEXT) sftpget$(EXEEXT) \ + ftpsget$(EXEEXT) subdir = docs/examples ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/curl-compilers.m4 \ $(top_srcdir)/m4/curl-confopts.m4 \ $(top_srcdir)/m4/curl-functions.m4 \ + $(top_srcdir)/m4/curl-openssl.m4 \ $(top_srcdir)/m4/curl-override.m4 \ - $(top_srcdir)/m4/curl-reentrant.m4 \ - $(top_srcdir)/m4/curl-system.m4 $(top_srcdir)/m4/libtool.m4 \ + $(top_srcdir)/m4/curl-reentrant.m4 $(top_srcdir)/m4/libtool.m4 \ $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \ $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \ - $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac + $(top_srcdir)/m4/xc-am-iface.m4 \ + $(top_srcdir)/m4/xc-cc-check.m4 \ + $(top_srcdir)/m4/xc-lt-iface.m4 \ + $(top_srcdir)/m4/xc-translit.m4 \ + $(top_srcdir)/m4/xc-val-flgs.m4 \ + $(top_srcdir)/m4/zz40-xc-ovr.m4 \ + $(top_srcdir)/m4/zz50-xc-ovr.m4 \ + $(top_srcdir)/m4/zz60-xc-ovr.m4 $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs CONFIG_HEADER = $(top_builddir)/lib/curl_config.h \ - $(top_builddir)/src/curl_config.h \ $(top_builddir)/include/curl/curlbuild.h CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = 10_at_a_time_SOURCES = 10-at-a-time.c 10_at_a_time_OBJECTS = 10-at-a-time.$(OBJEXT) 10_at_a_time_LDADD = $(LDADD) -10_at_a_time_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@10_at_a_time_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@10_at_a_time_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +AM_V_lt = $(am__v_lt_@AM_V@) +am__v_lt_ = $(am__v_lt_@AM_DEFAULT_V@) +am__v_lt_0 = --silent +am__v_lt_1 = anyauthput_SOURCES = anyauthput.c anyauthput_OBJECTS = anyauthput.$(OBJEXT) anyauthput_LDADD = $(LDADD) -anyauthput_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@anyauthput_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@anyauthput_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la certinfo_SOURCES = certinfo.c certinfo_OBJECTS = certinfo.$(OBJEXT) certinfo_LDADD = $(LDADD) -certinfo_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@certinfo_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@certinfo_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la chkspeed_SOURCES = chkspeed.c chkspeed_OBJECTS = chkspeed.$(OBJEXT) chkspeed_LDADD = $(LDADD) -chkspeed_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@chkspeed_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@chkspeed_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la cookie_interface_SOURCES = cookie_interface.c cookie_interface_OBJECTS = cookie_interface.$(OBJEXT) cookie_interface_LDADD = $(LDADD) -cookie_interface_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@cookie_interface_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@cookie_interface_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la debug_SOURCES = debug.c debug_OBJECTS = debug.$(OBJEXT) debug_LDADD = $(LDADD) -debug_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@debug_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@debug_DEPENDENCIES = $(LIBDIR)/libcurl.la +externalsocket_SOURCES = externalsocket.c +externalsocket_OBJECTS = externalsocket.$(OBJEXT) +externalsocket_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@externalsocket_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@externalsocket_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la fileupload_SOURCES = fileupload.c fileupload_OBJECTS = fileupload.$(OBJEXT) fileupload_LDADD = $(LDADD) -fileupload_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@fileupload_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@fileupload_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la fopen_SOURCES = fopen.c fopen_OBJECTS = fopen.$(OBJEXT) fopen_LDADD = $(LDADD) -fopen_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@fopen_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@fopen_DEPENDENCIES = $(LIBDIR)/libcurl.la ftp_wildcard_SOURCES = ftp-wildcard.c ftp_wildcard_OBJECTS = ftp-wildcard.$(OBJEXT) ftp_wildcard_LDADD = $(LDADD) -ftp_wildcard_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@ftp_wildcard_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@ftp_wildcard_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la ftpget_SOURCES = ftpget.c ftpget_OBJECTS = ftpget.$(OBJEXT) ftpget_LDADD = $(LDADD) -ftpget_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@ftpget_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@ftpget_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la ftpgetinfo_SOURCES = ftpgetinfo.c ftpgetinfo_OBJECTS = ftpgetinfo.$(OBJEXT) ftpgetinfo_LDADD = $(LDADD) -ftpgetinfo_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@ftpgetinfo_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@ftpgetinfo_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la ftpgetresp_SOURCES = ftpgetresp.c ftpgetresp_OBJECTS = ftpgetresp.$(OBJEXT) ftpgetresp_LDADD = $(LDADD) -ftpgetresp_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@ftpgetresp_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@ftpgetresp_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +ftpsget_SOURCES = ftpsget.c +ftpsget_OBJECTS = ftpsget.$(OBJEXT) +ftpsget_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@ftpsget_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@ftpsget_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la ftpupload_SOURCES = ftpupload.c ftpupload_OBJECTS = ftpupload.$(OBJEXT) ftpupload_LDADD = $(LDADD) -ftpupload_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@ftpupload_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@ftpupload_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la getinfo_SOURCES = getinfo.c getinfo_OBJECTS = getinfo.$(OBJEXT) getinfo_LDADD = $(LDADD) -getinfo_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@getinfo_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@getinfo_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la getinmemory_SOURCES = getinmemory.c getinmemory_OBJECTS = getinmemory.$(OBJEXT) getinmemory_LDADD = $(LDADD) -getinmemory_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@getinmemory_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@getinmemory_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la http_post_SOURCES = http-post.c http_post_OBJECTS = http-post.$(OBJEXT) http_post_LDADD = $(LDADD) -http_post_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@http_post_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@http_post_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la httpcustomheader_SOURCES = httpcustomheader.c httpcustomheader_OBJECTS = httpcustomheader.$(OBJEXT) httpcustomheader_LDADD = $(LDADD) -httpcustomheader_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@httpcustomheader_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@httpcustomheader_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la httpput_SOURCES = httpput.c httpput_OBJECTS = httpput.$(OBJEXT) httpput_LDADD = $(LDADD) -httpput_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@httpput_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@httpput_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la https_SOURCES = https.c https_OBJECTS = https.$(OBJEXT) https_LDADD = $(LDADD) -https_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@https_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@https_DEPENDENCIES = $(LIBDIR)/libcurl.la +imap_SOURCES = imap.c +imap_OBJECTS = imap.$(OBJEXT) +imap_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@imap_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@imap_DEPENDENCIES = $(LIBDIR)/libcurl.la multi_app_SOURCES = multi-app.c multi_app_OBJECTS = multi-app.$(OBJEXT) multi_app_LDADD = $(LDADD) -multi_app_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@multi_app_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@multi_app_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la multi_debugcallback_SOURCES = multi-debugcallback.c multi_debugcallback_OBJECTS = multi-debugcallback.$(OBJEXT) multi_debugcallback_LDADD = $(LDADD) -multi_debugcallback_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@multi_debugcallback_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@multi_debugcallback_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la multi_double_SOURCES = multi-double.c multi_double_OBJECTS = multi-double.$(OBJEXT) multi_double_LDADD = $(LDADD) -multi_double_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@multi_double_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@multi_double_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la multi_post_SOURCES = multi-post.c multi_post_OBJECTS = multi-post.$(OBJEXT) multi_post_LDADD = $(LDADD) -multi_post_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@multi_post_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@multi_post_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la multi_single_SOURCES = multi-single.c multi_single_OBJECTS = multi-single.$(OBJEXT) multi_single_LDADD = $(LDADD) -multi_single_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@multi_single_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@multi_single_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la persistant_SOURCES = persistant.c persistant_OBJECTS = persistant.$(OBJEXT) persistant_LDADD = $(LDADD) -persistant_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@persistant_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@persistant_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +pop3s_SOURCES = pop3s.c +pop3s_OBJECTS = pop3s.$(OBJEXT) +pop3s_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@pop3s_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@pop3s_DEPENDENCIES = $(LIBDIR)/libcurl.la +pop3slist_SOURCES = pop3slist.c +pop3slist_OBJECTS = pop3slist.$(OBJEXT) +pop3slist_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@pop3slist_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@pop3slist_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la post_callback_SOURCES = post-callback.c post_callback_OBJECTS = post-callback.$(OBJEXT) post_callback_LDADD = $(LDADD) -post_callback_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@post_callback_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@post_callback_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la postit2_SOURCES = postit2.c postit2_OBJECTS = postit2.$(OBJEXT) postit2_LDADD = $(LDADD) -postit2_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@postit2_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@postit2_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +progressfunc_SOURCES = progressfunc.c +progressfunc_OBJECTS = progressfunc.$(OBJEXT) +progressfunc_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@progressfunc_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@progressfunc_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +resolve_SOURCES = resolve.c +resolve_OBJECTS = resolve.$(OBJEXT) +resolve_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@resolve_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@resolve_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +rtsp_SOURCES = rtsp.c +rtsp_OBJECTS = rtsp.$(OBJEXT) +rtsp_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@rtsp_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@rtsp_DEPENDENCIES = $(LIBDIR)/libcurl.la sendrecv_SOURCES = sendrecv.c sendrecv_OBJECTS = sendrecv.$(OBJEXT) sendrecv_LDADD = $(LDADD) -sendrecv_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@sendrecv_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@sendrecv_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la sepheaders_SOURCES = sepheaders.c sepheaders_OBJECTS = sepheaders.$(OBJEXT) sepheaders_LDADD = $(LDADD) -sepheaders_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@sepheaders_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@sepheaders_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +sftpget_SOURCES = sftpget.c +sftpget_OBJECTS = sftpget.$(OBJEXT) +sftpget_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@sftpget_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@sftpget_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la simple_SOURCES = simple.c simple_OBJECTS = simple.$(OBJEXT) simple_LDADD = $(LDADD) -simple_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@simple_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@simple_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la simplepost_SOURCES = simplepost.c simplepost_OBJECTS = simplepost.$(OBJEXT) simplepost_LDADD = $(LDADD) -simplepost_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@simplepost_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@simplepost_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +simplesmtp_SOURCES = simplesmtp.c +simplesmtp_OBJECTS = simplesmtp.$(OBJEXT) +simplesmtp_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@simplesmtp_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@simplesmtp_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la simplessl_SOURCES = simplessl.c simplessl_OBJECTS = simplessl.$(OBJEXT) simplessl_LDADD = $(LDADD) -simplessl_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@simplessl_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@simplessl_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la smtp_multi_SOURCES = smtp-multi.c smtp_multi_OBJECTS = smtp-multi.$(OBJEXT) smtp_multi_LDADD = $(LDADD) -smtp_multi_DEPENDENCIES = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_FALSE@smtp_multi_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@smtp_multi_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +smtp_tls_SOURCES = smtp-tls.c +smtp_tls_OBJECTS = smtp-tls.$(OBJEXT) +smtp_tls_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@smtp_tls_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@smtp_tls_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +url2file_SOURCES = url2file.c +url2file_OBJECTS = url2file.$(OBJEXT) +url2file_LDADD = $(LDADD) +@USE_EXPLICIT_LIB_DEPS_FALSE@url2file_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_FALSE@ $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@url2file_DEPENDENCIES = \ +@USE_EXPLICIT_LIB_DEPS_TRUE@ $(LIBDIR)/libcurl.la +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = DEFAULT_INCLUDES = depcomp = $(SHELL) $(top_srcdir)/depcomp am__depfiles_maybe = depfiles +am__mv = mv -f COMPILE = $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) \ $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) -LTCOMPILE = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(DEFS) \ +LTCOMPILE = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \ + $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) \ $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) \ $(AM_CFLAGS) $(CFLAGS) +AM_V_CC = $(am__v_CC_@AM_V@) +am__v_CC_ = $(am__v_CC_@AM_DEFAULT_V@) +am__v_CC_0 = @echo " CC " $@; +am__v_CC_1 = CCLD = $(CC) -LINK = $(LIBTOOL) --tag=CC --mode=link $(CCLD) $(AM_CFLAGS) $(CFLAGS) \ +LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \ + $(LIBTOOLFLAGS) --mode=link $(CCLD) $(AM_CFLAGS) $(CFLAGS) \ $(AM_LDFLAGS) $(LDFLAGS) -o $@ +AM_V_CCLD = $(am__v_CCLD_@AM_V@) +am__v_CCLD_ = $(am__v_CCLD_@AM_DEFAULT_V@) +am__v_CCLD_0 = @echo " CCLD " $@; +am__v_CCLD_1 = SOURCES = 10-at-a-time.c anyauthput.c certinfo.c chkspeed.c \ - cookie_interface.c debug.c fileupload.c fopen.c ftp-wildcard.c \ - ftpget.c ftpgetinfo.c ftpgetresp.c ftpupload.c getinfo.c \ - getinmemory.c http-post.c httpcustomheader.c httpput.c https.c \ - multi-app.c multi-debugcallback.c multi-double.c multi-post.c \ - multi-single.c persistant.c post-callback.c postit2.c \ - sendrecv.c sepheaders.c simple.c simplepost.c simplessl.c \ - smtp-multi.c + cookie_interface.c debug.c externalsocket.c fileupload.c \ + fopen.c ftp-wildcard.c ftpget.c ftpgetinfo.c ftpgetresp.c \ + ftpsget.c ftpupload.c getinfo.c getinmemory.c http-post.c \ + httpcustomheader.c httpput.c https.c imap.c multi-app.c \ + multi-debugcallback.c multi-double.c multi-post.c \ + multi-single.c persistant.c pop3s.c pop3slist.c \ + post-callback.c postit2.c progressfunc.c resolve.c rtsp.c \ + sendrecv.c sepheaders.c sftpget.c simple.c simplepost.c \ + simplesmtp.c simplessl.c smtp-multi.c smtp-tls.c url2file.c DIST_SOURCES = 10-at-a-time.c anyauthput.c certinfo.c chkspeed.c \ - cookie_interface.c debug.c fileupload.c fopen.c ftp-wildcard.c \ - ftpget.c ftpgetinfo.c ftpgetresp.c ftpupload.c getinfo.c \ - getinmemory.c http-post.c httpcustomheader.c httpput.c https.c \ - multi-app.c multi-debugcallback.c multi-double.c multi-post.c \ - multi-single.c persistant.c post-callback.c postit2.c \ - sendrecv.c sepheaders.c simple.c simplepost.c simplessl.c \ - smtp-multi.c + cookie_interface.c debug.c externalsocket.c fileupload.c \ + fopen.c ftp-wildcard.c ftpget.c ftpgetinfo.c ftpgetresp.c \ + ftpsget.c ftpupload.c getinfo.c getinmemory.c http-post.c \ + httpcustomheader.c httpput.c https.c imap.c multi-app.c \ + multi-debugcallback.c multi-double.c multi-post.c \ + multi-single.c persistant.c pop3s.c pop3slist.c \ + post-callback.c postit2.c progressfunc.c resolve.c rtsp.c \ + sendrecv.c sepheaders.c sftpget.c simple.c simplepost.c \ + simplesmtp.c simplessl.c smtp-multi.c smtp-tls.c url2file.c +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +# Read a list of newline-separated strings from the standard input, +# and print each of them once, without duplicates. Input order is +# *not* preserved. +am__uniquify_input = $(AWK) '\ + BEGIN { nonempty = 0; } \ + { items[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in items) print i; }; } \ +' +# Make sure the list of sources is unique. This is necessary because, +# e.g., the same source file might be shared among _SOURCES variables +# for different programs/libraries. +am__define_uniq_tagged_files = \ + list='$(am__tagged_files)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | $(am__uniquify_input)` ETAGS = etags CTAGS = ctags DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) ACLOCAL = @ACLOCAL@ -AMDEP_FALSE = @AMDEP_FALSE@ -AMDEP_TRUE = @AMDEP_TRUE@ AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ AR = @AR@ AS = @AS@ AUTOCONF = @AUTOCONF@ AUTOHEADER = @AUTOHEADER@ AUTOMAKE = @AUTOMAKE@ AWK = @AWK@ -BUILD_LIBHOSTNAME_FALSE = @BUILD_LIBHOSTNAME_FALSE@ -BUILD_LIBHOSTNAME_TRUE = @BUILD_LIBHOSTNAME_TRUE@ +BLANK_AT_MAKETIME = @BLANK_AT_MAKETIME@ CC = @CC@ CCDEPMODE = @CCDEPMODE@ CFLAGS = @CFLAGS@ +CFLAG_CURL_SYMBOL_HIDING = @CFLAG_CURL_SYMBOL_HIDING@ CONFIGURE_OPTIONS = @CONFIGURE_OPTIONS@ CPP = @CPP@ -CPPFLAGS = -DCURL_NO_OLDIES $(STATICCPPFLAGS) -CROSSCOMPILING_FALSE = @CROSSCOMPILING_FALSE@ -CROSSCOMPILING_TRUE = @CROSSCOMPILING_TRUE@ -CURLDEBUG_FALSE = @CURLDEBUG_FALSE@ -CURLDEBUG_TRUE = @CURLDEBUG_TRUE@ +CPPFLAGS = @CPPFLAGS@ +CPPFLAG_CURL_STATICLIB = @CPPFLAG_CURL_STATICLIB@ +CURLVERSION = @CURLVERSION@ CURL_CA_BUNDLE = @CURL_CA_BUNDLE@ CURL_CFLAG_EXTRAS = @CURL_CFLAG_EXTRAS@ CURL_DISABLE_DICT = @CURL_DISABLE_DICT@ @@ -271,7 +571,8 @@ CURL_DISABLE_RTSP = @CURL_DISABLE_RTSP@ CURL_DISABLE_SMTP = @CURL_DISABLE_SMTP@ CURL_DISABLE_TELNET = @CURL_DISABLE_TELNET@ CURL_DISABLE_TFTP = @CURL_DISABLE_TFTP@ -CURL_LIBS = @CURL_LIBS@ +CURL_LT_SHLIB_VERSIONED_FLAVOUR = @CURL_LT_SHLIB_VERSIONED_FLAVOUR@ +CURL_NETWORK_AND_TIME_LIBS = @CURL_NETWORK_AND_TIME_LIBS@ CURL_NETWORK_LIBS = @CURL_NETWORK_LIBS@ CYGPATH_W = @CYGPATH_W@ DEFS = @DEFS@ @@ -284,15 +585,17 @@ ECHO_N = @ECHO_N@ ECHO_T = @ECHO_T@ EGREP = @EGREP@ ENABLE_SHARED = @ENABLE_SHARED@ +ENABLE_STATIC = @ENABLE_STATIC@ EXEEXT = @EXEEXT@ FGREP = @FGREP@ GREP = @GREP@ +HAVE_GNUTLS_SRP = @HAVE_GNUTLS_SRP@ HAVE_LDAP_SSL = @HAVE_LDAP_SSL@ HAVE_LIBZ = @HAVE_LIBZ@ -HAVE_LIBZ_FALSE = @HAVE_LIBZ_FALSE@ -HAVE_LIBZ_TRUE = @HAVE_LIBZ_TRUE@ -HAVE_PK11_CREATEGENERICOBJECT = @HAVE_PK11_CREATEGENERICOBJECT@ +HAVE_NSS_INITCONTEXT = @HAVE_NSS_INITCONTEXT@ +HAVE_SSLEAY_SRP = @HAVE_SSLEAY_SRP@ IDN_ENABLED = @IDN_ENABLED@ +INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_SCRIPT = @INSTALL_SCRIPT@ @@ -302,23 +605,24 @@ KRB4_ENABLED = @KRB4_ENABLED@ LD = @LD@ LDFLAGS = @LDFLAGS@ LIBCURL_LIBS = @LIBCURL_LIBS@ +LIBMETALINK_CPPFLAGS = @LIBMETALINK_CPPFLAGS@ +LIBMETALINK_LDFLAGS = @LIBMETALINK_LDFLAGS@ +LIBMETALINK_LIBS = @LIBMETALINK_LIBS@ LIBOBJS = @LIBOBJS@ -LIBS = @LIBS@ + +# Prevent LIBS from being used for all link targets +LIBS = $(BLANK_AT_MAKETIME) LIBTOOL = @LIBTOOL@ LIPO = @LIPO@ LN_S = @LN_S@ LTLIBOBJS = @LTLIBOBJS@ MAINT = @MAINT@ -MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@ -MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@ MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ MANOPT = @MANOPT@ -MIMPURE_FALSE = @MIMPURE_FALSE@ -MIMPURE_TRUE = @MIMPURE_TRUE@ +MKDIR_P = @MKDIR_P@ NM = @NM@ NMEDIT = @NMEDIT@ -NO_UNDEFINED_FALSE = @NO_UNDEFINED_FALSE@ -NO_UNDEFINED_TRUE = @NO_UNDEFINED_TRUE@ NROFF = @NROFF@ OBJDUMP = @OBJDUMP@ OBJEXT = @OBJEXT@ @@ -331,7 +635,6 @@ PACKAGE_STRING = @PACKAGE_STRING@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ -PATH = @PATH@ PATH_SEPARATOR = @PATH_SEPARATOR@ PERL = @PERL@ PKGADD_NAME = @PKGADD_NAME@ @@ -344,34 +647,34 @@ REQUIRE_LIB_DEPS = @REQUIRE_LIB_DEPS@ SED = @SED@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ -SONAME_BUMP_FALSE = @SONAME_BUMP_FALSE@ -SONAME_BUMP_TRUE = @SONAME_BUMP_TRUE@ SSL_ENABLED = @SSL_ENABLED@ -STATICLIB_FALSE = @STATICLIB_FALSE@ -STATICLIB_TRUE = @STATICLIB_TRUE@ STRIP = @STRIP@ SUPPORT_FEATURES = @SUPPORT_FEATURES@ SUPPORT_PROTOCOLS = @SUPPORT_PROTOCOLS@ -TEST_SERVER_LIBS = @TEST_SERVER_LIBS@ USE_ARES = @USE_ARES@ -USE_EMBEDDED_ARES_FALSE = @USE_EMBEDDED_ARES_FALSE@ -USE_EMBEDDED_ARES_TRUE = @USE_EMBEDDED_ARES_TRUE@ +USE_AXTLS = @USE_AXTLS@ +USE_CYASSL = @USE_CYASSL@ +USE_DARWINSSL = @USE_DARWINSSL@ USE_GNUTLS = @USE_GNUTLS@ +USE_GNUTLS_NETTLE = @USE_GNUTLS_NETTLE@ USE_LIBRTMP = @USE_LIBRTMP@ USE_LIBSSH2 = @USE_LIBSSH2@ -USE_MANUAL_FALSE = @USE_MANUAL_FALSE@ -USE_MANUAL_TRUE = @USE_MANUAL_TRUE@ USE_NSS = @USE_NSS@ USE_OPENLDAP = @USE_OPENLDAP@ USE_POLARSSL = @USE_POLARSSL@ +USE_SCHANNEL = @USE_SCHANNEL@ USE_SSLEAY = @USE_SSLEAY@ USE_WINDOWS_SSPI = @USE_WINDOWS_SSPI@ VERSION = @VERSION@ VERSIONNUM = @VERSIONNUM@ +ZLIB_LIBS = @ZLIB_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ ac_ct_CC = @ac_ct_CC@ ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ -am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ -am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ am__include = @am__include@ am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ @@ -383,6 +686,7 @@ build_alias = @build_alias@ build_cpu = @build_cpu@ build_os = @build_os@ build_vendor = @build_vendor@ +builddir = @builddir@ datadir = @datadir@ datarootdir = @datarootdir@ docdir = @docdir@ @@ -402,7 +706,6 @@ libexecdir = @libexecdir@ libext = @libext@ localedir = @localedir@ localstatedir = @localstatedir@ -lt_ECHO = @lt_ECHO@ mandir = @mandir@ mkdir_p = @mkdir_p@ oldincludedir = @oldincludedir@ @@ -412,12 +715,16 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ subdirs = @subdirs@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ AUTOMAKE_OPTIONS = foreign nostdinc EXTRA_DIST = README Makefile.example Makefile.inc Makefile.m32 \ - makefile.dj $(COMPLICATED_EXAMPLES) + Makefile.netware makefile.dj $(COMPLICATED_EXAMPLES) # Specify our include paths here, and do it relative to $(top_srcdir) and @@ -426,26 +733,25 @@ EXTRA_DIST = README Makefile.example Makefile.inc Makefile.m32 \ # might possibly already be installed in the system. # # $(top_builddir)/include/curl for generated curlbuild.h included from curl.h -# $(top_builddir)/include for generated curlbuild.h included from lib/setup.h +# $(top_builddir)/include for generated curlbuild.h inc. from lib/curl_setup.h # $(top_srcdir)/include is for libcurl's external include files -INCLUDES = -I$(top_builddir)/include/curl \ - -I$(top_builddir)/include \ - -I$(top_srcdir)/include +# Avoid libcurl obsolete stuff +AM_CPPFLAGS = -I$(top_builddir)/include/curl -I$(top_builddir)/include \ + -I$(top_srcdir)/include -DCURL_NO_OLDIES $(am__append_1) LIBDIR = $(top_builddir)/lib - -# we need this define when building with a static lib on Windows -@STATICLIB_TRUE@STATICCPPFLAGS = -DCURL_STATICLIB +@USE_EXPLICIT_LIB_DEPS_FALSE@LDADD = $(LIBDIR)/libcurl.la # Dependencies -LDADD = $(LIBDIR)/libcurl.la +@USE_EXPLICIT_LIB_DEPS_TRUE@LDADD = $(LIBDIR)/libcurl.la @LIBCURL_LIBS@ # These examples require external dependencies that may not be commonly # available on POSIX systems, so don't bother attempting to compile them here. -COMPLICATED_EXAMPLES = curlgtk.c curlx.c htmltitle.cc cacertinmem.c \ +COMPLICATED_EXAMPLES = curlgtk.c curlx.c htmltitle.cpp cacertinmem.c \ ftpuploadresume.c ghiper.c hiperfifo.c htmltidy.c multithread.c \ opensslthreadlock.c sampleconv.c synctime.c threaded-ssl.c evhiperfifo.c \ - smooth-gtk-thread.c version-check.pl + smooth-gtk-thread.c version-check.pl href_extractor.c asiohiper.cpp \ + multi-uv.c xmlstream.c usercertinmem.c all: all-am @@ -455,14 +761,14 @@ $(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(srcdir)/Ma @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ - && exit 0; \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ exit 1;; \ esac; \ done; \ - echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/examples/Makefile'; \ - cd $(top_srcdir) && \ - $(AUTOMAKE) --foreign docs/examples/Makefile + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/examples/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign docs/examples/Makefile .PRECIOUS: Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status @case '$?' in \ @@ -472,6 +778,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ esac; +$(srcdir)/Makefile.inc: $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh @@ -480,112 +787,196 @@ $(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh $(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): clean-checkPROGRAMS: - @list='$(check_PROGRAMS)'; for p in $$list; do \ - f=`echo $$p|sed 's/$(EXEEXT)$$//'`; \ - echo " rm -f $$p $$f"; \ - rm -f $$p $$f ; \ - done -10-at-a-time$(EXEEXT): $(10_at_a_time_OBJECTS) $(10_at_a_time_DEPENDENCIES) + @list='$(check_PROGRAMS)'; test -n "$$list" || exit 0; \ + echo " rm -f" $$list; \ + rm -f $$list || exit $$?; \ + test -n "$(EXEEXT)" || exit 0; \ + list=`for p in $$list; do echo "$$p"; done | sed 's/$(EXEEXT)$$//'`; \ + echo " rm -f" $$list; \ + rm -f $$list + +10-at-a-time$(EXEEXT): $(10_at_a_time_OBJECTS) $(10_at_a_time_DEPENDENCIES) $(EXTRA_10_at_a_time_DEPENDENCIES) @rm -f 10-at-a-time$(EXEEXT) - $(LINK) $(10_at_a_time_LDFLAGS) $(10_at_a_time_OBJECTS) $(10_at_a_time_LDADD) $(LIBS) -anyauthput$(EXEEXT): $(anyauthput_OBJECTS) $(anyauthput_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(10_at_a_time_OBJECTS) $(10_at_a_time_LDADD) $(LIBS) + +anyauthput$(EXEEXT): $(anyauthput_OBJECTS) $(anyauthput_DEPENDENCIES) $(EXTRA_anyauthput_DEPENDENCIES) @rm -f anyauthput$(EXEEXT) - $(LINK) $(anyauthput_LDFLAGS) $(anyauthput_OBJECTS) $(anyauthput_LDADD) $(LIBS) -certinfo$(EXEEXT): $(certinfo_OBJECTS) $(certinfo_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(anyauthput_OBJECTS) $(anyauthput_LDADD) $(LIBS) + +certinfo$(EXEEXT): $(certinfo_OBJECTS) $(certinfo_DEPENDENCIES) $(EXTRA_certinfo_DEPENDENCIES) @rm -f certinfo$(EXEEXT) - $(LINK) $(certinfo_LDFLAGS) $(certinfo_OBJECTS) $(certinfo_LDADD) $(LIBS) -chkspeed$(EXEEXT): $(chkspeed_OBJECTS) $(chkspeed_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(certinfo_OBJECTS) $(certinfo_LDADD) $(LIBS) + +chkspeed$(EXEEXT): $(chkspeed_OBJECTS) $(chkspeed_DEPENDENCIES) $(EXTRA_chkspeed_DEPENDENCIES) @rm -f chkspeed$(EXEEXT) - $(LINK) $(chkspeed_LDFLAGS) $(chkspeed_OBJECTS) $(chkspeed_LDADD) $(LIBS) -cookie_interface$(EXEEXT): $(cookie_interface_OBJECTS) $(cookie_interface_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(chkspeed_OBJECTS) $(chkspeed_LDADD) $(LIBS) + +cookie_interface$(EXEEXT): $(cookie_interface_OBJECTS) $(cookie_interface_DEPENDENCIES) $(EXTRA_cookie_interface_DEPENDENCIES) @rm -f cookie_interface$(EXEEXT) - $(LINK) $(cookie_interface_LDFLAGS) $(cookie_interface_OBJECTS) $(cookie_interface_LDADD) $(LIBS) -debug$(EXEEXT): $(debug_OBJECTS) $(debug_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(cookie_interface_OBJECTS) $(cookie_interface_LDADD) $(LIBS) + +debug$(EXEEXT): $(debug_OBJECTS) $(debug_DEPENDENCIES) $(EXTRA_debug_DEPENDENCIES) @rm -f debug$(EXEEXT) - $(LINK) $(debug_LDFLAGS) $(debug_OBJECTS) $(debug_LDADD) $(LIBS) -fileupload$(EXEEXT): $(fileupload_OBJECTS) $(fileupload_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(debug_OBJECTS) $(debug_LDADD) $(LIBS) + +externalsocket$(EXEEXT): $(externalsocket_OBJECTS) $(externalsocket_DEPENDENCIES) $(EXTRA_externalsocket_DEPENDENCIES) + @rm -f externalsocket$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(externalsocket_OBJECTS) $(externalsocket_LDADD) $(LIBS) + +fileupload$(EXEEXT): $(fileupload_OBJECTS) $(fileupload_DEPENDENCIES) $(EXTRA_fileupload_DEPENDENCIES) @rm -f fileupload$(EXEEXT) - $(LINK) $(fileupload_LDFLAGS) $(fileupload_OBJECTS) $(fileupload_LDADD) $(LIBS) -fopen$(EXEEXT): $(fopen_OBJECTS) $(fopen_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(fileupload_OBJECTS) $(fileupload_LDADD) $(LIBS) + +fopen$(EXEEXT): $(fopen_OBJECTS) $(fopen_DEPENDENCIES) $(EXTRA_fopen_DEPENDENCIES) @rm -f fopen$(EXEEXT) - $(LINK) $(fopen_LDFLAGS) $(fopen_OBJECTS) $(fopen_LDADD) $(LIBS) -ftp-wildcard$(EXEEXT): $(ftp_wildcard_OBJECTS) $(ftp_wildcard_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(fopen_OBJECTS) $(fopen_LDADD) $(LIBS) + +ftp-wildcard$(EXEEXT): $(ftp_wildcard_OBJECTS) $(ftp_wildcard_DEPENDENCIES) $(EXTRA_ftp_wildcard_DEPENDENCIES) @rm -f ftp-wildcard$(EXEEXT) - $(LINK) $(ftp_wildcard_LDFLAGS) $(ftp_wildcard_OBJECTS) $(ftp_wildcard_LDADD) $(LIBS) -ftpget$(EXEEXT): $(ftpget_OBJECTS) $(ftpget_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(ftp_wildcard_OBJECTS) $(ftp_wildcard_LDADD) $(LIBS) + +ftpget$(EXEEXT): $(ftpget_OBJECTS) $(ftpget_DEPENDENCIES) $(EXTRA_ftpget_DEPENDENCIES) @rm -f ftpget$(EXEEXT) - $(LINK) $(ftpget_LDFLAGS) $(ftpget_OBJECTS) $(ftpget_LDADD) $(LIBS) -ftpgetinfo$(EXEEXT): $(ftpgetinfo_OBJECTS) $(ftpgetinfo_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(ftpget_OBJECTS) $(ftpget_LDADD) $(LIBS) + +ftpgetinfo$(EXEEXT): $(ftpgetinfo_OBJECTS) $(ftpgetinfo_DEPENDENCIES) $(EXTRA_ftpgetinfo_DEPENDENCIES) @rm -f ftpgetinfo$(EXEEXT) - $(LINK) $(ftpgetinfo_LDFLAGS) $(ftpgetinfo_OBJECTS) $(ftpgetinfo_LDADD) $(LIBS) -ftpgetresp$(EXEEXT): $(ftpgetresp_OBJECTS) $(ftpgetresp_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(ftpgetinfo_OBJECTS) $(ftpgetinfo_LDADD) $(LIBS) + +ftpgetresp$(EXEEXT): $(ftpgetresp_OBJECTS) $(ftpgetresp_DEPENDENCIES) $(EXTRA_ftpgetresp_DEPENDENCIES) @rm -f ftpgetresp$(EXEEXT) - $(LINK) $(ftpgetresp_LDFLAGS) $(ftpgetresp_OBJECTS) $(ftpgetresp_LDADD) $(LIBS) -ftpupload$(EXEEXT): $(ftpupload_OBJECTS) $(ftpupload_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(ftpgetresp_OBJECTS) $(ftpgetresp_LDADD) $(LIBS) + +ftpsget$(EXEEXT): $(ftpsget_OBJECTS) $(ftpsget_DEPENDENCIES) $(EXTRA_ftpsget_DEPENDENCIES) + @rm -f ftpsget$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(ftpsget_OBJECTS) $(ftpsget_LDADD) $(LIBS) + +ftpupload$(EXEEXT): $(ftpupload_OBJECTS) $(ftpupload_DEPENDENCIES) $(EXTRA_ftpupload_DEPENDENCIES) @rm -f ftpupload$(EXEEXT) - $(LINK) $(ftpupload_LDFLAGS) $(ftpupload_OBJECTS) $(ftpupload_LDADD) $(LIBS) -getinfo$(EXEEXT): $(getinfo_OBJECTS) $(getinfo_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(ftpupload_OBJECTS) $(ftpupload_LDADD) $(LIBS) + +getinfo$(EXEEXT): $(getinfo_OBJECTS) $(getinfo_DEPENDENCIES) $(EXTRA_getinfo_DEPENDENCIES) @rm -f getinfo$(EXEEXT) - $(LINK) $(getinfo_LDFLAGS) $(getinfo_OBJECTS) $(getinfo_LDADD) $(LIBS) -getinmemory$(EXEEXT): $(getinmemory_OBJECTS) $(getinmemory_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(getinfo_OBJECTS) $(getinfo_LDADD) $(LIBS) + +getinmemory$(EXEEXT): $(getinmemory_OBJECTS) $(getinmemory_DEPENDENCIES) $(EXTRA_getinmemory_DEPENDENCIES) @rm -f getinmemory$(EXEEXT) - $(LINK) $(getinmemory_LDFLAGS) $(getinmemory_OBJECTS) $(getinmemory_LDADD) $(LIBS) -http-post$(EXEEXT): $(http_post_OBJECTS) $(http_post_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(getinmemory_OBJECTS) $(getinmemory_LDADD) $(LIBS) + +http-post$(EXEEXT): $(http_post_OBJECTS) $(http_post_DEPENDENCIES) $(EXTRA_http_post_DEPENDENCIES) @rm -f http-post$(EXEEXT) - $(LINK) $(http_post_LDFLAGS) $(http_post_OBJECTS) $(http_post_LDADD) $(LIBS) -httpcustomheader$(EXEEXT): $(httpcustomheader_OBJECTS) $(httpcustomheader_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(http_post_OBJECTS) $(http_post_LDADD) $(LIBS) + +httpcustomheader$(EXEEXT): $(httpcustomheader_OBJECTS) $(httpcustomheader_DEPENDENCIES) $(EXTRA_httpcustomheader_DEPENDENCIES) @rm -f httpcustomheader$(EXEEXT) - $(LINK) $(httpcustomheader_LDFLAGS) $(httpcustomheader_OBJECTS) $(httpcustomheader_LDADD) $(LIBS) -httpput$(EXEEXT): $(httpput_OBJECTS) $(httpput_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(httpcustomheader_OBJECTS) $(httpcustomheader_LDADD) $(LIBS) + +httpput$(EXEEXT): $(httpput_OBJECTS) $(httpput_DEPENDENCIES) $(EXTRA_httpput_DEPENDENCIES) @rm -f httpput$(EXEEXT) - $(LINK) $(httpput_LDFLAGS) $(httpput_OBJECTS) $(httpput_LDADD) $(LIBS) -https$(EXEEXT): $(https_OBJECTS) $(https_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(httpput_OBJECTS) $(httpput_LDADD) $(LIBS) + +https$(EXEEXT): $(https_OBJECTS) $(https_DEPENDENCIES) $(EXTRA_https_DEPENDENCIES) @rm -f https$(EXEEXT) - $(LINK) $(https_LDFLAGS) $(https_OBJECTS) $(https_LDADD) $(LIBS) -multi-app$(EXEEXT): $(multi_app_OBJECTS) $(multi_app_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(https_OBJECTS) $(https_LDADD) $(LIBS) + +imap$(EXEEXT): $(imap_OBJECTS) $(imap_DEPENDENCIES) $(EXTRA_imap_DEPENDENCIES) + @rm -f imap$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(imap_OBJECTS) $(imap_LDADD) $(LIBS) + +multi-app$(EXEEXT): $(multi_app_OBJECTS) $(multi_app_DEPENDENCIES) $(EXTRA_multi_app_DEPENDENCIES) @rm -f multi-app$(EXEEXT) - $(LINK) $(multi_app_LDFLAGS) $(multi_app_OBJECTS) $(multi_app_LDADD) $(LIBS) -multi-debugcallback$(EXEEXT): $(multi_debugcallback_OBJECTS) $(multi_debugcallback_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(multi_app_OBJECTS) $(multi_app_LDADD) $(LIBS) + +multi-debugcallback$(EXEEXT): $(multi_debugcallback_OBJECTS) $(multi_debugcallback_DEPENDENCIES) $(EXTRA_multi_debugcallback_DEPENDENCIES) @rm -f multi-debugcallback$(EXEEXT) - $(LINK) $(multi_debugcallback_LDFLAGS) $(multi_debugcallback_OBJECTS) $(multi_debugcallback_LDADD) $(LIBS) -multi-double$(EXEEXT): $(multi_double_OBJECTS) $(multi_double_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(multi_debugcallback_OBJECTS) $(multi_debugcallback_LDADD) $(LIBS) + +multi-double$(EXEEXT): $(multi_double_OBJECTS) $(multi_double_DEPENDENCIES) $(EXTRA_multi_double_DEPENDENCIES) @rm -f multi-double$(EXEEXT) - $(LINK) $(multi_double_LDFLAGS) $(multi_double_OBJECTS) $(multi_double_LDADD) $(LIBS) -multi-post$(EXEEXT): $(multi_post_OBJECTS) $(multi_post_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(multi_double_OBJECTS) $(multi_double_LDADD) $(LIBS) + +multi-post$(EXEEXT): $(multi_post_OBJECTS) $(multi_post_DEPENDENCIES) $(EXTRA_multi_post_DEPENDENCIES) @rm -f multi-post$(EXEEXT) - $(LINK) $(multi_post_LDFLAGS) $(multi_post_OBJECTS) $(multi_post_LDADD) $(LIBS) -multi-single$(EXEEXT): $(multi_single_OBJECTS) $(multi_single_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(multi_post_OBJECTS) $(multi_post_LDADD) $(LIBS) + +multi-single$(EXEEXT): $(multi_single_OBJECTS) $(multi_single_DEPENDENCIES) $(EXTRA_multi_single_DEPENDENCIES) @rm -f multi-single$(EXEEXT) - $(LINK) $(multi_single_LDFLAGS) $(multi_single_OBJECTS) $(multi_single_LDADD) $(LIBS) -persistant$(EXEEXT): $(persistant_OBJECTS) $(persistant_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(multi_single_OBJECTS) $(multi_single_LDADD) $(LIBS) + +persistant$(EXEEXT): $(persistant_OBJECTS) $(persistant_DEPENDENCIES) $(EXTRA_persistant_DEPENDENCIES) @rm -f persistant$(EXEEXT) - $(LINK) $(persistant_LDFLAGS) $(persistant_OBJECTS) $(persistant_LDADD) $(LIBS) -post-callback$(EXEEXT): $(post_callback_OBJECTS) $(post_callback_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(persistant_OBJECTS) $(persistant_LDADD) $(LIBS) + +pop3s$(EXEEXT): $(pop3s_OBJECTS) $(pop3s_DEPENDENCIES) $(EXTRA_pop3s_DEPENDENCIES) + @rm -f pop3s$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(pop3s_OBJECTS) $(pop3s_LDADD) $(LIBS) + +pop3slist$(EXEEXT): $(pop3slist_OBJECTS) $(pop3slist_DEPENDENCIES) $(EXTRA_pop3slist_DEPENDENCIES) + @rm -f pop3slist$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(pop3slist_OBJECTS) $(pop3slist_LDADD) $(LIBS) + +post-callback$(EXEEXT): $(post_callback_OBJECTS) $(post_callback_DEPENDENCIES) $(EXTRA_post_callback_DEPENDENCIES) @rm -f post-callback$(EXEEXT) - $(LINK) $(post_callback_LDFLAGS) $(post_callback_OBJECTS) $(post_callback_LDADD) $(LIBS) -postit2$(EXEEXT): $(postit2_OBJECTS) $(postit2_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(post_callback_OBJECTS) $(post_callback_LDADD) $(LIBS) + +postit2$(EXEEXT): $(postit2_OBJECTS) $(postit2_DEPENDENCIES) $(EXTRA_postit2_DEPENDENCIES) @rm -f postit2$(EXEEXT) - $(LINK) $(postit2_LDFLAGS) $(postit2_OBJECTS) $(postit2_LDADD) $(LIBS) -sendrecv$(EXEEXT): $(sendrecv_OBJECTS) $(sendrecv_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(postit2_OBJECTS) $(postit2_LDADD) $(LIBS) + +progressfunc$(EXEEXT): $(progressfunc_OBJECTS) $(progressfunc_DEPENDENCIES) $(EXTRA_progressfunc_DEPENDENCIES) + @rm -f progressfunc$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(progressfunc_OBJECTS) $(progressfunc_LDADD) $(LIBS) + +resolve$(EXEEXT): $(resolve_OBJECTS) $(resolve_DEPENDENCIES) $(EXTRA_resolve_DEPENDENCIES) + @rm -f resolve$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(resolve_OBJECTS) $(resolve_LDADD) $(LIBS) + +rtsp$(EXEEXT): $(rtsp_OBJECTS) $(rtsp_DEPENDENCIES) $(EXTRA_rtsp_DEPENDENCIES) + @rm -f rtsp$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(rtsp_OBJECTS) $(rtsp_LDADD) $(LIBS) + +sendrecv$(EXEEXT): $(sendrecv_OBJECTS) $(sendrecv_DEPENDENCIES) $(EXTRA_sendrecv_DEPENDENCIES) @rm -f sendrecv$(EXEEXT) - $(LINK) $(sendrecv_LDFLAGS) $(sendrecv_OBJECTS) $(sendrecv_LDADD) $(LIBS) -sepheaders$(EXEEXT): $(sepheaders_OBJECTS) $(sepheaders_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(sendrecv_OBJECTS) $(sendrecv_LDADD) $(LIBS) + +sepheaders$(EXEEXT): $(sepheaders_OBJECTS) $(sepheaders_DEPENDENCIES) $(EXTRA_sepheaders_DEPENDENCIES) @rm -f sepheaders$(EXEEXT) - $(LINK) $(sepheaders_LDFLAGS) $(sepheaders_OBJECTS) $(sepheaders_LDADD) $(LIBS) -simple$(EXEEXT): $(simple_OBJECTS) $(simple_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(sepheaders_OBJECTS) $(sepheaders_LDADD) $(LIBS) + +sftpget$(EXEEXT): $(sftpget_OBJECTS) $(sftpget_DEPENDENCIES) $(EXTRA_sftpget_DEPENDENCIES) + @rm -f sftpget$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(sftpget_OBJECTS) $(sftpget_LDADD) $(LIBS) + +simple$(EXEEXT): $(simple_OBJECTS) $(simple_DEPENDENCIES) $(EXTRA_simple_DEPENDENCIES) @rm -f simple$(EXEEXT) - $(LINK) $(simple_LDFLAGS) $(simple_OBJECTS) $(simple_LDADD) $(LIBS) -simplepost$(EXEEXT): $(simplepost_OBJECTS) $(simplepost_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(simple_OBJECTS) $(simple_LDADD) $(LIBS) + +simplepost$(EXEEXT): $(simplepost_OBJECTS) $(simplepost_DEPENDENCIES) $(EXTRA_simplepost_DEPENDENCIES) @rm -f simplepost$(EXEEXT) - $(LINK) $(simplepost_LDFLAGS) $(simplepost_OBJECTS) $(simplepost_LDADD) $(LIBS) -simplessl$(EXEEXT): $(simplessl_OBJECTS) $(simplessl_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(simplepost_OBJECTS) $(simplepost_LDADD) $(LIBS) + +simplesmtp$(EXEEXT): $(simplesmtp_OBJECTS) $(simplesmtp_DEPENDENCIES) $(EXTRA_simplesmtp_DEPENDENCIES) + @rm -f simplesmtp$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(simplesmtp_OBJECTS) $(simplesmtp_LDADD) $(LIBS) + +simplessl$(EXEEXT): $(simplessl_OBJECTS) $(simplessl_DEPENDENCIES) $(EXTRA_simplessl_DEPENDENCIES) @rm -f simplessl$(EXEEXT) - $(LINK) $(simplessl_LDFLAGS) $(simplessl_OBJECTS) $(simplessl_LDADD) $(LIBS) -smtp-multi$(EXEEXT): $(smtp_multi_OBJECTS) $(smtp_multi_DEPENDENCIES) + $(AM_V_CCLD)$(LINK) $(simplessl_OBJECTS) $(simplessl_LDADD) $(LIBS) + +smtp-multi$(EXEEXT): $(smtp_multi_OBJECTS) $(smtp_multi_DEPENDENCIES) $(EXTRA_smtp_multi_DEPENDENCIES) @rm -f smtp-multi$(EXEEXT) - $(LINK) $(smtp_multi_LDFLAGS) $(smtp_multi_OBJECTS) $(smtp_multi_LDADD) $(LIBS) + $(AM_V_CCLD)$(LINK) $(smtp_multi_OBJECTS) $(smtp_multi_LDADD) $(LIBS) + +smtp-tls$(EXEEXT): $(smtp_tls_OBJECTS) $(smtp_tls_DEPENDENCIES) $(EXTRA_smtp_tls_DEPENDENCIES) + @rm -f smtp-tls$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(smtp_tls_OBJECTS) $(smtp_tls_LDADD) $(LIBS) + +url2file$(EXEEXT): $(url2file_OBJECTS) $(url2file_DEPENDENCIES) $(EXTRA_url2file_DEPENDENCIES) + @rm -f url2file$(EXEEXT) + $(AM_V_CCLD)$(LINK) $(url2file_OBJECTS) $(url2file_LDADD) $(LIBS) mostlyclean-compile: -rm -f *.$(OBJEXT) @@ -599,12 +990,14 @@ distclean-compile: @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/chkspeed.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/cookie_interface.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/debug.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/externalsocket.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/fileupload.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/fopen.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/ftp-wildcard.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/ftpget.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/ftpgetinfo.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/ftpgetresp.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/ftpsget.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/ftpupload.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/getinfo.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/getinmemory.Po@am__quote@ @@ -612,41 +1005,51 @@ distclean-compile: @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/httpcustomheader.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/httpput.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/https.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/imap.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/multi-app.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/multi-debugcallback.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/multi-double.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/multi-post.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/multi-single.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/persistant.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/pop3s.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/pop3slist.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/post-callback.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/postit2.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/progressfunc.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/resolve.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/rtsp.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/sendrecv.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/sepheaders.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/sftpget.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/simple.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/simplepost.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/simplesmtp.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/simplessl.Po@am__quote@ @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/smtp-multi.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/smtp-tls.Po@am__quote@ +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/url2file.Po@am__quote@ .c.o: -@am__fastdepCC_TRUE@ if $(COMPILE) -MT $@ -MD -MP -MF "$(DEPDIR)/$*.Tpo" -c -o $@ $<; \ -@am__fastdepCC_TRUE@ then mv -f "$(DEPDIR)/$*.Tpo" "$(DEPDIR)/$*.Po"; else rm -f "$(DEPDIR)/$*.Tpo"; exit 1; fi -@AMDEP_TRUE@@am__fastdepCC_FALSE@ source='$<' object='$@' libtool=no @AMDEPBACKSLASH@ +@am__fastdepCC_TRUE@ $(AM_V_CC)$(COMPILE) -MT $@ -MD -MP -MF $(DEPDIR)/$*.Tpo -c -o $@ $< +@am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/$*.Tpo $(DEPDIR)/$*.Po +@AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='$<' object='$@' libtool=no @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ -@am__fastdepCC_FALSE@ $(COMPILE) -c $< +@am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(COMPILE) -c $< .c.obj: -@am__fastdepCC_TRUE@ if $(COMPILE) -MT $@ -MD -MP -MF "$(DEPDIR)/$*.Tpo" -c -o $@ `$(CYGPATH_W) '$<'`; \ -@am__fastdepCC_TRUE@ then mv -f "$(DEPDIR)/$*.Tpo" "$(DEPDIR)/$*.Po"; else rm -f "$(DEPDIR)/$*.Tpo"; exit 1; fi -@AMDEP_TRUE@@am__fastdepCC_FALSE@ source='$<' object='$@' libtool=no @AMDEPBACKSLASH@ +@am__fastdepCC_TRUE@ $(AM_V_CC)$(COMPILE) -MT $@ -MD -MP -MF $(DEPDIR)/$*.Tpo -c -o $@ `$(CYGPATH_W) '$<'` +@am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/$*.Tpo $(DEPDIR)/$*.Po +@AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='$<' object='$@' libtool=no @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ -@am__fastdepCC_FALSE@ $(COMPILE) -c `$(CYGPATH_W) '$<'` +@am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(COMPILE) -c `$(CYGPATH_W) '$<'` .c.lo: -@am__fastdepCC_TRUE@ if $(LTCOMPILE) -MT $@ -MD -MP -MF "$(DEPDIR)/$*.Tpo" -c -o $@ $<; \ -@am__fastdepCC_TRUE@ then mv -f "$(DEPDIR)/$*.Tpo" "$(DEPDIR)/$*.Plo"; else rm -f "$(DEPDIR)/$*.Tpo"; exit 1; fi -@AMDEP_TRUE@@am__fastdepCC_FALSE@ source='$<' object='$@' libtool=yes @AMDEPBACKSLASH@ +@am__fastdepCC_TRUE@ $(AM_V_CC)$(LTCOMPILE) -MT $@ -MD -MP -MF $(DEPDIR)/$*.Tpo -c -o $@ $< +@am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/$*.Tpo $(DEPDIR)/$*.Plo +@AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='$<' object='$@' libtool=yes @AMDEPBACKSLASH@ @AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ -@am__fastdepCC_FALSE@ $(LTCOMPILE) -c -o $@ $< +@am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LTCOMPILE) -c -o $@ $< mostlyclean-libtool: -rm -f *.lo @@ -654,82 +1057,85 @@ mostlyclean-libtool: clean-libtool: -rm -rf .libs _libs -distclean-libtool: - -rm -f libtool -uninstall-info-am: - -ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES) - list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ - unique=`for i in $$list; do \ - if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ - done | \ - $(AWK) ' { files[$$0] = 1; } \ - END { for (i in files) print i; }'`; \ - mkid -fID $$unique -tags: TAGS - -TAGS: $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ - $(TAGS_FILES) $(LISP) - tags=; \ +ID: $(am__tagged_files) + $(am__define_uniq_tagged_files); mkid -fID $$unique +tags: tags-am +TAGS: tags + +tags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) + set x; \ here=`pwd`; \ - list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ - unique=`for i in $$list; do \ - if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ - done | \ - $(AWK) ' { files[$$0] = 1; } \ - END { for (i in files) print i; }'`; \ - if test -z "$(ETAGS_ARGS)$$tags$$unique"; then :; else \ + $(am__define_uniq_tagged_files); \ + shift; \ + if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \ test -n "$$unique" || unique=$$empty_fix; \ - $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ - $$tags $$unique; \ + if test $$# -gt 0; then \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + "$$@" $$unique; \ + else \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + $$unique; \ + fi; \ fi -ctags: CTAGS -CTAGS: $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ - $(TAGS_FILES) $(LISP) - tags=; \ - here=`pwd`; \ - list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ - unique=`for i in $$list; do \ - if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ - done | \ - $(AWK) ' { files[$$0] = 1; } \ - END { for (i in files) print i; }'`; \ - test -z "$(CTAGS_ARGS)$$tags$$unique" \ +ctags: ctags-am + +CTAGS: ctags +ctags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) + $(am__define_uniq_tagged_files); \ + test -z "$(CTAGS_ARGS)$$unique" \ || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ - $$tags $$unique + $$unique GTAGS: here=`$(am__cd) $(top_builddir) && pwd` \ - && cd $(top_srcdir) \ - && gtags -i $(GTAGS_ARGS) $$here + && $(am__cd) $(top_srcdir) \ + && gtags -i $(GTAGS_ARGS) "$$here" +cscopelist: cscopelist-am + +cscopelist-am: $(am__tagged_files) + list='$(am__tagged_files)'; \ + case "$(srcdir)" in \ + [\\/]* | ?:[\\/]*) sdir="$(srcdir)" ;; \ + *) sdir=$(subdir)/$(srcdir) ;; \ + esac; \ + for i in $$list; do \ + if test -f "$$i"; then \ + echo "$(subdir)/$$i"; \ + else \ + echo "$$sdir/$$i"; \ + fi; \ + done >> $(top_builddir)/cscope.files distclean-tags: -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags distdir: $(DISTFILES) - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ - list='$(DISTFILES)'; for file in $$list; do \ - case $$file in \ - $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ - $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ - esac; \ + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ - dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ - if test "$$dir" != "$$file" && test "$$dir" != "."; then \ - dir="/$$dir"; \ - $(mkdir_p) "$(distdir)$$dir"; \ - else \ - dir=''; \ - fi; \ if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ - cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ fi; \ - cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ else \ - test -f $(distdir)/$$file \ - || cp -p $$d/$$file $(distdir)/$$file \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ || exit 1; \ fi; \ done @@ -748,16 +1154,22 @@ install-am: all-am installcheck: installcheck-am install-strip: - $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ - install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ - `test -z '$(STRIP)' || \ - echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi mostlyclean-generic: clean-generic: distclean-generic: -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @@ -771,7 +1183,7 @@ distclean: distclean-am -rm -rf ./$(DEPDIR) -rm -f Makefile distclean-am: clean-am distclean-compile distclean-generic \ - distclean-libtool distclean-tags + distclean-tags dvi: dvi-am @@ -779,18 +1191,38 @@ dvi-am: html: html-am +html-am: + info: info-am info-am: install-data-am: +install-dvi: install-dvi-am + +install-dvi-am: + install-exec-am: +install-html: install-html-am + +install-html-am: + install-info: install-info-am +install-info-am: + install-man: +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + installcheck-am: maintainer-clean: maintainer-clean-am @@ -811,22 +1243,29 @@ ps: ps-am ps-am: -uninstall-am: uninstall-info-am +uninstall-am: + +.MAKE: check-am install-am install-strip -.PHONY: CTAGS GTAGS all all-am check check-am clean \ - clean-checkPROGRAMS clean-generic clean-libtool ctags \ - distclean distclean-compile distclean-generic \ +.PHONY: CTAGS GTAGS TAGS all all-am check check-am clean \ + clean-checkPROGRAMS clean-generic clean-libtool cscopelist-am \ + ctags ctags-am distclean distclean-compile distclean-generic \ distclean-libtool distclean-tags distdir dvi dvi-am html \ html-am info info-am install install-am install-data \ - install-data-am install-exec install-exec-am install-info \ - install-info-am install-man install-strip installcheck \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-pdf install-pdf-am \ + install-ps install-ps-am install-strip installcheck \ installcheck-am installdirs maintainer-clean \ maintainer-clean-generic mostlyclean mostlyclean-compile \ mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ - tags uninstall uninstall-am uninstall-info-am + tags tags-am uninstall uninstall-am # Makefile.inc provides the check_PROGRAMS and COMPLICATED_EXAMPLES defines + +all: $(check_PROGRAMS) + # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: diff --git a/docs/examples/Makefile.inc b/docs/examples/Makefile.inc index 34c1c0f1d..6752db43d 100644 --- a/docs/examples/Makefile.inc +++ b/docs/examples/Makefile.inc @@ -4,11 +4,13 @@ check_PROGRAMS = 10-at-a-time anyauthput cookie_interface debug fileupload \ https multi-app multi-debugcallback multi-double multi-post multi-single \ persistant post-callback postit2 sepheaders simple simplepost simplessl \ sendrecv httpcustomheader certinfo chkspeed ftpgetinfo ftp-wildcard \ - smtp-multi + smtp-multi simplesmtp smtp-tls rtsp externalsocket resolve \ + progressfunc pop3s pop3slist imap url2file sftpget ftpsget # These examples require external dependencies that may not be commonly # available on POSIX systems, so don't bother attempting to compile them here. -COMPLICATED_EXAMPLES = curlgtk.c curlx.c htmltitle.cc cacertinmem.c \ +COMPLICATED_EXAMPLES = curlgtk.c curlx.c htmltitle.cpp cacertinmem.c \ ftpuploadresume.c ghiper.c hiperfifo.c htmltidy.c multithread.c \ opensslthreadlock.c sampleconv.c synctime.c threaded-ssl.c evhiperfifo.c \ - smooth-gtk-thread.c version-check.pl + smooth-gtk-thread.c version-check.pl href_extractor.c asiohiper.cpp \ + multi-uv.c xmlstream.c usercertinmem.c diff --git a/docs/examples/Makefile.m32 b/docs/examples/Makefile.m32 index 15750d01f..6bfb9fa81 100644 --- a/docs/examples/Makefile.m32 +++ b/docs/examples/Makefile.m32 @@ -1,28 +1,62 @@ -######################################################################### +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| # -## Makefile for building curl examples with MingW32 -## and optionally OpenSSL (0.9.8), libssh2 (0.18), zlib (1.2.3) +# Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +# +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### +# +## Makefile for building curl examples with MingW (GCC-3.2 or later) +## and optionally OpenSSL (0.9.8), libssh2 (1.3), zlib (1.2.5), librtmp (2.3) ## -## Usage: -## mingw32-make -f Makefile.m32 [SSL=1] [SSH2=1] [ZLIB=1] [SSPI=1] [IPV6=1] [DYN=1] +## Usage: mingw32-make -f Makefile.m32 CFG=-feature1[-feature2][-feature3][...] +## Example: mingw32-make -f Makefile.m32 CFG=-zlib-ssl-spi-winidn ## ## Hint: you can also set environment vars to control the build, f.e.: -## set ZLIB_PATH=c:/zlib-1.2.3 +## set ZLIB_PATH=c:/zlib-1.2.8 ## set ZLIB=1 -## -######################################################################### +# +########################################################################### # Edit the path below to point to the base of your Zlib sources. ifndef ZLIB_PATH -ZLIB_PATH = ../../zlib-1.2.3 +ZLIB_PATH = ../../../zlib-1.2.8 endif # Edit the path below to point to the base of your OpenSSL package. ifndef OPENSSL_PATH -OPENSSL_PATH = ../../openssl-0.9.8k +OPENSSL_PATH = ../../../openssl-0.9.8y endif # Edit the path below to point to the base of your LibSSH2 package. ifndef LIBSSH2_PATH -LIBSSH2_PATH = ../../libssh2-1.2 +LIBSSH2_PATH = ../../../libssh2-1.4.3 +endif +# Edit the path below to point to the base of your librtmp package. +ifndef LIBRTMP_PATH +LIBRTMP_PATH = ../../../librtmp-2.3 +endif +# Edit the path below to point to the base of your libidn package. +ifndef LIBIDN_PATH +LIBIDN_PATH = ../../../libidn-1.18 +endif +# Edit the path below to point to the base of your MS IDN package. +# Microsoft Internationalized Domain Names (IDN) Mitigation APIs 1.1 +# http://www.microsoft.com/downloads/en/details.aspx?FamilyID=ad6158d7-ddba-416a-9109-07607425a815 +ifndef WINIDN_PATH +WINIDN_PATH = ../../../Microsoft IDN Mitigation APIs endif # Edit the path below to point to the base of your Novell LDAP NDK. ifndef LDAP_SDK @@ -30,25 +64,108 @@ LDAP_SDK = c:/novell/ndk/cldapsdk/win32 endif PROOT = ../.. -ARES_LIB = $(PROOT)/ares -SSL = 1 -ZLIB = 1 +# Edit the path below to point to the base of your c-ares package. +ifndef LIBCARES_PATH +LIBCARES_PATH = $(PROOT)/ares +endif -CC = gcc -CFLAGS = -g -O2 -Wall +# Edit the var below to set to your architecture or set environment var. +ifndef ARCH +ARCH = w32 +endif + +CC = $(CROSSPREFIX)gcc +CFLAGS = -g -O2 -Wall +CFLAGS += -fno-strict-aliasing +ifeq ($(ARCH),w64) +CFLAGS += -D_AMD64_ +endif # comment LDFLAGS below to keep debug info -LDFLAGS = -s -RC = windres -RCFLAGS = --include-dir=$(PROOT)/include -O COFF -i -RM = del /q /f > NUL 2>&1 -CP = copy +LDFLAGS = -s +RC = $(CROSSPREFIX)windres +RCFLAGS = --include-dir=$(PROOT)/include -O COFF -i + +# Platform-dependent helper tool macros +ifeq ($(findstring /sh,$(SHELL)),/sh) +DEL = rm -f $1 +RMDIR = rm -fr $1 +MKDIR = mkdir -p $1 +COPY = -cp -afv $1 $2 +#COPYR = -cp -afr $1/* $2 +COPYR = -rsync -aC $1/* $2 +TOUCH = touch $1 +CAT = cat +ECHONL = echo "" +DL = ' +else +ifeq "$(OS)" "Windows_NT" +DEL = -del 2>NUL /q /f $(subst /,\,$1) +RMDIR = -rd 2>NUL /q /s $(subst /,\,$1) +else +DEL = -del 2>NUL $(subst /,\,$1) +RMDIR = -deltree 2>NUL /y $(subst /,\,$1) +endif +MKDIR = -md 2>NUL $(subst /,\,$1) +COPY = -copy 2>NUL /y $(subst /,\,$1) $(subst /,\,$2) +COPYR = -xcopy 2>NUL /q /y /e $(subst /,\,$1) $(subst /,\,$2) +TOUCH = copy 2>&1>NUL /b $(subst /,\,$1) +,, +CAT = type +ECHONL = $(ComSpec) /c echo. +endif ######################################################## ## Nothing more to do below this line! +ifeq ($(findstring -dyn,$(CFG)),-dyn) +DYN = 1 +endif +ifeq ($(findstring -ares,$(CFG)),-ares) +ARES = 1 +endif +ifeq ($(findstring -rtmp,$(CFG)),-rtmp) +RTMP = 1 +SSL = 1 +ZLIB = 1 +endif +ifeq ($(findstring -ssh2,$(CFG)),-ssh2) +SSH2 = 1 +SSL = 1 +ZLIB = 1 +endif +ifeq ($(findstring -ssl,$(CFG)),-ssl) +SSL = 1 +endif +ifeq ($(findstring -zlib,$(CFG)),-zlib) +ZLIB = 1 +endif +ifeq ($(findstring -idn,$(CFG)),-idn) +IDN = 1 +endif +ifeq ($(findstring -winidn,$(CFG)),-winidn) +WINIDN = 1 +endif +ifeq ($(findstring -sspi,$(CFG)),-sspi) +SSPI = 1 +endif +ifeq ($(findstring -spnego,$(CFG)),-spnego) +SPNEGO = 1 +endif +ifeq ($(findstring -ldaps,$(CFG)),-ldaps) +LDAPS = 1 +endif +ifeq ($(findstring -ipv6,$(CFG)),-ipv6) +IPV6 = 1 +endif +ifeq ($(findstring -metalink,$(CFG)),-metalink) +METALINK = 1 +endif +ifeq ($(findstring -winssl,$(CFG)),-winssl) +SCHANNEL = 1 +SSPI = 1 +endif + INCLUDES = -I. -I$(PROOT) -I$(PROOT)/include -I$(PROOT)/lib -LINK = $(CC) $(LDFLAGS) -o $@ ifdef DYN curl_DEPENDENCIES = $(PROOT)/lib/libcurldll.a $(PROOT)/lib/libcurl.dll @@ -57,37 +174,67 @@ else curl_DEPENDENCIES = $(PROOT)/lib/libcurl.a curl_LDADD = -L$(PROOT)/lib -lcurl CFLAGS += -DCURL_STATICLIB + LDFLAGS += -static endif ifdef ARES ifndef DYN - curl_DEPENDENCIES += $(ARES_LIB)/libcares.a + curl_DEPENDENCIES += $(LIBCARES_PATH)/libcares.a endif CFLAGS += -DUSE_ARES - curl_LDADD += -L$(ARES_LIB) -lcares + curl_LDADD += -L"$(LIBCARES_PATH)" -lcares +endif +ifdef RTMP + CFLAGS += -DUSE_LIBRTMP + curl_LDADD += -L"$(LIBRTMP_PATH)/librtmp" -lrtmp -lwinmm endif ifdef SSH2 CFLAGS += -DUSE_LIBSSH2 -DHAVE_LIBSSH2_H - curl_LDADD += -L$(LIBSSH2_PATH)/win32 -lssh2 + curl_LDADD += -L"$(LIBSSH2_PATH)/win32" -lssh2 endif ifdef SSL - INCLUDES += -I"$(OPENSSL_PATH)/outinc" - CFLAGS += -DUSE_SSLEAY -DHAVE_OPENSSL_ENGINE_H - ifdef DYN - curl_LDADD += -L$(OPENSSL_PATH)/out -leay32 -lssl32 - else - curl_LDADD += -L$(OPENSSL_PATH)/out -lssl -lcrypto -lgdi32 + ifndef OPENSSL_LIBPATH + OPENSSL_LIBS = -lssl -lcrypto + ifeq "$(wildcard $(OPENSSL_PATH)/out)" "$(OPENSSL_PATH)/out" + OPENSSL_LIBPATH = $(OPENSSL_PATH)/out + ifdef DYN + OPENSSL_LIBS = -lssl32 -leay32 + endif + endif + ifeq "$(wildcard $(OPENSSL_PATH)/lib)" "$(OPENSSL_PATH)/lib" + OPENSSL_LIBPATH = $(OPENSSL_PATH)/lib + endif + endif + ifndef DYN + OPENSSL_LIBS += -lgdi32 -lcrypt32 endif + CFLAGS += -DUSE_SSLEAY + curl_LDADD += -L"$(OPENSSL_LIBPATH)" $(OPENSSL_LIBS) endif ifdef ZLIB INCLUDES += -I"$(ZLIB_PATH)" CFLAGS += -DHAVE_LIBZ -DHAVE_ZLIB_H - curl_LDADD += -L$(ZLIB_PATH) -lz + curl_LDADD += -L"$(ZLIB_PATH)" -lz +endif +ifdef IDN + CFLAGS += -DUSE_LIBIDN + curl_LDADD += -L"$(LIBIDN_PATH)/lib" -lidn +else +ifdef WINIDN + CFLAGS += -DUSE_WIN32_IDN + curl_LDADD += -L"$(WINIDN_PATH)" -lnormaliz +endif endif ifdef SSPI CFLAGS += -DUSE_WINDOWS_SSPI + ifdef SCHANNEL + CFLAGS += -DUSE_SCHANNEL + endif +endif +ifdef SPNEGO + CFLAGS += -DHAVE_SPNEGO endif ifdef IPV6 - CFLAGS += -DENABLE_IPV6 + CFLAGS += -DENABLE_IPV6 -D_WIN32_WINNT=0x0501 endif ifdef LDAPS CFLAGS += -DHAVE_LDAP_SSL @@ -102,32 +249,34 @@ ifdef USE_LDAP_OPENLDAP endif ifndef USE_LDAP_NOVELL ifndef USE_LDAP_OPENLDAP -curl_LDADD += -lwldap32 + curl_LDADD += -lwldap32 endif endif curl_LDADD += -lws2_32 -COMPILE = $(CC) $(INCLUDES) $(CFLAGS) # Makefile.inc provides the check_PROGRAMS and COMPLICATED_EXAMPLES defines include Makefile.inc -example_PROGRAMS := $(patsubst %,%.exe,$(strip $(check_PROGRAMS))) +check_PROGRAMS := $(patsubst %,%.exe,$(strip $(check_PROGRAMS))) +check_PROGRAMS += ftpuploadresume.exe synctime.exe -.SUFFIXES: .rc .res .o .exe +.PRECIOUS: %.o -all: $(example_PROGRAMS) +all: $(check_PROGRAMS) -.o.exe: $(curl_DEPENDENCIES) - $(LINK) $< $(curl_LDADD) +%.exe: %.o $(curl_DEPENDENCIES) + $(CC) $(LDFLAGS) -o $@ $< $(curl_LDADD) -.c.o: - $(COMPILE) -c $< +%.o: %.c + $(CC) $(INCLUDES) $(CFLAGS) -c $< -.rc.res: +%.res: %.rc $(RC) $(RCFLAGS) $< -o $@ clean: - $(RM) $(example_PROGRAMS) + @$(call DEL, $(check_PROGRAMS:.exe=.o)) +distclean vclean: clean + @$(call DEL, $(check_PROGRAMS)) diff --git a/docs/examples/Makefile.netware b/docs/examples/Makefile.netware new file mode 100644 index 000000000..2816cbd77 --- /dev/null +++ b/docs/examples/Makefile.netware @@ -0,0 +1,441 @@ +################################################################# +# +## Makefile for building curl.nlm (NetWare version - gnu make) +## Use: make -f Makefile.netware +## +## Comments to: Guenter Knauf http://www.gknw.net/phpbb +# +################################################################# + +# Edit the path below to point to the base of your Novell NDK. +ifndef NDKBASE +NDKBASE = c:/novell +endif + +# Edit the path below to point to the base of your Zlib sources. +ifndef ZLIB_PATH +ZLIB_PATH = ../../../zlib-1.2.8 +endif + +# Edit the path below to point to the base of your OpenSSL package. +ifndef OPENSSL_PATH +OPENSSL_PATH = ../../../openssl-0.9.8y +endif + +# Edit the path below to point to the base of your LibSSH2 package. +ifndef LIBSSH2_PATH +LIBSSH2_PATH = ../../../libssh2-1.4.3 +endif + +# Edit the path below to point to the base of your axTLS package. +ifndef AXTLS_PATH +AXTLS_PATH = ../../../axTLS-1.2.7 +endif + +# Edit the path below to point to the base of your libidn package. +ifndef LIBIDN_PATH +LIBIDN_PATH = ../../../libidn-1.18 +endif + +# Edit the path below to point to the base of your librtmp package. +ifndef LIBRTMP_PATH +LIBRTMP_PATH = ../../../librtmp-2.3 +endif + +# Edit the path below to point to the base of your fbopenssl package. +ifndef FBOPENSSL_PATH +FBOPENSSL_PATH = ../../fbopenssl-0.4 +endif + +# Edit the path below to point to the base of your c-ares package. +ifndef LIBCARES_PATH +LIBCARES_PATH = ../../ares +endif + +ifndef INSTDIR +INSTDIR = ..$(DS)..$(DS)curl-$(LIBCURL_VERSION_STR)-bin-nw +endif + +# Edit the vars below to change NLM target settings. +TARGET = examples +VERSION = $(LIBCURL_VERSION) +COPYR = Copyright (C) $(LIBCURL_COPYRIGHT_STR) +DESCR = cURL ($(LIBARCH)) +MTSAFE = YES +STACK = 8192 +SCREEN = Example Program +# Comment the line below if you dont want to load protected automatically. +# LDRING = 3 + +# Uncomment the next line to enable linking with POSIX semantics. +# POSIXFL = 1 + +# Edit the var below to point to your lib architecture. +ifndef LIBARCH +LIBARCH = LIBC +endif + +# must be equal to NDEBUG or DEBUG, CURLDEBUG +ifndef DB +DB = NDEBUG +endif +# Optimization: -O<n> or debugging: -g +ifeq ($(DB),NDEBUG) + OPT = -O2 + OBJDIR = release +else + OPT = -g + OBJDIR = debug +endif + +# The following lines defines your compiler. +ifdef CWFolder + METROWERKS = $(CWFolder) +endif +ifdef METROWERKS + # MWCW_PATH = $(subst \,/,$(METROWERKS))/Novell Support + MWCW_PATH = $(subst \,/,$(METROWERKS))/Novell Support/Metrowerks Support + CC = mwccnlm +else + CC = gcc +endif +PERL = perl +# Here you can find a native Win32 binary of the original awk: +# http://www.gknw.net/development/prgtools/awk-20100523.zip +AWK = awk +CP = cp -afv +MKDIR = mkdir +# RM = rm -f +# If you want to mark the target as MTSAFE you will need a tool for +# generating the xdc data for the linker; here's a minimal tool: +# http://www.gknw.net/development/prgtools/mkxdc.zip +MPKXDC = mkxdc + +# LIBARCH_U = $(shell $(AWK) 'BEGIN {print toupper(ARGV[1])}' $(LIBARCH)) +LIBARCH_L = $(shell $(AWK) 'BEGIN {print tolower(ARGV[1])}' $(LIBARCH)) + +# Include the version info retrieved from curlver.h +-include $(OBJDIR)/version.inc + +# Global flags for all compilers +CFLAGS += $(OPT) -D$(DB) -DNETWARE -DHAVE_CONFIG_H -nostdinc + +ifeq ($(CC),mwccnlm) +LD = mwldnlm +LDFLAGS = -nostdlib $< $(PRELUDE) $(LDLIBS) -o $@ -commandfile +LIBEXT = lib +CFLAGS += -gccinc -inline off -opt nointrinsics -proc 586 +CFLAGS += -relax_pointers +#CFLAGS += -w on +ifeq ($(LIBARCH),LIBC) +ifeq ($(POSIXFL),1) + PRELUDE = $(NDK_LIBC)/imports/posixpre.o +else + PRELUDE = $(NDK_LIBC)/imports/libcpre.o +endif + CFLAGS += -align 4 +else + # PRELUDE = $(NDK_CLIB)/imports/clibpre.o + # to avoid the __init_* / __deinit_* whoes dont use prelude from NDK + PRELUDE = "$(MWCW_PATH)/libraries/runtime/prelude.obj" + # CFLAGS += -include "$(MWCW_PATH)/headers/nlm_clib_prefix.h" + CFLAGS += -align 1 +endif +else +LD = nlmconv +LDFLAGS = -T +LIBEXT = a +CFLAGS += -m32 +CFLAGS += -fno-builtin -fno-strict-aliasing +ifeq ($(findstring gcc,$(CC)),gcc) +CFLAGS += -fpcc-struct-return +endif +CFLAGS += -Wall # -pedantic +ifeq ($(LIBARCH),LIBC) +ifeq ($(POSIXFL),1) + PRELUDE = $(NDK_LIBC)/imports/posixpre.gcc.o +else + PRELUDE = $(NDK_LIBC)/imports/libcpre.gcc.o +endif +else + # PRELUDE = $(NDK_CLIB)/imports/clibpre.gcc.o + # to avoid the __init_* / __deinit_* whoes dont use prelude from NDK + # http://www.gknw.net/development/mk_nlm/gcc_pre.zip + PRELUDE = $(NDK_ROOT)/pre/prelude.o + CFLAGS += -include $(NDKBASE)/nlmconv/genlm.h +endif +endif + +NDK_ROOT = $(NDKBASE)/ndk +ifndef NDK_CLIB +NDK_CLIB = $(NDK_ROOT)/nwsdk +endif +ifndef NDK_LIBC +NDK_LIBC = $(NDK_ROOT)/libc +endif +ifndef NDK_LDAP +NDK_LDAP = $(NDK_ROOT)/cldapsdk/netware +endif +CURL_INC = ../../include +CURL_LIB = ../../lib + +INCLUDES = -I$(CURL_INC) + +ifeq ($(findstring -static,$(CFG)),-static) +LINK_STATIC = 1 +endif +ifeq ($(findstring -ares,$(CFG)),-ares) +WITH_ARES = 1 +endif +ifeq ($(findstring -rtmp,$(CFG)),-rtmp) +WITH_RTMP = 1 +WITH_SSL = 1 +WITH_ZLIB = 1 +endif +ifeq ($(findstring -ssh2,$(CFG)),-ssh2) +WITH_SSH2 = 1 +WITH_SSL = 1 +WITH_ZLIB = 1 +endif +ifeq ($(findstring -axtls,$(CFG)),-axtls) +WITH_AXTLS = 1 +WITH_SSL = +else +ifeq ($(findstring -ssl,$(CFG)),-ssl) +WITH_SSL = 1 +endif +endif +ifeq ($(findstring -zlib,$(CFG)),-zlib) +WITH_ZLIB = 1 +endif +ifeq ($(findstring -idn,$(CFG)),-idn) +WITH_IDN = 1 +endif +ifeq ($(findstring -spnego,$(CFG)),-spnego) +WITH_SPNEGO = 1 +endif +ifeq ($(findstring -ipv6,$(CFG)),-ipv6) +ENABLE_IPV6 = 1 +endif + +ifdef LINK_STATIC + LDLIBS = $(CURL_LIB)/libcurl.$(LIBEXT) +ifdef WITH_ARES + LDLIBS += $(LIBCARES_PATH)/libcares.$(LIBEXT) +endif +else + MODULES = libcurl.nlm + IMPORTS = @$(CURL_LIB)/libcurl.imp +endif +ifdef WITH_SSH2 + # INCLUDES += -I$(LIBSSH2_PATH)/include +ifdef LINK_STATIC + LDLIBS += $(LIBSSH2_PATH)/nw/libssh2.$(LIBEXT) +else + MODULES += libssh2.nlm + IMPORTS += @$(LIBSSH2_PATH)/nw/libssh2.imp +endif +endif +ifdef WITH_RTMP + # INCLUDES += -I$(LIBRTMP_PATH) +ifdef LINK_STATIC + LDLIBS += $(LIBRTMP_PATH)/librtmp/librtmp.$(LIBEXT) +endif +endif +ifdef WITH_SSL + INCLUDES += -I$(OPENSSL_PATH)/outinc_nw_$(LIBARCH_L) + LDLIBS += $(OPENSSL_PATH)/out_nw_$(LIBARCH_L)/ssl.$(LIBEXT) + LDLIBS += $(OPENSSL_PATH)/out_nw_$(LIBARCH_L)/crypto.$(LIBEXT) + IMPORTS += GetProcessSwitchCount RunningProcess +ifdef WITH_SPNEGO + # INCLUDES += -I$(FBOPENSSL_PATH)/include + LDLIBS += $(FBOPENSSL_PATH)/nw/fbopenssl.$(LIBEXT) +endif +else +ifdef WITH_AXTLS + INCLUDES += -I$(AXTLS_PATH)/inc +ifdef LINK_STATIC + LDLIBS += $(AXTLS_PATH)/lib/libaxtls.$(LIBEXT) +else + MODULES += libaxtls.nlm + IMPORTS += $(AXTLS_PATH)/lib/libaxtls.imp +endif +endif +endif +ifdef WITH_ZLIB + # INCLUDES += -I$(ZLIB_PATH) +ifdef LINK_STATIC + LDLIBS += $(ZLIB_PATH)/nw/$(LIBARCH)/libz.$(LIBEXT) +else + MODULES += libz.nlm + IMPORTS += @$(ZLIB_PATH)/nw/$(LIBARCH)/libz.imp +endif +endif +ifdef WITH_IDN + # INCLUDES += -I$(LIBIDN_PATH)/include + LDLIBS += $(LIBIDN_PATH)/lib/libidn.$(LIBEXT) +endif + +ifeq ($(LIBARCH),LIBC) + INCLUDES += -I$(NDK_LIBC)/include + # INCLUDES += -I$(NDK_LIBC)/include/nks + # INCLUDES += -I$(NDK_LIBC)/include/winsock + CFLAGS += -D_POSIX_SOURCE +else + INCLUDES += -I$(NDK_CLIB)/include/nlm + # INCLUDES += -I$(NDK_CLIB)/include +endif +ifndef DISABLE_LDAP + # INCLUDES += -I$(NDK_LDAP)/$(LIBARCH_L)/inc +endif +CFLAGS += $(INCLUDES) + +ifeq ($(MTSAFE),YES) + XDCOPT = -n +endif +ifeq ($(MTSAFE),NO) + XDCOPT = -u +endif +ifdef XDCOPT + XDCDATA = $(OBJDIR)/$(TARGET).xdc +endif + +ifeq ($(findstring /sh,$(SHELL)),/sh) +DL = ' +DS = / +PCT = % +#-include $(NDKBASE)/nlmconv/ncpfs.inc +else +DS = \\ +PCT = %% +endif + +# Makefile.inc provides the CSOURCES and HHEADERS defines +include Makefile.inc + +check_PROGRAMS := $(patsubst %,%.nlm,$(strip $(check_PROGRAMS))) + +.PRECIOUS: $(OBJDIR)/%.o $(OBJDIR)/%.def $(OBJDIR)/%.xdc + + +all: prebuild $(check_PROGRAMS) + +prebuild: $(OBJDIR) $(OBJDIR)/version.inc + +$(OBJDIR)/%.o: %.c + @echo Compiling $< + $(CC) $(CFLAGS) -c $< -o $@ + +$(OBJDIR)/version.inc: $(CURL_INC)/curl/curlver.h $(OBJDIR) + @echo Creating $@ + @$(AWK) -f ../../packages/NetWare/get_ver.awk $< > $@ + +install: $(INSTDIR) all + @$(CP) $(check_PROGRAMS) $(INSTDIR) + +clean: + -$(RM) -r $(OBJDIR) + +distclean vclean: clean + -$(RM) $(check_PROGRAMS) + +$(OBJDIR) $(INSTDIR): + @$(MKDIR) $@ + +%.nlm: $(OBJDIR)/%.o $(OBJDIR)/%.def $(XDCDATA) + @echo Linking $@ + @-$(RM) $@ + @$(LD) $(LDFLAGS) $(OBJDIR)/$(@:.nlm=.def) + +$(OBJDIR)/%.xdc: Makefile.netware + @echo Creating $@ + @$(MPKXDC) $(XDCOPT) $@ + +$(OBJDIR)/%.def: Makefile.netware + @echo $(DL)# DEF file for linking with $(LD)$(DL) > $@ + @echo $(DL)# Do not edit this file - it is created by Make!$(DL) >> $@ + @echo $(DL)# All your changes will be lost!!$(DL) >> $@ + @echo $(DL)#$(DL) >> $@ + @echo $(DL)copyright "$(COPYR)"$(DL) >> $@ + @echo $(DL)description "$(DESCR) $(notdir $(@:.def=)) Example"$(DL) >> $@ + @echo $(DL)version $(VERSION)$(DL) >> $@ +ifdef NLMTYPE + @echo $(DL)type $(NLMTYPE)$(DL) >> $@ +endif +ifdef STACK + @echo $(DL)stack $(STACK)$(DL) >> $@ +endif +ifdef SCREEN + @echo $(DL)screenname "$(DESCR) $(notdir $(@:.def=)) $(SCREEN)"$(DL) >> $@ +else + @echo $(DL)screenname "DEFAULT"$(DL) >> $@ +endif +ifneq ($(DB),NDEBUG) + @echo $(DL)debug$(DL) >> $@ +endif + @echo $(DL)threadname "_$(notdir $(@:.def=))"$(DL) >> $@ +ifdef XDCDATA + @echo $(DL)xdcdata $(XDCDATA)$(DL) >> $@ +endif +ifeq ($(LDRING),0) + @echo $(DL)flag_on 16$(DL) >> $@ +endif +ifeq ($(LDRING),3) + @echo $(DL)flag_on 512$(DL) >> $@ +endif +ifeq ($(LIBARCH),CLIB) + @echo $(DL)start _Prelude$(DL) >> $@ + @echo $(DL)exit _Stop$(DL) >> $@ + @echo $(DL)import @$(NDK_CLIB)/imports/clib.imp$(DL) >> $@ + @echo $(DL)import @$(NDK_CLIB)/imports/threads.imp$(DL) >> $@ + @echo $(DL)import @$(NDK_CLIB)/imports/nlmlib.imp$(DL) >> $@ + @echo $(DL)import @$(NDK_CLIB)/imports/socklib.imp$(DL) >> $@ + @echo $(DL)module clib$(DL) >> $@ +ifndef DISABLE_LDAP + @echo $(DL)import @$(NDK_LDAP)/clib/imports/ldapsdk.imp$(DL) >> $@ + @echo $(DL)import @$(NDK_LDAP)/clib/imports/ldapssl.imp$(DL) >> $@ +# @echo $(DL)import @$(NDK_LDAP)/clib/imports/ldapx.imp$(DL) >> $@ + @echo $(DL)module ldapsdk ldapssl$(DL) >> $@ +endif +else +ifeq ($(POSIXFL),1) + @echo $(DL)flag_on 4194304$(DL) >> $@ +endif + @echo $(DL)flag_on 64$(DL) >> $@ + @echo $(DL)pseudopreemption$(DL) >> $@ +ifeq ($(findstring posixpre,$(PRELUDE)),posixpre) + @echo $(DL)start POSIX_Start$(DL) >> $@ + @echo $(DL)exit POSIX_Stop$(DL) >> $@ + @echo $(DL)check POSIX_CheckUnload$(DL) >> $@ +else + @echo $(DL)start _LibCPrelude$(DL) >> $@ + @echo $(DL)exit _LibCPostlude$(DL) >> $@ + @echo $(DL)check _LibCCheckUnload$(DL) >> $@ +endif + @echo $(DL)import @$(NDK_LIBC)/imports/libc.imp$(DL) >> $@ + @echo $(DL)import @$(NDK_LIBC)/imports/netware.imp$(DL) >> $@ + @echo $(DL)module libc$(DL) >> $@ +ifndef DISABLE_LDAP + @echo $(DL)import @$(NDK_LDAP)/libc/imports/lldapsdk.imp$(DL) >> $@ + @echo $(DL)import @$(NDK_LDAP)/libc/imports/lldapssl.imp$(DL) >> $@ +# @echo $(DL)import @$(NDK_LDAP)/libc/imports/lldapx.imp$(DL) >> $@ + @echo $(DL)module lldapsdk lldapssl$(DL) >> $@ +endif +endif +ifdef MODULES + @echo $(DL)module $(MODULES)$(DL) >> $@ +endif +ifdef EXPORTS + @echo $(DL)export $(EXPORTS)$(DL) >> $@ +endif +ifdef IMPORTS + @echo $(DL)import $(IMPORTS)$(DL) >> $@ +endif +ifeq ($(findstring nlmconv,$(LD)),nlmconv) + @echo $(DL)input $(PRELUDE)$(DL) >> $@ + @echo $(DL)input $(@:.def=.o)$(DL) >> $@ +ifdef LDLIBS + @echo $(DL)input $(LDLIBS)$(DL) >> $@ +endif + @echo $(DL)output $(notdir $(@:.def=.nlm))$(DL) >> $@ +endif diff --git a/docs/examples/README b/docs/examples/README index d6c478568..1ca62a154 100644 --- a/docs/examples/README +++ b/docs/examples/README @@ -55,14 +55,18 @@ htmltitle.cc - download a HTML file and extract the <title> tag from a HTML http-post.c - HTTP POST httpput.c - HTTP PUT a local file https.c - simple HTTPS transfer +imap.c - simple IMAP transfer multi-app.c - a multi-interface app multi-debugcallback.c - a multi-interface app using the debug callback multi-double.c - a multi-interface app doing two simultaneous transfers multi-post.c - a multi-interface app doing a multipart formpost multi-single.c - a multi-interface app getting a single file +multi-uv.c - a multi-interface app using libuv multithread.c - an example using multi-treading transferring multiple files opensslthreadlock.c - show how to do locking when using OpenSSL multi-threaded persistant.c - request two URLs with a persistent connection +pop3s.c - POP3S transfer +pop3slist.c - POP3S LIST post-callback.c - send a HTTP POST using a callback postit2.c - send a HTTP multipart formpost sampleconv.c - showing how a program on a non-ASCII platform would invoke @@ -73,4 +77,6 @@ simple.c - the most simple download a URL source simplepost.c - HTTP POST simplessl.c - HTTPS example with certificates many options set synctime.c - Sync local time by extracting date from remote HTTP servers +url2file.c - download a document and store it in a file +xmlstream.c - Stream-parse a document using the streaming Expat parser 10-at-a-time.c - Download many files simultaneously, 10 at a time. diff --git a/docs/examples/anyauthput.c b/docs/examples/anyauthput.c index cec9fede5..b89dca2e1 100644 --- a/docs/examples/anyauthput.c +++ b/docs/examples/anyauthput.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <fcntl.h> #ifdef WIN32 @@ -14,7 +26,8 @@ #else # ifdef __VMS typedef int intptr_t; -# else +# endif +# if !defined(_AIX) && !defined(__sgi) && !defined(__osf__) # include <stdint.h> # endif # include <unistd.h> @@ -40,6 +53,12 @@ #define TRUE 1 #endif +#if defined(_AIX) || defined(__sgi) || defined(__osf__) +#ifndef intptr_t +#define intptr_t long +#endif +#endif + /* * This example shows a HTTP PUT operation with authentiction using "any" * type. It PUTs a file given as a command line argument to the URL also given @@ -77,12 +96,16 @@ static curlioerr my_ioctl(CURL *handle, curliocmd cmd, void *userp) static size_t read_callback(void *ptr, size_t size, size_t nmemb, void *stream) { size_t retcode; + curl_off_t nread; intptr_t fd = (intptr_t)stream; retcode = read(fd, ptr, size * nmemb); - fprintf(stderr, "*** We read %d bytes from file\n", retcode); + nread = (curl_off_t)retcode; + + fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T + " bytes from file\n", nread); return retcode; } @@ -147,6 +170,10 @@ int main(int argc, char **argv) /* Now run off and do what you've been told! */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); diff --git a/docs/examples/asiohiper.cpp b/docs/examples/asiohiper.cpp new file mode 100644 index 000000000..44836fdc1 --- /dev/null +++ b/docs/examples/asiohiper.cpp @@ -0,0 +1,454 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ + +/* + * file: asiohiper.cpp + * Example program to demonstrate the use of multi socket interface + * with boost::asio + * + * This program is in c++ and uses boost::asio instead of libevent/libev. + * Requires boost::asio, boost::bind and boost::system + * + * This is an adaptation of libcurl's "hiperfifo.c" and "evhiperfifo.c" + * sample programs. This example implements a subset of the functionality from + * hiperfifo.c, for full functionality refer hiperfifo.c or evhiperfifo.c + * + * Written by Lijo Antony based on hiperfifo.c by Jeff Pohlmeyer + * + * When running, the program creates an easy handle for a URL and + * uses the curl_multi API to fetch it. + * + * Note: + * For the sake of simplicity, URL is hard coded to "www.google.com" + * + * This is purely a demo app, all retrieved data is simply discarded by the write + * callback. + */ + + +#include <curl/curl.h> +#include <boost/asio.hpp> +#include <boost/bind.hpp> + +#define MSG_OUT stdout /* Send info to stdout, change to stderr if you want */ + +/* boost::asio related objects + * using global variables for simplicity + */ +boost::asio::io_service io_service; +boost::asio::deadline_timer timer(io_service); +std::map<curl_socket_t, boost::asio::ip::tcp::socket *> socket_map; + +/* Global information, common to all connections */ +typedef struct _GlobalInfo +{ + CURLM *multi; + int still_running; +} GlobalInfo; + +/* Information associated with a specific easy handle */ +typedef struct _ConnInfo +{ + CURL *easy; + char *url; + GlobalInfo *global; + char error[CURL_ERROR_SIZE]; +} ConnInfo; + +static void timer_cb(const boost::system::error_code & error, GlobalInfo *g); + +/* Update the event timer after curl_multi library calls */ +static int multi_timer_cb(CURLM *multi, long timeout_ms, GlobalInfo *g) +{ + fprintf(MSG_OUT, "\nmulti_timer_cb: timeout_ms %ld", timeout_ms); + + /* cancel running timer */ + timer.cancel(); + + if ( timeout_ms > 0 ) + { + /* update timer */ + timer.expires_from_now(boost::posix_time::millisec(timeout_ms)); + timer.async_wait(boost::bind(&timer_cb, _1, g)); + } + else + { + /* call timeout function immediately */ + boost::system::error_code error; /*success*/ + timer_cb(error, g); + } + + return 0; +} + +/* Die if we get a bad CURLMcode somewhere */ +static void mcode_or_die(const char *where, CURLMcode code) +{ + if ( CURLM_OK != code ) + { + const char *s; + switch ( code ) + { + case CURLM_CALL_MULTI_PERFORM: s="CURLM_CALL_MULTI_PERFORM"; break; + case CURLM_BAD_HANDLE: s="CURLM_BAD_HANDLE"; break; + case CURLM_BAD_EASY_HANDLE: s="CURLM_BAD_EASY_HANDLE"; break; + case CURLM_OUT_OF_MEMORY: s="CURLM_OUT_OF_MEMORY"; break; + case CURLM_INTERNAL_ERROR: s="CURLM_INTERNAL_ERROR"; break; + case CURLM_UNKNOWN_OPTION: s="CURLM_UNKNOWN_OPTION"; break; + case CURLM_LAST: s="CURLM_LAST"; break; + default: s="CURLM_unknown"; + break; + case CURLM_BAD_SOCKET: s="CURLM_BAD_SOCKET"; + fprintf(MSG_OUT, "\nERROR: %s returns %s", where, s); + /* ignore this error */ + return; + } + fprintf(MSG_OUT, "\nERROR: %s returns %s", where, s); + exit(code); + } +} + +/* Check for completed transfers, and remove their easy handles */ +static void check_multi_info(GlobalInfo *g) +{ + char *eff_url; + CURLMsg *msg; + int msgs_left; + ConnInfo *conn; + CURL *easy; + CURLcode res; + + fprintf(MSG_OUT, "\nREMAINING: %d", g->still_running); + + while ((msg = curl_multi_info_read(g->multi, &msgs_left))) + { + if (msg->msg == CURLMSG_DONE) + { + easy = msg->easy_handle; + res = msg->data.result; + curl_easy_getinfo(easy, CURLINFO_PRIVATE, &conn); + curl_easy_getinfo(easy, CURLINFO_EFFECTIVE_URL, &eff_url); + fprintf(MSG_OUT, "\nDONE: %s => (%d) %s", eff_url, res, conn->error); + curl_multi_remove_handle(g->multi, easy); + free(conn->url); + curl_easy_cleanup(easy); + free(conn); + } + } +} + +/* Called by asio when there is an action on a socket */ +static void event_cb(GlobalInfo * g, boost::asio::ip::tcp::socket * tcp_socket, int action) +{ + fprintf(MSG_OUT, "\nevent_cb: action=%d", action); + + CURLMcode rc; + rc = curl_multi_socket_action(g->multi, tcp_socket->native_handle(), action, &g->still_running); + + mcode_or_die("event_cb: curl_multi_socket_action", rc); + check_multi_info(g); + + if ( g->still_running <= 0 ) + { + fprintf(MSG_OUT, "\nlast transfer done, kill timeout"); + timer.cancel(); + } +} + +/* Called by asio when our timeout expires */ +static void timer_cb(const boost::system::error_code & error, GlobalInfo *g) +{ + if ( !error) + { + fprintf(MSG_OUT, "\ntimer_cb: "); + + CURLMcode rc; + rc = curl_multi_socket_action(g->multi, CURL_SOCKET_TIMEOUT, 0, &g->still_running); + + mcode_or_die("timer_cb: curl_multi_socket_action", rc); + check_multi_info(g); + } +} + +/* Clean up any data */ +static void remsock(int *f, GlobalInfo *g) +{ + fprintf(MSG_OUT, "\nremsock: "); + + if ( f ) + { + free(f); + } +} + +static void setsock(int *fdp, curl_socket_t s, CURL*e, int act, GlobalInfo*g) +{ + fprintf(MSG_OUT, "\nsetsock: socket=%d, act=%d, fdp=%p", s, act, fdp); + + std::map<curl_socket_t, boost::asio::ip::tcp::socket *>::iterator it = socket_map.find(s); + + if ( it == socket_map.end() ) + { + fprintf(MSG_OUT, "\nsocket %d is a c-ares socket, ignoring", s); + return; + } + + boost::asio::ip::tcp::socket * tcp_socket = it->second; + + *fdp = act; + + if ( act == CURL_POLL_IN ) + { + fprintf(MSG_OUT, "\nwatching for socket to become readable"); + + tcp_socket->async_read_some(boost::asio::null_buffers(), + boost::bind(&event_cb, g, + tcp_socket, + act)); + } + else if ( act == CURL_POLL_OUT ) + { + fprintf(MSG_OUT, "\nwatching for socket to become writable"); + + tcp_socket->async_write_some(boost::asio::null_buffers(), + boost::bind(&event_cb, g, + tcp_socket, + act)); + } + else if ( act == CURL_POLL_INOUT ) + { + fprintf(MSG_OUT, "\nwatching for socket to become readable & writable"); + + tcp_socket->async_read_some(boost::asio::null_buffers(), + boost::bind(&event_cb, g, + tcp_socket, + act)); + + tcp_socket->async_write_some(boost::asio::null_buffers(), + boost::bind(&event_cb, g, + tcp_socket, + act)); + } +} + + +static void addsock(curl_socket_t s, CURL *easy, int action, GlobalInfo *g) +{ + int *fdp = (int *)calloc(sizeof(int), 1); /* fdp is used to store current action */ + + setsock(fdp, s, easy, action, g); + curl_multi_assign(g->multi, s, fdp); +} + +/* CURLMOPT_SOCKETFUNCTION */ +static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp) +{ + fprintf(MSG_OUT, "\nsock_cb: socket=%d, what=%d, sockp=%p", s, what, sockp); + + GlobalInfo *g = (GlobalInfo*) cbp; + int *actionp = (int*) sockp; + const char *whatstr[]={ "none", "IN", "OUT", "INOUT", "REMOVE"}; + + fprintf(MSG_OUT, + "\nsocket callback: s=%d e=%p what=%s ", s, e, whatstr[what]); + + if ( what == CURL_POLL_REMOVE ) + { + fprintf(MSG_OUT, "\n"); + remsock(actionp, g); + } + else + { + if ( !actionp ) + { + fprintf(MSG_OUT, "\nAdding data: %s", whatstr[what]); + addsock(s, e, what, g); + } + else + { + fprintf(MSG_OUT, + "\nChanging action from %s to %s", + whatstr[*actionp], whatstr[what]); + setsock(actionp, s, e, what, g); + } + } + return 0; +} + + +/* CURLOPT_WRITEFUNCTION */ +static size_t write_cb(void *ptr, size_t size, size_t nmemb, void *data) +{ + + size_t written = size * nmemb; + char* pBuffer = (char*)malloc(written + 1); + + strncpy(pBuffer, (const char *)ptr, written); + pBuffer [written] = '\0'; + + fprintf(MSG_OUT, "%s", pBuffer); + + free(pBuffer); + + return written; +} + + +/* CURLOPT_PROGRESSFUNCTION */ +static int prog_cb (void *p, double dltotal, double dlnow, double ult, + double uln) +{ + ConnInfo *conn = (ConnInfo *)p; + (void)ult; + (void)uln; + + fprintf(MSG_OUT, "\nProgress: %s (%g/%g)", conn->url, dlnow, dltotal); + fprintf(MSG_OUT, "\nProgress: %s (%g)", conn->url, ult); + + return 0; +} + +/* CURLOPT_OPENSOCKETFUNCTION */ +static curl_socket_t opensocket(void *clientp, + curlsocktype purpose, + struct curl_sockaddr *address) +{ + fprintf(MSG_OUT, "\nopensocket :"); + + curl_socket_t sockfd = CURL_SOCKET_BAD; + + /* restrict to ipv4 */ + if (purpose == CURLSOCKTYPE_IPCXN && address->family == AF_INET) + { + /* create a tcp socket object */ + boost::asio::ip::tcp::socket *tcp_socket = new boost::asio::ip::tcp::socket(io_service); + + /* open it and get the native handle*/ + boost::system::error_code ec; + tcp_socket->open(boost::asio::ip::tcp::v4(), ec); + + if (ec) + { + //An error occurred + std::cout << std::endl << "Couldn't open socket [" << ec << "][" << ec.message() << "]"; + fprintf(MSG_OUT, "\nERROR: Returning CURL_SOCKET_BAD to signal error"); + } + else + { + sockfd = tcp_socket->native_handle(); + fprintf(MSG_OUT, "\nOpened socket %d", sockfd); + + /* save it for monitoring */ + socket_map.insert(std::pair<curl_socket_t, boost::asio::ip::tcp::socket *>(sockfd, tcp_socket)); + } + } + + return sockfd; +} + +/* CURLOPT_CLOSESOCKETFUNCTION */ +static int closesocket(void *clientp, curl_socket_t item) +{ + fprintf(MSG_OUT, "\nclosesocket : %d", item); + + std::map<curl_socket_t, boost::asio::ip::tcp::socket *>::iterator it = socket_map.find(item); + + if ( it != socket_map.end() ) + { + delete it->second; + socket_map.erase(it); + } + + return 0; +} + +/* Create a new easy handle, and add it to the global curl_multi */ +static void new_conn(char *url, GlobalInfo *g ) +{ + ConnInfo *conn; + CURLMcode rc; + + conn = (ConnInfo *)calloc(1, sizeof(ConnInfo)); + memset(conn, 0, sizeof(ConnInfo)); + conn->error[0]='\0'; + + conn->easy = curl_easy_init(); + + if ( !conn->easy ) + { + fprintf(MSG_OUT, "\ncurl_easy_init() failed, exiting!"); + exit(2); + } + conn->global = g; + conn->url = strdup(url); + curl_easy_setopt(conn->easy, CURLOPT_URL, conn->url); + curl_easy_setopt(conn->easy, CURLOPT_WRITEFUNCTION, write_cb); + curl_easy_setopt(conn->easy, CURLOPT_WRITEDATA, &conn); + curl_easy_setopt(conn->easy, CURLOPT_VERBOSE, 1L); + curl_easy_setopt(conn->easy, CURLOPT_ERRORBUFFER, conn->error); + curl_easy_setopt(conn->easy, CURLOPT_PRIVATE, conn); + curl_easy_setopt(conn->easy, CURLOPT_NOPROGRESS, 1L); + curl_easy_setopt(conn->easy, CURLOPT_PROGRESSFUNCTION, prog_cb); + curl_easy_setopt(conn->easy, CURLOPT_PROGRESSDATA, conn); + curl_easy_setopt(conn->easy, CURLOPT_LOW_SPEED_TIME, 3L); + curl_easy_setopt(conn->easy, CURLOPT_LOW_SPEED_LIMIT, 10L); + + /* call this function to get a socket */ + curl_easy_setopt(conn->easy, CURLOPT_OPENSOCKETFUNCTION, opensocket); + + /* call this function to close a socket */ + curl_easy_setopt(conn->easy, CURLOPT_CLOSESOCKETFUNCTION, closesocket); + + fprintf(MSG_OUT, + "\nAdding easy %p to multi %p (%s)", conn->easy, g->multi, url); + rc = curl_multi_add_handle(g->multi, conn->easy); + mcode_or_die("new_conn: curl_multi_add_handle", rc); + + /* note that the add_handle() will set a time-out to trigger very soon so + that the necessary socket_action() call will be called by this app */ +} + +int main(int argc, char **argv) +{ + GlobalInfo g; + CURLMcode rc; + (void)argc; + (void)argv; + + memset(&g, 0, sizeof(GlobalInfo)); + g.multi = curl_multi_init(); + + curl_multi_setopt(g.multi, CURLMOPT_SOCKETFUNCTION, sock_cb); + curl_multi_setopt(g.multi, CURLMOPT_SOCKETDATA, &g); + curl_multi_setopt(g.multi, CURLMOPT_TIMERFUNCTION, multi_timer_cb); + curl_multi_setopt(g.multi, CURLMOPT_TIMERDATA, &g); + + new_conn((char *)"www.google.com", &g); /* add a URL */ + + /* enter io_service run loop */ + io_service.run(); + + curl_multi_cleanup(g.multi); + + fprintf(MSG_OUT, "\ndone.\n"); + return 0; +} diff --git a/docs/examples/cacertinmem.c b/docs/examples/cacertinmem.c index 387029501..051afbca9 100644 --- a/docs/examples/cacertinmem.c +++ b/docs/examples/cacertinmem.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Example using a "in core" PEM certificate to retrieve a https page. + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example using a "in core" PEM certificate to retrieve a https page. * Written by Theo Borm */ diff --git a/docs/examples/certinfo.c b/docs/examples/certinfo.c index ceb0ac2b0..ac0109b07 100644 --- a/docs/examples/certinfo.c +++ b/docs/examples/certinfo.c @@ -1,17 +1,36 @@ -/***************************************************************************** - */ - +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> -#include <curl/types.h> -#include <curl/easy.h> static size_t wrfu(void *ptr, size_t size, size_t nmemb, void *stream) { + (void)stream; + (void)ptr; return size * nmemb; } -int main(int argc, char **argv) + +int main(void) { CURL *curl; CURLcode res; @@ -33,18 +52,24 @@ int main(int argc, char **argv) res = curl_easy_perform(curl); if(!res) { - struct curl_certinfo *ci = NULL; + union { + struct curl_slist *to_info; + struct curl_certinfo *to_certinfo; + } ptr; + + ptr.to_info = NULL; - res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci); + res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ptr.to_info); - if(!res && ci) { + if(!res && ptr.to_info) { int i; - printf("%d certs!\n", ci->num_of_certs); - for(i=0; i<ci->num_of_certs; i++) { + printf("%d certs!\n", ptr.to_certinfo->num_of_certs); + + for(i = 0; i < ptr.to_certinfo->num_of_certs; i++) { struct curl_slist *slist; - for(slist = ci->certinfo[i]; slist; slist = slist->next) + for(slist = ptr.to_certinfo->certinfo[i]; slist; slist = slist->next) printf("%s\n", slist->data); } @@ -52,7 +77,6 @@ int main(int argc, char **argv) } - curl_easy_cleanup(curl); } diff --git a/docs/examples/chkspeed.c b/docs/examples/chkspeed.c index 00db5bf1d..31949b892 100644 --- a/docs/examples/chkspeed.c +++ b/docs/examples/chkspeed.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Example source code to show how the callback function can be used to + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example source code to show how the callback function can be used to * download data into a chunk of memory instead of storing it in a file. * After successful download we use curl_easy_getinfo() calls to get the * amount of downloaded bytes, the time used for the whole download, and @@ -22,8 +35,6 @@ #include <time.h> #include <curl/curl.h> -#include <curl/types.h> -#include <curl/easy.h> #define URL_BASE "http://speedtest.your.domain/" #define URL_1M URL_BASE "file_1M.bin" @@ -49,7 +60,7 @@ int main(int argc, char *argv[]) { CURL *curl_handle; CURLcode res; - int prtsep = 0, prttime = 0; + int prtall = 0, prtsep = 0, prttime = 0; const char *url = URL_1M; char *appname = argv[0]; @@ -66,12 +77,14 @@ int main(int argc, char *argv[]) fprintf(stderr, "\r%s %s - %s\n", appname, CHKSPEED_VERSION, curl_version()); exit(1); + } else if (strncasecmp(*argv, "-A", 2) == 0) { + prtall = 1; } else if (strncasecmp(*argv, "-X", 2) == 0) { prtsep = 1; } else if (strncasecmp(*argv, "-T", 2) == 0) { prttime = 1; } else if (strncasecmp(*argv, "-M=", 3) == 0) { - long m = strtol(argv+3, NULL, 10); + long m = strtol((*argv)+3, NULL, 10); switch(m) { case 1: url = URL_1M; break; @@ -150,6 +163,18 @@ int main(int argc, char *argv[]) if((CURLE_OK == res) && (val>0)) printf("Average download speed: %0.3f kbyte/sec.\n", val / 1024); + if (prtall) { + /* check for name resolution time */ + res = curl_easy_getinfo(curl_handle, CURLINFO_NAMELOOKUP_TIME, &val); + if((CURLE_OK == res) && (val>0)) + printf("Name lookup time: %0.3f sec.\n", val); + + /* check for connect time */ + res = curl_easy_getinfo(curl_handle, CURLINFO_CONNECT_TIME, &val); + if((CURLE_OK == res) && (val>0)) + printf("Connect time: %0.3f sec.\n", val); + } + } else { fprintf(stderr, "Error while fetching '%s' : %s\n", url, curl_easy_strerror(res)); diff --git a/docs/examples/cookie_interface.c b/docs/examples/cookie_interface.c index 9f1e629e1..2e7c66db2 100644 --- a/docs/examples/cookie_interface.c +++ b/docs/examples/cookie_interface.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - * This example shows usage of simple cookie interface. - */ + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* This example shows usage of simple cookie interface. */ #include <stdio.h> #include <string.h> @@ -76,7 +89,7 @@ main(void) #endif /* Netscape format cookie */ snprintf(nline, sizeof(nline), "%s\t%s\t%s\t%s\t%lu\t%s\t%s", - ".google.com", "TRUE", "/", "FALSE", time(NULL) + 31337, "PREF", "hello google, i like you very much!"); + ".google.com", "TRUE", "/", "FALSE", (unsigned long)time(NULL) + 31337UL, "PREF", "hello google, i like you very much!"); res = curl_easy_setopt(curl, CURLOPT_COOKIELIST, nline); if (res != CURLE_OK) { fprintf(stderr, "Curl curl_easy_setopt failed: %s\n", curl_easy_strerror(res)); diff --git a/docs/examples/curlgtk.c b/docs/examples/curlgtk.c index 2c4428083..8cb9914c6 100644 --- a/docs/examples/curlgtk.c +++ b/docs/examples/curlgtk.c @@ -13,8 +13,6 @@ #include <gtk/gtk.h> #include <curl/curl.h> -#include <curl/types.h> /* new for v7 */ -#include <curl/easy.h> /* new for v7 */ GtkWidget *Bar; diff --git a/docs/examples/curlx.c b/docs/examples/curlx.c index 62bdfe405..89d5f407b 100644 --- a/docs/examples/curlx.c +++ b/docs/examples/curlx.c @@ -239,8 +239,7 @@ static CURLcode sslctxfun(CURL * curl, void * sslctx, void * parm) { SSL_CTX_set_cipher_list(ctx,"RC4-MD5"); SSL_CTX_set_mode(ctx, SSL_MODE_AUTO_RETRY); - X509_STORE_add_cert(ctx->cert_store,sk_X509_value(p->ca, - sk_X509_num(p->ca)-1)); + X509_STORE_add_cert(SSL_CTX_get_cert_store(ctx), sk_X509_value(p->ca, sk_X509_num(p->ca)-1)); SSL_CTX_set_verify_depth(ctx,2); diff --git a/docs/examples/debug.c b/docs/examples/debug.c index cc6848178..36dd80d70 100644 --- a/docs/examples/debug.c +++ b/docs/examples/debug.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> @@ -28,12 +40,12 @@ void dump(const char *text, /* without the hex output, we can fit more on screen */ width = 0x40; - fprintf(stream, "%s, %010.10ld bytes (0x%08.8lx)\n", + fprintf(stream, "%s, %10.10ld bytes (0x%8.8lx)\n", text, (long)size, (long)size); for(i=0; i<size; i+= width) { - fprintf(stream, "%04.4lx: ", (long)i); + fprintf(stream, "%4.4lx: ", (long)i); if(!nohex) { /* hex not disabled, show it */ @@ -118,8 +130,15 @@ int main(void) /* the DEBUGFUNCTION has no effect until we enable VERBOSE */ curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + /* example.com is redirected, so we tell libcurl to follow redirection */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/"); res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); diff --git a/docs/examples/evhiperfifo.c b/docs/examples/evhiperfifo.c index 6cdccf839..c2e87fcc5 100644 --- a/docs/examples/evhiperfifo.c +++ b/docs/examples/evhiperfifo.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Example application source code using the multi socket interface to + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example application source code using the multi socket interface to * download many files at once. * * This example features the same basic functionality as hiperfifo.c does, @@ -323,7 +336,7 @@ static void new_conn(char *url, GlobalInfo *g ) conn->url = strdup(url); curl_easy_setopt(conn->easy, CURLOPT_URL, conn->url); curl_easy_setopt(conn->easy, CURLOPT_WRITEFUNCTION, write_cb); - curl_easy_setopt(conn->easy, CURLOPT_WRITEDATA, &conn); + curl_easy_setopt(conn->easy, CURLOPT_WRITEDATA, conn); curl_easy_setopt(conn->easy, CURLOPT_VERBOSE, 1L); curl_easy_setopt(conn->easy, CURLOPT_ERRORBUFFER, conn->error); curl_easy_setopt(conn->easy, CURLOPT_PRIVATE, conn); @@ -367,7 +380,7 @@ static int init_fifo (GlobalInfo *g) { struct stat st; static const char *fifo = "hiper.fifo"; - int sockfd; + curl_socket_t sockfd; fprintf(MSG_OUT, "Creating named pipe \"%s\"\n", fifo); if ( lstat (fifo, &st) == 0 ) diff --git a/docs/examples/externalsocket.c b/docs/examples/externalsocket.c new file mode 100644 index 000000000..1b326c8b2 --- /dev/null +++ b/docs/examples/externalsocket.c @@ -0,0 +1,153 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* + * This is an example demonstrating how an application can pass in a custom + * socket to libcurl to use. This example also handles the connect itself. + */ +#include <stdio.h> +#include <string.h> +#include <stdlib.h> +#include <curl/curl.h> + +#ifdef WIN32 +#include <windows.h> +#include <winsock2.h> +#include <ws2tcpip.h> +#define close closesocket +#else +#include <sys/types.h> /* socket types */ +#include <sys/socket.h> /* socket definitions */ +#include <netinet/in.h> +#include <arpa/inet.h> /* inet (3) funtions */ +#include <unistd.h> /* misc. UNIX functions */ +#endif + +#include <errno.h> + +/* The IP address and port number to connect to */ +#define IPADDR "127.0.0.1" +#define PORTNUM 80 + +#ifndef INADDR_NONE +#define INADDR_NONE 0xffffffff +#endif + +static size_t write_data(void *ptr, size_t size, size_t nmemb, void *stream) +{ + int written = fwrite(ptr, size, nmemb, (FILE *)stream); + return written; +} + +static curl_socket_t opensocket(void *clientp, + curlsocktype purpose, + struct curl_sockaddr *address) +{ + curl_socket_t sockfd; + (void)purpose; + (void)address; + sockfd = *(curl_socket_t *)clientp; + /* the actual externally set socket is passed in via the OPENSOCKETDATA + option */ + return sockfd; +} + +static int sockopt_callback(void *clientp, curl_socket_t curlfd, + curlsocktype purpose) +{ + (void)clientp; + (void)curlfd; + (void)purpose; + /* This return code was added in libcurl 7.21.5 */ + return CURL_SOCKOPT_ALREADY_CONNECTED; +} + +int main(void) +{ + CURL *curl; + CURLcode res; + struct sockaddr_in servaddr; /* socket address structure */ + curl_socket_t sockfd; + +#ifdef WIN32 + WSADATA wsaData; + int initwsa; + + if((initwsa = WSAStartup(MAKEWORD(2,0), &wsaData)) != 0) { + printf("WSAStartup failed: %d\n", initwsa); + return 1; + } +#endif + + curl = curl_easy_init(); + if(curl) { + /* + * Note that libcurl will internally think that you connect to the host + * and port that you specify in the URL option. + */ + curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); + + /* Create the socket "manually" */ + if( (sockfd = socket(AF_INET, SOCK_STREAM, 0)) == CURL_SOCKET_BAD ) { + printf("Error creating listening socket.\n"); + return 3; + } + + memset(&servaddr, 0, sizeof(servaddr)); + servaddr.sin_family = AF_INET; + servaddr.sin_port = htons(PORTNUM); + + if (INADDR_NONE == (servaddr.sin_addr.s_addr = inet_addr(IPADDR))) + return 2; + + if(connect(sockfd,(struct sockaddr *) &servaddr, sizeof(servaddr)) == + -1) { + close(sockfd); + printf("client error: connect: %s\n", strerror(errno)); + return 1; + } + + /* no progress meter please */ + curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 1L); + + /* send all data to this function */ + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_data); + + /* call this function to get a socket */ + curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket); + curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd); + + /* call this function to set options for the socket */ + curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); + + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + + if(res) { + printf("libcurl error: %d\n", res); + return 4; + } + } + return 0; +} diff --git a/docs/examples/fileupload.c b/docs/examples/fileupload.c index cdec75137..665eca0af 100644 --- a/docs/examples/fileupload.c +++ b/docs/examples/fileupload.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> #include <sys/stat.h> @@ -52,14 +64,21 @@ int main(void) curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) { + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); - /* now extract transfer info */ - curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD, &speed_upload); - curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME, &total_time); + } + else { + /* now extract transfer info */ + curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD, &speed_upload); + curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME, &total_time); - fprintf(stderr, "Speed: %.3f bytes/sec during %.3f seconds\n", - speed_upload, total_time); + fprintf(stderr, "Speed: %.3f bytes/sec during %.3f seconds\n", + speed_upload, total_time); + } /* always cleanup */ curl_easy_cleanup(curl); } diff --git a/docs/examples/fopen.c b/docs/examples/fopen.c index e4505bf58..6fe5c0f9f 100644 --- a/docs/examples/fopen.c +++ b/docs/examples/fopen.c @@ -68,8 +68,8 @@ struct fcurl_data } handle; /* handle */ char *buffer; /* buffer to store cached data*/ - int buffer_len; /* currently allocated buffers length */ - int buffer_pos; /* end of data in buffer*/ + size_t buffer_len; /* currently allocated buffers length */ + size_t buffer_pos; /* end of data in buffer*/ int still_running; /* Is background url fetch still in progress */ }; @@ -80,7 +80,7 @@ URL_FILE *url_fopen(const char *url,const char *operation); int url_fclose(URL_FILE *file); int url_feof(URL_FILE *file); size_t url_fread(void *ptr, size_t size, size_t nmemb, URL_FILE *file); -char * url_fgets(char *ptr, int size, URL_FILE *file); +char * url_fgets(char *ptr, size_t size, URL_FILE *file); void url_rewind(URL_FILE *file); /* we use a global one for convenience */ @@ -93,7 +93,7 @@ static size_t write_callback(char *buffer, void *userp) { char *newbuff; - int rembuff; + size_t rembuff; URL_FILE *url = (URL_FILE *)userp; size *= nitems; @@ -121,7 +121,7 @@ static size_t write_callback(char *buffer, } /* use to attempt to fill the read buffer up to requested number of bytes */ -static int fill_buffer(URL_FILE *file,int want,int waittime) +static int fill_buffer(URL_FILE *file, size_t want) { fd_set fdread; fd_set fdwrite; @@ -323,7 +323,7 @@ size_t url_fread(void *ptr, size_t size, size_t nmemb, URL_FILE *file) case CFTYPE_CURL: want = nmemb * size; - fill_buffer(file,want,1); + fill_buffer(file,want); /* check if theres data in the buffer - if not fill_buffer() * either errored or EOF */ @@ -351,10 +351,10 @@ size_t url_fread(void *ptr, size_t size, size_t nmemb, URL_FILE *file) return want; } -char *url_fgets(char *ptr, int size, URL_FILE *file) +char *url_fgets(char *ptr, size_t size, URL_FILE *file) { - int want = size - 1;/* always need to leave room for zero termination */ - int loop; + size_t want = size - 1;/* always need to leave room for zero termination */ + size_t loop; switch(file->type) { case CFTYPE_FILE: @@ -362,7 +362,7 @@ char *url_fgets(char *ptr, int size, URL_FILE *file) break; case CFTYPE_CURL: - fill_buffer(file,want,1); + fill_buffer(file,want); /* check if theres data in the buffer - if not fill either errored or * EOF */ diff --git a/docs/examples/ftp-wildcard.c b/docs/examples/ftp-wildcard.c index 0186a38af..5a2a10311 100644 --- a/docs/examples/ftp-wildcard.c +++ b/docs/examples/ftp-wildcard.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <curl/curl.h> #include <stdio.h> @@ -21,7 +33,7 @@ static long file_is_comming(struct curl_fileinfo *finfo, static long file_is_downloaded(struct callback_data *data); static size_t write_it(char *buff, size_t size, size_t nmemb, - struct callback_data *data); + void *cb_data); int main(int argc, char **argv) { @@ -123,8 +135,9 @@ static long file_is_downloaded(struct callback_data *data) } static size_t write_it(char *buff, size_t size, size_t nmemb, - struct callback_data *data) + void *cb_data) { + struct callback_data *data = cb_data; size_t written = 0; if(data->output) written = fwrite(buff, size, nmemb, data->output); diff --git a/docs/examples/ftpget.c b/docs/examples/ftpget.c index 3c3888a20..bcb42bb30 100644 --- a/docs/examples/ftpget.c +++ b/docs/examples/ftpget.c @@ -1,17 +1,27 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> -#include <curl/types.h> -#include <curl/easy.h> /* * This is an example showing how to get a single file from an FTP server. diff --git a/docs/examples/ftpgetinfo.c b/docs/examples/ftpgetinfo.c index c4e234f18..dfdcf78b7 100644 --- a/docs/examples/ftpgetinfo.c +++ b/docs/examples/ftpgetinfo.c @@ -1,18 +1,28 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <string.h> #include <curl/curl.h> -#include <curl/types.h> -#include <curl/easy.h> /* * This is an example showing how to check a single file's size and mtime @@ -21,6 +31,8 @@ static size_t throw_away(void *ptr, size_t size, size_t nmemb, void *data) { + (void)ptr; + (void)data; /* we are not interested in the headers itself, so we only return the size we would have saved ... */ return (size_t)(size * nmemb); @@ -31,8 +43,8 @@ int main(void) char ftpurl[] = "ftp://ftp.example.com/gnu/binutils/binutils-2.19.1.tar.bz2"; CURL *curl; CURLcode res; - const time_t filetime; - const double filesize; + long filetime = -1; + double filesize = 0.0; const char *filename = strrchr(ftpurl, '/') + 1; curl_global_init(CURL_GLOBAL_DEFAULT); @@ -55,10 +67,12 @@ int main(void) if(CURLE_OK == res) { /* http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html */ res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime); - if((CURLE_OK == res) && filetime) - printf("filetime %s: %s", filename, ctime(&filetime)); + if((CURLE_OK == res) && (filetime >= 0)) { + time_t file_time = (time_t)filetime; + printf("filetime %s: %s", filename, ctime(&file_time)); + } res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD, &filesize); - if((CURLE_OK == res) && filesize) + if((CURLE_OK == res) && (filesize>0.0)) printf("filesize %s: %0.0f bytes\n", filename, filesize); } else { /* we failed */ diff --git a/docs/examples/ftpgetresp.c b/docs/examples/ftpgetresp.c index 2122c4f68..db96a3a13 100644 --- a/docs/examples/ftpgetresp.c +++ b/docs/examples/ftpgetresp.c @@ -1,17 +1,27 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> -#include <curl/types.h> -#include <curl/easy.h> /* * Similar to ftpget.c but this also stores the received response-lines @@ -27,7 +37,7 @@ write_response(void *ptr, size_t size, size_t nmemb, void *data) return fwrite(ptr, size, nmemb, writehere); } -int main(int argc, char **argv) +int main(void) { CURL *curl; CURLcode res; @@ -50,6 +60,10 @@ int main(int argc, char **argv) curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, write_response); curl_easy_setopt(curl, CURLOPT_WRITEHEADER, respfile); res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); diff --git a/docs/examples/ftpsget.c b/docs/examples/ftpsget.c new file mode 100644 index 000000000..0cfe32024 --- /dev/null +++ b/docs/examples/ftpsget.c @@ -0,0 +1,101 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ + +#include <stdio.h> + +#include <curl/curl.h> + +/* + * This is an example showing how to get a single file from an FTPS server. + * It delays the actual destination file creation until the first write + * callback so that it won't create an empty file in case the remote file + * doesn't exist or something else fails. + */ + +struct FtpFile { + const char *filename; + FILE *stream; +}; + +static size_t my_fwrite(void *buffer, size_t size, size_t nmemb, + void *stream) +{ + struct FtpFile *out=(struct FtpFile *)stream; + if(out && !out->stream) { + /* open file for writing */ + out->stream=fopen(out->filename, "wb"); + if(!out->stream) + return -1; /* failure, can't open file to write */ + } + return fwrite(buffer, size, nmemb, out->stream); +} + + +int main(void) +{ + CURL *curl; + CURLcode res; + struct FtpFile ftpfile={ + "yourfile.bin", /* name to store the file as if succesful */ + NULL + }; + + curl_global_init(CURL_GLOBAL_DEFAULT); + + curl = curl_easy_init(); + if(curl) { + /* + * You better replace the URL with one that works! Note that we use an + * FTP:// URL with standard explicit FTPS. You can also do FTPS:// URLs if + * you want to do the rarer kind of transfers: implicit. + */ + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://user@server/home/user/file.txt"); + /* Define our callback to get called when there's data to be written */ + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, my_fwrite); + /* Set a pointer to our struct to pass to the callback */ + curl_easy_setopt(curl, CURLOPT_WRITEDATA, &ftpfile); + + /* We activate SSL and we require it for both control and data */ + curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_ALL); + + /* Switch on full protocol/debug output */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + res = curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + + if(CURLE_OK != res) { + /* we failed */ + fprintf(stderr, "curl told us %d\n", res); + } + } + + if(ftpfile.stream) + fclose(ftpfile.stream); /* close the local file */ + + curl_global_cleanup(); + + return 0; +} diff --git a/docs/examples/ftpupload.c b/docs/examples/ftpupload.c index f1f66c0a1..e79f8d842 100644 --- a/docs/examples/ftpupload.c +++ b/docs/examples/ftpupload.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <string.h> @@ -39,16 +51,20 @@ variable's memory when passed in to it from an app like this. */ static size_t read_callback(void *ptr, size_t size, size_t nmemb, void *stream) { + curl_off_t nread; /* in real-world cases, this would probably get this data differently as this fread() stuff is exactly what the library already would do by default internally */ size_t retcode = fread(ptr, size, nmemb, stream); - fprintf(stderr, "*** We read %d bytes from file\n", retcode); + nread = (curl_off_t)retcode; + + fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T + " bytes from file\n", nread); return retcode; } -int main(int argc, char **argv) +int main(void) { CURL *curl; CURLcode res; @@ -106,6 +122,10 @@ int main(int argc, char **argv) /* Now run off and do what you've been told! */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* clean up the FTP commands list */ curl_slist_free_all (headerlist); diff --git a/docs/examples/ftpuploadresume.c b/docs/examples/ftpuploadresume.c index 81a790a11..55b8986c7 100644 --- a/docs/examples/ftpuploadresume.c +++ b/docs/examples/ftpuploadresume.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Upload to FTP, resuming failed transfers + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Upload to FTP, resuming failed transfers * * Compile for MinGW like this: * gcc -Wall -pedantic -std=c99 ftpuploadwithresume.c -o ftpuploadresume.exe @@ -26,7 +39,7 @@ /* The MinGW headers are missing a few Win32 function definitions, you shouldn't need this if you use VC++ */ -#ifdef __MINGW32__ +#if defined(__MINGW32__) && !defined(__MINGW64__) int __cdecl _snscanf(const char * input, size_t length, const char * format, ...); #endif diff --git a/docs/examples/getinfo.c b/docs/examples/getinfo.c index 0d8f1f2e9..acbe1e1af 100644 --- a/docs/examples/getinfo.c +++ b/docs/examples/getinfo.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> diff --git a/docs/examples/getinmemory.c b/docs/examples/getinmemory.c index 635a936ba..8e31e8f00 100644 --- a/docs/examples/getinmemory.c +++ b/docs/examples/getinmemory.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Example source code to show how the callback function can be used to + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example source code to show how the callback function can be used to * download data into a chunk of memory instead of storing it in a file. */ @@ -23,19 +36,19 @@ struct MemoryStruct { static size_t -WriteMemoryCallback(void *ptr, size_t size, size_t nmemb, void *data) +WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp) { size_t realsize = size * nmemb; - struct MemoryStruct *mem = (struct MemoryStruct *)data; + struct MemoryStruct *mem = (struct MemoryStruct *)userp; mem->memory = realloc(mem->memory, mem->size + realsize + 1); - if (mem->memory == NULL) { + if(mem->memory == NULL) { /* out of memory! */ printf("not enough memory (realloc returned NULL)\n"); - exit(EXIT_FAILURE); + return 0; } - memcpy(&(mem->memory[mem->size]), ptr, realsize); + memcpy(&(mem->memory[mem->size]), contents, realsize); mem->size += realsize; mem->memory[mem->size] = 0; @@ -43,9 +56,10 @@ WriteMemoryCallback(void *ptr, size_t size, size_t nmemb, void *data) } -int main(int argc, char **argv) +int main(void) { CURL *curl_handle; + CURLcode res; struct MemoryStruct chunk; @@ -71,24 +85,31 @@ int main(int argc, char **argv) curl_easy_setopt(curl_handle, CURLOPT_USERAGENT, "libcurl-agent/1.0"); /* get it! */ - curl_easy_perform(curl_handle); + res = curl_easy_perform(curl_handle); + + /* check for errors */ + if(res != CURLE_OK) { + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + } + else { + /* + * Now, our chunk.memory points to a memory block that is chunk.size + * bytes big and contains the remote file. + * + * Do something nice with it! + * + * You should be aware of the fact that at this point we might have an + * allocated data block, and nothing has yet deallocated that data. So when + * you're done with it, you should free() it as a nice application. + */ + + printf("%lu bytes retrieved\n", (long)chunk.size); + } /* cleanup curl stuff */ curl_easy_cleanup(curl_handle); - /* - * Now, our chunk.memory points to a memory block that is chunk.size - * bytes big and contains the remote file. - * - * Do something nice with it! - * - * You should be aware of the fact that at this point we might have an - * allocated data block, and nothing has yet deallocated that data. So when - * you're done with it, you should free() it as a nice application. - */ - - printf("%lu bytes retrieved\n", chunk.size); - if(chunk.memory) free(chunk.memory); diff --git a/docs/examples/ghiper.c b/docs/examples/ghiper.c index ac11790cc..9a3f46d3f 100644 --- a/docs/examples/ghiper.c +++ b/docs/examples/ghiper.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Example application source code using the multi socket interface to + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example application source code using the multi socket interface to * download many files at once. * * Written by Jeff Pohlmeyer diff --git a/docs/examples/hiperfifo.c b/docs/examples/hiperfifo.c index c9096871b..4c4e22388 100644 --- a/docs/examples/hiperfifo.c +++ b/docs/examples/hiperfifo.c @@ -1,17 +1,30 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Example application source code using the multi socket interface to - * download many files at once. + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. * - * Written by Jeff Pohlmeyer + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example application source code using the multi socket interface to + download many files at once. + +Written by Jeff Pohlmeyer -Requires libevent and a (POSIX?) system that has mkfifo(). +Requires libevent version 2 and a (POSIX?) system that has mkfifo(). This is an adaptation of libcurl's "hipev.c" and libevent's "event-test.c" sample programs. @@ -48,7 +61,7 @@ callback. #include <unistd.h> #include <sys/poll.h> #include <curl/curl.h> -#include <event.h> +#include <event2/event.h> #include <fcntl.h> #include <sys/stat.h> #include <errno.h> @@ -58,9 +71,11 @@ callback. /* Global information, common to all connections */ -typedef struct _GlobalInfo { - struct event fifo_event; - struct event timer_event; +typedef struct _GlobalInfo +{ + struct event_base *evbase; + struct event *fifo_event; + struct event *timer_event; CURLM *multi; int still_running; FILE* input; @@ -68,7 +83,8 @@ typedef struct _GlobalInfo { /* Information associated with a specific easy handle */ -typedef struct _ConnInfo { +typedef struct _ConnInfo +{ CURL *easy; char *url; GlobalInfo *global; @@ -77,12 +93,13 @@ typedef struct _ConnInfo { /* Information associated with a specific socket */ -typedef struct _SockInfo { +typedef struct _SockInfo +{ curl_socket_t sockfd; CURL *easy; int action; long timeout; - struct event ev; + struct event *ev; int evset; GlobalInfo *global; } SockInfo; @@ -98,7 +115,7 @@ static int multi_timer_cb(CURLM *multi, long timeout_ms, GlobalInfo *g) timeout.tv_sec = timeout_ms/1000; timeout.tv_usec = (timeout_ms%1000)*1000; fprintf(MSG_OUT, "multi_timer_cb: Setting timeout to %ld ms\n", timeout_ms); - evtimer_add(&g->timer_event, &timeout); + evtimer_add(g->timer_event, &timeout); return 0; } @@ -173,8 +190,8 @@ static void event_cb(int fd, short kind, void *userp) check_multi_info(g); if ( g->still_running <= 0 ) { fprintf(MSG_OUT, "last transfer done, kill timeout\n"); - if (evtimer_pending(&g->timer_event, NULL)) { - evtimer_del(&g->timer_event); + if (evtimer_pending(g->timer_event, NULL)) { + evtimer_del(g->timer_event); } } } @@ -202,7 +219,7 @@ static void remsock(SockInfo *f) { if (f) { if (f->evset) - event_del(&f->ev); + event_free(f->ev); free(f); } } @@ -219,16 +236,17 @@ static void setsock(SockInfo*f, curl_socket_t s, CURL*e, int act, GlobalInfo*g) f->action = act; f->easy = e; if (f->evset) - event_del(&f->ev); - event_set(&f->ev, f->sockfd, kind, event_cb, g); - f->evset=1; - event_add(&f->ev, NULL); + event_free(f->ev); + f->ev = event_new(g->evbase, f->sockfd, kind, event_cb, g); + f->evset = 1; + event_add(f->ev, NULL); } /* Initialize a new SockInfo structure */ -static void addsock(curl_socket_t s, CURL *easy, int action, GlobalInfo *g) { +static void addsock(curl_socket_t s, CURL *easy, int action, GlobalInfo *g) +{ SockInfo *fdp = calloc(sizeof(SockInfo), 1); fdp->global = g; @@ -346,11 +364,11 @@ static void fifo_cb(int fd, short event, void *arg) } /* Create a named pipe and tell libevent to monitor it */ +static const char *fifo = "hiper.fifo"; static int init_fifo (GlobalInfo *g) { struct stat st; - static const char *fifo = "hiper.fifo"; - int sockfd; + curl_socket_t sockfd; fprintf(MSG_OUT, "Creating named pipe \"%s\"\n", fifo); if (lstat (fifo, &st) == 0) { @@ -373,11 +391,18 @@ static int init_fifo (GlobalInfo *g) g->input = fdopen(sockfd, "r"); fprintf(MSG_OUT, "Now, pipe some URL's into > %s\n", fifo); - event_set(&g->fifo_event, sockfd, EV_READ | EV_PERSIST, fifo_cb, g); - event_add(&g->fifo_event, NULL); + g->fifo_event = event_new(g->evbase, sockfd, EV_READ|EV_PERSIST, fifo_cb, g); + event_add(g->fifo_event, NULL); return (0); } +static void clean_fifo(GlobalInfo *g) +{ + event_free(g->fifo_event); + fclose(g->input); + unlink(fifo); +} + int main(int argc, char **argv) { GlobalInfo g; @@ -385,10 +410,10 @@ int main(int argc, char **argv) (void)argv; memset(&g, 0, sizeof(GlobalInfo)); - event_init(); + g.evbase = event_base_new(); init_fifo(&g); g.multi = curl_multi_init(); - evtimer_set(&g.timer_event, timer_cb, &g); + g.timer_event = evtimer_new(g.evbase, timer_cb, &g); /* setup the generic multi interface options we want */ curl_multi_setopt(g.multi, CURLMOPT_SOCKETFUNCTION, sock_cb); @@ -399,7 +424,13 @@ int main(int argc, char **argv) /* we don't call any curl_multi_socket*() function yet as we have no handles added! */ - event_dispatch(); + event_base_dispatch(g.evbase); + + /* this, of course, won't get called since only way to stop this program is + via ctrl-C, but it is here to show how cleanup /would/ be done. */ + clean_fifo(&g); + event_free(g.timer_event); + event_base_free(g.evbase); curl_multi_cleanup(g.multi); return 0; } diff --git a/docs/examples/href_extractor.c b/docs/examples/href_extractor.c new file mode 100644 index 000000000..4b307a29e --- /dev/null +++ b/docs/examples/href_extractor.c @@ -0,0 +1,86 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ + +/* + * This example uses the "Streaming HTML parser" to extract the href pieces in + * a streaming manner from a downloaded HTML. Kindly donated by MichaÅ‚ + * Kowalczyk. + * + * The parser is found at + * http://code.google.com/p/htmlstreamparser/ + */ + +#include <stdio.h> +#include <curl/curl.h> +#include <htmlstreamparser.h> + + +static size_t write_callback(void *buffer, size_t size, size_t nmemb, + void *hsp) +{ + size_t realsize = size * nmemb, p; + for (p = 0; p < realsize; p++) { + html_parser_char_parse(hsp, ((char *)buffer)[p]); + if (html_parser_cmp_tag(hsp, "a", 1)) + if (html_parser_cmp_attr(hsp, "href", 4)) + if (html_parser_is_in(hsp, HTML_VALUE_ENDED)) { + html_parser_val(hsp)[html_parser_val_length(hsp)] = '\0'; + printf("%s\n", html_parser_val(hsp)); + } + } + return realsize; +} + +int main(int argc, char *argv[]) +{ + char tag[1], attr[4], val[128]; + CURL *curl; + HTMLSTREAMPARSER *hsp; + + if (argc != 2) { + printf("Usage: %s URL\n", argv[0]); + return EXIT_FAILURE; + } + + curl = curl_easy_init(); + + hsp = html_parser_init(); + + html_parser_set_tag_to_lower(hsp, 1); + html_parser_set_attr_to_lower(hsp, 1); + html_parser_set_tag_buffer(hsp, tag, sizeof(tag)); + html_parser_set_attr_buffer(hsp, attr, sizeof(attr)); + html_parser_set_val_buffer(hsp, val, sizeof(val)-1); + + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback); + curl_easy_setopt(curl, CURLOPT_WRITEDATA, hsp); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1); + + curl_easy_perform(curl); + + curl_easy_cleanup(curl); + + html_parser_cleanup(hsp); + + return EXIT_SUCCESS; +} diff --git a/docs/examples/htmltidy.c b/docs/examples/htmltidy.c index 9a46955da..a36e331bf 100644 --- a/docs/examples/htmltidy.c +++ b/docs/examples/htmltidy.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Download a document and use libtidy to parse the HTML. + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Download a document and use libtidy to parse the HTML. * Written by Jeff Pohlmeyer * * LibTidy => http://tidy.sourceforge.net diff --git a/docs/examples/htmltitle.cc b/docs/examples/htmltitle.cpp index da3354a55..ab89bb6a7 100644 --- a/docs/examples/htmltitle.cc +++ b/docs/examples/htmltitle.cpp @@ -1,19 +1,31 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ // Get a web page, parse it with libxml. // // Written by Lars Nilsson // // GNU C++ compile command line suggestion (edit paths accordingly): // -// g++ -Wall -I/opt/curl/include -I/opt/libxml/include/libxml2 htmltitle.cc \ +// g++ -Wall -I/opt/curl/include -I/opt/libxml/include/libxml2 htmltitle.cpp \ // -o htmltitle -L/opt/curl/lib -L/opt/libxml/lib -lcurl -lxml2 #include <stdio.h> diff --git a/docs/examples/http-post.c b/docs/examples/http-post.c index 523177d28..f1975b1ec 100644 --- a/docs/examples/http-post.c +++ b/docs/examples/http-post.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> @@ -15,6 +27,10 @@ int main(void) CURL *curl; CURLcode res; + /* In windows, this will init the winsock stuff */ + curl_global_init(CURL_GLOBAL_ALL); + + /* get a curl handle */ curl = curl_easy_init(); if(curl) { /* First set the URL that is about to receive our POST. This URL can @@ -26,9 +42,14 @@ int main(void) /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); } + curl_global_cleanup(); return 0; } diff --git a/docs/examples/httpcustomheader.c b/docs/examples/httpcustomheader.c index 599b84fe8..07ff95997 100644 --- a/docs/examples/httpcustomheader.c +++ b/docs/examples/httpcustomheader.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> @@ -26,13 +38,24 @@ int main(void) curl_easy_setopt(curl, CURLOPT_URL, "localhost"); curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* redo request with our own custom Accept: */ res = curl_easy_setopt(curl, CURLOPT_HTTPHEADER, chunk); res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); + + /* free the custom headers */ + curl_slist_free_all(chunk); } return 0; } diff --git a/docs/examples/httpput.c b/docs/examples/httpput.c index 821e95fd8..fbbca9448 100644 --- a/docs/examples/httpput.c +++ b/docs/examples/httpput.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <fcntl.h> #include <sys/stat.h> @@ -27,13 +39,17 @@ static size_t read_callback(void *ptr, size_t size, size_t nmemb, void *stream) { size_t retcode; + curl_off_t nread; /* in real-world cases, this would probably get this data differently as this fread() stuff is exactly what the library already would do by default internally */ retcode = fread(ptr, size, nmemb, stream); - fprintf(stderr, "*** We read %d bytes from file\n", retcode); + nread = (curl_off_t)retcode; + + fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T + " bytes from file\n", nread); return retcode; } @@ -94,6 +110,10 @@ int main(int argc, char **argv) /* Now run off and do what you've been told! */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); diff --git a/docs/examples/https.c b/docs/examples/https.c index 10b5c657f..bd9a33ba6 100644 --- a/docs/examples/https.c +++ b/docs/examples/https.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> @@ -15,6 +27,8 @@ int main(void) CURL *curl; CURLcode res; + curl_global_init(CURL_GLOBAL_DEFAULT); + curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); @@ -33,7 +47,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); #endif -#ifdef SKIP_HOSTNAME_VERFICATION +#ifdef SKIP_HOSTNAME_VERIFICATION /* * If the site you're connecting to uses a different host name that what * they have mentioned in their server certificate's commonName (or @@ -43,10 +57,18 @@ int main(void) curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); #endif + /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); } + + curl_global_cleanup(); + return 0; } diff --git a/docs/examples/imap.c b/docs/examples/imap.c new file mode 100644 index 000000000..ba07f022a --- /dev/null +++ b/docs/examples/imap.c @@ -0,0 +1,44 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include <stdio.h> +#include <curl/curl.h> + +int main(void) +{ + CURL *curl; + CURLcode res = CURLE_OK; + + curl = curl_easy_init(); + if(curl) { + /* Set username and password */ + curl_easy_setopt(curl, CURLOPT_USERPWD, "user:password"); + + /* This will fetch the mailbox named "foobar" */ + curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/foobar"); + + res = curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + return (int)res; +} diff --git a/docs/examples/makefile.dj b/docs/examples/makefile.dj index 8736e6e78..c18ef8a70 100644 --- a/docs/examples/makefile.dj +++ b/docs/examples/makefile.dj @@ -1,6 +1,27 @@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| +# +# Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +# +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### # # Adapted for djgpp / Watt-32 / DOS by -# Gisle Vanem <giva@bgnett.no> +# Gisle Vanem <gvanem@broadpark.no> # TOPDIR = ../.. diff --git a/docs/examples/multi-app.c b/docs/examples/multi-app.c index 6ba131830..a5f71c5ac 100644 --- a/docs/examples/multi-app.c +++ b/docs/examples/multi-app.c @@ -1,13 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * This is an example application source code using the multi interface. - */ + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* This is an example application source code using the multi interface. */ #include <stdio.h> #include <string.h> @@ -27,7 +39,7 @@ #define HTTP_HANDLE 0 /* Index for the HTTP transfer */ #define FTP_HANDLE 1 /* Index for the FTP transfer */ -int main(int argc, char **argv) +int main(void) { CURL *handles[HANDLECOUNT]; CURLM *multi_handle; @@ -58,7 +70,7 @@ int main(int argc, char **argv) /* we start some action by calling perform right away */ curl_multi_perform(multi_handle, &still_running); - while(still_running) { + do { struct timeval timeout; int rc; /* select() return code */ @@ -106,7 +118,7 @@ int main(int argc, char **argv) curl_multi_perform(multi_handle, &still_running); break; } - } + } while(still_running); /* See how the transfers went */ while ((msg = curl_multi_info_read(multi_handle, &msgs_left))) { diff --git a/docs/examples/multi-debugcallback.c b/docs/examples/multi-debugcallback.c index 529c3d9bb..8eedcee5b 100644 --- a/docs/examples/multi-debugcallback.c +++ b/docs/examples/multi-debugcallback.c @@ -1,14 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * This is a very simple example using the multi interface and the debug - * callback. - */ + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* This is an example showing the multi interface and the debug callback. */ #include <stdio.h> #include <string.h> @@ -37,12 +48,12 @@ void dump(const char *text, /* without the hex output, we can fit more on screen */ width = 0x40; - fprintf(stream, "%s, %010.10ld bytes (0x%08.8lx)\n", + fprintf(stream, "%s, %10.10ld bytes (0x%8.8lx)\n", text, (long)size, (long)size); for(i=0; i<size; i+= width) { - fprintf(stream, "%04.4lx: ", (long)i); + fprintf(stream, "%4.4lx: ", (long)i); if(!nohex) { /* hex not disabled, show it */ @@ -79,6 +90,7 @@ int my_trace(CURL *handle, curl_infotype type, { const char *text; + (void)userp; (void)handle; /* prevent compiler warning */ switch (type) { @@ -108,7 +120,7 @@ int my_trace(CURL *handle, curl_infotype type, /* * Simply download a HTTP file. */ -int main(int argc, char **argv) +int main(void) { CURL *http_handle; CURLM *multi_handle; @@ -132,7 +144,7 @@ int main(int argc, char **argv) /* we start some action by calling perform right away */ curl_multi_perform(multi_handle, &still_running); - while(still_running) { + do { struct timeval timeout; int rc; /* select() return code */ @@ -183,7 +195,7 @@ int main(int argc, char **argv) curl_multi_perform(multi_handle, &still_running); break; } - } + } while(still_running); curl_multi_cleanup(multi_handle); diff --git a/docs/examples/multi-double.c b/docs/examples/multi-double.c index 3ea106bf7..91422e6e2 100644 --- a/docs/examples/multi-double.c +++ b/docs/examples/multi-double.c @@ -1,14 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * This is a very simple example using the multi interface. - */ - + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <string.h> @@ -22,7 +32,7 @@ /* * Simply download two HTTP files! */ -int main(int argc, char **argv) +int main(void) { CURL *http_handle; CURL *http_handle2; @@ -49,7 +59,7 @@ int main(int argc, char **argv) /* we start some action by calling perform right away */ curl_multi_perform(multi_handle, &still_running); - while(still_running) { + do { struct timeval timeout; int rc; /* select() return code */ @@ -98,7 +108,7 @@ int main(int argc, char **argv) curl_multi_perform(multi_handle, &still_running); break; } - } + } while(still_running); curl_multi_cleanup(multi_handle); diff --git a/docs/examples/multi-post.c b/docs/examples/multi-post.c index 8b4f03e9e..965a2c3f6 100644 --- a/docs/examples/multi-post.c +++ b/docs/examples/multi-post.c @@ -1,21 +1,33 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * This is an example application source code using the multi interface - * to do a multipart formpost without "blocking". - */ + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* This is an example application source code using the multi interface + * to do a multipart formpost without "blocking". */ #include <stdio.h> #include <string.h> #include <sys/time.h> #include <curl/curl.h> -int main(int argc, char *argv[]) +int main(void) { CURL *curl; @@ -68,7 +80,7 @@ int main(int argc, char *argv[]) curl_multi_perform(multi_handle, &still_running); - while(still_running) { + do { struct timeval timeout; int rc; /* select() return code */ @@ -119,7 +131,7 @@ int main(int argc, char *argv[]) printf("running: %d!\n", still_running); break; } - } + } while(still_running); curl_multi_cleanup(multi_handle); diff --git a/docs/examples/multi-single.c b/docs/examples/multi-single.c index f248afe76..37a01cd83 100644 --- a/docs/examples/multi-single.c +++ b/docs/examples/multi-single.c @@ -1,13 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * This is a very simple example using the multi interface. - */ + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* This is a very simple example using the multi interface. */ #include <stdio.h> #include <string.h> @@ -22,13 +34,15 @@ /* * Simply download a HTTP file. */ -int main(int argc, char **argv) +int main(void) { CURL *http_handle; CURLM *multi_handle; int still_running; /* keep number of running handles */ + curl_global_init(CURL_GLOBAL_DEFAULT); + http_handle = curl_easy_init(); /* set the options (I left out a few, you'll get the point anyway) */ @@ -43,7 +57,7 @@ int main(int argc, char **argv) /* we start some action by calling perform right away */ curl_multi_perform(multi_handle, &still_running); - while(still_running) { + do { struct timeval timeout; int rc; /* select() return code */ @@ -94,11 +108,15 @@ int main(int argc, char **argv) curl_multi_perform(multi_handle, &still_running); break; } - } + } while(still_running); - curl_multi_cleanup(multi_handle); + curl_multi_remove_handle(multi_handle, http_handle); curl_easy_cleanup(http_handle); + curl_multi_cleanup(multi_handle); + + curl_global_cleanup(); + return 0; } diff --git a/docs/examples/multi-uv.c b/docs/examples/multi-uv.c new file mode 100644 index 000000000..57d712fcf --- /dev/null +++ b/docs/examples/multi-uv.c @@ -0,0 +1,212 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ + +/* Example application code using the multi socket interface to download + multiple files at once, but instead of using curl_multi_perform and + curl_multi_wait, which uses select(), we use libuv. + It supports epoll, kqueue, etc. on unixes and fast IO completion ports on + Windows, which means, it should be very fast on all platforms.. + + Written by Clemens Gruber, based on an outdated example from uvbook and + some tests from libuv. + + Requires libuv and (of course) libcurl. + + See http://nikhilm.github.com/uvbook/ for more information on libuv. +*/ + +#include <stdio.h> +#include <stdlib.h> +#include <uv.h> +#include <curl/curl.h> + +uv_loop_t *loop; +CURLM *curl_handle; +uv_timer_t timeout; + +typedef struct curl_context_s { + uv_poll_t poll_handle; + curl_socket_t sockfd; +} curl_context_t; + +curl_context_t* create_curl_context(curl_socket_t sockfd) +{ + curl_context_t *context; + + context = (curl_context_t *) malloc(sizeof *context); + + context->sockfd = sockfd; + + uv_poll_init_socket(loop, &context->poll_handle, sockfd); + context->poll_handle.data = context; + + return context; +} + +void curl_close_cb(uv_handle_t *handle) +{ + curl_context_t* context = (curl_context_t*) handle->data; + free(context); +} + +void destroy_curl_context(curl_context_t *context) +{ + uv_close((uv_handle_t*) &context->poll_handle, curl_close_cb); +} + + +void add_download(const char *url, int num) +{ + char filename[50]; + FILE *file; + CURL *handle; + + sprintf(filename, "%d.download", num); + + file = fopen(filename, "w"); + if (file == NULL) { + fprintf(stderr, "Error opening %s\n", filename); + return; + } + + handle = curl_easy_init(); + curl_easy_setopt(handle, CURLOPT_WRITEDATA, file); + curl_easy_setopt(handle, CURLOPT_URL, url); + curl_multi_add_handle(curl_handle, handle); + fprintf(stderr, "Added download %s -> %s\n", url, filename); +} + +void curl_perform(uv_poll_t *req, int status, int events) +{ + int running_handles; + int flags = 0; + curl_context_t *context; + char *done_url; + CURLMsg *message; + int pending; + + uv_timer_stop(&timeout); + + if (events & UV_READABLE) + flags |= CURL_CSELECT_IN; + if (events & UV_WRITABLE) + flags |= CURL_CSELECT_OUT; + + context = (curl_context_t*)req; + + curl_multi_socket_action(curl_handle, context->sockfd, flags, + &running_handles); + + while ((message = curl_multi_info_read(curl_handle, &pending))) { + switch (message->msg) { + case CURLMSG_DONE: + curl_easy_getinfo(message->easy_handle, CURLINFO_EFFECTIVE_URL, + &done_url); + printf("%s DONE\n", done_url); + + curl_multi_remove_handle(curl_handle, message->easy_handle); + curl_easy_cleanup(message->easy_handle); + + break; + default: + fprintf(stderr, "CURLMSG default\n"); + abort(); + } + } +} + +void on_timeout(uv_timer_t *req, int status) +{ + int running_handles; + curl_multi_socket_action(curl_handle, CURL_SOCKET_TIMEOUT, 0, + &running_handles); +} + +void start_timeout(CURLM *multi, long timeout_ms, void *userp) +{ + if (timeout_ms <= 0) + timeout_ms = 1; /* 0 means directly call socket_action, but we'll do it in + a bit */ + uv_timer_start(&timeout, on_timeout, timeout_ms, 0); +} + +int handle_socket(CURL *easy, curl_socket_t s, int action, void *userp, + void *socketp) +{ + curl_context_t *curl_context; + if (action == CURL_POLL_IN || action == CURL_POLL_OUT) { + if (socketp) { + curl_context = (curl_context_t*) socketp; + } + else { + curl_context = create_curl_context(s); + } + curl_multi_assign(curl_handle, s, (void *) curl_context); + } + + switch (action) { + case CURL_POLL_IN: + uv_poll_start(&curl_context->poll_handle, UV_READABLE, curl_perform); + break; + case CURL_POLL_OUT: + uv_poll_start(&curl_context->poll_handle, UV_WRITABLE, curl_perform); + break; + case CURL_POLL_REMOVE: + if (socketp) { + uv_poll_stop(&((curl_context_t*)socketp)->poll_handle); + destroy_curl_context((curl_context_t*) socketp); + curl_multi_assign(curl_handle, s, NULL); + } + break; + default: + abort(); + } + + return 0; +} + +int main(int argc, char **argv) +{ + loop = uv_default_loop(); + + if (argc <= 1) + return 0; + + if (curl_global_init(CURL_GLOBAL_ALL)) { + fprintf(stderr, "Could not init cURL\n"); + return 1; + } + + uv_timer_init(loop, &timeout); + + curl_handle = curl_multi_init(); + curl_multi_setopt(curl_handle, CURLMOPT_SOCKETFUNCTION, handle_socket); + curl_multi_setopt(curl_handle, CURLMOPT_TIMERFUNCTION, start_timeout); + + while (argc-- > 1) { + add_download(argv[argc], argc); + } + + uv_run(loop, UV_RUN_DEFAULT); + curl_multi_cleanup(curl_handle); + return 0; +} diff --git a/docs/examples/multithread.c b/docs/examples/multithread.c index 5f59a99d7..831a07467 100644 --- a/docs/examples/multithread.c +++ b/docs/examples/multithread.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ /* A multi-threaded example that uses pthreads extensively to fetch * X remote files at once */ diff --git a/docs/examples/opensslthreadlock.c b/docs/examples/opensslthreadlock.c index 706e90121..ad54f08ea 100644 --- a/docs/examples/opensslthreadlock.c +++ b/docs/examples/opensslthreadlock.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Example source code to show one way to set the necessary OpenSSL locking + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example source code to show one way to set the necessary OpenSSL locking * callbacks if you want to do multi-threaded transfers with HTTPS/FTPS with * libcurl built to use OpenSSL. * diff --git a/docs/examples/persistant.c b/docs/examples/persistant.c index 177ada359..0917dfdb8 100644 --- a/docs/examples/persistant.c +++ b/docs/examples/persistant.c @@ -1,17 +1,29 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <unistd.h> #include <curl/curl.h> -int main(int argc, char **argv) +int main(void) { CURL *curl; CURLcode res; @@ -25,12 +37,24 @@ int main(int argc, char **argv) /* get the first document */ curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/"); + + /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* get another document from the same server using the same connection */ curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/docs/"); + + /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); diff --git a/docs/examples/pop3s.c b/docs/examples/pop3s.c new file mode 100644 index 000000000..44d7c80d0 --- /dev/null +++ b/docs/examples/pop3s.c @@ -0,0 +1,73 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include <stdio.h> +#include <curl/curl.h> + +int main(void) +{ + CURL *curl; + CURLcode res; + + curl = curl_easy_init(); + if(curl) { + /* Set username and password */ + curl_easy_setopt(curl, CURLOPT_USERPWD, "user:password"); + + /* This will only fetch the message with ID "1" of the given mailbox */ + curl_easy_setopt(curl, CURLOPT_URL, "pop3s://user@pop.example.com/1"); + +#ifdef SKIP_PEER_VERIFICATION + /* + * If you want to connect to a site who isn't using a certificate that is + * signed by one of the certs in the CA bundle you have, you can skip the + * verification of the server's certificate. This makes the connection + * A LOT LESS SECURE. + * + * If you have a CA cert for the server stored someplace else than in the + * default bundle, then the CURLOPT_CAPATH option might come handy for + * you. + */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); +#endif + +#ifdef SKIP_HOSTNAME_VERFICATION + /* + * If the site you're connecting to uses a different host name that what + * they have mentioned in their server certificate's commonName (or + * subjectAltName) fields, libcurl will refuse to connect. You can skip + * this check, but this will make the connection less secure. + */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); +#endif + + /* Perform the request, res will get the return code */ + res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + return 0; +} diff --git a/docs/examples/pop3slist.c b/docs/examples/pop3slist.c new file mode 100644 index 000000000..9d9668fa0 --- /dev/null +++ b/docs/examples/pop3slist.c @@ -0,0 +1,73 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include <stdio.h> +#include <curl/curl.h> + +int main(void) +{ + CURL *curl; + CURLcode res; + + curl = curl_easy_init(); + if(curl) { + /* Set username and password */ + curl_easy_setopt(curl, CURLOPT_USERPWD, "user:password"); + + /* This will list every message of the given mailbox */ + curl_easy_setopt(curl, CURLOPT_URL, "pop3s://user@pop.example.com/"); + +#ifdef SKIP_PEER_VERIFICATION + /* + * If you want to connect to a site who isn't using a certificate that is + * signed by one of the certs in the CA bundle you have, you can skip the + * verification of the server's certificate. This makes the connection + * A LOT LESS SECURE. + * + * If you have a CA cert for the server stored someplace else than in the + * default bundle, then the CURLOPT_CAPATH option might come handy for + * you. + */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); +#endif + +#ifdef SKIP_HOSTNAME_VERFICATION + /* + * If the site you're connecting to uses a different host name that what + * they have mentioned in their server certificate's commonName (or + * subjectAltName) fields, libcurl will refuse to connect. You can skip + * this check, but this will make the connection less secure. + */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); +#endif + + /* Perform the request, res will get the return code */ + res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + return 0; +} diff --git a/docs/examples/post-callback.c b/docs/examples/post-callback.c index ae4f4db98..3e1cfb060 100644 --- a/docs/examples/post-callback.c +++ b/docs/examples/post-callback.c @@ -1,14 +1,26 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. * - * An example source code that issues a HTTP POST and we provide the actual - * data through a read callback. + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. * + ***************************************************************************/ +/* An example source code that issues a HTTP POST and we provide the actual + * data through a read callback. */ #include <stdio.h> #include <string.h> @@ -18,7 +30,7 @@ const char data[]="this is what we post to the silly web server"; struct WriteThis { const char *readptr; - int sizeleft; + long sizeleft; }; static size_t read_callback(void *ptr, size_t size, size_t nmemb, void *userp) @@ -46,8 +58,18 @@ int main(void) struct WriteThis pooh; pooh.readptr = data; - pooh.sizeleft = strlen(data); + pooh.sizeleft = (long)strlen(data); + + /* In windows, this will init the winsock stuff */ + res = curl_global_init(CURL_GLOBAL_DEFAULT); + /* Check for errors */ + if(res != CURLE_OK) { + fprintf(stderr, "curl_global_init() failed: %s\n", + curl_easy_strerror(res)); + return 1; + } + /* get a curl handle */ curl = curl_easy_init(); if(curl) { /* First set the URL that is about to receive our POST. */ @@ -84,7 +106,7 @@ int main(void) #else /* Set the expected POST size. If you want to POST large amounts of data, consider CURLOPT_POSTFIELDSIZE_LARGE */ - curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (curl_off_t)pooh.sizeleft); + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, pooh.sizeleft); #endif #ifdef DISABLE_EXPECT @@ -108,9 +130,14 @@ int main(void) /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); } + curl_global_cleanup(); return 0; } diff --git a/docs/examples/postit2.c b/docs/examples/postit2.c index a6292c5f1..67dcc1330 100644 --- a/docs/examples/postit2.c +++ b/docs/examples/postit2.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * Example code that uploads a file name 'foo' to a remote script that accepts + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example code that uploads a file name 'foo' to a remote script that accepts * "HTML form based" (as described in RFC1738) uploads using HTTP POST. * * The imaginary form we'll fill in looks like: @@ -24,8 +37,6 @@ #include <string.h> #include <curl/curl.h> -#include <curl/types.h> -#include <curl/easy.h> int main(int argc, char *argv[]) { @@ -72,7 +83,13 @@ int main(int argc, char *argv[]) /* only disable 100-continue header if explicitly requested */ curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headerlist); curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); + + /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); diff --git a/docs/examples/progressfunc.c b/docs/examples/progressfunc.c new file mode 100644 index 000000000..b2635bc8a --- /dev/null +++ b/docs/examples/progressfunc.c @@ -0,0 +1,119 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include <stdio.h> +#include <curl/curl.h> + +#define STOP_DOWNLOAD_AFTER_THIS_MANY_BYTES 6000 +#define MINIMAL_PROGRESS_FUNCTIONALITY_INTERVAL 3 + +struct myprogress { + double lastruntime; + CURL *curl; +}; + +/* this is how the CURLOPT_XFERINFOFUNCTION callback works */ +static int xferinfo(void *p, + curl_off_t dltotal, curl_off_t dlnow, + curl_off_t ultotal, curl_off_t ulnow) +{ + struct myprogress *myp = (struct myprogress *)p; + CURL *curl = myp->curl; + double curtime = 0; + + curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME, &curtime); + + /* under certain circumstances it may be desirable for certain functionality + to only run every N seconds, in order to do this the transaction time can + be used */ + if((curtime - myp->lastruntime) >= MINIMAL_PROGRESS_FUNCTIONALITY_INTERVAL) { + myp->lastruntime = curtime; + fprintf(stderr, "TOTAL TIME: %f \r\n", curtime); + } + + fprintf(stderr, "UP: %" CURL_FORMAT_CURL_OFF_T " of %" CURL_FORMAT_CURL_OFF_T + " DOWN: %" CURL_FORMAT_CURL_OFF_T " of %" CURL_FORMAT_CURL_OFF_T + "\r\n", + ulnow, ultotal, dlnow, dltotal); + + if(dlnow > STOP_DOWNLOAD_AFTER_THIS_MANY_BYTES) + return 1; + return 0; +} + +/* for libcurl older than 7.32.0 (CURLOPT_PROGRESSFUNCTION) */ +static int older_progress(void *p, + double dltotal, double dlnow, + double ultotal, double ulnow) +{ + return xferinfo(p, + (curl_off_t)dltotal, + (curl_off_t)dlnow, + (curl_off_t)ultotal, + (curl_off_t)ulnow); +} + + +int main(void) +{ + CURL *curl; + CURLcode res = CURLE_OK; + struct myprogress prog; + + curl = curl_easy_init(); + if(curl) { + prog.lastruntime = 0; + prog.curl = curl; + + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/"); + + curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, older_progress); + /* pass the struct pointer into the progress function */ + curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &prog); + +#if LIBCURL_VERSION_NUM >= 0x072000 + /* xferinfo was introduced in 7.32.0, no earlier libcurl versions will + compile as they won't have the symbols around. + + If built with a newer libcurl, but running with an older libcurl: + curl_easy_setopt() will fail in run-time trying to set the new + callback, making the older callback get used. + + New libcurls will prefer the new callback and instead use that one even + if both callbacks are set. */ + + curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, xferinfo); + /* pass the struct pointer into the xferinfo function, note that this is + an alias to CURLOPT_PROGRESSDATA */ + curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &prog); +#endif + + curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L); + res = curl_easy_perform(curl); + + if(res != CURLE_OK) + fprintf(stderr, "%s\n", curl_easy_strerror(res)); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + return (int)res; +} diff --git a/docs/examples/resolve.c b/docs/examples/resolve.c new file mode 100644 index 000000000..7b3e5656e --- /dev/null +++ b/docs/examples/resolve.c @@ -0,0 +1,51 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include <stdio.h> +#include <curl/curl.h> + +int main(void) +{ + CURL *curl; + CURLcode res = CURLE_OK; + struct curl_slist *host = NULL; + + /* Each single name resolve string should be written using the format + HOST:PORT:ADDRESS where HOST is the name libcurl will try to resolve, + PORT is the port number of the service where libcurl wants to connect to + the HOST and ADDRESS is the numerical IP address + */ + host = curl_slist_append(NULL, "example.com:80:127.0.0.1"); + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_RESOLVE, host); + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + res = curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + + curl_slist_free_all(host); + + return (int)res; +} diff --git a/docs/examples/rtsp.c b/docs/examples/rtsp.c new file mode 100644 index 000000000..669780a9b --- /dev/null +++ b/docs/examples/rtsp.c @@ -0,0 +1,271 @@ +/* + * Copyright (c) 2011, Jim Hollinger + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * * Neither the name of Jim Hollinger nor the names of its contributors + * may be used to endorse or promote products derived from this + * software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ + +#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +#if defined (WIN32) +# include <conio.h> /* _getch() */ +#else +# include <termios.h> +# include <unistd.h> + +static int _getch(void) +{ + struct termios oldt, newt; + int ch; + tcgetattr( STDIN_FILENO, &oldt ); + newt = oldt; + newt.c_lflag &= ~( ICANON | ECHO ); + tcsetattr( STDIN_FILENO, TCSANOW, &newt ); + ch = getchar(); + tcsetattr( STDIN_FILENO, TCSANOW, &oldt ); + return ch; +} +#endif + +#include <curl/curl.h> + +#define VERSION_STR "V1.0" + +/* error handling macros */ +#define my_curl_easy_setopt(A, B, C) \ + if ((res = curl_easy_setopt((A), (B), (C))) != CURLE_OK) \ + fprintf(stderr, "curl_easy_setopt(%s, %s, %s) failed: %d\n", \ + #A, #B, #C, res); + +#define my_curl_easy_perform(A) \ + if ((res = curl_easy_perform((A))) != CURLE_OK) \ + fprintf(stderr, "curl_easy_perform(%s) failed: %d\n", #A, res); + + +/* send RTSP OPTIONS request */ +static void rtsp_options(CURL *curl, const char *uri) +{ + CURLcode res = CURLE_OK; + printf("\nRTSP: OPTIONS %s\n", uri); + my_curl_easy_setopt(curl, CURLOPT_RTSP_STREAM_URI, uri); + my_curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, (long)CURL_RTSPREQ_OPTIONS); + my_curl_easy_perform(curl); +} + + +/* send RTSP DESCRIBE request and write sdp response to a file */ +static void rtsp_describe(CURL *curl, const char *uri, + const char *sdp_filename) +{ + CURLcode res = CURLE_OK; + FILE *sdp_fp = fopen(sdp_filename, "wt"); + printf("\nRTSP: DESCRIBE %s\n", uri); + if (sdp_fp == NULL) { + fprintf(stderr, "Could not open '%s' for writing\n", sdp_filename); + sdp_fp = stdout; + } + else { + printf("Writing SDP to '%s'\n", sdp_filename); + } + my_curl_easy_setopt(curl, CURLOPT_WRITEDATA, sdp_fp); + my_curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, (long)CURL_RTSPREQ_DESCRIBE); + my_curl_easy_perform(curl); + my_curl_easy_setopt(curl, CURLOPT_WRITEDATA, stdout); + if (sdp_fp != stdout) { + fclose(sdp_fp); + } +} + +/* send RTSP SETUP request */ +static void rtsp_setup(CURL *curl, const char *uri, const char *transport) +{ + CURLcode res = CURLE_OK; + printf("\nRTSP: SETUP %s\n", uri); + printf(" TRANSPORT %s\n", transport); + my_curl_easy_setopt(curl, CURLOPT_RTSP_STREAM_URI, uri); + my_curl_easy_setopt(curl, CURLOPT_RTSP_TRANSPORT, transport); + my_curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, (long)CURL_RTSPREQ_SETUP); + my_curl_easy_perform(curl); +} + + +/* send RTSP PLAY request */ +static void rtsp_play(CURL *curl, const char *uri, const char *range) +{ + CURLcode res = CURLE_OK; + printf("\nRTSP: PLAY %s\n", uri); + my_curl_easy_setopt(curl, CURLOPT_RTSP_STREAM_URI, uri); + my_curl_easy_setopt(curl, CURLOPT_RANGE, range); + my_curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, (long)CURL_RTSPREQ_PLAY); + my_curl_easy_perform(curl); +} + + +/* send RTSP TEARDOWN request */ +static void rtsp_teardown(CURL *curl, const char *uri) +{ + CURLcode res = CURLE_OK; + printf("\nRTSP: TEARDOWN %s\n", uri); + my_curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, (long)CURL_RTSPREQ_TEARDOWN); + my_curl_easy_perform(curl); +} + + +/* convert url into an sdp filename */ +static void get_sdp_filename(const char *url, char *sdp_filename) +{ + const char *s = strrchr(url, '/'); + strcpy(sdp_filename, "video.sdp"); + if (s != NULL) { + s++; + if (s[0] != '\0') { + sprintf(sdp_filename, "%s.sdp", s); + } + } +} + + +/* scan sdp file for media control attribute */ +static void get_media_control_attribute(const char *sdp_filename, + char *control) +{ + int max_len = 256; + char *s = malloc(max_len); + FILE *sdp_fp = fopen(sdp_filename, "rt"); + control[0] = '\0'; + if (sdp_fp != NULL) { + while (fgets(s, max_len - 2, sdp_fp) != NULL) { + sscanf(s, " a = control: %s", control); + } + fclose(sdp_fp); + } + free(s); +} + + +/* main app */ +int main(int argc, char * const argv[]) +{ +#if 1 + const char *transport = "RTP/AVP;unicast;client_port=1234-1235"; /* UDP */ +#else + const char *transport = "RTP/AVP/TCP;unicast;client_port=1234-1235"; /* TCP */ +#endif + const char *range = "0.000-"; + int rc = EXIT_SUCCESS; + char *base_name = NULL; + + printf("\nRTSP request %s\n", VERSION_STR); + printf(" Project web site: http://code.google.com/p/rtsprequest/\n"); + printf(" Requires cURL V7.20 or greater\n\n"); + + /* check command line */ + if ((argc != 2) && (argc != 3)) { + base_name = strrchr(argv[0], '/'); + if (base_name == NULL) { + base_name = strrchr(argv[0], '\\'); + } + if (base_name == NULL) { + base_name = argv[0]; + } else { + base_name++; + } + printf("Usage: %s url [transport]\n", base_name); + printf(" url of video server\n"); + printf(" transport (optional) specifier for media stream protocol\n"); + printf(" default transport: %s\n", transport); + printf("Example: %s rtsp://192.168.0.2/media/video1\n\n", base_name); + rc = EXIT_FAILURE; + } else { + const char *url = argv[1]; + char *uri = malloc(strlen(url) + 32); + char *sdp_filename = malloc(strlen(url) + 32); + char *control = malloc(strlen(url) + 32); + CURLcode res; + get_sdp_filename(url, sdp_filename); + if (argc == 3) { + transport = argv[2]; + } + + /* initialize curl */ + res = curl_global_init(CURL_GLOBAL_ALL); + if (res == CURLE_OK) { + curl_version_info_data *data = curl_version_info(CURLVERSION_NOW); + CURL *curl; + fprintf(stderr, " cURL V%s loaded\n", data->version); + + /* initialize this curl session */ + curl = curl_easy_init(); + if (curl != NULL) { + my_curl_easy_setopt(curl, CURLOPT_VERBOSE, 0L); + my_curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 1L); + my_curl_easy_setopt(curl, CURLOPT_WRITEHEADER, stdout); + my_curl_easy_setopt(curl, CURLOPT_URL, url); + + /* request server options */ + sprintf(uri, "%s", url); + rtsp_options(curl, uri); + + /* request session description and write response to sdp file */ + rtsp_describe(curl, uri, sdp_filename); + + /* get media control attribute from sdp file */ + get_media_control_attribute(sdp_filename, control); + + /* setup media stream */ + sprintf(uri, "%s/%s", url, control); + rtsp_setup(curl, uri, transport); + + /* start playing media stream */ + sprintf(uri, "%s/", url); + rtsp_play(curl, uri, range); + printf("Playing video, press any key to stop ..."); + _getch(); + printf("\n"); + + /* teardown session */ + rtsp_teardown(curl, uri); + + /* cleanup */ + curl_easy_cleanup(curl); + curl = NULL; + } else { + fprintf(stderr, "curl_easy_init() failed\n"); + } + curl_global_cleanup(); + } else { + fprintf(stderr, "curl_global_init(%s) failed: %d\n", + "CURL_GLOBAL_ALL", res); + } + free(control); + free(sdp_filename); + free(uri); + } + + return rc; +} diff --git a/docs/examples/sampleconv.c b/docs/examples/sampleconv.c index ed458516d..3db316096 100644 --- a/docs/examples/sampleconv.c +++ b/docs/examples/sampleconv.c @@ -1,11 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ /* This is a simple example showing how a program on a non-ASCII platform would invoke callbacks to do its own codeset conversions instead of diff --git a/docs/examples/sendrecv.c b/docs/examples/sendrecv.c index ad5ddd115..88fddf59f 100644 --- a/docs/examples/sendrecv.c +++ b/docs/examples/sendrecv.c @@ -1,20 +1,32 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - * An example of curl_easy_send() and curl_easy_recv() usage. + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. * - */ + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* An example of curl_easy_send() and curl_easy_recv() usage. */ #include <stdio.h> #include <string.h> #include <curl/curl.h> /* Auxiliary function that waits on the socket. */ -static int wait_on_socket(int sockfd, int for_recv, long timeout_ms) +static int wait_on_socket(curl_socket_t sockfd, int for_recv, long timeout_ms) { struct timeval tv; fd_set infd, outfd, errfd; @@ -49,8 +61,10 @@ int main(void) CURLcode res; /* Minimalistic http request */ const char *request = "GET / HTTP/1.0\r\nHost: example.com\r\n\r\n"; - int sockfd; /* socket */ + curl_socket_t sockfd; /* socket */ + long sockextr; size_t iolen; + curl_off_t nread; curl = curl_easy_init(); if(curl) { @@ -65,9 +79,11 @@ int main(void) return 1; } - /* Extract the socket from the curl handle - we'll need it - * for waiting */ - res = curl_easy_getinfo(curl, CURLINFO_LASTSOCKET, &sockfd); + /* Extract the socket from the curl handle - we'll need it for waiting. + * Note that this API takes a pointer to a 'long' while we use + * curl_socket_t for sockets otherwise. + */ + res = curl_easy_getinfo(curl, CURLINFO_LASTSOCKET, &sockextr); if(CURLE_OK != res) { @@ -75,6 +91,8 @@ int main(void) return 1; } + sockfd = sockextr; + /* wait for the socket to become ready for sending */ if(!wait_on_socket(sockfd, 0, 60000L)) { @@ -105,7 +123,9 @@ int main(void) if(CURLE_OK != res) break; - printf("Received %u bytes.\n", iolen); + nread = (curl_off_t)iolen; + + printf("Received %" CURL_FORMAT_CURL_OFF_T " bytes.\n", nread); } /* always cleanup */ diff --git a/docs/examples/sepheaders.c b/docs/examples/sepheaders.c index e0c4cbbb7..d944ab99d 100644 --- a/docs/examples/sepheaders.c +++ b/docs/examples/sepheaders.c @@ -1,19 +1,29 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <curl/curl.h> -#include <curl/types.h> -#include <curl/easy.h> static size_t write_data(void *ptr, size_t size, size_t nmemb, void *stream) { @@ -21,7 +31,7 @@ static size_t write_data(void *ptr, size_t size, size_t nmemb, void *stream) return written; } -int main(int argc, char **argv) +int main(void) { CURL *curl_handle; static const char *headerfilename = "head.out"; @@ -44,23 +54,22 @@ int main(int argc, char **argv) curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, write_data); /* open the files */ - headerfile = fopen(headerfilename,"w"); + headerfile = fopen(headerfilename,"wb"); if (headerfile == NULL) { curl_easy_cleanup(curl_handle); return -1; } - bodyfile = fopen(bodyfilename,"w"); + bodyfile = fopen(bodyfilename,"wb"); if (bodyfile == NULL) { curl_easy_cleanup(curl_handle); return -1; } - /* we want the headers to this file handle */ + /* we want the headers be written to this file handle */ curl_easy_setopt(curl_handle, CURLOPT_WRITEHEADER, headerfile); - /* - * Notice here that if you want the actual data sent anywhere else but - * stdout, you should consider using the CURLOPT_WRITEDATA option. */ + /* we want the body be written to this file handle instead of stdout */ + curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, bodyfile); /* get it! */ curl_easy_perform(curl_handle); @@ -68,6 +77,9 @@ int main(int argc, char **argv) /* close the header file */ fclose(headerfile); + /* close the body file */ + fclose(bodyfile); + /* cleanup curl stuff */ curl_easy_cleanup(curl_handle); diff --git a/docs/examples/sftpget.c b/docs/examples/sftpget.c new file mode 100644 index 000000000..8317462e9 --- /dev/null +++ b/docs/examples/sftpget.c @@ -0,0 +1,106 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ + +#include <stdio.h> + +#include <curl/curl.h> + +/* define this to switch off the use of ssh-agent in this program */ +#undef DISABLE_SSH_AGENT + +/* + * This is an example showing how to get a single file from an SFTP server. + * It delays the actual destination file creation until the first write + * callback so that it won't create an empty file in case the remote file + * doesn't exist or something else fails. + */ + +struct FtpFile { + const char *filename; + FILE *stream; +}; + +static size_t my_fwrite(void *buffer, size_t size, size_t nmemb, + void *stream) +{ + struct FtpFile *out=(struct FtpFile *)stream; + if(out && !out->stream) { + /* open file for writing */ + out->stream=fopen(out->filename, "wb"); + if(!out->stream) + return -1; /* failure, can't open file to write */ + } + return fwrite(buffer, size, nmemb, out->stream); +} + + +int main(void) +{ + CURL *curl; + CURLcode res; + struct FtpFile ftpfile={ + "yourfile.bin", /* name to store the file as if succesful */ + NULL + }; + + curl_global_init(CURL_GLOBAL_DEFAULT); + + curl = curl_easy_init(); + if(curl) { + /* + * You better replace the URL with one that works! + */ + curl_easy_setopt(curl, CURLOPT_URL, + "sftp://user@server/home/user/file.txt"); + /* Define our callback to get called when there's data to be written */ + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, my_fwrite); + /* Set a pointer to our struct to pass to the callback */ + curl_easy_setopt(curl, CURLOPT_WRITEDATA, &ftpfile); + +#ifndef DISABLE_SSH_AGENT + /* We activate ssh agent. For this to work you need + to have ssh-agent running (type set | grep SSH_AGENT to check) or + pageant on Windows (there is an icon in systray if so) */ + curl_easy_setopt(curl, CURLOPT_SSH_AUTH_TYPES, CURLSSH_AUTH_AGENT); +#endif + + /* Switch on full protocol/debug output */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + res = curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + + if(CURLE_OK != res) { + /* we failed */ + fprintf(stderr, "curl told us %d\n", res); + } + } + + if(ftpfile.stream) + fclose(ftpfile.stream); /* close the local file */ + + curl_global_cleanup(); + + return 0; +} diff --git a/docs/examples/simple.c b/docs/examples/simple.c index 351cf729b..1912ce66e 100644 --- a/docs/examples/simple.c +++ b/docs/examples/simple.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> @@ -18,7 +30,15 @@ int main(void) curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + /* example.com is redirected, so we tell libcurl to follow redirection */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); diff --git a/docs/examples/simplepost.c b/docs/examples/simplepost.c index b8e61e07d..8657771f4 100644 --- a/docs/examples/simplepost.c +++ b/docs/examples/simplepost.c @@ -1,12 +1,24 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <string.h> #include <curl/curl.h> @@ -27,7 +39,12 @@ int main(void) itself */ curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long)strlen(postthis)); + /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); /* always cleanup */ curl_easy_cleanup(curl); diff --git a/docs/examples/simplesmtp.c b/docs/examples/simplesmtp.c new file mode 100644 index 000000000..df8516242 --- /dev/null +++ b/docs/examples/simplesmtp.c @@ -0,0 +1,87 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include <stdio.h> +#include <string.h> +#include <curl/curl.h> + +int main(void) +{ + CURL *curl; + CURLcode res; + struct curl_slist *recipients = NULL; + + /* value for envelope reverse-path */ + static const char *from = "<bradh@example.com>"; + + /* this becomes the envelope forward-path */ + static const char *to = "<bradh@example.net>"; + + curl = curl_easy_init(); + if(curl) { + /* this is the URL for your mailserver - you can also use an smtps:// URL + * here */ + curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.net."); + + /* Note that this option isn't strictly required, omitting it will result in + * libcurl will sent the MAIL FROM command with no sender data. All + * autoresponses should have an empty reverse-path, and should be directed + * to the address in the reverse-path which triggered them. Otherwise, they + * could cause an endless loop. See RFC 5321 Section 4.5.5 for more details. + */ + curl_easy_setopt(curl, CURLOPT_MAIL_FROM, from); + + /* Note that the CURLOPT_MAIL_RCPT takes a list, not a char array. */ + recipients = curl_slist_append(recipients, to); + curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients); + + /* You provide the payload (headers and the body of the message) as the + * "data" element. There are two choices, either: + * - provide a callback function and specify the function name using the + * CURLOPT_READFUNCTION option; or + * - just provide a FILE pointer that can be used to read the data from. + * The easiest case is just to read from standard input, (which is available + * as a FILE pointer) as shown here. + */ + curl_easy_setopt(curl, CURLOPT_READDATA, stdin); + + /* send the message (including headers) */ + res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + + /* free the list of recipients */ + curl_slist_free_all(recipients); + + /* curl won't send the QUIT command until you call cleanup, so you should be + * able to re-use this connection for additional messages (setting + * CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and calling + * curl_easy_perform() again. It may not be a good idea to keep the + * connection open for a very long time though (more than a few minutes may + * result in the server timing out the connection), and you do want to clean + * up in the end. + */ + curl_easy_cleanup(curl); + } + return 0; +} diff --git a/docs/examples/simplessl.c b/docs/examples/simplessl.c index db3accaaa..74c58461a 100644 --- a/docs/examples/simplessl.c +++ b/docs/examples/simplessl.c @@ -1,18 +1,27 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - */ - + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ #include <stdio.h> #include <curl/curl.h> -#include <curl/types.h> -#include <curl/easy.h> - /* some requirements for this to work: 1. set pCertFile to the file with the client certificate @@ -32,8 +41,9 @@ */ -int main(int argc, char **argv) +int main(void) { + int i; CURL *curl; CURLcode res; FILE *headerfile; @@ -47,7 +57,7 @@ int main(int argc, char **argv) const char *pEngine; -#if USE_ENGINE +#ifdef USE_ENGINE pKeyName = "rsa_test"; pKeyType = "ENG"; pEngine = "chil"; /* for nChiper HSM... */ @@ -67,7 +77,7 @@ int main(int argc, char **argv) curl_easy_setopt(curl, CURLOPT_URL, "HTTPS://your.favourite.ssl.site"); curl_easy_setopt(curl, CURLOPT_WRITEHEADER, headerfile); - while(1) /* do some ugly short cut... */ + for(i = 0; i < 1; i++) /* single-iteration loop, just to break out from */ { if (pEngine) /* use crypto engine */ { @@ -109,8 +119,14 @@ int main(int argc, char **argv) /* disconnect if we can't validate server's cert */ curl_easy_setopt(curl,CURLOPT_SSL_VERIFYPEER,1L); + /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); - break; /* we are done... */ + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + + /* we are done... */ } /* always cleanup */ curl_easy_cleanup(curl); diff --git a/docs/examples/smooth-gtk-thread.c b/docs/examples/smooth-gtk-thread.c index 5b60ded31..932f6e396 100644 --- a/docs/examples/smooth-gtk-thread.c +++ b/docs/examples/smooth-gtk-thread.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * This is a multi threaded application that uses a progress bar to show + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* This is a multi threaded application that uses a progress bar to show * status. It uses Gtk+ to make a smooth pulse. * * Written by Jud Bishop after studying the other examples provided with @@ -24,8 +37,6 @@ #include <pthread.h> #include <curl/curl.h> -#include <curl/types.h> /* new for v7 */ -#include <curl/easy.h> /* new for v7 */ #define NUMT 4 diff --git a/docs/examples/smtp-multi.c b/docs/examples/smtp-multi.c index 239172ba9..6462aff2d 100644 --- a/docs/examples/smtp-multi.c +++ b/docs/examples/smtp-multi.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * This is an example application source code sending SMTP mail using the + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* This is an example application source code sending SMTP mail using the * multi interface. */ @@ -21,7 +34,7 @@ #define SMTPSERVER "smtp.example.com" #define SMTPPORT ":587" /* it is a colon+port string, but you can set it to "" to use the default port */ -#define RECEPIENT "receipient@example.com" +#define RECIPIENT "<recipient@example.com>" #define MAILFROM "<realuser@example.com>" #define MULTI_PERFORM_HANG_TIMEOUT 60 * 1000 @@ -83,7 +96,6 @@ int main(void) CURLM *mcurl; int still_running = 1; struct timeval mp_start; - char mp_timedout = 0; struct WriteThis pooh; struct curl_slist* rcpt_list = NULL; @@ -99,9 +111,9 @@ int main(void) if(!mcurl) return 2; - rcpt_list = curl_slist_append(rcpt_list, RECEPIENT); + rcpt_list = curl_slist_append(rcpt_list, RECIPIENT); /* more addresses can be added here - rcpt_list = curl_slist_append(rcpt_list, "others@example.com"); + rcpt_list = curl_slist_append(rcpt_list, "<others@example.com>"); */ curl_easy_setopt(curl, CURLOPT_URL, "smtp://" SMTPSERVER SMTPPORT); @@ -110,16 +122,15 @@ int main(void) curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback); curl_easy_setopt(curl, CURLOPT_MAIL_FROM, MAILFROM); curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, rcpt_list); - curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_ALL); - curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER,0); - curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0); + curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); curl_easy_setopt(curl, CURLOPT_READDATA, &pooh); - curl_easy_setopt(curl, CURLOPT_VERBOSE, 1); - curl_easy_setopt(curl, CURLOPT_SSLVERSION, 0); - curl_easy_setopt(curl, CURLOPT_SSL_SESSIONID_CACHE, 0); + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + curl_easy_setopt(curl, CURLOPT_SSLVERSION, 0L); + curl_easy_setopt(curl, CURLOPT_SSL_SESSIONID_CACHE, 0L); curl_multi_add_handle(mcurl, curl); - mp_timedout = 0; mp_start = tvnow(); /* we start some action by calling perform right away */ diff --git a/docs/examples/smtp-tls.c b/docs/examples/smtp-tls.c new file mode 100644 index 000000000..3635c103f --- /dev/null +++ b/docs/examples/smtp-tls.c @@ -0,0 +1,152 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include <stdio.h> +#include <string.h> +#include <curl/curl.h> + +/* This is a simple example showing how to send mail using libcurl's SMTP + * capabilities. It builds on the simplesmtp.c example, adding some + * authentication and transport security. + */ + +#define FROM "<sender@example.org>" +#define TO "<addressee@example.net>" +#define CC "<info@example.org>" + +static const char *payload_text[]={ + "Date: Mon, 29 Nov 2010 21:54:29 +1100\n", + "To: " TO "\n", + "From: " FROM "(Example User)\n", + "Cc: " CC "(Another example User)\n", + "Message-ID: <dcd7cb36-11db-487a-9f3a-e652a9458efd@rfcpedant.example.org>\n", + "Subject: SMTP TLS example message\n", + "\n", /* empty line to divide headers from body, see RFC5322 */ + "The body of the message starts here.\n", + "\n", + "It could be a lot of lines, could be MIME encoded, whatever.\n", + "Check RFC5322.\n", + NULL +}; + +struct upload_status { + int lines_read; +}; + +static size_t payload_source(void *ptr, size_t size, size_t nmemb, void *userp) +{ + struct upload_status *upload_ctx = (struct upload_status *)userp; + const char *data; + + if ((size == 0) || (nmemb == 0) || ((size*nmemb) < 1)) { + return 0; + } + + data = payload_text[upload_ctx->lines_read]; + + if (data) { + size_t len = strlen(data); + memcpy(ptr, data, len); + upload_ctx->lines_read ++; + return len; + } + return 0; +} + + +int main(void) +{ + CURL *curl; + CURLcode res; + struct curl_slist *recipients = NULL; + struct upload_status upload_ctx; + + upload_ctx.lines_read = 0; + + curl = curl_easy_init(); + if (curl) { + /* This is the URL for your mailserver. Note the use of port 587 here, + * instead of the normal SMTP port (25). Port 587 is commonly used for + * secure mail submission (see RFC4403), but you should use whatever + * matches your server configuration. */ + curl_easy_setopt(curl, CURLOPT_URL, "smtp://mainserver.example.net:587"); + + /* In this example, we'll start with a plain text connection, and upgrade + * to Transport Layer Security (TLS) using the STARTTLS command. Be careful + * of using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer + * will continue anyway - see the security discussion in the libcurl + * tutorial for more details. */ + curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); + + /* If your server doesn't have a valid certificate, then you can disable + * part of the Transport Layer Security protection by setting the + * CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST options to 0 (false). + * curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); + * curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); + * That is, in general, a bad idea. It is still better than sending your + * authentication details in plain text though. + * Instead, you should get the issuer certificate (or the host certificate + * if the certificate is self-signed) and add it to the set of certificates + * that are known to libcurl using CURLOPT_CAINFO and/or CURLOPT_CAPATH. See + * docs/SSLCERTS for more information. + */ + curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem"); + + /* A common reason for requiring transport security is to protect + * authentication details (user names and passwords) from being "snooped" + * on the network. Here is how the user name and password are provided: */ + curl_easy_setopt(curl, CURLOPT_USERNAME, "user@example.net"); + curl_easy_setopt(curl, CURLOPT_PASSWORD, "P@ssw0rd"); + + /* value for envelope reverse-path */ + curl_easy_setopt(curl, CURLOPT_MAIL_FROM, FROM); + /* Add two recipients, in this particular case they correspond to the + * To: and Cc: addressees in the header, but they could be any kind of + * recipient. */ + recipients = curl_slist_append(recipients, TO); + recipients = curl_slist_append(recipients, CC); + curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients); + + /* In this case, we're using a callback function to specify the data. You + * could just use the CURLOPT_READDATA option to specify a FILE pointer to + * read from. + */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source); + curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx); + + /* Since the traffic will be encrypted, it is very useful to turn on debug + * information within libcurl to see what is happening during the transfer. + */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + /* send the message (including headers) */ + res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + + /* free the list of recipients and clean up */ + curl_slist_free_all(recipients); + curl_easy_cleanup(curl); + } + return 0; +} diff --git a/docs/examples/synctime.c b/docs/examples/synctime.c index 4ed031ac4..14d77de27 100644 --- a/docs/examples/synctime.c +++ b/docs/examples/synctime.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * This example code only builds as-is on Windows. + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* This example code only builds as-is on Windows. * * While Unix/Linux user, you do not need this software. * You can achieve the same result as synctime using curl, awk and date. @@ -134,7 +147,7 @@ size_t SyncTime_CURL_WriteHeader(void *ptr, size_t size, size_t nmemb, TmpStr1 & 2? */ AutoSyncTime = 0; else { - RetVal = sscanf ((char *)(ptr), "Date: %s %d %s %d %d:%d:%d", + RetVal = sscanf ((char *)(ptr), "Date: %s %hu %s %hu %hu:%hu:%hu", TmpStr1, &SYSTime.wDay, TmpStr2, &SYSTime.wYear, &SYSTime.wHour, &SYSTime.wMinute, &SYSTime.wSecond); diff --git a/docs/examples/threaded-ssl.c b/docs/examples/threaded-ssl.c index 284edc419..a7e9c2de1 100644 --- a/docs/examples/threaded-ssl.c +++ b/docs/examples/threaded-ssl.c @@ -1,12 +1,25 @@ -/***************************************************************************** +/*************************************************************************** * _ _ ____ _ * Project ___| | | | _ \| | * / __| | | | |_) | | * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * + * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. * - * A multi-threaded example that uses pthreads and fetches 4 remote files at + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* A multi-threaded example that uses pthreads and fetches 4 remote files at * once over HTTPS. The lock callbacks and stuff assume OpenSSL or GnuTLS * (libgcrypt) so far. * diff --git a/docs/examples/url2file.c b/docs/examples/url2file.c new file mode 100644 index 000000000..64d27c88f --- /dev/null +++ b/docs/examples/url2file.c @@ -0,0 +1,81 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> + +#include <curl/curl.h> + +static size_t write_data(void *ptr, size_t size, size_t nmemb, void *stream) +{ + size_t written = fwrite(ptr, size, nmemb, (FILE *)stream); + return written; +} + +int main(int argc, char *argv[]) +{ + CURL *curl_handle; + static const char *pagefilename = "page.out"; + FILE *pagefile; + + if(argc < 2 ) { + printf("Usage: %s <URL>\n", argv[0]); + return 1; + } + + curl_global_init(CURL_GLOBAL_ALL); + + /* init the curl session */ + curl_handle = curl_easy_init(); + + /* set URL to get here */ + curl_easy_setopt(curl_handle, CURLOPT_URL, argv[1]); + + /* Switch on full protocol/debug output while testing */ + curl_easy_setopt(curl_handle, CURLOPT_VERBOSE, 1L); + + /* disable progress meter, set to 0L to enable and disable debug output */ + curl_easy_setopt(curl_handle, CURLOPT_NOPROGRESS, 1L); + + /* send all data to this function */ + curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, write_data); + + /* open the file */ + pagefile = fopen(pagefilename, "wb"); + if (pagefile) { + + /* write the page body to this file handle. CURLOPT_FILE is also known as + CURLOPT_WRITEDATA*/ + curl_easy_setopt(curl_handle, CURLOPT_FILE, pagefile); + + /* get it! */ + curl_easy_perform(curl_handle); + + /* close the header file */ + fclose(pagefile); + } + + /* cleanup curl stuff */ + curl_easy_cleanup(curl_handle); + + return 0; +} diff --git a/docs/examples/usercertinmem.c b/docs/examples/usercertinmem.c new file mode 100644 index 000000000..99740fdce --- /dev/null +++ b/docs/examples/usercertinmem.c @@ -0,0 +1,211 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 2013, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Example using an in memory PEM user certificate and RSA key to retrieve an + * https page. + * Written by Ishan SinghLevett, based on Theo Borm's cacertinmem.c. + * Note this example does not use a CA certificate, however one should be used + * if you want a properly secure connection + */ + +#include <openssl/ssl.h> +#include <openssl/x509.h> +#include <openssl/pem.h> +#include <curl/curl.h> +#include <stdio.h> + +static size_t writefunction(void *ptr, size_t size, size_t nmemb, void *stream) +{ + fwrite(ptr,size,nmemb,stream); + return(nmemb*size); +} + +static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm) +{ + X509 *cert = NULL; + BIO *bio = NULL; + BIO *kbio = NULL; + RSA *rsa = NULL; + int ret; + + const char *mypem = /* www.cacert.org */ + "-----BEGIN CERTIFICATE-----\n"\ + "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\n"\ + "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\n"\ + "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\n"\ + "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\n"\ + "BgNVBAoTB1Jvb3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEi\n"\ + "MCAGA1UEAxMZQ0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJ\n"\ + "ARYSc3VwcG9ydEBjYWNlcnQub3JnMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIIC\n"\ + "CgKCAgEAziLA4kZ97DYoB1CW8qAzQIxL8TtmPzHlawI229Z89vGIj053NgVBlfkJ\n"\ + "8BLPRoZzYLdufujAWGSuzbCtRRcMY/pnCujW0r8+55jE8Ez64AO7NV1sId6eINm6\n"\ + "zWYyN3L69wj1x81YyY7nDl7qPv4coRQKFWyGhFtkZip6qUtTefWIonvuLwphK42y\n"\ + "fk1WpRPs6tqSnqxEQR5YYGUFZvjARL3LlPdCfgv3ZWiYUQXw8wWRBB0bF4LsyFe7\n"\ + "w2t6iPGwcswlWyCR7BYCEo8y6RcYSNDHBS4CMEK4JZwFaz+qOqfrU0j36NK2B5jc\n"\ + "G8Y0f3/JHIJ6BVgrCFvzOKKrF11myZjXnhCLotLddJr3cQxyYN/Nb5gznZY0dj4k\n"\ + "epKwDpUeb+agRThHqtdB7Uq3EvbXG4OKDy7YCbZZ16oE/9KTfWgu3YtLq1i6L43q\n"\ + "laegw1SJpfvbi1EinbLDvhG+LJGGi5Z4rSDTii8aP8bQUWWHIbEZAWV/RRyH9XzQ\n"\ + "QUxPKZgh/TMfdQwEUfoZd9vUFBzugcMd9Zi3aQaRIt0AUMyBMawSB3s42mhb5ivU\n"\ + "fslfrejrckzzAeVLIL+aplfKkQABi6F1ITe1Yw1nPkZPcCBnzsXWWdsC4PDSy826\n"\ + "YreQQejdIOQpvGQpQsgi3Hia/0PsmBsJUUtaWsJx8cTLc6nloQsCAwEAAaOCAc4w\n"\ + "ggHKMB0GA1UdDgQWBBQWtTIb1Mfz4OaO873SsDrusjkY0TCBowYDVR0jBIGbMIGY\n"\ + "gBQWtTIb1Mfz4OaO873SsDrusjkY0aF9pHsweTEQMA4GA1UEChMHUm9vdCBDQTEe\n"\ + "MBwGA1UECxMVaHR0cDovL3d3dy5jYWNlcnQub3JnMSIwIAYDVQQDExlDQSBDZXJ0\n"\ + "IFNpZ25pbmcgQXV0aG9yaXR5MSEwHwYJKoZIhvcNAQkBFhJzdXBwb3J0QGNhY2Vy\n"\ + "dC5vcmeCAQAwDwYDVR0TAQH/BAUwAwEB/zAyBgNVHR8EKzApMCegJaAjhiFodHRw\n"\ + "czovL3d3dy5jYWNlcnQub3JnL3Jldm9rZS5jcmwwMAYJYIZIAYb4QgEEBCMWIWh0\n"\ + "dHBzOi8vd3d3LmNhY2VydC5vcmcvcmV2b2tlLmNybDA0BglghkgBhvhCAQgEJxYl\n"\ + "aHR0cDovL3d3dy5jYWNlcnQub3JnL2luZGV4LnBocD9pZD0xMDBWBglghkgBhvhC\n"\ + "AQ0ESRZHVG8gZ2V0IHlvdXIgb3duIGNlcnRpZmljYXRlIGZvciBGUkVFIGhlYWQg\n"\ + "b3ZlciB0byBodHRwOi8vd3d3LmNhY2VydC5vcmcwDQYJKoZIhvcNAQEEBQADggIB\n"\ + "ACjH7pyCArpcgBLKNQodgW+JapnM8mgPf6fhjViVPr3yBsOQWqy1YPaZQwGjiHCc\n"\ + "nWKdpIevZ1gNMDY75q1I08t0AoZxPuIrA2jxNGJARjtT6ij0rPtmlVOKTV39O9lg\n"\ + "18p5aTuxZZKmxoGCXJzN600BiqXfEVWqFcofN8CCmHBh22p8lqOOLlQ+TyGpkO/c\n"\ + "gr/c6EWtTZBzCDyUZbAEmXZ/4rzCahWqlwQ3JNgelE5tDlG+1sSPypZt90Pf6DBl\n"\ + "Jzt7u0NDY8RD97LsaMzhGY4i+5jhe1o+ATc7iwiwovOVThrLm82asduycPAtStvY\n"\ + "sONvRUgzEv/+PDIqVPfE94rwiCPCR/5kenHA0R6mY7AHfqQv0wGP3J8rtsYIqQ+T\n"\ + "SCX8Ev2fQtzzxD72V7DX3WnRBnc0CkvSyqD/HMaMyRa+xMwyN2hzXwj7UfdJUzYF\n"\ + "CpUCTPJ5GhD22Dp1nPMd8aINcGeGG7MW9S/lpOt5hvk9C8JzC6WZrG/8Z7jlLwum\n"\ + "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\n"\ + "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\n"\ + "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\n"\ + "-----END CERTIFICATE-----\n"; + +/*replace the XXX with the actual RSA key*/ + const char *mykey = + "-----BEGIN RSA PRIVATE KEY-----\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\ + "-----END RSA PRIVATE KEY-----\n"; + + (void)curl; /* avoid warnings */ + (void)parm; /* avoid warnings */ + + /* get a BIO */ + bio = BIO_new_mem_buf((char *)mypem, -1); + + if (bio == NULL) { + printf("BIO_new_mem_buf failed\n"); + } + + /* use it to read the PEM formatted certificate from memory into an X509 + * structure that SSL can use + */ + cert = PEM_read_bio_X509(bio, NULL, 0, NULL); + if (cert == NULL) { + printf("PEM_read_bio_X509 failed...\n"); + } + + /*tell SSL to use the X509 certificate*/ + ret = SSL_CTX_use_certificate((SSL_CTX*)sslctx, cert); + if (ret != 1) { + printf("Use certificate failed\n"); + } + + /*create a bio for the RSA key*/ + kbio = BIO_new_mem_buf((char *)mykey, -1); + if (kbio == NULL) { + printf("BIO_new_mem_buf failed\n"); + } + + /*read the key bio into an RSA object*/ + rsa = PEM_read_bio_RSAPrivateKey(kbio, NULL, 0, NULL); + if (rsa == NULL) { + printf("Failed to create key bio\n"); + } + + /*tell SSL to use the RSA key from memory*/ + ret = SSL_CTX_use_RSAPrivateKey((SSL_CTX*)sslctx, rsa); + if (ret != 1) { + printf("Use Key failed\n"); + } + + + /* all set to go */ + return CURLE_OK ; +} + +int main(void) +{ + CURL *ch; + CURLcode rv; + + rv = curl_global_init(CURL_GLOBAL_ALL); + ch = curl_easy_init(); + rv = curl_easy_setopt(ch,CURLOPT_VERBOSE, 0L); + rv = curl_easy_setopt(ch,CURLOPT_HEADER, 0L); + rv = curl_easy_setopt(ch,CURLOPT_NOPROGRESS, 1L); + rv = curl_easy_setopt(ch,CURLOPT_NOSIGNAL, 1L); + rv = curl_easy_setopt(ch,CURLOPT_WRITEFUNCTION, *writefunction); + rv = curl_easy_setopt(ch,CURLOPT_WRITEDATA, stdout); + rv = curl_easy_setopt(ch,CURLOPT_HEADERFUNCTION, *writefunction); + rv = curl_easy_setopt(ch,CURLOPT_WRITEHEADER, stderr); + rv = curl_easy_setopt(ch,CURLOPT_SSLCERTTYPE,"PEM"); + + /* both VERIFYPEER and VERIFYHOST are set to 0 in this case because there is + no CA certificate*/ + + rv = curl_easy_setopt(ch,CURLOPT_SSL_VERIFYPEER, 0L); + rv = curl_easy_setopt(ch,CURLOPT_SSL_VERIFYHOST, 0L); + rv = curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); + rv = curl_easy_setopt(ch, CURLOPT_SSLKEYTYPE, "PEM"); + + /* first try: retrieve page without user certificate and key -> will fail + */ + rv = curl_easy_perform(ch); + if (rv==CURLE_OK) { + printf("*** transfer succeeded ***\n"); + } + else { + printf("*** transfer failed ***\n"); + } + + /* second try: retrieve page using user certificate and key -> will succeed + * load the certificate and key by installing a function doing the necessary + * "modifications" to the SSL CONTEXT just before link init + */ + rv = curl_easy_setopt(ch,CURLOPT_SSL_CTX_FUNCTION, *sslctx_function); + rv = curl_easy_perform(ch); + if (rv==CURLE_OK) { + printf("*** transfer succeeded ***\n"); + } + else { + printf("*** transfer failed ***\n"); + } + + curl_easy_cleanup(ch); + curl_global_cleanup(); + return rv; +} diff --git a/docs/examples/version-check.pl b/docs/examples/version-check.pl index 9b6a2684c..92f0808d6 100755 --- a/docs/examples/version-check.pl +++ b/docs/examples/version-check.pl @@ -90,7 +90,7 @@ my @recent = reverse sort sortversions keys %used; # the most recent symbol my $newsym = $recent[0]; # the most recent version -my $newver = $doc{$newsym}; +my $newver = $doc{$newsym}; print "The scanned source uses these symbols introduced in $newver:\n"; diff --git a/docs/examples/xmlstream.c b/docs/examples/xmlstream.c new file mode 100644 index 000000000..4d67f98eb --- /dev/null +++ b/docs/examples/xmlstream.c @@ -0,0 +1,158 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. + * + * This software is licensed as described in the file COPYING, which + * you should have received as part of this distribution. The terms + * are also available at http://curl.haxx.se/docs/copyright.html. + * + * You may opt to use, copy, modify, merge, publish, distribute and/or sell + * copies of the Software, and permit persons to whom the Software is + * furnished to do so, under the terms of the COPYING file. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ***************************************************************************/ +/* Stream-parse a document using the streaming Expat parser. + * Written by David Strauss + * + * Expat => http://www.libexpat.org/ + * + * gcc -Wall -I/usr/local/include xmlstream.c -lcurl -lexpat -o xmlstream + * + */ + +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <assert.h> + +#include <expat.h> +#include <curl/curl.h> + +struct MemoryStruct { + char *memory; + size_t size; +}; + +struct ParserStruct { + int ok; + size_t tags; + size_t depth; + struct MemoryStruct characters; +}; + +static void startElement(void *userData, const XML_Char *name, const XML_Char **atts) +{ + struct ParserStruct *state = (struct ParserStruct *) userData; + state->tags++; + state->depth++; + + /* Get a clean slate for reading in character data. */ + free(state->characters.memory); + state->characters.memory = NULL; + state->characters.size = 0; +} + +static void characterDataHandler(void *userData, const XML_Char *s, int len) +{ + struct ParserStruct *state = (struct ParserStruct *) userData; + struct MemoryStruct *mem = &state->characters; + + mem->memory = realloc(mem->memory, mem->size + len + 1); + if(mem->memory == NULL) { + /* Out of memory. */ + fprintf(stderr, "Not enough memory (realloc returned NULL).\n"); + state->ok = 0; + return; + } + + memcpy(&(mem->memory[mem->size]), s, len); + mem->size += len; + mem->memory[mem->size] = 0; +} + +static void endElement(void *userData, const XML_Char *name) +{ + struct ParserStruct *state = (struct ParserStruct *) userData; + state->depth--; + + printf("%5lu %10lu %s\n", state->depth, state->characters.size, name); +} + +static size_t parseStreamCallback(void *contents, size_t length, size_t nmemb, void *userp) +{ + XML_Parser parser = (XML_Parser) userp; + size_t real_size = length * nmemb; + struct ParserStruct *state = (struct ParserStruct *) XML_GetUserData(parser); + + /* Only parse if we're not already in a failure state. */ + if (state->ok && XML_Parse(parser, contents, real_size, 0) == 0) { + int error_code = XML_GetErrorCode(parser); + fprintf(stderr, "Parsing response buffer of length %lu failed with error code %d (%s).\n", + real_size, error_code, XML_ErrorString(error_code)); + state->ok = 0; + } + + return real_size; +} + +int main(void) +{ + CURL *curl_handle; + CURLcode res; + XML_Parser parser; + struct ParserStruct state; + + /* Initialize the state structure for parsing. */ + memset(&state, 0, sizeof(struct ParserStruct)); + state.ok = 1; + + /* Initialize a namespace-aware parser. */ + parser = XML_ParserCreateNS(NULL, '\0'); + XML_SetUserData(parser, &state); + XML_SetElementHandler(parser, startElement, endElement); + XML_SetCharacterDataHandler(parser, characterDataHandler); + + /* Initalize a libcurl handle. */ + curl_global_init(CURL_GLOBAL_ALL ^ CURL_GLOBAL_SSL); + curl_handle = curl_easy_init(); + curl_easy_setopt(curl_handle, CURLOPT_URL, "http://www.w3schools.com/xml/simple.xml"); + curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, parseStreamCallback); + curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)parser); + + printf("Depth Characters Closing Tag\n"); + + /* Perform the request and any follow-up parsing. */ + res = curl_easy_perform(curl_handle); + if(res != CURLE_OK) { + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + } + else if (state.ok) { + /* Expat requires one final call to finalize parsing. */ + if (XML_Parse(parser, NULL, 0, 1) == 0) { + int error_code = XML_GetErrorCode(parser); + fprintf(stderr, "Finalizing parsing failed with error code %d (%s).\n", + error_code, XML_ErrorString(error_code)); + } + else { + printf(" --------------\n"); + printf(" %lu tags total\n", state.tags); + } + } + + /* Clean up. */ + free(state.characters.memory); + XML_ParserFree(parser); + curl_easy_cleanup(curl_handle); + curl_global_cleanup(); + + return 0; +} diff --git a/docs/index.html b/docs/index.html index f53411b17..4390378af 100644 --- a/docs/index.html +++ b/docs/index.html @@ -12,7 +12,7 @@ <br><a href="curl.html">curl</A> <h2>Tutorial</h2> -<a href="../TheArtOfHttpScripting.gz">The Art Of Scripting HTTP Requests Using Curl</a> (plain text) +<a href="TheArtOfHttpScripting">The Art Of Scripting HTTP Requests Using Curl</a> (plain text) <h2>libcurl</h2> See the <a href="libcurl/index.html">libcurl section</a> diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 3f949d66c..3114e2b3b 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -1,5 +1,24 @@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| # +# Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. # +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### AUTOMAKE_OPTIONS = foreign no-dependencies @@ -19,7 +38,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \ curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3 \ - curl_multi_socket_action.3 + curl_multi_socket_action.3 curl_multi_wait.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -39,7 +58,7 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_unescape.html curl_multi_setopt.html curl_multi_socket.html \ curl_multi_timeout.html curl_formget.html curl_multi_assign.html \ curl_easy_pause.html curl_easy_recv.html curl_easy_send.html \ - curl_multi_socket_action.html + curl_multi_socket_action.html curl_multi_wait.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ @@ -58,12 +77,12 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_escape.pdf curl_easy_unescape.pdf curl_multi_setopt.pdf \ curl_multi_socket.pdf curl_multi_timeout.pdf curl_formget.pdf \ curl_multi_assign.pdf curl_easy_pause.pdf curl_easy_recv.pdf \ - curl_easy_send.pdf curl_multi_socket_action.pdf + curl_easy_send.pdf curl_multi_socket_action.pdf curl_multi_wait.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 ABI \ - symbols-in-versions + symbols-in-versions symbols.pl MAN2HTML= roffit --mandir=. < $< >$@ SUFFIXES = .3 .html diff --git a/docs/libcurl/Makefile.in b/docs/libcurl/Makefile.in index 48151272f..fa1939dba 100644 --- a/docs/libcurl/Makefile.in +++ b/docs/libcurl/Makefile.in @@ -1,8 +1,8 @@ -# Makefile.in generated by automake 1.9.6 from Makefile.am. +# Makefile.in generated by automake 1.13.3 from Makefile.am. # @configure_input@ -# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -# 2003, 2004, 2005 Free Software Foundation, Inc. +# Copyright (C) 1994-2013 Free Software Foundation, Inc. + # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. @@ -14,17 +14,78 @@ @SET_MAKE@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| # +# Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. # -srcdir = @srcdir@ -top_srcdir = @top_srcdir@ +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### VPATH = @srcdir@ +am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)' +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) pkgdatadir = $(datadir)/@PACKAGE@ -pkglibdir = $(libdir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ -top_builddir = ../.. +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd -INSTALL = @INSTALL@ install_sh_DATA = $(install_sh) -c -m 644 install_sh_PROGRAM = $(install_sh) -c install_sh_SCRIPT = $(install_sh) -c @@ -39,54 +100,105 @@ POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ subdir = docs/libcurl -DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in +DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am \ + $(top_srcdir)/mkinstalldirs ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/curl-compilers.m4 \ $(top_srcdir)/m4/curl-confopts.m4 \ $(top_srcdir)/m4/curl-functions.m4 \ + $(top_srcdir)/m4/curl-openssl.m4 \ $(top_srcdir)/m4/curl-override.m4 \ - $(top_srcdir)/m4/curl-reentrant.m4 \ - $(top_srcdir)/m4/curl-system.m4 $(top_srcdir)/m4/libtool.m4 \ + $(top_srcdir)/m4/curl-reentrant.m4 $(top_srcdir)/m4/libtool.m4 \ $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \ $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \ - $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac + $(top_srcdir)/m4/xc-am-iface.m4 \ + $(top_srcdir)/m4/xc-cc-check.m4 \ + $(top_srcdir)/m4/xc-lt-iface.m4 \ + $(top_srcdir)/m4/xc-translit.m4 \ + $(top_srcdir)/m4/xc-val-flgs.m4 \ + $(top_srcdir)/m4/zz40-xc-ovr.m4 \ + $(top_srcdir)/m4/zz50-xc-ovr.m4 \ + $(top_srcdir)/m4/zz60-xc-ovr.m4 $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs CONFIG_HEADER = $(top_builddir)/lib/curl_config.h \ - $(top_builddir)/src/curl_config.h \ $(top_builddir)/include/curl/curlbuild.h CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = depcomp = am__depfiles_maybe = SOURCES = DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } man3dir = $(mandir)/man3 am__installdirs = "$(DESTDIR)$(man3dir)" MANS = $(man_MANS) +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) ACLOCAL = @ACLOCAL@ -AMDEP_FALSE = @AMDEP_FALSE@ -AMDEP_TRUE = @AMDEP_TRUE@ AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ AR = @AR@ AS = @AS@ AUTOCONF = @AUTOCONF@ AUTOHEADER = @AUTOHEADER@ AUTOMAKE = @AUTOMAKE@ AWK = @AWK@ -BUILD_LIBHOSTNAME_FALSE = @BUILD_LIBHOSTNAME_FALSE@ -BUILD_LIBHOSTNAME_TRUE = @BUILD_LIBHOSTNAME_TRUE@ +BLANK_AT_MAKETIME = @BLANK_AT_MAKETIME@ CC = @CC@ CCDEPMODE = @CCDEPMODE@ CFLAGS = @CFLAGS@ +CFLAG_CURL_SYMBOL_HIDING = @CFLAG_CURL_SYMBOL_HIDING@ CONFIGURE_OPTIONS = @CONFIGURE_OPTIONS@ CPP = @CPP@ CPPFLAGS = @CPPFLAGS@ -CROSSCOMPILING_FALSE = @CROSSCOMPILING_FALSE@ -CROSSCOMPILING_TRUE = @CROSSCOMPILING_TRUE@ -CURLDEBUG_FALSE = @CURLDEBUG_FALSE@ -CURLDEBUG_TRUE = @CURLDEBUG_TRUE@ +CPPFLAG_CURL_STATICLIB = @CPPFLAG_CURL_STATICLIB@ +CURLVERSION = @CURLVERSION@ CURL_CA_BUNDLE = @CURL_CA_BUNDLE@ CURL_CFLAG_EXTRAS = @CURL_CFLAG_EXTRAS@ CURL_DISABLE_DICT = @CURL_DISABLE_DICT@ @@ -103,7 +215,8 @@ CURL_DISABLE_RTSP = @CURL_DISABLE_RTSP@ CURL_DISABLE_SMTP = @CURL_DISABLE_SMTP@ CURL_DISABLE_TELNET = @CURL_DISABLE_TELNET@ CURL_DISABLE_TFTP = @CURL_DISABLE_TFTP@ -CURL_LIBS = @CURL_LIBS@ +CURL_LT_SHLIB_VERSIONED_FLAVOUR = @CURL_LT_SHLIB_VERSIONED_FLAVOUR@ +CURL_NETWORK_AND_TIME_LIBS = @CURL_NETWORK_AND_TIME_LIBS@ CURL_NETWORK_LIBS = @CURL_NETWORK_LIBS@ CYGPATH_W = @CYGPATH_W@ DEFS = @DEFS@ @@ -116,15 +229,17 @@ ECHO_N = @ECHO_N@ ECHO_T = @ECHO_T@ EGREP = @EGREP@ ENABLE_SHARED = @ENABLE_SHARED@ +ENABLE_STATIC = @ENABLE_STATIC@ EXEEXT = @EXEEXT@ FGREP = @FGREP@ GREP = @GREP@ +HAVE_GNUTLS_SRP = @HAVE_GNUTLS_SRP@ HAVE_LDAP_SSL = @HAVE_LDAP_SSL@ HAVE_LIBZ = @HAVE_LIBZ@ -HAVE_LIBZ_FALSE = @HAVE_LIBZ_FALSE@ -HAVE_LIBZ_TRUE = @HAVE_LIBZ_TRUE@ -HAVE_PK11_CREATEGENERICOBJECT = @HAVE_PK11_CREATEGENERICOBJECT@ +HAVE_NSS_INITCONTEXT = @HAVE_NSS_INITCONTEXT@ +HAVE_SSLEAY_SRP = @HAVE_SSLEAY_SRP@ IDN_ENABLED = @IDN_ENABLED@ +INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_SCRIPT = @INSTALL_SCRIPT@ @@ -134,6 +249,9 @@ KRB4_ENABLED = @KRB4_ENABLED@ LD = @LD@ LDFLAGS = @LDFLAGS@ LIBCURL_LIBS = @LIBCURL_LIBS@ +LIBMETALINK_CPPFLAGS = @LIBMETALINK_CPPFLAGS@ +LIBMETALINK_LDFLAGS = @LIBMETALINK_LDFLAGS@ +LIBMETALINK_LIBS = @LIBMETALINK_LIBS@ LIBOBJS = @LIBOBJS@ LIBS = @LIBS@ LIBTOOL = @LIBTOOL@ @@ -141,16 +259,12 @@ LIPO = @LIPO@ LN_S = @LN_S@ LTLIBOBJS = @LTLIBOBJS@ MAINT = @MAINT@ -MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@ -MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@ MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ MANOPT = @MANOPT@ -MIMPURE_FALSE = @MIMPURE_FALSE@ -MIMPURE_TRUE = @MIMPURE_TRUE@ +MKDIR_P = @MKDIR_P@ NM = @NM@ NMEDIT = @NMEDIT@ -NO_UNDEFINED_FALSE = @NO_UNDEFINED_FALSE@ -NO_UNDEFINED_TRUE = @NO_UNDEFINED_TRUE@ NROFF = @NROFF@ OBJDUMP = @OBJDUMP@ OBJEXT = @OBJEXT@ @@ -163,7 +277,6 @@ PACKAGE_STRING = @PACKAGE_STRING@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ -PATH = @PATH@ PATH_SEPARATOR = @PATH_SEPARATOR@ PERL = @PERL@ PKGADD_NAME = @PKGADD_NAME@ @@ -176,34 +289,34 @@ REQUIRE_LIB_DEPS = @REQUIRE_LIB_DEPS@ SED = @SED@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ -SONAME_BUMP_FALSE = @SONAME_BUMP_FALSE@ -SONAME_BUMP_TRUE = @SONAME_BUMP_TRUE@ SSL_ENABLED = @SSL_ENABLED@ -STATICLIB_FALSE = @STATICLIB_FALSE@ -STATICLIB_TRUE = @STATICLIB_TRUE@ STRIP = @STRIP@ SUPPORT_FEATURES = @SUPPORT_FEATURES@ SUPPORT_PROTOCOLS = @SUPPORT_PROTOCOLS@ -TEST_SERVER_LIBS = @TEST_SERVER_LIBS@ USE_ARES = @USE_ARES@ -USE_EMBEDDED_ARES_FALSE = @USE_EMBEDDED_ARES_FALSE@ -USE_EMBEDDED_ARES_TRUE = @USE_EMBEDDED_ARES_TRUE@ +USE_AXTLS = @USE_AXTLS@ +USE_CYASSL = @USE_CYASSL@ +USE_DARWINSSL = @USE_DARWINSSL@ USE_GNUTLS = @USE_GNUTLS@ +USE_GNUTLS_NETTLE = @USE_GNUTLS_NETTLE@ USE_LIBRTMP = @USE_LIBRTMP@ USE_LIBSSH2 = @USE_LIBSSH2@ -USE_MANUAL_FALSE = @USE_MANUAL_FALSE@ -USE_MANUAL_TRUE = @USE_MANUAL_TRUE@ USE_NSS = @USE_NSS@ USE_OPENLDAP = @USE_OPENLDAP@ USE_POLARSSL = @USE_POLARSSL@ +USE_SCHANNEL = @USE_SCHANNEL@ USE_SSLEAY = @USE_SSLEAY@ USE_WINDOWS_SSPI = @USE_WINDOWS_SSPI@ VERSION = @VERSION@ VERSIONNUM = @VERSIONNUM@ +ZLIB_LIBS = @ZLIB_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ ac_ct_CC = @ac_ct_CC@ ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ -am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ -am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ am__include = @am__include@ am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ @@ -215,6 +328,7 @@ build_alias = @build_alias@ build_cpu = @build_cpu@ build_os = @build_os@ build_vendor = @build_vendor@ +builddir = @builddir@ datadir = @datadir@ datarootdir = @datarootdir@ docdir = @docdir@ @@ -234,7 +348,6 @@ libexecdir = @libexecdir@ libext = @libext@ localedir = @localedir@ localstatedir = @localstatedir@ -lt_ECHO = @lt_ECHO@ mandir = @mandir@ mkdir_p = @mkdir_p@ oldincludedir = @oldincludedir@ @@ -244,9 +357,13 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ subdirs = @subdirs@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ AUTOMAKE_OPTIONS = foreign no-dependencies man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_easy_perform.3 curl_easy_setopt.3 curl_easy_duphandle.3 \ @@ -264,7 +381,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \ curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3 \ - curl_multi_socket_action.3 + curl_multi_socket_action.3 curl_multi_wait.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -284,7 +401,7 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_unescape.html curl_multi_setopt.html curl_multi_socket.html \ curl_multi_timeout.html curl_formget.html curl_multi_assign.html \ curl_easy_pause.html curl_easy_recv.html curl_easy_send.html \ - curl_multi_socket_action.html + curl_multi_socket_action.html curl_multi_wait.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ @@ -303,11 +420,11 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_escape.pdf curl_easy_unescape.pdf curl_multi_setopt.pdf \ curl_multi_socket.pdf curl_multi_timeout.pdf curl_formget.pdf \ curl_multi_assign.pdf curl_easy_pause.pdf curl_easy_recv.pdf \ - curl_easy_send.pdf curl_multi_socket_action.pdf + curl_easy_send.pdf curl_multi_socket_action.pdf curl_multi_wait.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 ABI \ - symbols-in-versions + symbols-in-versions symbols.pl MAN2HTML = roffit --mandir=. < $< >$@ SUFFIXES = .3 .html @@ -319,14 +436,14 @@ $(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__confi @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ - && exit 0; \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ exit 1;; \ esac; \ done; \ - echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/libcurl/Makefile'; \ - cd $(top_srcdir) && \ - $(AUTOMAKE) --foreign docs/libcurl/Makefile + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/libcurl/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign docs/libcurl/Makefile .PRECIOUS: Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status @case '$?' in \ @@ -344,92 +461,90 @@ $(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh $(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): mostlyclean-libtool: -rm -f *.lo clean-libtool: -rm -rf .libs _libs - -distclean-libtool: - -rm -f libtool -uninstall-info-am: -install-man3: $(man3_MANS) $(man_MANS) +install-man3: $(man_MANS) @$(NORMAL_INSTALL) - test -z "$(man3dir)" || $(mkdir_p) "$(DESTDIR)$(man3dir)" - @list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.3*) list="$$list $$i" ;; \ - esac; \ + @list1=''; \ + list2='$(man_MANS)'; \ + test -n "$(man3dir)" \ + && test -n "`echo $$list1$$list2`" \ + || exit 0; \ + echo " $(MKDIR_P) '$(DESTDIR)$(man3dir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(man3dir)" || exit 1; \ + { for i in $$list1; do echo "$$i"; done; \ + if test -n "$$list2"; then \ + for i in $$list2; do echo "$$i"; done \ + | sed -n '/\.3[a-z]*$$/p'; \ + fi; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^3][0-9a-z]*$$,3,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man3dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man3dir)/$$inst" || exit $$?; \ + fi; \ done; \ - for i in $$list; do \ - if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ - else file=$$i; fi; \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 3*) ;; \ - *) ext='3' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man3dir)/$$inst'"; \ - $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man3dir)/$$inst"; \ - done + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man3dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man3dir)" || exit $$?; }; \ + done; } + uninstall-man3: @$(NORMAL_UNINSTALL) - @list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.3*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 3*) ;; \ - *) ext='3' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " rm -f '$(DESTDIR)$(man3dir)/$$inst'"; \ - rm -f "$(DESTDIR)$(man3dir)/$$inst"; \ - done -tags: TAGS -TAGS: + @list=''; test -n "$(man3dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.3[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^3][0-9a-z]*$$,3,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + dir='$(DESTDIR)$(man3dir)'; $(am__uninstall_files_from_dir) +tags TAGS: + +ctags CTAGS: -ctags: CTAGS -CTAGS: +cscope cscopelist: distdir: $(DISTFILES) - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ - list='$(DISTFILES)'; for file in $$list; do \ - case $$file in \ - $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ - $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ - esac; \ + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ - dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ - if test "$$dir" != "$$file" && test "$$dir" != "."; then \ - dir="/$$dir"; \ - $(mkdir_p) "$(distdir)$$dir"; \ - else \ - dir=''; \ - fi; \ if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ - cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ fi; \ - cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ else \ - test -f $(distdir)/$$file \ - || cp -p $$d/$$file $(distdir)/$$file \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ || exit 1; \ fi; \ done @@ -438,7 +553,7 @@ check: check-am all-am: Makefile $(MANS) installdirs: for dir in "$(DESTDIR)$(man3dir)"; do \ - test -z "$$dir" || $(mkdir_p) "$$dir"; \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ done install: install-am install-exec: install-exec-am @@ -450,10 +565,15 @@ install-am: all-am installcheck: installcheck-am install-strip: - $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ - install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ - `test -z '$(STRIP)' || \ - echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi mostlyclean-generic: clean-generic: @@ -461,6 +581,7 @@ clean-generic: distclean-generic: -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @@ -471,24 +592,44 @@ clean-am: clean-generic clean-libtool mostlyclean-am distclean: distclean-am -rm -f Makefile -distclean-am: clean-am distclean-generic distclean-libtool +distclean-am: clean-am distclean-generic dvi: dvi-am dvi-am: +html-am: + info: info-am info-am: install-data-am: install-man +install-dvi: install-dvi-am + +install-dvi-am: + install-exec-am: +install-html: install-html-am + +install-html-am: + install-info: install-info-am +install-info-am: + install-man: install-man3 +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + installcheck-am: maintainer-clean: maintainer-clean-am @@ -505,19 +646,23 @@ ps: ps-am ps-am: -uninstall-am: uninstall-info-am uninstall-man +uninstall-am: uninstall-man uninstall-man: uninstall-man3 +.MAKE: install-am install-strip + .PHONY: all all-am check check-am clean clean-generic clean-libtool \ - distclean distclean-generic distclean-libtool distdir dvi \ - dvi-am html html-am info info-am install install-am \ - install-data install-data-am install-exec install-exec-am \ - install-info install-info-am install-man install-man3 \ - install-strip installcheck installcheck-am installdirs \ - maintainer-clean maintainer-clean-generic mostlyclean \ - mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ - uninstall uninstall-am uninstall-info-am uninstall-man \ + cscopelist-am ctags-am distclean distclean-generic \ + distclean-libtool distdir dvi dvi-am html html-am info info-am \ + install install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-man3 install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-generic \ + mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \ + ps ps-am tags-am uninstall uninstall-am uninstall-man \ uninstall-man3 @@ -534,6 +679,7 @@ pdf: $(PDFPAGES) ps2pdf $$foo.ps $@; \ rm $$foo.ps; \ echo "converted $< to $@") + # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index 75a370367..d8a3f9fcf 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -37,8 +37,15 @@ This will effectively close all connections this handle has used and possibly has kept open until now. Don't call this function if you intend to transfer more files. -Any uses of the \fBhandle\fP after this function has been called are -illegal. This kills the handle and all memory associated with it! +Occasionally you may get your progress callback or header callback called from +within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using +\fIcurl_easy_setopt(3)\fP). Like if libcurl decides to shut down the +connection and the protocol is of a kind that requires a command/response +sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP. + +Any uses of the \fBhandle\fP after this function has been called and have +returned, are illegal. This kills the handle and all memory associated with +it! With libcurl versions prior to 7.17.: when you've called this, you can safely remove all the strings you've previously told libcurl to use, as it won't use diff --git a/docs/libcurl/curl_easy_cleanup.html b/docs/libcurl/curl_easy_cleanup.html index bc113e660..2ea921d88 100644 --- a/docs/libcurl/curl_easy_cleanup.html +++ b/docs/libcurl/curl_easy_cleanup.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_cleanup man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -50,7 +52,8 @@ p.roffit { <p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> <p class="level0">This function must be the last function to call for an easy session. It is the opposite of the <a class="emphasis" href="./curl_easy_init.html">curl_easy_init(3)</a> function and must be called with the same <span Class="emphasis">handle</span> as input that the curl_easy_init call returned. <p class="level0">This will effectively close all connections this handle has used and possibly has kept open until now. Don't call this function if you intend to transfer more files. -<p class="level0">Any uses of the <span Class="bold">handle</span> after this function has been called are illegal. This kills the handle and all memory associated with it! +<p class="level0">Occasionally you may get your progress callback or header callback called from within <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a> (if previously set for the handle using <a class="emphasis" href="./curl_easy_setopt.html">curl_easy_setopt(3)</a>). Like if libcurl decides to shut down the connection and the protocol is of a kind that requires a command/response sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP. +<p class="level0">Any uses of the <span Class="bold">handle</span> after this function has been called and have returned, are illegal. This kills the handle and all memory associated with it! <p class="level0">With libcurl versions prior to 7.17.: when you've called this, you can safely remove all the strings you've previously told libcurl to use, as it won't use them anymore now. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">None <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_easy_init.html">curl_easy_init (3)</a> <span Class="manpage"> </span> diff --git a/docs/libcurl/curl_easy_cleanup.pdf b/docs/libcurl/curl_easy_cleanup.pdf Binary files differindex 76a030625..cf588e5e2 100644 --- a/docs/libcurl/curl_easy_cleanup.pdf +++ b/docs/libcurl/curl_easy_cleanup.pdf diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3 index 3fae30e6a..e53ced48b 100644 --- a/docs/libcurl/curl_easy_duphandle.3 +++ b/docs/libcurl/curl_easy_duphandle.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_duphandle 3 "18 September 2001" "libcurl 7.9" "libcurl Manual" .SH NAME curl_easy_duphandle - Clone a libcurl session handle diff --git a/docs/libcurl/curl_easy_duphandle.html b/docs/libcurl/curl_easy_duphandle.html index d072ded22..f84f0d375 100644 --- a/docs/libcurl/curl_easy_duphandle.html +++ b/docs/libcurl/curl_easy_duphandle.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_duphandle man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_easy_duphandle.pdf b/docs/libcurl/curl_easy_duphandle.pdf Binary files differindex b8fcc8b7b..864fedf05 100644 --- a/docs/libcurl/curl_easy_duphandle.pdf +++ b/docs/libcurl/curl_easy_duphandle.pdf diff --git a/docs/libcurl/curl_easy_escape.3 b/docs/libcurl/curl_easy_escape.3 index 2c09875cb..3a98e6fe8 100644 --- a/docs/libcurl/curl_easy_escape.3 +++ b/docs/libcurl/curl_easy_escape.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -31,8 +31,8 @@ curl_easy_escape - URL encodes the given string .SH DESCRIPTION This function converts the given input string to an URL encoded string and returns that as a new allocated string. All input characters that are not a-z, -A-Z or 0-9 are converted to their "URL escaped" version (%NN where NN is a -two-digit hexadecimal number). +A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version +(%NN where NN is a two-digit hexadecimal number). If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on the input \fBurl\fP to find out the size. diff --git a/docs/libcurl/curl_easy_escape.html b/docs/libcurl/curl_easy_escape.html index 1ecf46468..64b65dcc7 100644 --- a/docs/libcurl/curl_easy_escape.html +++ b/docs/libcurl/curl_easy_escape.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_escape man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -48,11 +50,11 @@ p.roffit { <p class="level0"><span Class="bold">#include <curl/curl.h></span> <p class="level0"><span Class="bold">char *curl_easy_escape( CURL * curl , char * url , int length );</span> <p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> -<p class="level0">This function converts the given input string to an URL encoded string and returns that as a new allocated string. All input characters that are not a-z, A-Z or 0-9 are converted to their "URL escaped" version (%NN where NN is a two-digit hexadecimal number). +<p class="level0">This function converts the given input string to an URL encoded string and returns that as a new allocated string. All input characters that are not a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version (%NN where NN is a two-digit hexadecimal number). <p class="level0">If the <span Class="bold">length</span> argument is set to 0 (zero), <a class="emphasis" href="./curl_easy_escape.html">curl_easy_escape(3)</a> uses strlen() on the input <span Class="bold">url</span> to find out the size. <p class="level0">You must <a class="emphasis" href="./curl_free.html">curl_free(3)</a> the returned string when you're done with it. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> <p class="level0">Added in 7.15.4 and replaces the old <a class="emphasis" href="./curl_escape.html">curl_escape(3)</a> function. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">A pointer to a zero terminated string or NULL if it failed. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> -<p class="level0"><a class="manpage" href="./curl_easy_unescape.html">curl_easy_unescape (3)</a> <a class="manpage" href="./curl_free.html"> curl_free (3)</a> <span Class="manpage"> RFC 2396</span> <p class="roffit"> +<p class="level0"><a class="manpage" href="./curl_easy_unescape.html">curl_easy_unescape (3)</a> <a class="manpage" href="./curl_free.html"> curl_free (3)</a> <span Class="manpage"> <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a></span> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/libcurl/curl_easy_escape.pdf b/docs/libcurl/curl_easy_escape.pdf Binary files differindex 0f44f2240..cf281c873 100644 --- a/docs/libcurl/curl_easy_escape.pdf +++ b/docs/libcurl/curl_easy_escape.pdf diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 9f298ed71..62d8ae482 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -44,11 +44,13 @@ The following information can be extracted: .IP CURLINFO_EFFECTIVE_URL Pass a pointer to a char pointer to receive the last used effective URL. .IP CURLINFO_RESPONSE_CODE -Pass a pointer to a long to receive the last received HTTP or FTP code. This -option was known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. This -will be zero if no server response code has been received. Note that a proxy's -CONNECT response should be read with \fICURLINFO_HTTP_CONNECTCODE\fP and not -this. +Pass a pointer to a long to receive the last received HTTP, FTP or SMTP +response code. This option was previously known as CURLINFO_HTTP_CODE in +libcurl 7.10.7 and earlier. The value will be zero if no server response code +has been received. Note that a proxy's CONNECT response should be read with +\fICURLINFO_HTTP_CONNECTCODE\fP and not this. + +Support for SMTP responses added in 7.25.0. .IP CURLINFO_HTTP_CONNECTCODE Pass a pointer to a long to receive the last received proxy response code to a CONNECT request. @@ -80,12 +82,13 @@ waits in line for the pipeline and more. (Added in 7.19.0) Pass a pointer to a double to receive the time, in seconds, it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular -protocol(s) involved. +protocol(s) involved. It does \fInot\fP involve the sending of the protocol- +specific request that triggers a transfer. .IP CURLINFO_STARTTRANSFER_TIME Pass a pointer to a double to receive the time, in seconds, it took from the -start until the first byte is just about to be transferred. This includes -CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate -the result. +start until the first byte is received by libcurl. This includes +CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate the +result. .IP CURLINFO_REDIRECT_TIME Pass a pointer to a double to receive the total time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer @@ -159,7 +162,7 @@ method(s) available for your proxy authentication. (Added in 7.10.8) .IP CURLINFO_OS_ERRNO Pass a pointer to a long to receive the errno variable from a connect failure. Note that the value is only set on failure, it is not reset upon a -successfull operation. (Added in 7.12.2) +successful operation. (Added in 7.12.2) .IP CURLINFO_NUM_CONNECTS Pass a pointer to a long to receive how many new connections libcurl had to create to achieve the previous transfer (only the successful connects are @@ -206,6 +209,8 @@ Pass a pointer to a char pointer to receive a pointer to a string holding the path of the entry path. That is the initial path libcurl ended up in when logging on to the remote FTP server. This stores a NULL as pointer if something is wrong. (Added in 7.15.4) + +Also works for SFTP since 7.21.4 .IP CURLINFO_CERTINFO Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to struct that holds a number of linked lists with info about the certificate @@ -227,7 +232,7 @@ Pass a pointer to a char pointer to receive a pointer to a string holding the most recent RTSP Session ID. Applications wishing to resume an RTSP session on another connection should -retreive this info before closing the active connection. +retrieve this info before closing the active connection. .IP CURLINFO_RTSP_CLIENT_CSEQ Pass a pointer to a long to receive the next CSeq that will be used by the application. @@ -239,7 +244,7 @@ by the application. unimplemented).\fP Applications wishing to resume an RTSP session on another connection should -retreive this info before closing the active connection. +retrieve this info before closing the active connection. .IP CURLINFO_RTSP_CSEQ_RECV Pass a pointer to a long to receive the most recently received CSeq from the server. If your application encounters a \fICURLE_RTSP_CSEQ_ERROR\fP then you @@ -273,7 +278,7 @@ file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. .IP STARTTRANSFER \fICURLINFO_STARTTRANSFER_TIME\fP. The time it took from the start until the -first byte is just about to be transferred. +first byte is received by libcurl. .IP TOTAL \fICURLINFO_TOTAL_TIME\fP. Total time of the previous request. .IP REDIRECT diff --git a/docs/libcurl/curl_easy_getinfo.html b/docs/libcurl/curl_easy_getinfo.html index 5b949e952..6a9967dda 100644 --- a/docs/libcurl/curl_easy_getinfo.html +++ b/docs/libcurl/curl_easy_getinfo.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_getinfo man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -54,7 +56,8 @@ p.roffit { <p class="level0"><a name="CURLINFOEFFECTIVEURL"></a><span class="nroffip">CURLINFO_EFFECTIVE_URL</span> <p class="level1">Pass a pointer to a char pointer to receive the last used effective URL. <p class="level0"><a name="CURLINFORESPONSECODE"></a><span class="nroffip">CURLINFO_RESPONSE_CODE</span> -<p class="level1">Pass a pointer to a long to receive the last received HTTP or FTP code. This option was known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. This will be zero if no server response code has been received. Note that a proxy's CONNECT response should be read with <a class="emphasis" href="#CURLINFOHTTPCONNECTCODE">CURLINFO_HTTP_CONNECTCODE</a> and not this. +<p class="level1">Pass a pointer to a long to receive the last received HTTP, FTP or SMTP response code. This option was previously known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. The value will be zero if no server response code has been received. Note that a proxy's CONNECT response should be read with <a class="emphasis" href="#CURLINFOHTTPCONNECTCODE">CURLINFO_HTTP_CONNECTCODE</a> and not this. +<p class="level1">Support for SMTP responses added in 7.25.0. <p class="level0"><a name="CURLINFOHTTPCONNECTCODE"></a><span class="nroffip">CURLINFO_HTTP_CONNECTCODE</span> <p class="level1">Pass a pointer to a long to receive the last received proxy response code to a CONNECT request. <p class="level0"><a name="CURLINFOFILETIME"></a><span class="nroffip">CURLINFO_FILETIME</span> @@ -68,9 +71,9 @@ p.roffit { <p class="level0"><a name="CURLINFOAPPCONNECTTIME"></a><span class="nroffip">CURLINFO_APPCONNECT_TIME</span> <p class="level1">Pass a pointer to a double to receive the time, in seconds, it took from the start until the SSL/SSH connect/handshake to the remote host was completed. This time is most often very near to the PRETRANSFER time, except for cases such as HTTP pippelining where the pretransfer time can be delayed due to waits in line for the pipeline and more. (Added in 7.19.0) <p class="level0"><a name="CURLINFOPRETRANSFERTIME"></a><span class="nroffip">CURLINFO_PRETRANSFER_TIME</span> -<p class="level1">Pass a pointer to a double to receive the time, in seconds, it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. +<p class="level1">Pass a pointer to a double to receive the time, in seconds, it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. It does <span Class="emphasis">not</span> involve the sending of the protocol- specific request that triggers a transfer. <p class="level0"><a name="CURLINFOSTARTTRANSFERTIME"></a><span class="nroffip">CURLINFO_STARTTRANSFER_TIME</span> -<p class="level1">Pass a pointer to a double to receive the time, in seconds, it took from the start until the first byte is just about to be transferred. This includes CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate the result. +<p class="level1">Pass a pointer to a double to receive the time, in seconds, it took from the start until the first byte is received by libcurl. This includes CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate the result. <p class="level0"><a name="CURLINFOREDIRECTTIME"></a><span class="nroffip">CURLINFO_REDIRECT_TIME</span> <p class="level1">Pass a pointer to a double to receive the total time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. CURLINFO_REDIRECT_TIME contains the complete execution time for multiple redirections. (Added in 7.9.7) <p class="level0"><a name="CURLINFOREDIRECTCOUNT"></a><span class="nroffip">CURLINFO_REDIRECT_COUNT</span> @@ -106,7 +109,7 @@ p.roffit { <p class="level0"><a name="CURLINFOPROXYAUTHAVAIL"></a><span class="nroffip">CURLINFO_PROXYAUTH_AVAIL</span> <p class="level1">Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available for your proxy authentication. (Added in 7.10.8) <p class="level0"><a name="CURLINFOOSERRNO"></a><span class="nroffip">CURLINFO_OS_ERRNO</span> -<p class="level1">Pass a pointer to a long to receive the errno variable from a connect failure. Note that the value is only set on failure, it is not reset upon a successfull operation. (Added in 7.12.2) +<p class="level1">Pass a pointer to a long to receive the errno variable from a connect failure. Note that the value is only set on failure, it is not reset upon a successful operation. (Added in 7.12.2) <p class="level0"><a name="CURLINFONUMCONNECTS"></a><span class="nroffip">CURLINFO_NUM_CONNECTS</span> <p class="level1">Pass a pointer to a long to receive how many new connections libcurl had to create to achieve the previous transfer (only the successful connects are counted). Combined with <a class="emphasis" href="#CURLINFOREDIRECTCOUNT">CURLINFO_REDIRECT_COUNT</a> you are able to know how many times libcurl successfully reused existing connection(s) or not. See the Connection Options of <a class="emphasis" href="./curl_easy_setopt.html">curl_easy_setopt(3)</a> to see how libcurl tries to make persistent connections to save time. (Added in 7.12.3) <p class="level0"><a name="CURLINFOPRIMARYIP"></a><span class="nroffip">CURLINFO_PRIMARY_IP</span> @@ -124,19 +127,20 @@ p.roffit { <p class="level1">NOTE: this API is not really working on win64, since the SOCKET type on win64 is 64 bit large while its 'long' is only 32 bits. <p class="level0"><a name="CURLINFOFTPENTRYPATH"></a><span class="nroffip">CURLINFO_FTP_ENTRY_PATH</span> <p class="level1">Pass a pointer to a char pointer to receive a pointer to a string holding the path of the entry path. That is the initial path libcurl ended up in when logging on to the remote FTP server. This stores a NULL as pointer if something is wrong. (Added in 7.15.4) +<p class="level1">Also works for SFTP since 7.21.4 <p class="level0"><a name="CURLINFOCERTINFO"></a><span class="nroffip">CURLINFO_CERTINFO</span> <p class="level1">Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to struct that holds a number of linked lists with info about the certificate chain, assuming you had CURLOPT_CERTINFO enabled when the previous request was done. The struct reports how many certs it found and then you can extract info for each of those certs by following the linked lists. The info chain is provided in a series of data in the format "name:content" where the content is for the specific named data. See also the certinfo.c example. NOTE: this option is only available in libcurl built with OpenSSL support. (Added in 7.19.1) <p class="level0"><a name="CURLINFOCONDITIONUNMET"></a><span class="nroffip">CURLINFO_CONDITION_UNMET</span> <p class="level1">Pass a pointer to a long to receive the number 1 if the condition provided in the previous request didn't match (see <span Class="emphasis">CURLOPT_TIMECONDITION</span>). Alas, if this returns a 1 you know that the reason you didn't get data in return is because it didn't fulfill the condition. The long ths argument points to will get a zero stored if the condition instead was met. (Added in 7.19.4) <p class="level0"><a name="CURLINFORTSPSESSIONID"></a><span class="nroffip">CURLINFO_RTSP_SESSION_ID</span> <p class="level1">Pass a pointer to a char pointer to receive a pointer to a string holding the most recent RTSP Session ID. -<p class="level1">Applications wishing to resume an RTSP session on another connection should retreive this info before closing the active connection. +<p class="level1">Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection. <p class="level0"><a name="CURLINFORTSPCLIENTCSEQ"></a><span class="nroffip">CURLINFO_RTSP_CLIENT_CSEQ</span> <p class="level1">Pass a pointer to a long to receive the next CSeq that will be used by the application. <p class="level0"><a name="CURLINFORTSPSERVERCSEQ"></a><span class="nroffip">CURLINFO_RTSP_SERVER_CSEQ</span> <p class="level1">Pass a pointer to a long to receive the next server CSeq that will be expected by the application. <p class="level1"><span class="emphasis">(NOTE: listening for server initiated requests is currently unimplemented).</span> -<p class="level1">Applications wishing to resume an RTSP session on another connection should retreive this info before closing the active connection. +<p class="level1">Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection. <p class="level0"><a name="CURLINFORTSPCSEQRECV"></a><span class="nroffip">CURLINFO_RTSP_CSEQ_RECV</span> <p class="level1">Pass a pointer to a long to receive the most recently received CSeq from the server. If your application encounters a <span Class="emphasis">CURLE_RTSP_CSEQ_ERROR</span> then you may wish to troubleshoot and/or fix the CSeq mismatch by peeking at this value. <a name="TIMES"></a><h2 class="nroffsh">TIMES</h2> <p class="level0"><pre> @@ -162,7 +166,7 @@ p.roffit { <p class="level0"><a name="PRETRANSFER"></a><span class="nroffip">PRETRANSFER</span> <p class="level1"><a class="emphasis" href="#CURLINFOPRETRANSFERTIME">CURLINFO_PRETRANSFER_TIME</a>. The time it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. <p class="level0"><a name="STARTTRANSFER"></a><span class="nroffip">STARTTRANSFER</span> -<p class="level1"><a class="emphasis" href="#CURLINFOSTARTTRANSFERTIME">CURLINFO_STARTTRANSFER_TIME</a>. The time it took from the start until the first byte is just about to be transferred. +<p class="level1"><a class="emphasis" href="#CURLINFOSTARTTRANSFERTIME">CURLINFO_STARTTRANSFER_TIME</a>. The time it took from the start until the first byte is received by libcurl. <p class="level0"><a name="TOTAL"></a><span class="nroffip">TOTAL</span> <p class="level1"><a class="emphasis" href="#CURLINFOTOTALTIME">CURLINFO_TOTAL_TIME</a>. Total time of the previous request. <p class="level0"><a name="REDIRECT"></a><span class="nroffip">REDIRECT</span> diff --git a/docs/libcurl/curl_easy_getinfo.pdf b/docs/libcurl/curl_easy_getinfo.pdf Binary files differindex 53e77f864..d5d43b672 100644 --- a/docs/libcurl/curl_easy_getinfo.pdf +++ b/docs/libcurl/curl_easy_getinfo.pdf diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 478db5c03..837ba32a5 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_init 3 "4 March 2002" "libcurl 7.8.1" "libcurl Manual" .SH NAME curl_easy_init - Start a libcurl easy session diff --git a/docs/libcurl/curl_easy_init.html b/docs/libcurl/curl_easy_init.html index 7e63cbdf1..2f547dceb 100644 --- a/docs/libcurl/curl_easy_init.html +++ b/docs/libcurl/curl_easy_init.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_init man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_easy_init.pdf b/docs/libcurl/curl_easy_init.pdf Binary files differindex c7bd250d6..18cdc7cf8 100644 --- a/docs/libcurl/curl_easy_init.pdf +++ b/docs/libcurl/curl_easy_init.pdf diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3 index 4d16ecffe..7debfd842 100644 --- a/docs/libcurl/curl_easy_pause.3 +++ b/docs/libcurl/curl_easy_pause.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_pause 3 "17 Dec 2007" "libcurl 7.18.0" "libcurl Manual" .SH NAME curl_easy_pause - pause and unpause a connection @@ -48,6 +68,18 @@ code means something wrong occurred after the new state was set. See the .SH AVAILABILITY This function was added in libcurl 7.18.0. Before this version, there was no explicit support for pausing transfers. +.SH "USAGE WITH THE MULTI-SOCKET INTERFACE" +Before libcurl 7.32.0, when a specific handle was unpaused with this function, +there was no particular forced rechecking or similar of the socket's state, +which made the continuation of the transfer get delayed until next +multi-socket call invoke or even longer. Alternatively, the user could +forcibly call for example curl_multi_socket_all(3) - with a rather hefty +performance penalty. + +Starting in libcurl 7.32.0, unpausing a transfer will schedule a timeout +trigger for that handle 1 millisecond into the future, so that a +curl_multi_socket_action( ... CURL_SOCKET_TIMEOUT) can be used immediately +afterwards to get the transfer going again as desired. .SH "MEMORY USE" When pausing a read by returning the magic return code from a write callback, the read data is already in libcurl's internal buffers so it'll have to keep diff --git a/docs/libcurl/curl_easy_pause.html b/docs/libcurl/curl_easy_pause.html index a82a77bd9..866a84851 100644 --- a/docs/libcurl/curl_easy_pause.html +++ b/docs/libcurl/curl_easy_pause.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_pause man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -63,7 +65,9 @@ p.roffit { <p class="level0"><a name="CURLPAUSECONT"></a><span class="nroffip">CURLPAUSE_CONT</span> <p class="level1">Convenience define that unpauses both directions <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">CURLE_OK (zero) means that the option was set properly, and a non-zero return code means something wrong occurred after the new state was set. See the <span Class="emphasis">libcurl-errors(3)</span> man page for the full list with descriptions. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> -<p class="level0">This function was added in libcurl 7.18.0. Before this version, there was no explicit support for pausing transfers. <a name="MEMORY"></a><h2 class="nroffsh">MEMORY USE</h2> +<p class="level0">This function was added in libcurl 7.18.0. Before this version, there was no explicit support for pausing transfers. <a name="USAGE"></a><h2 class="nroffsh">USAGE WITH THE MULTI-SOCKET INTERFACE</h2> +<p class="level0">Before libcurl 7.32.0, when a specific handle was unpaused with this function, there was no particular forced rechecking or similar of the socket's state, which made the continuation of the transfer get delayed until next multi-socket call invoke or even longer. Alternatively, the user could forcibly call for example curl_multi_socket_all(3) - with a rather hefty performance penalty. +<p class="level0">Starting in libcurl 7.32.0, unpausing a transfer will schedule a timeout trigger for that handle 1 millisecond into the future, so that a curl_multi_socket_action( ... CURL_SOCKET_TIMEOUT) can be used immediately afterwards to get the transfer going again as desired. <a name="MEMORY"></a><h2 class="nroffsh">MEMORY USE</h2> <p class="level0">When pausing a read by returning the magic return code from a write callback, the read data is already in libcurl's internal buffers so it'll have to keep it in an allocated buffer until the reading is again unpaused using this function. <p class="level0">If the downloaded data is compressed and is asked to get uncompressed automatically on download, libcurl will continue to uncompress the entire downloaded chunk and it will cache the data uncompressed. This has the side- effect that if you download something that is compressed a lot, it can result in a very large data amount needing to be allocated to save the data during the pause. This said, you should probably consider not using paused reading if you allow libcurl to uncompress data automatically. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_easy_cleanup.html">curl_easy_cleanup (3)</a> <a class="manpage" href="./curl_easy_reset.html"> curl_easy_reset (3)</a> <p class="roffit"> diff --git a/docs/libcurl/curl_easy_pause.pdf b/docs/libcurl/curl_easy_pause.pdf Binary files differindex 383834c36..86196a350 100644 --- a/docs/libcurl/curl_easy_pause.pdf +++ b/docs/libcurl/curl_easy_pause.pdf diff --git a/docs/libcurl/curl_easy_perform.3 b/docs/libcurl/curl_easy_perform.3 index 1ed006b0b..8f8517f22 100644 --- a/docs/libcurl/curl_easy_perform.3 +++ b/docs/libcurl/curl_easy_perform.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_perform 3 "5 Mar 2001" "libcurl 7.7" "libcurl Manual" .SH NAME curl_easy_perform - Perform a file transfer diff --git a/docs/libcurl/curl_easy_perform.html b/docs/libcurl/curl_easy_perform.html index 8654fea60..f50024b43 100644 --- a/docs/libcurl/curl_easy_perform.html +++ b/docs/libcurl/curl_easy_perform.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_perform man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_easy_perform.pdf b/docs/libcurl/curl_easy_perform.pdf Binary files differindex 537da2d67..72e34cb16 100644 --- a/docs/libcurl/curl_easy_perform.pdf +++ b/docs/libcurl/curl_easy_perform.pdf diff --git a/docs/libcurl/curl_easy_recv.3 b/docs/libcurl/curl_easy_recv.3 index 1ede58944..0de6037ba 100644 --- a/docs/libcurl/curl_easy_recv.3 +++ b/docs/libcurl/curl_easy_recv.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -59,8 +59,13 @@ On success, returns \fBCURLE_OK\fP, stores the received data into On failure, returns the appropriate error code. -If there is no data to read, the function returns \fBCURLE_AGAIN\fP. Use -your operating system facilities to wait until the data is ready, and retry. +If there is no data to read, the function returns \fBCURLE_AGAIN\fP. Use your +operating system facilities to wait until the data is ready, and retry. + +Reading exactly 0 bytes would indicate a closed connection. + +If there's no socket available to use from the previous transfer, this function +returns CURLE_UNSUPPORTED_PROTOCOL. .SH EXAMPLE See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_easy_recv.html b/docs/libcurl/curl_easy_recv.html index 51f77f9e4..48ba906c1 100644 --- a/docs/libcurl/curl_easy_recv.html +++ b/docs/libcurl/curl_easy_recv.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_recv man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -55,7 +57,9 @@ p.roffit { <p class="level0">Added in 7.18.2. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">On success, returns <span Class="bold">CURLE_OK</span>, stores the received data into <span Class="bold">buffer</span>, and the number of bytes it actually read into <span Class="bold">*n</span>. <p class="level0">On failure, returns the appropriate error code. -<p class="level0">If there is no data to read, the function returns <span Class="bold">CURLE_AGAIN</span>. Use your operating system facilities to wait until the data is ready, and retry. <a name="EXAMPLE"></a><h2 class="nroffsh">EXAMPLE</h2> +<p class="level0">If there is no data to read, the function returns <span Class="bold">CURLE_AGAIN</span>. Use your operating system facilities to wait until the data is ready, and retry. +<p class="level0">Reading exactly 0 bytes would indicate a closed connection. +<p class="level0">If there's no socket available to use from the previous transfer, this function returns CURLE_UNSUPPORTED_PROTOCOL. <a name="EXAMPLE"></a><h2 class="nroffsh">EXAMPLE</h2> <p class="level0">See <span Class="bold">sendrecv.c</span> in <span Class="bold">docs/examples</span> directory for usage example. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_easy_setopt.html">curl_easy_setopt (3)</a> <a class="manpage" href="./curl_easy_perform.html"> curl_easy_perform (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_easy_getinfo.html">curl_easy_getinfo (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_easy_send.html">curl_easy_send (3) </a> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. diff --git a/docs/libcurl/curl_easy_recv.pdf b/docs/libcurl/curl_easy_recv.pdf Binary files differindex 2a968c5b2..521cd2ab3 100644 --- a/docs/libcurl/curl_easy_recv.pdf +++ b/docs/libcurl/curl_easy_recv.pdf diff --git a/docs/libcurl/curl_easy_reset.3 b/docs/libcurl/curl_easy_reset.3 index 4652f7e60..592d3ed5c 100644 --- a/docs/libcurl/curl_easy_reset.3 +++ b/docs/libcurl/curl_easy_reset.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_reset 3 "31 July 2004" "libcurl 7.12.1" "libcurl Manual" .SH NAME curl_easy_reset - reset all options of a libcurl session handle diff --git a/docs/libcurl/curl_easy_reset.html b/docs/libcurl/curl_easy_reset.html index daed7426c..a7dc70c84 100644 --- a/docs/libcurl/curl_easy_reset.html +++ b/docs/libcurl/curl_easy_reset.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_reset man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_easy_reset.pdf b/docs/libcurl/curl_easy_reset.pdf Binary files differindex 0be6286e8..ba8e1714d 100644 --- a/docs/libcurl/curl_easy_reset.pdf +++ b/docs/libcurl/curl_easy_reset.pdf diff --git a/docs/libcurl/curl_easy_send.3 b/docs/libcurl/curl_easy_send.3 index 17c4c1f54..777735f92 100644 --- a/docs/libcurl/curl_easy_send.3 +++ b/docs/libcurl/curl_easy_send.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -57,6 +57,9 @@ sent into \fB*n\fP. Note that this may very well be less than the amount you wanted to send. On failure, returns the appropriate error code. + +If there's no socket available to use from the previous transfer, this function +returns CURLE_UNSUPPORTED_PROTOCOL. .SH EXAMPLE See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_easy_send.html b/docs/libcurl/curl_easy_send.html index b24a60111..4a85a2744 100644 --- a/docs/libcurl/curl_easy_send.html +++ b/docs/libcurl/curl_easy_send.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_send man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -54,7 +56,8 @@ p.roffit { <p class="level0">You must ensure that the socket is writable before calling <a class="emphasis" href="./curl_easy_send.html">curl_easy_send(3)</a>, otherwise the call will return <span Class="bold">CURLE_AGAIN</span> - the socket is used in non-blocking mode internally. Use <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a> with <span Class="bold">CURLINFO_LASTSOCKET</span> to obtain the socket; use your operating system facilities like <span Class="emphasis">select(2)</span> to check if it can be written to. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> <p class="level0">Added in 7.18.2. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">On success, returns <span Class="bold">CURLE_OK</span> and stores the number of bytes actually sent into <span Class="bold">*n</span>. Note that this may very well be less than the amount you wanted to send. -<p class="level0">On failure, returns the appropriate error code. <a name="EXAMPLE"></a><h2 class="nroffsh">EXAMPLE</h2> +<p class="level0">On failure, returns the appropriate error code. +<p class="level0">If there's no socket available to use from the previous transfer, this function returns CURLE_UNSUPPORTED_PROTOCOL. <a name="EXAMPLE"></a><h2 class="nroffsh">EXAMPLE</h2> <p class="level0">See <span Class="bold">sendrecv.c</span> in <span Class="bold">docs/examples</span> directory for usage example. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_easy_setopt.html">curl_easy_setopt (3)</a> <a class="manpage" href="./curl_easy_perform.html"> curl_easy_perform (3)</a> <a class="manpage" href="./curl_easy_getinfo.html"> curl_easy_getinfo (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_easy_recv.html">curl_easy_recv (3) </a> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. diff --git a/docs/libcurl/curl_easy_send.pdf b/docs/libcurl/curl_easy_send.pdf Binary files differindex a6afb67a9..bb73bfcaf 100644 --- a/docs/libcurl/curl_easy_send.pdf +++ b/docs/libcurl/curl_easy_send.pdf diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3d76b6616..bebf8c08d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -58,7 +58,8 @@ The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or Set the parameter to 1 to get the library to display a lot of verbose information about its operations. Very useful for libcurl and/or protocol debugging and understanding. The verbose information will be sent to stderr, -or the stream set with \fICURLOPT_STDERR\fP. +or the stream set with \fICURLOPT_STDERR\fP. The default value for this +parameter is 0. You hardly ever want this set in production use, you will almost always want this when you debug/report problems. Another neat option for debugging is the @@ -66,10 +67,11 @@ this when you debug/report problems. Another neat option for debugging is the .IP CURLOPT_HEADER A parameter set to 1 tells the library to include the header in the body output. This is only relevant for protocols that actually have headers -preceding the data (like HTTP). +preceding the data (like HTTP). The default value for this parameter is 0. .IP CURLOPT_NOPROGRESS -A parameter set to 1 tells the library to shut off the built-in progress meter -completely. +Pass a long. If set to 1, it tells the library to shut off the progress meter +completely. It will also prevent the \fICURLOPT_PROGRESSFUNCTION\fP from +getting called. The default value for this parameter is 1. Future versions of libcurl are likely to not have any built-in progress meter at all. @@ -78,6 +80,7 @@ Pass a long. If it is 1, libcurl will not use any functions that install signal handlers or any functions that cause signals to be sent to the process. This option is mainly here to allow multi-threaded unix applications to still set/use all timeout options etc, without risking getting signals. +The default value for this parameter is 0. (Added in 7.10) If this option is set and libcurl has been built with the standard name @@ -90,7 +93,9 @@ SIGPIPE signals, which otherwise are sent by the system when trying to send data to a socket which is closed in the other end. libcurl makes an effort to never cause such SIGPIPEs to trigger, but some operating systems have no way to avoid them and even on those that have there are some corner cases when -they may still happen, contrary to our desire. +they may still happen, contrary to our desire. In addition, using +\fICURLAUTH_NTLM_WB\fP authentication could cause a SIGCHLD signal to be +raised. .IP CURLOPT_WILDCARDMATCH Set this option to 1 if you want to transfer multiple files according to a file name pattern. The pattern can be specified as part of the @@ -105,18 +110,18 @@ This feature is only supported by the FTP download for now. A brief introduction of its syntax follows: .RS -.IP "\fB*\fP - ASTERISK" +.IP "* - ASTERISK" \&ftp://example.com/some/path/\fB*.txt\fP (for all txt's from the root directory) .RE .RS -.IP "\fB?\fP - QUESTION MARK" +.IP "? - QUESTION MARK" Question mark matches any (exactly one) character. \&ftp://example.com/some/path/\fBphoto?.jpeg\fP .RE .RS -.IP "\fB[\fP - BRACKET EXPRESSION" +.IP "[ - BRACKET EXPRESSION" The left bracket opens a bracket expression. The question mark and asterisk have no special meaning in a bracket expression. Each bracket expression ends by the right bracket and matches exactly one character. Some examples follow: @@ -144,10 +149,10 @@ Using the rules above, a file name pattern can be constructed: (This was added in 7.21.0) .SH CALLBACK OPTIONS .IP CURLOPT_WRITEFUNCTION -Function pointer that should match the following prototype: \fBsize_t -function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP This -function gets called by libcurl as soon as there is data received that needs -to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP +Pass a pointer to a function that matches the following prototype: +\fBsize_t function( char *ptr, size_t size, size_t nmemb, void *userdata);\fP +This function gets called by libcurl as soon as there is data received that +needs to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied with \fInmemb\fP, it will not be zero terminated. Return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the @@ -168,13 +173,18 @@ Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA\fP option. The callback function will be passed as much data as possible in all invokes, but you cannot possibly make any assumptions. It may be one byte, it may be -thousands. The maximum amount of data that can be passed to the write callback -is defined in the curl.h header file: CURL_MAX_WRITE_SIZE. +thousands. The maximum amount of body data that can be passed to the write +callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE (the usual +default is 16K). If you however have \fICURLOPT_HEADER\fP set, which sends +header data to the write callback, you can get up to +\fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually +means 100K. .IP CURLOPT_WRITEDATA Data pointer to pass to the file write function. If you use the \fICURLOPT_WRITEFUNCTION\fP option, this is the pointer you'll get as -input. If you don't use a callback, you must pass a 'FILE *' as libcurl will -pass this to fwrite() when writing data. +input. If you don't use a callback, you must pass a 'FILE *' (cast +to 'void *') as libcurl will pass this to fwrite() when writing data. +By default, the value of this parameter is unspecified. The internal \fICURLOPT_WRITEFUNCTION\fP will write the data to the FILE * given with this option, or to stdout if this option hasn't been set. @@ -186,11 +196,11 @@ crashes. This option is also known with the older name \fICURLOPT_FILE\fP, the name \fICURLOPT_WRITEDATA\fP was introduced in 7.9.7. .IP CURLOPT_READFUNCTION -Function pointer that should match the following prototype: \fBsize_t -function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP This -function gets called by libcurl as soon as it needs to read data in order to -send it to the peer. The data area pointed at by the pointer \fIptr\fP may be -filled with at most \fIsize\fP multiplied with \fInmemb\fP number of +Pass a pointer to a function that matches the following prototype: +\fBsize_t function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP +This function gets called by libcurl as soon as it needs to read data in order +to send it to the peer. The data area pointed at by the pointer \fIptr\fP may +be filled with at most \fIsize\fP multiplied with \fInmemb\fP number of bytes. Your function must return the actual number of bytes that you stored in that memory area. Returning 0 will signal end-of-file to the library and cause it to stop the current transfer. @@ -208,6 +218,10 @@ From 7.18.0, the function can return CURL_READFUNC_PAUSE which then will cause reading from this connection to become paused. See \fIcurl_easy_pause(3)\fP for further details. +\fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data +that the callback wants, or it will be considered the final packet by the +server end and the transfer will end there. + If you set this callback pointer to NULL, or don't set it at all, the default internal read function will be used. It is doing an fread() on the FILE * userdata set with \fICURLOPT_READDATA\fP. @@ -215,7 +229,7 @@ userdata set with \fICURLOPT_READDATA\fP. Data pointer to pass to the file read function. If you use the \fICURLOPT_READFUNCTION\fP option, this is the pointer you'll get as input. If you don't specify a read callback but instead rely on the default internal -read function, this data must be a valid readable FILE *. +read function, this data must be a valid readable FILE * (cast to 'void *'). If you're using libcurl as a win32 DLL, you MUST use a \fICURLOPT_READFUNCTION\fP if you set this option. @@ -223,21 +237,23 @@ If you're using libcurl as a win32 DLL, you MUST use a This option was also known by the older name \fICURLOPT_INFILE\fP, the name \fICURLOPT_READDATA\fP was introduced in 7.9.7. .IP CURLOPT_IOCTLFUNCTION -Function pointer that should match the \fIcurl_ioctl_callback\fP prototype -found in \fI<curl/curl.h>\fP. This function gets called by libcurl when -something special I/O-related needs to be done that the library can't do by -itself. For now, rewinding the read data stream is the only action it can -request. The rewinding of the read data stream may be necessary when doing a -HTTP PUT or POST with a multi-pass authentication method. (Option added in -7.12.3). - -Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking! +Pass a pointer to a function that matches the following prototype: +\fBcurlioerr function(CURL *handle, int cmd, void *clientp);\fP. This function +gets called by libcurl when something special I/O-related needs to be done +that the library can't do by itself. For now, rewinding the read data stream +is the only action it can request. The rewinding of the read data stream may +be necessary when doing a HTTP PUT or POST with a multi-pass authentication +method. By default, this parameter is set to NULL. (Option added in 7.12.3). + +Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking! If +\fICURLOPT_SEEKFUNCTION\fP is set, this parameter will be ignored when seeking. .IP CURLOPT_IOCTLDATA Pass a pointer that will be untouched by libcurl and passed as the 3rd -argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP. (Option -added in 7.12.3) +argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP. +By default, the value of this parameter is unspecified. (Option added in +7.12.3) .IP CURLOPT_SEEKFUNCTION -Function pointer that should match the following prototype: \fIint +Pass a pointer to a function that matches the following prototype: \fBint function(void *instream, curl_off_t offset, int origin);\fP This function gets called by libcurl to seek to a certain position in the input stream and can be used to fast forward a file in a resumed upload (instead of reading all @@ -251,46 +267,58 @@ success, 1 (CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2 free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar. +By default, this parameter is unset. + If you forward the input arguments directly to "fseek" or "lseek", note that the data type for \fIoffset\fP is not the same as defined for curl_off_t on many systems! (Option added in 7.18.0) .IP CURLOPT_SEEKDATA -Data pointer to pass to the file read function. If you use the +Data pointer to pass to the file seek function. If you use the \fICURLOPT_SEEKFUNCTION\fP option, this is the pointer you'll get as input. If you don't specify a seek callback, NULL is passed. (Option added in 7.18.0) .IP CURLOPT_SOCKOPTFUNCTION -Function pointer that should match the \fIcurl_sockopt_callback\fP prototype -found in \fI<curl/curl.h>\fP. This function gets called by libcurl after the -socket() call but before the connect() call. The callback's \fIpurpose\fP -argument identifies the exact purpose for this particular socket, and -currently only one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the -primary connection (meaning the control connection in the FTP case). Future -versions of libcurl may support more purposes. It passes the newly created -socket descriptor so additional setsockopt() calls can be done at the user's -discretion. Return 0 (zero) from the callback on success. Return 1 from the -callback function to signal an unrecoverable error to the library and it will -close the socket and return \fICURLE_COULDNT_CONNECT\fP. (Option added in -7.15.6.) +Pass a pointer to a function that matches the following prototype: \fBint +function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);\fP. By +default, this parameter is unset. If set, this +function gets called by libcurl after the socket() call but before the +connect() call. The callback's \fIpurpose\fP argument identifies the exact +purpose for this particular socket: + +\fICURLSOCKTYPE_IPCXN\fP for actively created connections or since 7.28.0 +\fICURLSOCKTYPE_ACCEPT\fP for FTP when the connection was setup with PORT/EPSV +(in earlier versions these sockets weren't passed to this callback). + +Future versions of libcurl may support more purposes. It passes the newly +created socket descriptor so additional setsockopt() calls can be done at the +user's discretion. Return 0 (zero) from the callback on success. Return 1 +from the callback function to signal an unrecoverable error to the library and +it will close the socket and return \fICURLE_COULDNT_CONNECT\fP. (Option +added in 7.16.0) + +Added in 7.21.5, the callback function may return +\fICURL_SOCKOPT_ALREADY_CONNECTED\fP, which tells libcurl that the socket is +in fact already connected and then libcurl will not attempt to connect it. .IP CURLOPT_SOCKOPTDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. -(Option added in 7.15.6.) +The default value of this parameter is unspecified. +(Option added in 7.16.0) .IP CURLOPT_OPENSOCKETFUNCTION -Function pointer that should match the \fIcurl_opensocket_callback\fP -prototype found in \fI<curl/curl.h>\fP. This function gets called by libcurl -instead of the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument -identifies the exact purpose for this particular socket, and currently only -one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the primary connection -(meaning the control connection in the FTP case). Future versions of libcurl -may support more purposes. It passes the resolved peer address as a -\fIaddress\fP argument so the callback can modify the address or refuse to -connect at all. The callback function should return the socket or -\fICURL_SOCKET_BAD\fP in case no connection should be established or any error -detected. Any additional \fIsetsockopt(2)\fP calls can be done on the socket -at the user's discretion. \fICURL_SOCKET_BAD\fP return value from the -callback function will signal an unrecoverable error to the library and it -will return \fICURLE_COULDNT_CONNECT\fP. This return code can be used for IP -address blacklisting. The default behavior is: +Pass a pointer to a function that matches the following prototype: +\fBcurl_socket_t function(void *clientp, curlsocktype purpose, struct +curl_sockaddr *address);\fP. This function gets called by libcurl instead of +the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument identifies the +exact purpose for this particular socket: \fICURLSOCKTYPE_IPCXN\fP is for IP +based connections. Future versions of libcurl may support more purposes. It +passes the resolved peer address as a \fIaddress\fP argument so the callback +can modify the address or refuse to connect at all. The callback function +should return the socket or \fICURL_SOCKET_BAD\fP in case no connection could +be established or another error was detected. Any additional +\fIsetsockopt(2)\fP calls can be done on the socket at the user's discretion. +\fICURL_SOCKET_BAD\fP return value from the callback function will signal an +unrecoverable error to the library and it will return +\fICURLE_COULDNT_CONNECT\fP. This return code can be used for IP address +blacklisting. The default behavior is: .nf return socket(addr->family, addr->socktype, addr->protocol); .fi @@ -298,16 +326,50 @@ address blacklisting. The default behavior is: .IP CURLOPT_OPENSOCKETDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP. +The default value of this parameter is unspecified. (Option added in 7.17.1.) +.IP CURLOPT_CLOSESOCKETFUNCTION +Pass a pointer to a function that matches the following prototype: \fBint +function(void *clientp, curl_socket_t item);\fP. This function gets called by +libcurl instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when +sockets are closed (not for any other file descriptors). This is pretty much +the reverse to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. Return 0 to signal +success and 1 if there was an error. (Option added in 7.21.7) +.IP CURLOPT_CLOSESOCKETDATA +Pass a pointer that will be untouched by libcurl and passed as the first +argument in the closesocket callback set with +\fICURLOPT_CLOSESOCKETFUNCTION\fP. +The default value of this parameter is unspecified. +(Option added in 7.21.7) .IP CURLOPT_PROGRESSFUNCTION -Function pointer that should match the \fIcurl_progress_callback\fP prototype -found in \fI<curl/curl.h>\fP. This function gets called by libcurl instead of -its internal equivalent with a frequent interval during operation (roughly -once per second or sooner) no matter if data is being transfered or not. +Pass a pointer to a function that matches the following prototype: + +\fBint function(void *clientp, double dltotal, double dlnow, double ultotal, +double ulnow);\fP + +This function gets called by libcurl instead of its internal equivalent with a +frequent interval. While data is being transferred it will be called very +frequently, and during slow periods like when nothing is being transferred it +can slow down to about one call per second. + +\fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA\fP, it is not +actually used by libcurl but is only passed along from the application to the +callback. + +The callback gets told how much data libcurl will transfer and has +transferred, in number of bytes. \fIdltotal\fP is the total number of bytes +libcurl expects to download in this transfer. \fIdlnow\fP is the number of +bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl +expects to upload in this transfer. \fIulnow\fP is the number of bytes +uploaded so far. + Unknown/unused argument values passed to the callback will be set to zero -(like if you only download data, the upload size will remain 0). Returning a -non-zero value from this callback will cause libcurl to abort the transfer and -return \fICURLE_ABORTED_BY_CALLBACK\fP. +(like if you only download data, the upload size will remain 0). Many times +the callback will be called one or more times first, before it knows the data +sizes so a program must be made to handle that. + +Returning a non-zero value from this callback will cause libcurl to abort the +transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl @@ -315,23 +377,71 @@ function that performs transfers. \fICURLOPT_NOPROGRESS\fP must be set to 0 to make this function actually get called. +.IP CURLOPT_XFERINFOFUNCTION +Pass a pointer to a function that matches the following prototype: + +.nf +\fBint function(void *clientp, curl_off_t dltotal, curl_off_t dlnow, + curl_off_t ultotal, curl_off_t ulnow);\fP +.fi + +This function gets called by libcurl instead of its internal equivalent with a +frequent interval. While data is being transferred it will be called very +frequently, and during slow periods like when nothing is being transferred it +can slow down to about one call per second. + +\fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA\fP, it is only +passed along from the application to the callback. + +The callback gets told how much data libcurl will transfer and has +transferred, in number of bytes. \fIdltotal\fP is the total number of bytes +libcurl expects to download in this transfer. \fIdlnow\fP is the number of +bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl +expects to upload in this transfer. \fIulnow\fP is the number of bytes +uploaded so far. + +Unknown/unused argument values passed to the callback will be set to zero +(like if you only download data, the upload size will remain 0). Many times +the callback will be called one or more times first, before it knows the data +sizes so a program must be made to handle that. + +Returning a non-zero value from this callback will cause libcurl to abort the +transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. + +If you transfer data with the multi interface, this function will not be +called during periods of idleness unless you call the appropriate libcurl +function that performs transfers. + +\fICURLOPT_NOPROGRESS\fP must be set to 0 to make this function actually +get called. + +(Added in 7.32.0) .IP CURLOPT_PROGRESSDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. +The default value of this parameter is unspecified. +.IP CURLOPT_XFERINFODATA +Pass a pointer that will be untouched by libcurl and passed as the first +argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION\fP. +The default value of this parameter is unspecified. This option is an alias +for CURLOPT_PROGRESSDATA. (Added in 7.32.0) .IP CURLOPT_HEADERFUNCTION -Function pointer that should match the following prototype: \fIsize_t -function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP. This -function gets called by libcurl as soon as it has received header data. The -header callback will be called once for each header and only complete header -lines are passed on to the callback. Parsing headers should be easy enough -using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP -multiplied with \fInmemb\fP. Do not assume that the header line is zero -terminated! The pointer named \fIuserdata\fP is the one you set with the +Pass a pointer to a function that matches the following prototype: +\fBsize_t function( void *ptr, size_t size, size_t nmemb, void +*userdata);\fP. This function gets called by libcurl as soon as it has +received header data. The header callback will be called once for each header +and only complete header lines are passed on to the callback. Parsing headers +is very easy using this. The size of the data pointed to by \fIptr\fP is +\fIsize\fP multiplied with \fInmemb\fP. Do not assume that the header line is +zero terminated! The pointer named \fIuserdata\fP is the one you set with the \fICURLOPT_WRITEHEADER\fP option. The callback function must return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the transfer and return \fICURL_WRITE_ERROR\fP. +A complete HTTP header that is passed to this function can be up to +\fICURL_MAX_HTTP_HEADER\fP (100K) bytes. + If this option is not set, or if it is set to NULL, but \fICURLOPT_HEADERDATA\fP (\fICURLOPT_WRITEHEADER\fP) is set to anything but NULL, the function used to accept response data will be used instead. That is, @@ -345,21 +455,25 @@ negotiation. If you need to operate on only the headers from the final response, you will need to collect headers in the callback yourself and use HTTP status lines, for example, to delimit response boundaries. -Since 7.14.1: When a server sends a chunked encoded transfer, it may contain a -trailer. That trailer is identical to a HTTP header and if such a trailer is -received it is passed to the application using this callback as well. There -are several ways to detect it being a trailer and not an ordinary header: 1) -it comes after the response-body. 2) it comes after the final header line (CR -LF) 3) a Trailer: header among the response-headers mention what header to -expect in the trailer. +When a server sends a chunked encoded transfer, it may contain a trailer. That +trailer is identical to a HTTP header and if such a trailer is received it is +passed to the application using this callback as well. There are several ways +to detect it being a trailer and not an ordinary header: 1) it comes after the +response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: +header among the regular response-headers mention what header(s) to expect in +the trailer. + +For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get +called with the server responses to the commands that libcurl sends. .IP CURLOPT_WRITEHEADER (This option is also known as \fBCURLOPT_HEADERDATA\fP) Pass a pointer to be -used to write the header part of the received data to. If you don't use your -own callback to take care of the writing, this must be a valid FILE *. See -also the \fICURLOPT_HEADERFUNCTION\fP option above on how to set a custom -get-all-headers callback. +used to write the header part of the received data to. If you don't use +\fICURLOPT_WRITEFUNCTION\fP or \fICURLOPT_HEADERFUNCTION\fP to take care of +the writing, this must be a valid FILE * as the internal default will then be +a plain fwrite(). See also the \fICURLOPT_HEADERFUNCTION\fP option above on +how to set a custom get-all-headers callback. .IP CURLOPT_DEBUGFUNCTION -Function pointer that should match the following prototype: \fIint +Pass a pointer to a function that matches the following prototype: \fBint curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP \fICURLOPT_DEBUGFUNCTION\fP replaces the standard debug function used when \fICURLOPT_VERBOSE \fP is in effect. This callback receives debug information, @@ -388,11 +502,11 @@ used by libcurl, it is only passed to the callback. This option does only function for libcurl powered by OpenSSL. If libcurl was built against another SSL library, this functionality is absent. -Function pointer that should match the following prototype: \fBCURLcode -sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called -by libcurl just before the initialization of an SSL connection after having -processed all other SSL related options to give a last chance to an -application to modify the behaviour of openssl's ssl initialization. The +Pass a pointer to a function that matches the following prototype: +\fBCURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function +gets called by libcurl just before the initialization of a SSL connection +after having processed all other SSL related options to give a last chance to +an application to modify the behaviour of openssl's ssl initialization. The \fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If an error is returned no attempt to establish a connection is made and the perform operation will return the error code from this callback function. Set @@ -405,7 +519,7 @@ the SSL negotiation. The SSL_CTX pointer will be a new one every time. To use this properly, a non-trivial amount of knowledge of the openssl libraries is necessary. For example, using this function allows you to use openssl callbacks to add additional validation code for certificates, and even -to change the actual URI of an HTTPS request (example used in the lib509 test +to change the actual URI of a HTTPS request (example used in the lib509 test case). See also the example section for a replacement of the key, certificate and trust file settings. .IP CURLOPT_SSL_CTX_DATA @@ -415,8 +529,8 @@ parameter, otherwise \fBNULL\fP. (Added in 7.11.0) .IP CURLOPT_CONV_TO_NETWORK_FUNCTION .IP CURLOPT_CONV_FROM_NETWORK_FUNCTION .IP CURLOPT_CONV_FROM_UTF8_FUNCTION -Function pointers that should match the following prototype: CURLcode -function(char *ptr, size_t length); +Pass a pointer to a function that matches the following prototype: +\fBCURLcode function(char *ptr, size_t length);\fP These three options apply to non-ASCII platforms only. They are available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. When @@ -458,18 +572,19 @@ follows: You will need to override these definitions if they are different on your system. .IP CURLOPT_INTERLEAVEFUNCTION -Function pointer that should match the following prototype: \fIsize_t -function( void *ptr, size_t size, size_t nmemb, void *userdata)\fP. This -function gets called by libcurl as soon as it has received interleaved RTP -data. This function gets called for each $ block and therefore contains -exactly one upper-layer protocol unit (e.g. one RTP packet). Curl writes the -interleaved header as well as the included data for each call. The first byte -is always an ASCII dollar sign. The dollar sign is followed by a one byte -channel identifier and then a 2 byte integer length in network byte order. See -\fIRFC 2326 Section 10.12\fP for more information on how RTP interleaving -behaves. If unset or set to NULL, curl will use the default write function. - -Interleaved RTP poses some challeneges for the client application. Since the +Pass a pointer to a function that matches the following prototype: +\fBsize_t function( void *ptr, size_t size, size_t nmemb, void +*userdata)\fP. This function gets called by libcurl as soon as it has received +interleaved RTP data. This function gets called for each $ block and therefore +contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl +writes the interleaved header as well as the included data for each call. The +first byte is always an ASCII dollar sign. The dollar sign is followed by a +one byte channel identifier and then a 2 byte integer length in network byte +order. See \fIRFC2326 Section 10.12\fP for more information on how RTP +interleaving behaves. If unset or set to NULL, curl will use the default write +function. + +Interleaved RTP poses some challenges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service the RTP in a timely fashion. If the RTP data is not handled quickly, subsequent response processing may become unreasonably delayed and the @@ -483,10 +598,10 @@ This is the userdata pointer that will be passed to \fICURLOPT_INTERLEAVEFUNCTION\fP when interleaved RTP data is received. (Added in 7.20.0) .IP CURLOPT_CHUNK_BGN_FUNCTION -Function pointer that should match the following prototype: \fBlong function -(const void *transfer_info, void *ptr, int remains)\fP. This function gets -called by libcurl before a part of the stream is going to be transferred (if -the transfer supports chunks). +Pass a pointer to a function that matches the following prototype: +\fBlong function (const void *transfer_info, void *ptr, int remains)\fP. This +function gets called by libcurl before a part of the stream is going to be +transferred (if the transfer supports chunks). This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH\fP option for now. @@ -503,9 +618,9 @@ Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine, \fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred. (This was added in 7.21.0) .IP CURLOPT_CHUNK_END_FUNCTION -Function pointer that should match the following prototype: \fBlong -function(void *ptr)\fP. This function gets called by libcurl as soon as a part -of the stream has been transferred (or skipped). +Pass a pointer to a function that matches the following prototype: +\fBlong function(void *ptr)\fP. This function gets called by libcurl as soon +as a part of the stream has been transferred (or skipped). Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or \fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred. @@ -515,9 +630,9 @@ Pass a pointer that will be untouched by libcurl and passed as the ptr argument to the \fICURL_CHUNK_BGN_FUNTION\fP and \fICURL_CHUNK_END_FUNTION\fP. (This was added in 7.21.0) .IP CURLOPT_FNMATCH_FUNCTION -Function pointer that should match \fBint function(void *ptr, const char -*pattern, const char *string)\fP prototype (see \fIcurl/curl.h\fP). It is used -internally for the wildcard matching feature. +Pass a pointer to a function that matches the following prototype: \fBint +function(void *ptr, const char *pattern, const char *string)\fP prototype (see +\fIcurl/curl.h\fP). It is used internally for the wildcard matching feature. Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string, \fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an @@ -531,11 +646,11 @@ Pass a char * to a buffer that the libcurl may store human readable error messages in. This may be more helpful than just the return code from \fIcurl_easy_perform\fP. The buffer must be at least CURL_ERROR_SIZE big. Although this argument is a 'char *', it does not describe an input string. -Therefore the (probably undefined) contents of the buffer is NOT copied -by the library. You should keep the associated storage available until -libcurl no longer needs it. Failing to do so will cause very odd behavior -or even crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP -or you set the same option again to use a different pointer. +Therefore the (probably undefined) contents of the buffer is NOT copied by the +library. You must keep the associated storage available until libcurl no +longer needs it. Failing to do so will cause very odd behavior or even +crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP or you +set the same option again to use a different pointer. Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better debug/trace why errors happen. @@ -560,21 +675,226 @@ detected, like when a "100-continue" is received as a response to a POST/PUT and a 401 or 407 is received immediately afterwards. .SH NETWORK OPTIONS .IP CURLOPT_URL -The actual URL to deal with. The parameter should be a char * to a zero -terminated string. +Pass in a pointer to the actual URL to deal with. The parameter should be a +char * to a zero terminated string which must be URL-encoded in the following +format: + +scheme://host:port/path + +For a greater explanation of the format please see RFC3986. + +If the given URL lacks the scheme (such as "http://" or "ftp://" etc) then +libcurl will attempt to resolve the protocol based on one of the following +given host names: + +HTTP, FTP, DICT, LDAP, IMAP, POP3 or SMTP + +(POP3 and SMTP added in 7.31.0) + +Should the protocol, either that specified by the scheme or deduced by libcurl +from the host name, not be supported by libcurl then +(\fICURLE_UNSUPPORTED_PROTOCOL\fP) will be returned from either the +\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you +call them. Use \fIcurl_version_info(3)\fP for detailed information of which +protocols are supported by the build of libcurl you are using. + +The host part of the URL contains the address of the server that you want to +connect to. This can be the fully qualified domain name of the server, the +local network name of the machine on your network or the IP address of the +server or machine represented by either an IPv4 or IPv6 address. For example: + +http://www.example.com/ + +http://hostname/ + +http://192.168.0.1/ + +http://[2001:1890:1112:1::20]/ + +It is also possible to specify the user name, password and any supported login +options as part of the host, for the following protocols, when connecting to +servers that require authentication: + +http://user:password@www.example.com + +ftp://user:password@ftp.example.com + +imap://user:password;options@mail.example.com + +pop3://user:password;options@mail.example.com + +smtp://user:password;options@mail.example.com + +At present only IMAP, POP3 and SMTP support login options as part of the host. +For more information about the login options in URL syntax please see RFC2384, +RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0). + +The port is optional and when not specified libcurl will use the default port +based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25 +for SMTP, etc. The following examples show how to specify the port: + +http://www.example.com:8080/ - This will connect to a web server using port +8080 rather than 80. + +smtp://mail.example.com:587/ - This will connect to a SMTP server on the +alternative mail port. + +The path part of the URL is protocol specific and whilst some examples are +given below this list is not conclusive: + +.B HTTP + +The path part of a HTTP request specifies the file to retrieve and from what +directory. If the directory is not specified then the web server's root +directory is used. If the file is omitted then the default document will be +retrieved for either the directory specified or the root directory. The +exact resource returned for each URL is entirely dependent on the server's +configuration. + +http://www.example.com - This gets the main page from the web server. + +http://www.example.com/index.html - This returns the main page by explicitly +requesting it. + +http://www.example.com/contactus/ - This returns the default document from +the contactus directory. + +.B FTP + +The path part of an FTP request specifies the file to retrieve and from what +directory. If the file part is omitted then libcurl downloads the directory +listing for the directory specified. If the directory is omitted then +the directory listing for the root / home directory will be returned. + +ftp://ftp.example.com - This retrieves the directory listing for the root +directory. + +ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the +root directory. + +ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the +libcurl directory. + +ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt +file from the user's home directory. When a username and password is +specified, everything that is specified in the path part is relative to the +user's home directory. To retrieve files from the root directory or a +directory underneath the root directory then the absolute path must be +specified by prepending an additional forward slash to the beginning of the +path. + +ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt +from the root directory when logging in as a specified user. + +.B SMTP + +The path part of a SMTP request specifies the host name to present during +communication with the mail server. If the path is omitted then libcurl will +attempt to resolve the local computer's host name. However, this may not +return the fully qualified domain name that is required by some mail servers +and specifying this path allows you to set an alternative name, such as +your machine's fully qualified domain name, which you might have obtained +from an external function such as gethostname or getaddrinfo. + +smtp://mail.example.com - This connects to the mail server at example.com and +sends your local computer's host name in the HELO / EHLO command. + +smtp://mail.example.com/client.example.com - This will send client.example.com in +the HELO / EHLO command to the mail server at example.com. + +.B POP3 + +The path part of a POP3 request specifies the message ID to retrieve. If the +ID is not specified then a list of waiting messages is returned instead. + +pop3://user:password@mail.example.com - This lists the available messages for +the user + +pop3://user:password@mail.example.com/1 - This retrieves the first message for +the user + +.B IMAP + +The path part of an IMAP request not only specifies the mailbox to list (Added +in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the +mailbox and to specify the UID and SECTION of the message to fetch (Added in +7.30.0). + +imap://user:password@mail.example.com - Performs a top level folder list + +imap://user:password@mail.example.com/INBOX - Performs a folder list on the +user's inbox + +imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox +and fetches message 1 + +imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects +the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches +message 2 if it is + +imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the +user's inbox and fetches message 3 with only the text portion of the message + +For more information about the individual components of an IMAP URL please +see RFC5092. + +.B SCP -If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will -attempt to guess which protocol to use based on the given host name. If the -given protocol of the set URL is not supported, libcurl will return on error -(\fICURLE_UNSUPPORTED_PROTOCOL\fP) when you call \fIcurl_easy_perform(3)\fP or -\fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed info -on which protocols are supported. +The path part of a SCP request specifies the file to retrieve and from what +directory. The file part may not be omitted. The file is taken as an absolute +path from the root directory on the server. To specify a path relative to +the user's home directory on the server, prepend ~/ to the path portion. +If the user name is not embedded in the URL, it can be set with the +\fICURLOPT_USERPWD\fP or \fBCURLOPT_USERNAME\fP option. -The string given to CURLOPT_URL must be url-encoded and follow RFC 2396 -(http://curl.haxx.se/rfc/rfc2396.txt). +scp://user@example.com/etc/issue - This specifies the file /etc/issue -Starting with version 7.20.0, the fragment part of the URI will not be send as -part of the path, which was the case previously. +scp://example.com/~/my-file - This specifies the file my-file in the +user's home directory on the server + +.B SFTP + +The path part of a SFTP request specifies the file to retrieve and from what +directory. If the file part is omitted then libcurl downloads the directory +listing for the directory specified. If the path ends in a / then a directory +listing is returned instead of a file. If the path is omitted entirely then +the directory listing for the root / home directory will be returned. +If the user name is not embedded in the URL, it can be set with the +\fICURLOPT_USERPWD\fP or \fBCURLOPT_USERNAME\fP option. + +sftp://user:password@example.com/etc/issue - This specifies the file +/etc/issue + +sftp://user@example.com/~/my-file - This specifies the file my-file in the +user's home directory + +sftp://ssh.example.com/~/Documents/ - This requests a directory listing +of the Documents directory under the user's home directory + +.B LDAP + +The path part of a LDAP request can be used to specify the: Distinguished +Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field +is separated by a question mark and when that field is not required an empty +string with the question mark separator should be included. + +ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search +with the DN as My Organisation. + +ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform +the same search but will only return postalAddress attributes. + +ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN +and requests information about the rootDomainNamingContext attribute for an +Active Directory server. + +For more information about the individual components of a LDAP URL please +see RFC4516. + +.B NOTES + +Starting with version 7.20.0, the fragment part of the URI will not be sent as +part of the path, which was previously the case. \fICURLOPT_URL\fP is the only option that \fBmust\fP be set before \fIcurl_easy_perform(3)\fP is called. @@ -607,7 +927,7 @@ proxy's port number may optionally be specified with the separate option. If not specified, libcurl will default to using port 1080 for proxies. \fICURLOPT_PROXYPORT\fP. -When you tell the library to use an HTTP proxy, libcurl will transparently +When you tell the library to use a HTTP proxy, libcurl will transparently convert operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as \fICURLOPT_QUOTE\fP and similar FTP specifics that don't work unless you @@ -624,23 +944,36 @@ use of a proxy, even if there is an environment variable set for it. Since 7.14.1, the proxy host string given in environment variables can be specified the exact same way as the proxy can be set with \fICURLOPT_PROXY\fP, include protocol prefix (http://) and embedded user + password. + +Since 7.21.7, the proxy string may be specified with a protocol:// prefix to +specify alternative proxy protocols. Use socks4://, socks4a://, socks5:// or +socks5h:// (the last one to enable socks5 and asking the proxy to do the +resolving, also known as CURLPROXY_SOCKS5_HOSTNAME type) to request the +specific SOCKS version to be used. No protocol specified, http:// and all +others will be treated as HTTP proxies. .IP CURLOPT_PROXYPORT Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. .IP CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_HTTP_1_0\fP (added in 7.19.4), -\fICURLPROXY_SOCKS4\fP (added in 7.15.2), \fICURLPROXY_SOCKS5\fP, +\fICURLPROXY_SOCKS4\fP (added in 7.10), \fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and \fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is default. (Added in 7.10) + +If you set \fBCURLOPT_PROXYTYPE\fP to \fICURLPROXY_HTTP_1_0\fP, it will only +affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version +used for "regular" HTTP requests is instead controlled with +\fICURLOPT_HTTP_VERSION\fP. .IP CURLOPT_NOPROXY -Pass a pointer to a zero terminated string. The should be a comma- separated -list of hosts which do not use a proxy, if one is specified. The only -wildcard is a single * character, which matches all hosts, and effectively -disables the proxy. Each name in this list is matched as either a domain which -contains the hostname, or the hostname itself. For example, local.com would -match local.com, local.com:80, and www.local.com, but not www.notlocal.com. -(Added in 7.19.4) +Pass a pointer to a zero terminated string. The string consists of a comma +separated list of host names that do not require a proxy to get reached, even +if one is specified. The only wildcard available is a single * character, +which matches all hosts, and effectively disables the proxy. Each name in this +list is matched as either a domain which contains the hostname, or the +hostname itself. For example, example.com would match example.com, +example.com:80, and www.example.com, but not www.notanexample.com. (Added in +7.19.4) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to 1 to make the library tunnel all operations through a given HTTP proxy. There is a big difference between using a proxy and to @@ -652,7 +985,7 @@ default service name for a SOCKS5 server is rcmd/server-fqdn. This option allows you to change it. (Added in 7.19.4) .IP CURLOPT_SOCKS5_GSSAPI_NEC Pass a long set to 1 to enable or 0 to disable. As part of the gssapi -negotiation a protection mode is negotiated. The rfc1961 says in section +negotiation a protection mode is negotiated. The RFC1961 says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. If enabled, this option allows the unprotected exchange of the protection mode negotiation. (Added in 7.19.4). @@ -660,13 +993,22 @@ negotiation. (Added in 7.19.4). Pass a char * as parameter. This sets the interface name to use as outgoing network interface. The name can be an interface name, an IP address, or a host name. + +Starting with 7.24.0: If the parameter starts with "if!" then it is treated as +only as interface name and no attempt will ever be named to do treat it as an +IP address or to do name resolution on it. If the parameter starts with +\&"host!" it is treated as either an IP address or a hostname. Hostnames are +resolved synchronously. Using the if! format is highly recommended when using +the multi interfaces to avoid allowing the code to block. If "if!" is +specified but the parameter does not match an existing interface, +CURLE_INTERFACE_FAILED is returned. .IP CURLOPT_LOCALPORT Pass a long. This sets the local port number of the socket used for connection. This can be used in combination with \fICURLOPT_INTERFACE\fP and you are recommended to use \fICURLOPT_LOCALPORTRANGE\fP as well when this is set. Valid port numbers are 1 - 65535. (Added in 7.15.2) .IP CURLOPT_LOCALPORTRANGE -Pass a long. This is the number of attempts libcurl should make to find a +Pass a long. This is the number of attempts libcurl will make to find a working local port number. It starts with the given \fICURLOPT_LOCALPORT\fP and adds one to the number for each retry. Setting this to 1 or below will make libcurl do only one try for the exact port number. Port numbers by nature @@ -705,24 +1047,37 @@ only makes sense to use this option if you want it smaller. Pass a long specifying what remote port number to connect to, instead of the one specified in the URL or the default port for the used protocol. .IP CURLOPT_TCP_NODELAY -Pass a long specifying whether the TCP_NODELAY option should be set or -cleared (1 = set, 0 = clear). The option is cleared by default. This -will have no effect after the connection has been established. +Pass a long specifying whether the TCP_NODELAY option is to be set or cleared +(1 = set, 0 = clear). The option is cleared by default. This will have no +effect after the connection has been established. -Setting this option will disable TCP's Nagle algorithm. The purpose of -this algorithm is to try to minimize the number of small packets on -the network (where "small packets" means TCP segments less than the -Maximum Segment Size (MSS) for the network). +Setting this option will disable TCP's Nagle algorithm. The purpose of this +algorithm is to try to minimize the number of small packets on the network +(where "small packets" means TCP segments less than the Maximum Segment Size +(MSS) for the network). Maximizing the amount of data sent per TCP segment is good because it -amortizes the overhead of the send. However, in some cases (most -notably telnet or rlogin) small segments may need to be sent -without delay. This is less efficient than sending larger amounts of -data at a time, and can contribute to congestion on the network if -overdone. +amortizes the overhead of the send. However, in some cases (most notably +telnet or rlogin) small segments may need to be sent without delay. This is +less efficient than sending larger amounts of data at a time, and can +contribute to congestion on the network if overdone. .IP CURLOPT_ADDRESS_SCOPE Pass a long specifying the scope_id value to use when connecting to IPv6 link-local or site-local addresses. (Added in 7.19.0) +.IP CURLOPT_TCP_KEEPALIVE +Pass a long. If set to 1, TCP keepalive probes will be sent. The delay and +frequency of these probes can be controlled by the \fICURLOPT_TCP_KEEPIDLE\fP +and \fICURLOPT_TCP_KEEPINTVL\fP options, provided the operating system supports +them. Set to 0 (default behavior) to disable keepalive probes (Added in +7.25.0). +.IP CURLOPT_TCP_KEEPIDLE +Pass a long. Sets the delay, in seconds, that the operating system will wait +while the connection is idle before sending keepalive probes. Not all operating +systems support this option. (Added in 7.25.0) +.IP CURLOPT_TCP_KEEPINTVL +Pass a long. Sets the interval, in seconds, that the operating system will wait +between sending keepalive probes. Not all operating systems support this +option. (Added in 7.25.0) .SH NAMES and PASSWORDS OPTIONS (Authentication) .IP CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and @@ -762,8 +1117,8 @@ the full path name to the file you want libcurl to use as .netrc file. If this option is omitted, and \fICURLOPT_NETRC\fP is set, libcurl will attempt to find a .netrc file in the current user's home directory. (Added in 7.10.9) .IP CURLOPT_USERPWD -Pass a char * as parameter, which should be [user name]:[password] to use for -the connection. Use \fICURLOPT_HTTPAUTH\fP to decide the authentication method. +Pass a char * as parameter, pointing to a zero terminated login details string +for the connection. The format of which is: [user name]:[password];[options]. When using NTLM, you can set the domain by prepending it to the user name and separating the domain and name with a forward (/) or backward slash (\\). Like @@ -776,10 +1131,18 @@ and password information to hosts using the initial host name (unless \fICURLOPT_UNRESTRICTED_AUTH\fP is set), so if libcurl follows locations to other hosts it will not send the user and password to those. This is enforced to prevent accidental information leakage. + +At present only IMAP, POP3 and SMTP support login options as part of the +details string. For more information about the login options please see +RFC2384, RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0). + +Use \fICURLOPT_HTTPAUTH\fP to specify the authentication method for HTTP based +connections. .IP CURLOPT_PROXYUSERPWD Pass a char * as parameter, which should be [user name]:[password] to use for -the connection to the HTTP proxy. Use \fICURLOPT_PROXYAUTH\fP to decide -the authentication method. +the connection to the HTTP proxy. + +Use \fICURLOPT_PROXYAUTH\fP to specify the authentication method. .IP CURLOPT_USERNAME Pass a char * as parameter, which should be pointing to the zero terminated user name to use for the transfer. @@ -823,7 +1186,7 @@ below. If more than one bit is set, libcurl will first query the site to see which authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the \fICURLOPT_USERPWD\fP option or -with the \fICURLOPT_USERNAME\fP and the \fICURLOPT_USERPASSWORD\fP options. +with the \fICURLOPT_USERNAME\fP and the \fICURLOPT_PASSWORD\fP options. (Added in 7.10.6) .RS .IP CURLAUTH_BASIC @@ -855,8 +1218,22 @@ HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to prevent the password from being eavesdropped. -You need to build libcurl with OpenSSL support for this option to work, or -build libcurl on Windows. +You need to build libcurl with either OpenSSL, GnuTLS or NSS support for this +option to work, or build libcurl on Windows with SSPI support. +.IP CURLAUTH_NTLM_WB +NTLM delegating to winbind helper. Authentication is performed by a separate +binary application that is executed when needed. The name of the application +is specified at compile time but is typically /usr/bin/ntlm_auth +(Added in 7.22.0) + +Note that libcurl will fork when necessary to run the winbind application and +kill it when complete, calling waitpid() to await its exit when done. On POSIX +operating systems, killing the process will cause a SIGCHLD signal to be +raised (regardless of whether \fICURLOPT_NOSIGNAL\fP is set), which must be +handled intelligently by the application. In particular, the application must +not unconditionally call wait() in its SIGCHLD signal handler to avoid being +subject to a race condition. This behavior is subject to change in future +versions of libcurl. .IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most @@ -870,6 +1247,29 @@ This is a meta symbol. Or this value together with a single specific auth value to force libcurl to probe for un-restricted auth and if not, only that single auth algorithm is acceptable. (Added in 7.21.3) .RE +.IP CURLOPT_TLSAUTH_TYPE +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +authentication method(s) you want it to use for TLS authentication. +.RS +.IP CURLOPT_TLSAUTH_SRP +TLS-SRP authentication. Secure Remote Password authentication for TLS is +defined in RFC5054 and provides mutual authentication if both sides have a +shared secret. To use TLS-SRP, you must also set the +\fICURLOPT_TLSAUTH_USERNAME\fP and \fICURLOPT_TLSAUTH_PASSWORD\fP options. + +You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this +to work. (Added in 7.21.4) +.RE +.IP CURLOPT_TLSAUTH_USERNAME +Pass a char * as parameter, which should point to the zero terminated username +to use for the TLS authentication method specified with the +\fICURLOPT_TLSAUTH_TYPE\fP option. Requires that the +\fICURLOPT_TLS_PASSWORD\fP option also be set. (Added in 7.21.4) +.IP CURLOPT_TLSAUTH_PASSWORD +Pass a char * as parameter, which should point to the zero terminated password +to use for the TLS authentication method specified with the +\fICURLOPT_TLSAUTH_TYPE\fP option. Requires that the +\fICURLOPT_TLS_USERNAME\fP option also be set. (Added in 7.21.4) .IP CURLOPT_PROXYAUTH Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use for your proxy authentication. If @@ -880,13 +1280,22 @@ actual name and password with the \fICURLOPT_PROXYUSERPWD\fP option. The bitmask can be constructed by or'ing together the bits listed above for the \fICURLOPT_HTTPAUTH\fP option. As of this writing, only Basic, Digest and NTLM work. (Added in 7.10.7) +.IP CURLOPT_SASL_IR +Pass a long. If the value is 1, curl will send the initial response to the +server in the first authentication packet in order to reduce the number of +ping pong requests. Only applicable to supporting SASL authentication +mechanisms and to the IMAP, POP3 and SMTP protocols. (Added in 7.31.0) + +Note: Whilst IMAP supports this option there is no need to explicitly set it, +as libcurl can determine the feature itself when the server supports the +SASL-IR CAPABILITY. .SH HTTP OPTIONS .IP CURLOPT_AUTOREFERER Pass a parameter set to 1 to enable this. When enabled, libcurl will automatically set the Referer: field in requests where it follows a Location: redirect. -.IP CURLOPT_ENCODING -Sets the contents of the Accept-Encoding: header sent in an HTTP request, and +.IP CURLOPT_ACCEPT_ENCODING +Sets the contents of the Accept-Encoding: header sent in a HTTP request, and enables decoding of a response when a Content-Encoding: header is received. Three encodings are supported: \fIidentity\fP, which does nothing, \fIdeflate\fP which requests the server to compress its response using the @@ -897,9 +1306,24 @@ supported encodings is sent. This is a request, not an order; the server may or may not do it. This option must be set (to any non-NULL value) or else any unsolicited encoding done by the server is ignored. See the special file lib/README.encoding for details. + +(This option was called CURLOPT_ENCODING before 7.21.6) +.IP CURLOPT_TRANSFER_ENCODING +Adds a request for compressed Transfer Encoding in the outgoing HTTP +request. If the server supports this and so desires, it can respond with the +HTTP response sent using a compressed Transfer-Encoding that will be +automatically uncompressed by libcurl on reception. + +Transfer-Encoding differs slightly from the Content-Encoding you ask for with +\fBCURLOPT_ACCEPT_ENCODING\fP in that a Transfer-Encoding is strictly meant to +be for the transfer and thus MUST be decoded before the data arrives in the +client. Traditionally, Transfer-Encoding has been much less used and supported +by both HTTP clients and HTTP servers. + +(Added in 7.21.6) .IP CURLOPT_FOLLOWLOCATION A parameter set to 1 tells the library to follow any Location: header that the -server sends as part of an HTTP header. +server sends as part of a HTTP header. This means that the library will re-send the same request on the new location and follow new Location: headers all the way until no more such headers are @@ -922,19 +1346,20 @@ Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite number of redirects (which is the default) .IP CURLOPT_POSTREDIR Pass a bitmask to control how libcurl acts on redirects after POSTs that get a -301 or 302 response back. A parameter with bit 0 set (value -\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 2616/10.3.2 and -not convert POST requests into GET requests when following a 301 -redirection. Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain -the request method after a 302 redirect. CURL_REDIR_POST_ALL is a convenience -define that sets both bits. +301, 302 or 303 response back. A parameter with bit 0 set (value +\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC2616/10.3.2 and not +convert POST requests into GET requests when following a 301 redirection. +Setting bit 1 (value \fBCURL_REDIR_POST_302\fP) makes libcurl maintain the +request method after a 302 redirect whilst setting bit 2 (value +\fBCURL_REDIR_POST_303\fP) makes libcurl maintain the request method after a +303 redirect. The value \fBCURL_REDIR_POST_ALL\fP is a convenience define that +sets all three bits. The non-RFC behaviour is ubiquitous in web browsers, so the library does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. (Added in 7.17.1) (This option was -known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 way before -then) +known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 then) .IP CURLOPT_PUT A parameter set to 1 tells the library to use HTTP PUT to transfer data. The data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP. @@ -979,7 +1404,7 @@ If you issue a POST request and then want to make a HEAD or GET using the same re-used handle, you must explicitly set the new request type using \fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar. .IP CURLOPT_POSTFIELDS -Pass a void * as parameter, which should be the full data to post in an HTTP +Pass a void * as parameter, which should be the full data to post in a HTTP POST operation. You must make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded. @@ -1014,7 +1439,7 @@ Pass a curl_off_t as parameter. Use this to set the size of the data to figure out the size. This is the large file version of the \fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1) .IP CURLOPT_COPYPOSTFIELDS -Pass a char * as parameter, which should be the full data to post in an HTTP +Pass a char * as parameter, which should be the full data to post in a HTTP POST operation. It behaves as the \fICURLOPT_POSTFIELDS\fP option, but the original data are copied by the library, allowing the application to overwrite the original data after setting this option. @@ -1061,10 +1486,12 @@ internally, your added one will be used instead. If you add a header with no content as in 'Accept:' (no data on the right side of the colon), the internally used header will get disabled. Thus, using this option you can add new headers, replace internal headers and remove internal headers. To add a -header with no content, make the content be two quotes: \&"". The headers -included in the linked list must not be CRLF-terminated, because curl adds -CRLF after each header item. Failure to comply with this will result in -strange bugs because the server will most likely ignore part of the headers +header with no content (nothing to the right side of the colon), use the +form 'MyHeader;' (note the ending semicolon). + +The headers included in the linked list must not be CRLF-terminated, because +curl adds CRLF after each header item. Failure to comply with this will result +in strange bugs because the server will most likely ignore part of the headers you specified. The first line in a request (containing the method, usually a GET or POST) is @@ -1101,7 +1528,7 @@ option and thus you need to concatenate them all in one single string. Set multiple cookies in one string like this: "name1=content1; name2=content2;" etc. -This option sets the cookie header explictly in the outgoing request(s). If +This option sets the cookie header explicitly in the outgoing request(s). If multiple requests are done due to authentication, followed redirections or similar, they will all get this cookie passed on. @@ -1154,7 +1581,7 @@ to GET. Usable if a POST, HEAD, PUT, or a custom request has been used previously using the same curl handle. When setting \fICURLOPT_HTTPGET\fP to 1, it will automatically set -\fICURLOPT_NOBODY\fP to 0 (since 7.14.1). +\fICURLOPT_NOBODY\fP to 0 and \fICURLOPT_UPLOAD\fP to 0. .IP CURLOPT_HTTP_VERSION Pass a long, set to one of the values described below. They force libcurl to use the specific HTTP versions. This is not sensible to do unless you have a @@ -1177,8 +1604,8 @@ connection. (added in 7.14.1) .IP CURLOPT_HTTP_CONTENT_DECODING Pass a long to tell libcurl how to act on content decoding. If set to zero, content decoding will be disabled. If set to 1 it is enabled. Libcurl has no -default content decoding but requires you to use \fICURLOPT_ENCODING\fP for -that. (added in 7.16.2) +default content decoding but requires you to use \fICURLOPT_ACCEPT_ENCODING\fP +for that. (added in 7.16.2) .IP CURLOPT_HTTP_TRANSFER_DECODING Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding will be disabled, if set to 1 it is enabled @@ -1186,28 +1613,55 @@ transfer decoding will be disabled, if set to 1 it is enabled option is set to zero. (added in 7.16.2) .SH SMTP OPTIONS .IP CURLOPT_MAIL_FROM -Pass a pointer to a zero terminated string as parameter. It will be used to -specify the sender address in a mail when sending an SMTP mail with libcurl. +Pass a pointer to a zero terminated string as parameter. This should be used +to specify the sender's email address when sending SMTP mail with libcurl. + +An originator email address should be specified with angled brackets (<>) +around it, which if not specified, will be added by libcurl from version +7.21.4 onwards. Failing to provide such brackets may cause the server to +reject the email. + +If this parameter is not specified then an empty address will be sent to the +mail server which may or may not cause the email to be rejected. (Added in 7.20.0) .IP CURLOPT_MAIL_RCPT Pass a pointer to a linked list of recipients to pass to the server in your -SMTP mail request. The linked list should be a fully valid list of \fBstruct +SMTP mail request. The linked list should be a fully valid list of \fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. -Each recipient in SMTP lingo is specified with angle brackets (<>), but should -you not use an angle bracket as first letter libcurl will assume you provide a -single email address only and enclose that with angle brackets for you. +Each recipient should be specified within a pair of angled brackets (<>), +however, should you not use an angled bracket as the first character libcurl +will assume you provided a single email address and enclose that address +within brackets for you. (Added in 7.20.0) +.IP CURLOPT_MAIL_AUTH +Pass a pointer to a zero terminated string as parameter. This will be used +to specify the authentication address (identity) of a submitted message that +is being relayed to another server. + +This optional parameter allows co-operating agents in a trusted environment to +communicate the authentication of individual messages and should only be used +by the application program, using libcurl, if the application is itself a +mail server acting in such an environment. If the application is operating as +such and the AUTH address is not known or is invalid, then an empty string +should be used for this parameter. + +Unlike CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT, the address should not be +specified within a pair of angled brackets (<>). However, if an empty string +is used then a pair of brackets will be sent by libcurl as required by +RFC2554. + +(Added in 7.25.0) .SH TFTP OPTIONS .IP CURLOPT_TFTP_BLKSIZE -Specify block size to use for TFTP data transmission. Valid range as per RFC -2348 is 8-65464 bytes. The default of 512 bytes will be used if this option is -not specified. The specified block size will only be used pending support by -the remote server. If the server does not return an option acknowledgement or -returns an option acknowledgement with no blksize, the default of 512 bytes +Specify block size to use for TFTP data transmission. Valid range as per +RFC2348 is 8-65464 bytes. The default of 512 bytes will be used if this option +is not specified. The specified block size will only be used pending support +by the remote server. If the server does not return an option acknowledgement +or returns an option acknowledgement with no blksize, the default of 512 bytes will be used. (added in 7.19.4) .SH FTP OPTIONS .IP CURLOPT_FTPPORT @@ -1238,18 +1692,22 @@ Examples with specified ports: You disable PORT again and go back to using the passive version by setting this option to NULL. .IP CURLOPT_QUOTE -Pass a pointer to a linked list of FTP or SFTP commands to pass to -the server prior to your FTP request. This will be done before any -other commands are issued (even before the CWD command for FTP). The -linked list should be a fully valid list of 'struct curl_slist' structs -properly filled in with text strings. Use \fIcurl_slist_append(3)\fP -to append strings (commands) to the list, and clear the entire list -afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation -again by setting a NULL to this option. -The set of valid FTP commands depends on the server (see RFC959 for a -list of mandatory commands). -The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, -rename, rm, rmdir, symlink (see +Pass a pointer to a linked list of FTP or SFTP commands to pass to the server +prior to your FTP request. This will be done before any other commands are +issued (even before the CWD command for FTP). The linked list should be a +fully valid list of 'struct curl_slist' structs properly filled in with text +strings. Use \fIcurl_slist_append(3)\fP to append strings (commands) to the +list, and clear the entire list afterwards with +\fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL +to this option. When speaking to a FTP (or SFTP since 7.24.0) server, prefix +the command with an asterisk (*) to make libcurl continue even if the command +fails as by default libcurl will stop at first failure. + +The set of valid FTP commands depends on the server (see RFC959 for a list of +mandatory commands). + +The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm, +rmdir, symlink (see .BR curl (1)) (SFTP support added in 7.16.3) .IP CURLOPT_POSTQUOTE @@ -1263,7 +1721,7 @@ Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for \fICURLOPT_QUOTE\fP. Disable this operation again by setting a NULL to this -option. Before version 7.15.6, if you also set \fICURLOPT_NOBODY\fP to 1, this +option. Before version 7.16.0, if you also set \fICURLOPT_NOBODY\fP to 1, this option didn't work. .IP CURLOPT_DIRLISTONLY A parameter set to 1 tells the library to just list the names of files in a @@ -1318,7 +1776,7 @@ already exists or lack of permissions prevents creation. (Added in 7.16.3) Starting with 7.19.4, you can also set this value to 2, which will make libcurl retry the CWD command again if the subsequent MKD command fails. This -is especially useful if you're doing many simultanoes connections against the +is especially useful if you're doing many simultaneous connections against the same server and they all have this option enabled, as then CWD may first fail but then another connection does MKD before this connection and thus MKD fails but trying CWD works! 7.19.4 also introduced the \fICURLFTP_CREATE_DIR\fP and @@ -1376,7 +1834,7 @@ a reply. Initiate the shutdown and wait for a reply. .RE .IP CURLOPT_FTP_ACCOUNT -Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP +Pass a pointer to a zero terminated string (or NULL to disable). When an FTP server asks for "account data" after user name and password has been provided, this data is sent off using the ACCT command. (Added in 7.13.0) .IP CURLOPT_FTP_FILEMETHOD @@ -1405,7 +1863,7 @@ initialized. (Added in 7.20.0) .RS .IP CURL_RTSPREQ_OPTIONS Used to retrieve the available methods of the server. The application is -responsbile for parsing and obeying the response. \fB(The session ID is not +responsible for parsing and obeying the response. \fB(The session ID is not needed for this method.)\fP (Added in 7.20.0) .IP CURL_RTSPREQ_DESCRIBE Used to get the low level description of a stream. The application should note @@ -1418,7 +1876,7 @@ needed for this method)\fP (Added in 7.20.0) When sent by a client, this method changes the description of the session. For example, if a client is using the server to record a meeting, the client can use Announce to inform the server of all the meta-information about the -session. ANNOUNCE acts like an HTTP PUT or POST just like +session. ANNOUNCE acts like a HTTP PUT or POST just like \fICURL_RTSPREQ_SET_PARAMETER\fP (Added in 7.20.0) .IP CURL_RTSPREQ_SETUP Setup is used to initialize the transport layer for the session. The @@ -1441,7 +1899,7 @@ different connections. (Added in 7.20.0) .IP CURL_RTSPREQ_GET_PARAMETER Retrieve a parameter from the server. By default, libcurl will automatically include a \fIContent-Type: text/parameters\fP header on all non-empty requests -unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST +unless a custom one is set. GET_PARAMETER acts just like a HTTP PUT or POST (see \fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat message (e.g. in the presence of a server-specified timeout) should send use an empty GET_PARAMETER request. @@ -1449,9 +1907,9 @@ server-specified timeout) should send use an empty GET_PARAMETER request. .IP CURL_RTSPREQ_SET_PARAMETER Set a parameter on the server. By default, libcurl will automatically include a \fIContent-Type: text/parameters\fP header unless a custom one is set. The -interaction with SET_PARAMTER is much like an HTTP PUT or POST. An application -may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like an HTTP -PUT, or it may use \fICURLOPT_POSTFIELDS\fP like an HTTP POST. No chunked +interaction with SET_PARAMTER is much like a HTTP PUT or POST. An application +may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like a HTTP +PUT, or it may use \fICURLOPT_POSTFIELDS\fP like a HTTP POST. No chunked transfers are allowed, so the application must set the \fICURLOPT_INFILESIZE\fP in the former and \fICURLOPT_POSTFIELDSIZE\fP in the latter. Also, there is no use of multi-part POSTs within RTSP. (Added in @@ -1513,7 +1971,7 @@ over FTP. This is a known limitation/flaw that nobody has rectified. libcurl simply sets the mode to ASCII and performs a standard transfer. .IP CURLOPT_PROXY_TRANSFER_MODE Pass a long. If the value is set to 1 (one), it tells libcurl to set the -transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by +transfer mode (binary or ASCII) for FTP transfers done via a HTTP proxy, by appending ;type=a or ;type=i to the URL. Without this setting, or it being set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing FTP via a proxy. Beware that not all proxies support this feature. (Added in @@ -1528,7 +1986,7 @@ want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in \fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation -techniques). For RTSP, the formatting of a range should follow RFC 2326 +techniques). For RTSP, the formatting of a range should follow RFC2326 Section 12.29. For RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should be given in npt, utc, or smpte formats. @@ -1550,33 +2008,45 @@ source file to the remote target file. Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) .IP CURLOPT_CUSTOMREQUEST -Pass a pointer to a zero terminated string as parameter. It will be used -instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST -when doing a FTP directory listing. This is useful for doing DELETE or other -more or less obscure HTTP requests. Don't do this at will, make sure your -server supports the command first. - +Pass a pointer to a zero terminated string as parameter. It can be used to +specify the request instead of GET or HEAD when performing HTTP based +requests, instead of LIST and NLST when performing FTP directory listings and +instead of LIST and RETR when issuing POP3 based commands. This is +particularly useful, for example, for performing a HTTP DELETE request or a +POP3 DELE command. + +Please don't perform this at will, on HTTP based requests, by making sure +your server supports the command you are sending first. + When you change the request method by setting \fBCURLOPT_CUSTOMREQUEST\fP to -something, you don't actually change how libcurl behaves or acts in regards to -the particular request method, it will only change the actual string sent in -the request. +something, you don't actually change how libcurl behaves or acts in regards +to the particular request method, it will only change the actual string sent +in the request. -For example: if you tell libcurl to do a HEAD request, but then change the -request to a "GET" with \fBCURLOPT_CUSTOMREQUEST\fP you'll still see libcurl -act as if it sent a HEAD even when it does send a GET. +For example: -To switch to a proper HEAD, use \fICURLOPT_NOBODY\fP, to switch to a proper -POST, use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and so on. +With the HTTP protocol when you tell libcurl to do a HEAD request, but then +specify a GET though a custom request libcurl will still act as if it sent a +HEAD. To switch to a proper HEAD use \fICURLOPT_NOBODY\fP, to switch to a +proper POST use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and to switch +to a proper GET use CURLOPT_HTTPGET. + +With the POP3 protocol when you tell libcurl to use a custom request it will +behave like a LIST or RETR command was sent where it expects data to be +returned by the server. As such \fICURLOPT_NOBODY\fP should be used when +specifying commands such as DELE and NOOP for example. Restore to the internal default by setting this to NULL. Many people have wrongly used this option to replace the entire request with -their own, including multiple headers and POST contents. While that might work -in many cases, it will cause libcurl to send invalid requests and it could -possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and +their own, including multiple headers and POST contents. While that might +work in many cases, it will cause libcurl to send invalid requests and it +could possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and \fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to replace or extend the set of headers sent by libcurl. Use \fICURLOPT_HTTP_VERSION\fP to change HTTP version. + +(Support for POP3 added in 7.26.0) .IP CURLOPT_FILETIME Pass a long. If it is 1, libcurl will attempt to get the modification date of the remote document in this operation. This requires that the remote server @@ -1585,11 +2055,11 @@ sends the time or replies to a time querying command. The can be used after a transfer to extract the received time (if any). .IP CURLOPT_NOBODY A parameter set to 1 tells the library to not include the body-part in the -output. This is only relevant for protocols that have separate header and body -parts. On HTTP(S) servers, this will make libcurl do a HEAD request. +output. This is only relevant for protocols that have separate header and +body parts. On HTTP(S) servers, this will make libcurl do a HEAD request. -To change request to GET, you should use \fICURLOPT_HTTPGET\fP. Change request -to POST with \fICURLOPT_POST\fP etc. +To change request to GET, you should use \fICURLOPT_HTTPGET\fP. Change +request to POST with \fICURLOPT_POST\fP etc. .IP CURLOPT_INFILESIZE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed @@ -1598,6 +2068,9 @@ as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE\fP is mandatory. +When sending emails using SMTP, this command can be used to specify the +optional SIZE parameter for the MAIL FROM command. (Added in 7.23.0) + This option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns. .IP CURLOPT_INFILESIZE_LARGE @@ -1644,8 +2117,8 @@ given limit. This concerns both FTP and HTTP transfers. .IP CURLOPT_TIMECONDITION Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP -or \fICURL_TIMECOND_IFUNMODSINCE\fP. This feature applies to HTTP, FTP, and -RTSP. +or \fICURL_TIMECOND_IFUNMODSINCE\fP. This feature applies to HTTP, FTP, RTSP, +and FILE. The last modification time of a file is not always known and in such instances this feature will have no effect even if the given time condition would not @@ -1666,6 +2139,8 @@ SIGALRM to enable time-outing system calls. In unix-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL\fP is set. + +Default timeout is 0 (zero) which means it never times out. .IP CURLOPT_TIMEOUT_MS Like \fICURLOPT_TIMEOUT\fP but takes number of milliseconds instead. If libcurl is built to use the standard system name resolver, that portion @@ -1727,9 +2202,9 @@ re-use (default behavior). .IP CURLOPT_CONNECTTIMEOUT Pass a long. It should contain the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once -it has connected, this option is of no more use. Set to zero to disable -connection timeout (it will then only timeout on the system's internal -timeouts). See also the \fICURLOPT_TIMEOUT\fP option. +it has connected, this option is of no more use. Set to zero to switch to the +default built-in connection timeout - 300 seconds. See also the +\fICURLOPT_TIMEOUT\fP option. In unix-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL\fP is set. @@ -1754,11 +2229,12 @@ Resolve to IPv6 addresses. .IP CURLOPT_CONNECT_ONLY Pass a long. If the parameter equals 1, it tells the library to perform all the required proxy authentication and connection setup, but no data transfer. -This option is useful only on HTTP URLs. +This option is implemented for HTTP, SMTP and POP3. -This option is useful with the \fICURLINFO_LASTSOCKET\fP option to -\fIcurl_easy_getinfo(3)\fP. The library can set up the connection and then the -application can obtain the most recently used socket for special data +The option can be used to simply test a connection to a server, but is more +useful when used with the \fICURLINFO_LASTSOCKET\fP option to +\fIcurl_easy_getinfo(3)\fP as the library can set up the connection and then +the application can obtain the most recently used socket for special data transfers. (Added in 7.15.2) .IP CURLOPT_USE_SSL Pass a long using one of the values from below, to make libcurl use your @@ -1800,15 +2276,40 @@ resolves, by including a string in the linked list that uses the format \&"-HOST:PORT". The host name must be prefixed with a dash, and the host name and port number must exactly match what was already added previously. -(Added in 7.12.3) +(Added in 7.21.3) +.IP CURLOPT_DNS_SERVERS +Set the list of DNS servers to be used instead of the system default. +The format of the dns servers option is: + +host[:port][,host[:port]]... + +For example: + +192.168.1.100,192.168.1.101,3.4.5.6 + +This option requires that libcurl was built with a resolver backend that +supports this operation. The c-ares backend is the only such one. + +(Added in 7.24.0) +.IP CURLOPT_ACCEPTTIMEOUT_MS +Pass a long telling libcurl the maximum number of milliseconds to wait for a +server to connect back to libcurl when an active FTP connection is used. If no +timeout is set, the internal default of 60000 will be used. (Added in 7.24.0) .SH SSL and SECURITY OPTIONS .IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be the file name of your certificate. The default format is "PEM" and can be changed with \fICURLOPT_SSLCERTTYPE\fP. -With NSS this is the nickname of the certificate you wish to authenticate -with. +With NSS this can also be the nickname of the certificate you wish to +authenticate with. If you want to use a file from the current directory, please +precede it with "./" prefix, in order to avoid confusion with a nickname. + +(iOS and Mac OS X only) With Secure Transport, this string must match the name +of a certificate that's in the system or user keychain. You should encode this +string in UTF-8 format in case it contains non-ASCII characters. The private +key corresponding to the certificate, and certificate chain (if any), must +also be present in the keychain. (Added in 7.31.0) .IP CURLOPT_SSLCERTTYPE Pass a pointer to a zero terminated string as parameter. The string should be the format of your certificate. Supported formats are "PEM" and "DER". (Added @@ -1817,6 +2318,10 @@ in 7.9.3) Pass a pointer to a zero terminated string as parameter. The string should be the file name of your private key. The default format is "PEM" and can be changed with \fICURLOPT_SSLKEYTYPE\fP. + +(iOS and Mac OS X only) This option is ignored if curl was built against Secure +Transport. Secure Transport expects the private key to be already present in +the keychain containing the certificate. .IP CURLOPT_SSLKEYTYPE Pass a pointer to a zero terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG". @@ -1867,28 +2372,30 @@ Force SSLv2 Force SSLv3 .RE .IP CURLOPT_SSL_VERIFYPEER -Pass a long as parameter. +Pass a long as parameter. By default, curl assumes a value of 1. This option determines whether curl verifies the authenticity of the peer's -certificate. A value of 1 means curl verifies; zero means it doesn't. The -default is nonzero, but before 7.10, it was zero. +certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't. -When negotiating an SSL connection, the server sends a certificate indicating +When negotiating a SSL connection, the server sends a certificate indicating its identity. Curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority -(CA) certificates you supply. As of 7.10, curl installs a default bundle of -CA certificates and you can specify alternate certificates with the -\fICURLOPT_CAINFO\fP option or the \fICURLOPT_CAPATH\fP option. +(CA) certificates you supply. curl uses a default bundle of CA certificates +(the path for that is determined at build time) and you can specify alternate +certificates with the \fICURLOPT_CAINFO\fP option or the \fICURLOPT_CAPATH\fP +option. When \fICURLOPT_SSL_VERIFYPEER\fP is nonzero, and the verification fails to prove that the certificate is authentic, the connection fails. When the -option is zero, the connection succeeds regardless. +option is zero, the peer certificate verification succeeds regardless. Authenticating the certificate is not by itself very useful. You typically want to ensure that the server, as authentically identified by its certificate, is the server you mean to be talking to. Use -\fICURLOPT_SSL_VERIFYHOST\fP to control that. +\fICURLOPT_SSL_VERIFYHOST\fP to control that. The check that the host name in +the certificate is valid for the host name you're connecting to is done +independently of the \fICURLOPT_SSL_VERIFYPEER\fP option. .IP CURLOPT_CAINFO Pass a char * to a zero terminated string naming a file holding one or more certificates to verify the peer with. This makes sense only when used in @@ -1899,8 +2406,8 @@ even indicate an accessible file. This option is by default set to the system path where libcurl's cacert bundle is assumed to be stored, as established at build time. -When built against NSS, this is the directory that the NSS certificate -database resides in. +If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module +(libnsspem.so) needs to be available for this option to work properly. .IP CURLOPT_ISSUERCERT Pass a char * to a zero terminated string naming a file holding a CA certificate in PEM format. If the option is set, an additional check against @@ -1919,13 +2426,15 @@ mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER\fP has to be set too for the check to fail). (Added in 7.19.0) .IP CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple -CA certificates to verify the peer with. The certificate directory must be -prepared using the openssl c_rehash utility. This makes sense only when used -in combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If -\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAPATH\fP need not even -indicate an accessible path. The \fICURLOPT_CAPATH\fP function apparently -does not work in Windows due to some limitation in openssl. This option is -OpenSSL-specific and does nothing if libcurl is built to use GnuTLS. +CA certificates to verify the peer with. If libcurl is built against OpenSSL, +the certificate directory must be prepared using the openssl c_rehash utility. +This makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER\fP option. If \fICURLOPT_SSL_VERIFYPEER\fP is zero, +\fICURLOPT_CAPATH\fP need not even indicate an accessible path. The +\fICURLOPT_CAPATH\fP function apparently does not work in Windows due to some +limitation in openssl. This option is OpenSSL-specific and does nothing if +libcurl is built to use GnuTLS. NSS-powered libcurl provides the option only +for backward compatibility. .IP CURLOPT_CRLFILE Pass a char * to a zero terminated string naming a file with the concatenation of CRL (in PEM format) to use in the certificate validation that occurs during @@ -1944,20 +2453,6 @@ A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. A failure in certificate verification due to a revocation information found in the CRL does not trigger this specific error. (Added in 7.19.0) -.IP CURLOPT_CERTINFO -Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With -this enabled, libcurl (if built with OpenSSL) will extract lots of information -and data about the certificates in the certificate chain used in the SSL -connection. This data is then possible to extract after a transfer using -\fIcurl_easy_getinfo(3)\fP and its option \fICURLINFO_CERTINFO\fP. (Added in -7.19.1) -.IP CURLOPT_RANDOM_FILE -Pass a char * to a zero terminated file name. The file will be used to read -from to seed the random engine for SSL. The more random the specified file is, -the more secure the SSL connection will become. -.IP CURLOPT_EGDSOCKET -Pass a char * to the zero terminated path name to the Entropy Gathering Daemon -socket. It will be used to seed the random engine for SSL. .IP CURLOPT_SSL_VERIFYHOST Pass a long as parameter. @@ -1975,16 +2470,35 @@ Curl considers the server the intended one when the Common Name field or a Subject Alternate Name field in the certificate matches the host name in the URL to which you told Curl to connect. -When the value is 1, the certificate must contain a Common Name field, but it -doesn't matter what name it says. (This is not ordinarily a useful setting). +When the value is 1, libcurl will return a failure. It was previously (in +7.28.0 and earlier) a debug option of some sorts, but it is no longer +supported due to frequently leading to programmer mistakes. When the value is 0, the connection succeeds regardless of the names in the certificate. -The default, since 7.10, is 2. +The default value for this option is 2. + +This option controls checking the server's certificate's claimed identity. +The server could be lying. To control lying, see +\fICURLOPT_SSL_VERIFYPEER\fP. If libcurl is built against NSS and +\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_SSL_VERIFYHOST\fP +is ignored. -This option controls checking the server's claimed identity. The server could -be lying. To control lying, see \fICURLOPT_SSL_VERIFYPEER\fP. +.IP CURLOPT_CERTINFO +Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With +this enabled, libcurl (if built with OpenSSL) will extract lots of information +and data about the certificates in the certificate chain used in the SSL +connection. This data is then possible to extract after a transfer using +\fIcurl_easy_getinfo(3)\fP and its option \fICURLINFO_CERTINFO\fP. (Added in +7.19.1) +.IP CURLOPT_RANDOM_FILE +Pass a char * to a zero terminated file name. The file will be used to read +from to seed the random engine for SSL. The more random the specified file is, +the more secure the SSL connection will become. +.IP CURLOPT_EGDSOCKET +Pass a char * to the zero terminated path name to the Entropy Gathering Daemon +socket. It will be used to seed the random engine for SSL. .IP CURLOPT_SSL_CIPHER_LIST Pass a char *, pointing to a zero terminated string holding the list of ciphers to use for the SSL connection. The list must be syntactically correct, @@ -2005,7 +2519,7 @@ this option then all known ciphers are disabled and only those passed in are enabled. You'll find more details about the NSS cipher lists on this URL: -\fIhttp://directory.fedora.redhat.com/docs/mod_nss.html#Directives\fP +\fIhttp://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives\fP .IP CURLOPT_SSL_SESSIONID_CACHE Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set @@ -2013,6 +2527,16 @@ this to 1 to enable it. By default all transfers are done using the cache. While nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0) +.IP CURLOPT_SSL_OPTIONS +Pass a long with a bitmask to tell libcurl about specific SSL behaviors. + +CURLSSLOPT_ALLOW_BEAST is the only supported bit and by setting this the user +will tell libcurl to not attempt to use any workarounds for a security flaw +in the SSL3 and TLS1.0 protocols. If this option isn't used or this bit is +set to 0, the SSL layer libcurl uses may use a work-around for this flaw +although it might cause interoperability problems with some (older) SSL +implementations. WARNING: avoiding this work-around loosens the security, and +by setting this option to 1 you ask for exactly that. (Added in 7.25.0) .IP CURLOPT_KRBLEVEL Pass a char * as parameter. Set the kerberos security level for FTP; this also enables kerberos awareness. This is a string, \&'clear', \&'safe', @@ -2021,12 +2545,23 @@ of these, 'private' will be used. Set the string to NULL to disable kerberos support for FTP. (This option was known as CURLOPT_KRB4LEVEL up to 7.16.3) +.IP CURLOPT_GSSAPI_DELEGATION +Set the parameter to CURLGSSAPI_DELEGATION_FLAG to allow unconditional GSSAPI +credential delegation. The delegation is disabled by default since 7.21.7. +Set the parameter to CURLGSSAPI_DELEGATION_POLICY_FLAG to delegate only if +the OK-AS-DELEGATE flag is set in the service ticket in case this feature is +supported by the GSSAPI implementation and the definition of +GSS_C_DELEG_POLICY_FLAG was available at compile-time. +(Added in 7.22.0) .SH SSH OPTIONS .IP CURLOPT_SSH_AUTH_TYPES Pass a long set to a bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, -CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one. -(Added in 7.16.1) +CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT. Set CURLSSH_AUTH_ANY to let +libcurl pick a suitable one. Currently CURLSSH_AUTH_HOST has no effect. (Added +in 7.16.1) If CURLSSH_AUTH_AGENT is used, libcurl attempts to connect to +ssh-agent or pageant and let the agent attempt the authentication. (Added in +7.28.0) .IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 Pass a char * pointing to a string containing 32 hexadecimal digits. The string should be the 128 bit MD5 checksum of the remote host's public key, and @@ -2034,13 +2569,18 @@ libcurl will reject the connection to the host unless the md5sums match. This option is only for SCP and SFTP transfers. (Added in 7.17.1) .IP CURLOPT_SSH_PUBLIC_KEYFILE Pass a char * pointing to a file name for your public key. If not used, -libcurl defaults to using \fB~/.ssh/id_dsa.pub\fP. -(Added in 7.16.1) +libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment +variable is set, and just "id_dsa.pub" in the current directory if HOME is not +set. (Added in 7.16.1) +If an empty string is passed, libcurl will pass no public key to libssh2 +which then tries to compute it from the private key, this is known to work +when libssh2 1.4.0+ is linked against OpenSSL. (Added in 7.26.0) .IP CURLOPT_SSH_PRIVATE_KEYFILE Pass a char * pointing to a file name for your private key. If not used, -libcurl defaults to using \fB~/.ssh/id_dsa\fP. If the file is -password-protected, set the password with \fICURLOPT_KEYPASSWD\fP. (Added in -7.16.1) +libcurl defaults to \fB$HOME/.ssh/id_dsa\fP if the HOME environment variable +is set, and just "id_dsa" in the current directory if HOME is not set. If the +file is password-protected, set the password with +\fICURLOPT_KEYPASSWD\fP. (Added in 7.16.1) .IP CURLOPT_SSH_KNOWNHOSTS Pass a pointer to a zero terminated string holding the file name of the known_host file to use. The known_hosts file should use the OpenSSH file @@ -2051,7 +2591,10 @@ behavior on host and key (mis)matching. (Added in 7.19.6) .IP CURLOPT_SSH_KEYFUNCTION Pass a pointer to a curl_sshkeycallback function. It gets called when the known_host matching has been done, to allow the application to act and decide -for libcurl how to proceed. It gets passed the CURL handle, the key from the +for libcurl how to proceed. The callback will only be called if +\fICURLOPT_SSH_KNOWNHOSTS\fP is also set. + +The curl_sshkeycallback function gets passed the CURL handle, the key from the known_hosts file, the key from the remote site, info from libcurl on the matching status and a custom pointer (set with \fICURLOPT_SSH_KEYDATA\fP). It MUST return one of the following return codes to tell libcurl how to act: diff --git a/docs/libcurl/curl_easy_setopt.html b/docs/libcurl/curl_easy_setopt.html index 396c61b0a..f39674f7a 100644 --- a/docs/libcurl/curl_easy_setopt.html +++ b/docs/libcurl/curl_easy_setopt.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_setopt man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -54,104 +56,139 @@ p.roffit { <p class="level0">The <span Class="emphasis">handle</span> is the return code from a <a class="emphasis" href="./curl_easy_init.html">curl_easy_init(3)</a> or <a class="emphasis" href="./curl_easy_duphandle.html">curl_easy_duphandle(3)</a> call. <a name="BEHAVIOR"></a><h2 class="nroffsh">BEHAVIOR OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTVERBOSE"></a><span class="nroffip">CURLOPT_VERBOSE</span> -<p class="level1">Set the parameter to 1 to get the library to display a lot of verbose information about its operations. Very useful for libcurl and/or protocol debugging and understanding. The verbose information will be sent to stderr, or the stream set with <a class="emphasis" href="#CURLOPTSTDERR">CURLOPT_STDERR</a>. +<p class="level1">Set the parameter to 1 to get the library to display a lot of verbose information about its operations. Very useful for libcurl and/or protocol debugging and understanding. The verbose information will be sent to stderr, or the stream set with <a class="emphasis" href="#CURLOPTSTDERR">CURLOPT_STDERR</a>. The default value for this parameter is 0. <p class="level1">You hardly ever want this set in production use, you will almost always want this when you debug/report problems. Another neat option for debugging is the <a class="emphasis" href="#CURLOPTDEBUGFUNCTION">CURLOPT_DEBUGFUNCTION</a>. <p class="level0"><a name="CURLOPTHEADER"></a><span class="nroffip">CURLOPT_HEADER</span> -<p class="level1">A parameter set to 1 tells the library to include the header in the body output. This is only relevant for protocols that actually have headers preceding the data (like HTTP). +<p class="level1">A parameter set to 1 tells the library to include the header in the body output. This is only relevant for protocols that actually have headers preceding the data (like HTTP). The default value for this parameter is 0. <p class="level0"><a name="CURLOPTNOPROGRESS"></a><span class="nroffip">CURLOPT_NOPROGRESS</span> -<p class="level1">A parameter set to 1 tells the library to shut off the built-in progress meter completely. +<p class="level1">Pass a long. If set to 1, it tells the library to shut off the progress meter completely. It will also prevent the <a class="emphasis" href="#CURLOPTPROGRESSFUNCTION">CURLOPT_PROGRESSFUNCTION</a> from getting called. The default value for this parameter is 1. <p class="level1">Future versions of libcurl are likely to not have any built-in progress meter at all. <p class="level0"><a name="CURLOPTNOSIGNAL"></a><span class="nroffip">CURLOPT_NOSIGNAL</span> -<p class="level1">Pass a long. If it is 1, libcurl will not use any functions that install signal handlers or any functions that cause signals to be sent to the process. This option is mainly here to allow multi-threaded unix applications to still set/use all timeout options etc, without risking getting signals. (Added in 7.10) +<p class="level1">Pass a long. If it is 1, libcurl will not use any functions that install signal handlers or any functions that cause signals to be sent to the process. This option is mainly here to allow multi-threaded unix applications to still set/use all timeout options etc, without risking getting signals. The default value for this parameter is 0. (Added in 7.10) <p class="level1">If this option is set and libcurl has been built with the standard name resolver, timeouts will not occur while the name resolve takes place. Consider building libcurl with c-ares support to enable asynchronous DNS lookups, which enables nice timeouts for name resolves without signals. -<p class="level1">Setting <a class="emphasis" href="#CURLOPTNOSIGNAL">CURLOPT_NOSIGNAL</a> to 1 makes libcurl NOT ask the system to ignore SIGPIPE signals, which otherwise are sent by the system when trying to send data to a socket which is closed in the other end. libcurl makes an effort to never cause such SIGPIPEs to trigger, but some operating systems have no way to avoid them and even on those that have there are some corner cases when they may still happen, contrary to our desire. +<p class="level1">Setting <a class="emphasis" href="#CURLOPTNOSIGNAL">CURLOPT_NOSIGNAL</a> to 1 makes libcurl NOT ask the system to ignore SIGPIPE signals, which otherwise are sent by the system when trying to send data to a socket which is closed in the other end. libcurl makes an effort to never cause such SIGPIPEs to trigger, but some operating systems have no way to avoid them and even on those that have there are some corner cases when they may still happen, contrary to our desire. In addition, using <a class="emphasis" href="#CURLAUTHNTLMWB">CURLAUTH_NTLM_WB</a> authentication could cause a SIGCHLD signal to be raised. <p class="level0"><a name="CURLOPTWILDCARDMATCH"></a><span class="nroffip">CURLOPT_WILDCARDMATCH</span> <p class="level1">Set this option to 1 if you want to transfer multiple files according to a file name pattern. The pattern can be specified as part of the <a class="emphasis" href="#CURLOPTURL">CURLOPT_URL</a> option, using an fnmatch-like pattern (Shell Pattern Matching) in the last part of URL (file name). <p class="level1">By default, libcurl uses its internal wildcard matching implementation. You can provide your own matching function by the <a class="emphasis" href="#CURLOPTFNMATCHFUNCTION">CURLOPT_FNMATCH_FUNCTION</a> option. <p class="level1">This feature is only supported by the FTP download for now. <p class="level1">A brief introduction of its syntax follows: <p class="level2"> -<p class="level1"><a name="fBfP"></a><span class="nroffip">\fB*\fP - ASTERISK</span> +<p class="level1"><a name=""></a><span class="nroffip">* - ASTERISK</span> <p class="level2"><a href="ftp://example.com/some/path/">ftp://example.com/some/path/</a><span Class="bold">*.txt</span> (for all txt's from the root directory) <p class="level1"> <p class="level2"> -<p class="level1"><a name="fBfP"></a><span class="nroffip">\fB?\fP - QUESTION MARK</span> +<p class="level1"><a name=""></a><span class="nroffip">? - QUESTION MARK</span> <p class="level2">Question mark matches any (exactly one) character. <p class="level2"><a href="ftp://example.com/some/path/">ftp://example.com/some/path/</a><span Class="bold">photo?.jpeg</span> <p class="level1"> <p class="level2"> -<p class="level1"><a name="fBfP"></a><span class="nroffip">\fB[\fP - BRACKET EXPRESSION</span> +<p class="level1"><a name=""></a><span class="nroffip">[ - BRACKET EXPRESSION</span> <p class="level2">The left bracket opens a bracket expression. The question mark and asterisk have no special meaning in a bracket expression. Each bracket expression ends by the right bracket and matches exactly one character. Some examples follow: <p class="level2"><span Class="bold">[a-zA-Z0-9]</span> or <span Class="bold">[f-gF-G]</span> - character interval <p class="level2"><span Class="bold">[abc]</span> - character enumeration <p class="level2"><span Class="bold">[^abc]</span> or <span Class="bold">[!abc]</span> - negation -<p class="level2"><span Class="bold">[[:</span><span Class="emphasis">name</span><span Class="bold">:]]</span> class expression. Supported classes are <span Class="bold">alnum</span>,<span Class="bold">lower</span>, <span Class="bold">space</span>, <span Class="bold">alpha</span>, <span Class="bold">digit</span>, <span Class="bold">print</span>, <span Class="bold">upper</span>, <span Class="bold">blank</span>, <span Class="bold">graph</span>, <span Class="bold">xdigit</span>. +<p class="level2"><a class="bold" href="#">[[:</a><span Class="emphasis">name</span><a class="bold" href="#">:]]</a> class expression. Supported classes are <span Class="bold">alnum</span>,<span Class="bold">lower</span>, <span Class="bold">space</span>, <span Class="bold">alpha</span>, <span Class="bold">digit</span>, <span Class="bold">print</span>, <span Class="bold">upper</span>, <span Class="bold">blank</span>, <span Class="bold">graph</span>, <span Class="bold">xdigit</span>. <p class="level2"><span Class="bold">[][-!^]</span> - special case - matches only '-', ']', '[', '!' or '^'. These characters have no special purpose. -<p class="level2"><span Class="bold">[\[\]\\]</span> - escape syntax. Matches '[', ']' or '´. +<p class="level2"><a class="bold" href="#">[\[\]\\]</a> - escape syntax. Matches '[', ']' or '´. <p class="level2">Using the rules above, a file name pattern can be constructed: <p class="level2"><a href="ftp://example.com/some/path/">ftp://example.com/some/path/</a><span Class="bold">[a-z[:upper:]\\].jpeg</span> <p class="level1"> <p class="level1">(This was added in 7.21.0) <a name="CALLBACK"></a><h2 class="nroffsh">CALLBACK OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTWRITEFUNCTION"></a><span class="nroffip">CURLOPT_WRITEFUNCTION</span> -<p class="level1">Function pointer that should match the following prototype: <span class="bold">size_t function( void *ptr, size_t size, size_t nmemb, void *userdata);</span> This function gets called by libcurl as soon as there is data received that needs to be saved. The size of the data pointed to by <span Class="emphasis">ptr</span> is <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span>, it will not be zero terminated. Return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the transfer and return <span Class="emphasis">CURLE_WRITE_ERROR</span>. +<p class="level1">Pass a pointer to a function that matches the following prototype: <span Class="bold">size_t function( char *ptr, size_t size, size_t nmemb, void *userdata);</span> This function gets called by libcurl as soon as there is data received that needs to be saved. The size of the data pointed to by <span Class="emphasis">ptr</span> is <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span>, it will not be zero terminated. Return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the transfer and return <span Class="emphasis">CURLE_WRITE_ERROR</span>. <p class="level1">From 7.18.0, the function can return CURL_WRITEFUNC_PAUSE which then will cause writing to this connection to become paused. See <a class="emphasis" href="./curl_easy_pause.html">curl_easy_pause(3)</a> for further details. <p class="level1">This function may be called with zero bytes data if the transferred file is empty. <p class="level1">Set this option to NULL to get the internal default function. The internal default function will write the data to the FILE * given with <a class="emphasis" href="#CURLOPTWRITEDATA">CURLOPT_WRITEDATA</a>. <p class="level1">Set the <span Class="emphasis">userdata</span> argument with the <a class="emphasis" href="#CURLOPTWRITEDATA">CURLOPT_WRITEDATA</a> option. -<p class="level1">The callback function will be passed as much data as possible in all invokes, but you cannot possibly make any assumptions. It may be one byte, it may be thousands. The maximum amount of data that can be passed to the write callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE. +<p class="level1">The callback function will be passed as much data as possible in all invokes, but you cannot possibly make any assumptions. It may be one byte, it may be thousands. The maximum amount of body data that can be passed to the write callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE (the usual default is 16K). If you however have <a class="emphasis" href="#CURLOPTHEADER">CURLOPT_HEADER</a> set, which sends header data to the write callback, you can get up to <span Class="emphasis">CURL_MAX_HTTP_HEADER</span> bytes of header data passed into it. This usually means 100K. <p class="level0"><a name="CURLOPTWRITEDATA"></a><span class="nroffip">CURLOPT_WRITEDATA</span> -<p class="level1">Data pointer to pass to the file write function. If you use the <a class="emphasis" href="#CURLOPTWRITEFUNCTION">CURLOPT_WRITEFUNCTION</a> option, this is the pointer you'll get as input. If you don't use a callback, you must pass a 'FILE *' as libcurl will pass this to fwrite() when writing data. +<p class="level1">Data pointer to pass to the file write function. If you use the <a class="emphasis" href="#CURLOPTWRITEFUNCTION">CURLOPT_WRITEFUNCTION</a> option, this is the pointer you'll get as input. If you don't use a callback, you must pass a 'FILE *' (cast to 'void *') as libcurl will pass this to fwrite() when writing data. By default, the value of this parameter is unspecified. <p class="level1">The internal <a class="emphasis" href="#CURLOPTWRITEFUNCTION">CURLOPT_WRITEFUNCTION</a> will write the data to the FILE * given with this option, or to stdout if this option hasn't been set. <p class="level1">If you're using libcurl as a win32 DLL, you <span Class="bold">MUST</span> use the <a class="emphasis" href="#CURLOPTWRITEFUNCTION">CURLOPT_WRITEFUNCTION</a> if you set this option or you will experience crashes. <p class="level1">This option is also known with the older name <span Class="emphasis">CURLOPT_FILE</span>, the name <a class="emphasis" href="#CURLOPTWRITEDATA">CURLOPT_WRITEDATA</a> was introduced in 7.9.7. <p class="level0"><a name="CURLOPTREADFUNCTION"></a><span class="nroffip">CURLOPT_READFUNCTION</span> -<p class="level1">Function pointer that should match the following prototype: <span class="bold">size_t function( void *ptr, size_t size, size_t nmemb, void *userdata);</span> This function gets called by libcurl as soon as it needs to read data in order to send it to the peer. The data area pointed at by the pointer <span Class="emphasis">ptr</span> may be filled with at most <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span> number of bytes. Your function must return the actual number of bytes that you stored in that memory area. Returning 0 will signal end-of-file to the library and cause it to stop the current transfer. +<p class="level1">Pass a pointer to a function that matches the following prototype: <span Class="bold">size_t function( void *ptr, size_t size, size_t nmemb, void *userdata);</span> This function gets called by libcurl as soon as it needs to read data in order to send it to the peer. The data area pointed at by the pointer <span Class="emphasis">ptr</span> may be filled with at most <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span> number of bytes. Your function must return the actual number of bytes that you stored in that memory area. Returning 0 will signal end-of-file to the library and cause it to stop the current transfer. <p class="level1">If you stop the current transfer by returning 0 "pre-maturely" (i.e before the server expected it, like when you've said you will upload N bytes and you upload less than N bytes), you may experience that the server "hangs" waiting for the rest of the data that won't come. <p class="level1">The read callback may return <span Class="emphasis">CURL_READFUNC_ABORT</span> to stop the current operation immediately, resulting in a <span Class="emphasis">CURLE_ABORTED_BY_CALLBACK</span> error code from the transfer (Added in 7.12.1) <p class="level1">From 7.18.0, the function can return CURL_READFUNC_PAUSE which then will cause reading from this connection to become paused. See <a class="emphasis" href="./curl_easy_pause.html">curl_easy_pause(3)</a> for further details. +<p class="level1"><span Class="bold">Bugs</span>: when doing TFTP uploads, you must return the exact amount of data that the callback wants, or it will be considered the final packet by the server end and the transfer will end there. <p class="level1">If you set this callback pointer to NULL, or don't set it at all, the default internal read function will be used. It is doing an fread() on the FILE * userdata set with <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a>. <p class="level0"><a name="CURLOPTREADDATA"></a><span class="nroffip">CURLOPT_READDATA</span> -<p class="level1">Data pointer to pass to the file read function. If you use the <a class="emphasis" href="#CURLOPTREADFUNCTION">CURLOPT_READFUNCTION</a> option, this is the pointer you'll get as input. If you don't specify a read callback but instead rely on the default internal read function, this data must be a valid readable FILE *. +<p class="level1">Data pointer to pass to the file read function. If you use the <a class="emphasis" href="#CURLOPTREADFUNCTION">CURLOPT_READFUNCTION</a> option, this is the pointer you'll get as input. If you don't specify a read callback but instead rely on the default internal read function, this data must be a valid readable FILE * (cast to 'void *'). <p class="level1">If you're using libcurl as a win32 DLL, you MUST use a <a class="emphasis" href="#CURLOPTREADFUNCTION">CURLOPT_READFUNCTION</a> if you set this option. <p class="level1">This option was also known by the older name <span Class="emphasis">CURLOPT_INFILE</span>, the name <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a> was introduced in 7.9.7. <p class="level0"><a name="CURLOPTIOCTLFUNCTION"></a><span class="nroffip">CURLOPT_IOCTLFUNCTION</span> -<p class="level1">Function pointer that should match the <span Class="emphasis">curl_ioctl_callback</span> prototype found in <span Class="emphasis"><curl/curl.h></span>. This function gets called by libcurl when something special I/O-related needs to be done that the library can't do by itself. For now, rewinding the read data stream is the only action it can request. The rewinding of the read data stream may be necessary when doing a HTTP PUT or POST with a multi-pass authentication method. (Option added in 7.12.3). -<p class="level1">Use <a class="emphasis" href="#CURLOPTSEEKFUNCTION">CURLOPT_SEEKFUNCTION</a> instead to provide seeking! +<p class="level1">Pass a pointer to a function that matches the following prototype: <span Class="bold">curlioerr function(CURL *handle, int cmd, void *clientp);</span>. This function gets called by libcurl when something special I/O-related needs to be done that the library can't do by itself. For now, rewinding the read data stream is the only action it can request. The rewinding of the read data stream may be necessary when doing a HTTP PUT or POST with a multi-pass authentication method. By default, this parameter is set to NULL. (Option added in 7.12.3). +<p class="level1">Use <a class="emphasis" href="#CURLOPTSEEKFUNCTION">CURLOPT_SEEKFUNCTION</a> instead to provide seeking! If <a class="emphasis" href="#CURLOPTSEEKFUNCTION">CURLOPT_SEEKFUNCTION</a> is set, this parameter will be ignored when seeking. <p class="level0"><a name="CURLOPTIOCTLDATA"></a><span class="nroffip">CURLOPT_IOCTLDATA</span> -<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the 3rd argument in the ioctl callback set with <a class="emphasis" href="#CURLOPTIOCTLFUNCTION">CURLOPT_IOCTLFUNCTION</a>. (Option added in 7.12.3) +<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the 3rd argument in the ioctl callback set with <a class="emphasis" href="#CURLOPTIOCTLFUNCTION">CURLOPT_IOCTLFUNCTION</a>. By default, the value of this parameter is unspecified. (Option added in 7.12.3) <p class="level0"><a name="CURLOPTSEEKFUNCTION"></a><span class="nroffip">CURLOPT_SEEKFUNCTION</span> -<p class="level1">Function pointer that should match the following prototype: <span class="emphasis">int function(void *instream, curl_off_t offset, int origin);</span> This function gets called by libcurl to seek to a certain position in the input stream and can be used to fast forward a file in a resumed upload (instead of reading all uploaded bytes with the normal read function/callback). It is also called to rewind a stream when doing a HTTP PUT or POST with a multi-pass authentication method. The function shall work like "fseek" or "lseek" and accepted SEEK_SET, SEEK_CUR and SEEK_END as argument for origin, although (in 7.18.0) libcurl only passes SEEK_SET. The callback must return 0 (CURL_SEEKFUNC_OK) on success, 1 (CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2 (CURL_SEEKFUNC_CANTSEEK) to indicate that while the seek failed, libcurl is free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar. +<p class="level1">Pass a pointer to a function that matches the following prototype: <span class="bold">int function(void *instream, curl_off_t offset, int origin);</span> This function gets called by libcurl to seek to a certain position in the input stream and can be used to fast forward a file in a resumed upload (instead of reading all uploaded bytes with the normal read function/callback). It is also called to rewind a stream when doing a HTTP PUT or POST with a multi-pass authentication method. The function shall work like "fseek" or "lseek" and accepted SEEK_SET, SEEK_CUR and SEEK_END as argument for origin, although (in 7.18.0) libcurl only passes SEEK_SET. The callback must return 0 (CURL_SEEKFUNC_OK) on success, 1 (CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2 (CURL_SEEKFUNC_CANTSEEK) to indicate that while the seek failed, libcurl is free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar. +<p class="level1">By default, this parameter is unset. <p class="level1">If you forward the input arguments directly to "fseek" or "lseek", note that the data type for <span Class="emphasis">offset</span> is not the same as defined for curl_off_t on many systems! (Option added in 7.18.0) <p class="level0"><a name="CURLOPTSEEKDATA"></a><span class="nroffip">CURLOPT_SEEKDATA</span> -<p class="level1">Data pointer to pass to the file read function. If you use the <a class="emphasis" href="#CURLOPTSEEKFUNCTION">CURLOPT_SEEKFUNCTION</a> option, this is the pointer you'll get as input. If you don't specify a seek callback, NULL is passed. (Option added in 7.18.0) +<p class="level1">Data pointer to pass to the file seek function. If you use the <a class="emphasis" href="#CURLOPTSEEKFUNCTION">CURLOPT_SEEKFUNCTION</a> option, this is the pointer you'll get as input. If you don't specify a seek callback, NULL is passed. (Option added in 7.18.0) <p class="level0"><a name="CURLOPTSOCKOPTFUNCTION"></a><span class="nroffip">CURLOPT_SOCKOPTFUNCTION</span> -<p class="level1">Function pointer that should match the <span Class="emphasis">curl_sockopt_callback</span> prototype found in <span Class="emphasis"><curl/curl.h></span>. This function gets called by libcurl after the socket() call but before the connect() call. The callback's <span Class="emphasis">purpose</span> argument identifies the exact purpose for this particular socket, and currently only one value is supported: <span Class="emphasis">CURLSOCKTYPE_IPCXN</span> for the primary connection (meaning the control connection in the FTP case). Future versions of libcurl may support more purposes. It passes the newly created socket descriptor so additional setsockopt() calls can be done at the user's discretion. Return 0 (zero) from the callback on success. Return 1 from the callback function to signal an unrecoverable error to the library and it will close the socket and return <span Class="emphasis">CURLE_COULDNT_CONNECT</span>. (Option added in 7.15.6.) +<p class="level1">Pass a pointer to a function that matches the following prototype: <span class="bold">int function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);</span>. By default, this parameter is unset. If set, this function gets called by libcurl after the socket() call but before the connect() call. The callback's <span Class="emphasis">purpose</span> argument identifies the exact purpose for this particular socket: +<p class="level1"><span Class="emphasis">CURLSOCKTYPE_IPCXN</span> for actively created connections or since 7.28.0 <span Class="emphasis">CURLSOCKTYPE_ACCEPT</span> for FTP when the connection was setup with PORT/EPSV (in earlier versions these sockets weren't passed to this callback). +<p class="level1">Future versions of libcurl may support more purposes. It passes the newly created socket descriptor so additional setsockopt() calls can be done at the user's discretion. Return 0 (zero) from the callback on success. Return 1 from the callback function to signal an unrecoverable error to the library and it will close the socket and return <span Class="emphasis">CURLE_COULDNT_CONNECT</span>. (Option added in 7.16.0) +<p class="level1">Added in 7.21.5, the callback function may return <span Class="emphasis">CURL_SOCKOPT_ALREADY_CONNECTED</span>, which tells libcurl that the socket is in fact already connected and then libcurl will not attempt to connect it. <p class="level0"><a name="CURLOPTSOCKOPTDATA"></a><span class="nroffip">CURLOPT_SOCKOPTDATA</span> -<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the sockopt callback set with <a class="emphasis" href="#CURLOPTSOCKOPTFUNCTION">CURLOPT_SOCKOPTFUNCTION</a>. (Option added in 7.15.6.) +<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the sockopt callback set with <a class="emphasis" href="#CURLOPTSOCKOPTFUNCTION">CURLOPT_SOCKOPTFUNCTION</a>. The default value of this parameter is unspecified. (Option added in 7.16.0) <p class="level0"><a name="CURLOPTOPENSOCKETFUNCTION"></a><span class="nroffip">CURLOPT_OPENSOCKETFUNCTION</span> -<p class="level1">Function pointer that should match the <span Class="emphasis">curl_opensocket_callback</span> prototype found in <span Class="emphasis"><curl/curl.h></span>. This function gets called by libcurl instead of the <span Class="emphasis">socket(2)</span> call. The callback's <span Class="emphasis">purpose</span> argument identifies the exact purpose for this particular socket, and currently only one value is supported: <span Class="emphasis">CURLSOCKTYPE_IPCXN</span> for the primary connection (meaning the control connection in the FTP case). Future versions of libcurl may support more purposes. It passes the resolved peer address as a <span Class="emphasis">address</span> argument so the callback can modify the address or refuse to connect at all. The callback function should return the socket or <span Class="emphasis">CURL_SOCKET_BAD</span> in case no connection should be established or any error detected. Any additional <span Class="emphasis">setsockopt(2)</span> calls can be done on the socket at the user's discretion. <span Class="emphasis">CURL_SOCKET_BAD</span> return value from the callback function will signal an unrecoverable error to the library and it will return <span Class="emphasis">CURLE_COULDNT_CONNECT</span>. This return code can be used for IP address blacklisting. The default behavior is: <pre> +<p class="level1">Pass a pointer to a function that matches the following prototype: <span class="bold">curl_socket_t function(void *clientp, curlsocktype purpose, struct curl_sockaddr *address);</span>. This function gets called by libcurl instead of the <span Class="emphasis">socket(2)</span> call. The callback's <span Class="emphasis">purpose</span> argument identifies the exact purpose for this particular socket: <span Class="emphasis">CURLSOCKTYPE_IPCXN</span> is for IP based connections. Future versions of libcurl may support more purposes. It passes the resolved peer address as a <span Class="emphasis">address</span> argument so the callback can modify the address or refuse to connect at all. The callback function should return the socket or <span Class="emphasis">CURL_SOCKET_BAD</span> in case no connection could be established or another error was detected. Any additional <span Class="emphasis">setsockopt(2)</span> calls can be done on the socket at the user's discretion. <span Class="emphasis">CURL_SOCKET_BAD</span> return value from the callback function will signal an unrecoverable error to the library and it will return <span Class="emphasis">CURLE_COULDNT_CONNECT</span>. This return code can be used for IP address blacklisting. The default behavior is: <pre> <p class="level1"> return socket(addr->family, addr->socktype, addr->protocol); </pre> <p class="level1">(Option added in 7.17.1.) <p class="level0"><a name="CURLOPTOPENSOCKETDATA"></a><span class="nroffip">CURLOPT_OPENSOCKETDATA</span> -<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the opensocket callback set with <a class="emphasis" href="#CURLOPTOPENSOCKETFUNCTION">CURLOPT_OPENSOCKETFUNCTION</a>. (Option added in 7.17.1.) +<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the opensocket callback set with <a class="emphasis" href="#CURLOPTOPENSOCKETFUNCTION">CURLOPT_OPENSOCKETFUNCTION</a>. The default value of this parameter is unspecified. (Option added in 7.17.1.) +<p class="level0"><a name="CURLOPTCLOSESOCKETFUNCTION"></a><span class="nroffip">CURLOPT_CLOSESOCKETFUNCTION</span> +<p class="level1">Pass a pointer to a function that matches the following prototype: <span class="bold">int function(void *clientp, curl_socket_t item);</span>. This function gets called by libcurl instead of the <span Class="emphasis">close(3)</span> or <span Class="emphasis">closesocket(3)</span> call when sockets are closed (not for any other file descriptors). This is pretty much the reverse to the <a class="emphasis" href="#CURLOPTOPENSOCKETFUNCTION">CURLOPT_OPENSOCKETFUNCTION</a> option. Return 0 to signal success and 1 if there was an error. (Option added in 7.21.7) +<p class="level0"><a name="CURLOPTCLOSESOCKETDATA"></a><span class="nroffip">CURLOPT_CLOSESOCKETDATA</span> +<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the closesocket callback set with <a class="emphasis" href="#CURLOPTCLOSESOCKETFUNCTION">CURLOPT_CLOSESOCKETFUNCTION</a>. The default value of this parameter is unspecified. (Option added in 7.21.7) <p class="level0"><a name="CURLOPTPROGRESSFUNCTION"></a><span class="nroffip">CURLOPT_PROGRESSFUNCTION</span> -<p class="level1">Function pointer that should match the <span Class="emphasis">curl_progress_callback</span> prototype found in <span Class="emphasis"><curl/curl.h></span>. This function gets called by libcurl instead of its internal equivalent with a frequent interval during operation (roughly once per second or sooner) no matter if data is being transfered or not. Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0). Returning a non-zero value from this callback will cause libcurl to abort the transfer and return <span Class="emphasis">CURLE_ABORTED_BY_CALLBACK</span>. +<p class="level1">Pass a pointer to a function that matches the following prototype: +<p class="level1"><span class="bold">int function(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow);</span> +<p class="level1">This function gets called by libcurl instead of its internal equivalent with a frequent interval. While data is being transferred it will be called very frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second. +<p class="level1"><span Class="emphasis">clientp</span> is the pointer set with <a class="emphasis" href="#CURLOPTPROGRESSDATA">CURLOPT_PROGRESSDATA</a>, it is not actually used by libcurl but is only passed along from the application to the callback. +<p class="level1">The callback gets told how much data libcurl will transfer and has transferred, in number of bytes. <span Class="emphasis">dltotal</span> is the total number of bytes libcurl expects to download in this transfer. <span Class="emphasis">dlnow</span> is the number of bytes downloaded so far. <span Class="emphasis">ultotal</span> is the total number of bytes libcurl expects to upload in this transfer. <span Class="emphasis">ulnow</span> is the number of bytes uploaded so far. +<p class="level1">Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0). Many times the callback will be called one or more times first, before it knows the data sizes so a program must be made to handle that. +<p class="level1">Returning a non-zero value from this callback will cause libcurl to abort the transfer and return <span Class="emphasis">CURLE_ABORTED_BY_CALLBACK</span>. <p class="level1">If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers. <p class="level1"><a class="emphasis" href="#CURLOPTNOPROGRESS">CURLOPT_NOPROGRESS</a> must be set to 0 to make this function actually get called. +<p class="level0"><a name="CURLOPTXFERINFOFUNCTION"></a><span class="nroffip">CURLOPT_XFERINFOFUNCTION</span> +<p class="level1">Pass a pointer to a function that matches the following prototype: +<p class="level1"><pre> +<p class="level1"><span class="bold">int function(void *clientp, curl_off_t dltotal, curl_off_t dlnow, + curl_off_t ultotal, curl_off_t ulnow);</span> + </pre> + +<p class="level1"> +<p class="level1">This function gets called by libcurl instead of its internal equivalent with a frequent interval. While data is being transferred it will be called very frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second. +<p class="level1"><span Class="emphasis">clientp</span> is the pointer set with <a class="emphasis" href="#CURLOPTXFERINFODATA">CURLOPT_XFERINFODATA</a>, it is only passed along from the application to the callback. +<p class="level1">The callback gets told how much data libcurl will transfer and has transferred, in number of bytes. <span Class="emphasis">dltotal</span> is the total number of bytes libcurl expects to download in this transfer. <span Class="emphasis">dlnow</span> is the number of bytes downloaded so far. <span Class="emphasis">ultotal</span> is the total number of bytes libcurl expects to upload in this transfer. <span Class="emphasis">ulnow</span> is the number of bytes uploaded so far. +<p class="level1">Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0). Many times the callback will be called one or more times first, before it knows the data sizes so a program must be made to handle that. +<p class="level1">Returning a non-zero value from this callback will cause libcurl to abort the transfer and return <span Class="emphasis">CURLE_ABORTED_BY_CALLBACK</span>. +<p class="level1">If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers. +<p class="level1"><a class="emphasis" href="#CURLOPTNOPROGRESS">CURLOPT_NOPROGRESS</a> must be set to 0 to make this function actually get called. +<p class="level1">(Added in 7.32.0) <p class="level0"><a name="CURLOPTPROGRESSDATA"></a><span class="nroffip">CURLOPT_PROGRESSDATA</span> -<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with <a class="emphasis" href="#CURLOPTPROGRESSFUNCTION">CURLOPT_PROGRESSFUNCTION</a>. +<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with <a class="emphasis" href="#CURLOPTPROGRESSFUNCTION">CURLOPT_PROGRESSFUNCTION</a>. The default value of this parameter is unspecified. +<p class="level0"><a name="CURLOPTXFERINFODATA"></a><span class="nroffip">CURLOPT_XFERINFODATA</span> +<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with <a class="emphasis" href="#CURLOPTXFERINFOFUNCTION">CURLOPT_XFERINFOFUNCTION</a>. The default value of this parameter is unspecified. This option is an alias for CURLOPT_PROGRESSDATA. (Added in 7.32.0) <p class="level0"><a name="CURLOPTHEADERFUNCTION"></a><span class="nroffip">CURLOPT_HEADERFUNCTION</span> -<p class="level1">Function pointer that should match the following prototype: <span class="emphasis">size_t function( void *ptr, size_t size, size_t nmemb, void *userdata);</span>. This function gets called by libcurl as soon as it has received header data. The header callback will be called once for each header and only complete header lines are passed on to the callback. Parsing headers should be easy enough using this. The size of the data pointed to by <span Class="emphasis">ptr</span> is <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span>. Do not assume that the header line is zero terminated! The pointer named <span Class="emphasis">userdata</span> is the one you set with the <a class="emphasis" href="#CURLOPTWRITEHEADER">CURLOPT_WRITEHEADER</a> option. The callback function must return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the transfer and return <span Class="emphasis">CURL_WRITE_ERROR</span>. +<p class="level1">Pass a pointer to a function that matches the following prototype: <span class="bold">size_t function( void *ptr, size_t size, size_t nmemb, void *userdata);</span>. This function gets called by libcurl as soon as it has received header data. The header callback will be called once for each header and only complete header lines are passed on to the callback. Parsing headers is very easy using this. The size of the data pointed to by <span Class="emphasis">ptr</span> is <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span>. Do not assume that the header line is zero terminated! The pointer named <span Class="emphasis">userdata</span> is the one you set with the <a class="emphasis" href="#CURLOPTWRITEHEADER">CURLOPT_WRITEHEADER</a> option. The callback function must return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the transfer and return <span Class="emphasis">CURL_WRITE_ERROR</span>. +<p class="level1">A complete HTTP header that is passed to this function can be up to <span Class="emphasis">CURL_MAX_HTTP_HEADER</span> (100K) bytes. <p class="level1">If this option is not set, or if it is set to NULL, but <span Class="emphasis">CURLOPT_HEADERDATA</span> (<a class="emphasis" href="#CURLOPTWRITEHEADER">CURLOPT_WRITEHEADER</a>) is set to anything but NULL, the function used to accept response data will be used instead. That is, it will be the function specified with <a class="emphasis" href="#CURLOPTWRITEFUNCTION">CURLOPT_WRITEFUNCTION</a>, or if it is not specified or NULL - the default, stream-writing function. <p class="level1">It's important to note that the callback will be invoked for the headers of all responses received after initiating a request and not just the final response. This includes all responses which occur during authentication negotiation. If you need to operate on only the headers from the final response, you will need to collect headers in the callback yourself and use HTTP status lines, for example, to delimit response boundaries. -<p class="level1">Since 7.14.1: When a server sends a chunked encoded transfer, it may contain a trailer. That trailer is identical to a HTTP header and if such a trailer is received it is passed to the application using this callback as well. There are several ways to detect it being a trailer and not an ordinary header: 1) it comes after the response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: header among the response-headers mention what header to expect in the trailer. +<p class="level1">When a server sends a chunked encoded transfer, it may contain a trailer. That trailer is identical to a HTTP header and if such a trailer is received it is passed to the application using this callback as well. There are several ways to detect it being a trailer and not an ordinary header: 1) it comes after the response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: header among the regular response-headers mention what header(s) to expect in the trailer. +<p class="level1">For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get called with the server responses to the commands that libcurl sends. <p class="level0"><a name="CURLOPTWRITEHEADER"></a><span class="nroffip">CURLOPT_WRITEHEADER</span> -<p class="level1">(This option is also known as <span Class="bold">CURLOPT_HEADERDATA</span>) Pass a pointer to be used to write the header part of the received data to. If you don't use your own callback to take care of the writing, this must be a valid FILE *. See also the <a class="emphasis" href="#CURLOPTHEADERFUNCTION">CURLOPT_HEADERFUNCTION</a> option above on how to set a custom get-all-headers callback. +<p class="level1">(This option is also known as <span Class="bold">CURLOPT_HEADERDATA</span>) Pass a pointer to be used to write the header part of the received data to. If you don't use <a class="emphasis" href="#CURLOPTWRITEFUNCTION">CURLOPT_WRITEFUNCTION</a> or <a class="emphasis" href="#CURLOPTHEADERFUNCTION">CURLOPT_HEADERFUNCTION</a> to take care of the writing, this must be a valid FILE * as the internal default will then be a plain fwrite(). See also the <a class="emphasis" href="#CURLOPTHEADERFUNCTION">CURLOPT_HEADERFUNCTION</a> option above on how to set a custom get-all-headers callback. <p class="level0"><a name="CURLOPTDEBUGFUNCTION"></a><span class="nroffip">CURLOPT_DEBUGFUNCTION</span> -<p class="level1">Function pointer that should match the following prototype: <span class="emphasis">int curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);</span> <a class="emphasis" href="#CURLOPTDEBUGFUNCTION">CURLOPT_DEBUGFUNCTION</a> replaces the standard debug function used when <a class="emphasis" href="#CURLOPTVERBOSE">CURLOPT_VERBOSE </a> is in effect. This callback receives debug information, as specified with the <span Class="bold">curl_infotype</span> argument. This function must return 0. The data pointed to by the char * passed to this function WILL NOT be zero terminated, but will be exactly of the size as told by the size_t argument. +<p class="level1">Pass a pointer to a function that matches the following prototype: <span class="bold">int curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);</span> <a class="emphasis" href="#CURLOPTDEBUGFUNCTION">CURLOPT_DEBUGFUNCTION</a> replaces the standard debug function used when <a class="emphasis" href="#CURLOPTVERBOSE">CURLOPT_VERBOSE </a> is in effect. This callback receives debug information, as specified with the <span Class="bold">curl_infotype</span> argument. This function must return 0. The data pointed to by the char * passed to this function WILL NOT be zero terminated, but will be exactly of the size as told by the size_t argument. <p class="level1">Available curl_infotype values: <p class="level2"> <p class="level1"><a name="CURLINFOTEXT"></a><span class="nroffip">CURLINFO_TEXT</span> @@ -169,9 +206,9 @@ p.roffit { <p class="level1">Pass a pointer to whatever you want passed in to your <a class="emphasis" href="#CURLOPTDEBUGFUNCTION">CURLOPT_DEBUGFUNCTION</a> in the last void * argument. This pointer is not used by libcurl, it is only passed to the callback. <p class="level0"><a name="CURLOPTSSLCTXFUNCTION"></a><span class="nroffip">CURLOPT_SSL_CTX_FUNCTION</span> <p class="level1">This option does only function for libcurl powered by OpenSSL. If libcurl was built against another SSL library, this functionality is absent. -<p class="level1">Function pointer that should match the following prototype: <span class="bold">CURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);</span> This function gets called by libcurl just before the initialization of an SSL connection after having processed all other SSL related options to give a last chance to an application to modify the behaviour of openssl's ssl initialization. The <span Class="emphasis">sslctx</span> parameter is actually a pointer to an openssl <span Class="emphasis">SSL_CTX</span>. If an error is returned no attempt to establish a connection is made and the perform operation will return the error code from this callback function. Set the <span Class="emphasis">parm</span> argument with the <a class="emphasis" href="#CURLOPTSSLCTXDATA">CURLOPT_SSL_CTX_DATA</a> option. This option was introduced in 7.11.0. +<p class="level1">Pass a pointer to a function that matches the following prototype: <span Class="bold">CURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);</span> This function gets called by libcurl just before the initialization of a SSL connection after having processed all other SSL related options to give a last chance to an application to modify the behaviour of openssl's ssl initialization. The <span Class="emphasis">sslctx</span> parameter is actually a pointer to an openssl <span Class="emphasis">SSL_CTX</span>. If an error is returned no attempt to establish a connection is made and the perform operation will return the error code from this callback function. Set the <span Class="emphasis">parm</span> argument with the <a class="emphasis" href="#CURLOPTSSLCTXDATA">CURLOPT_SSL_CTX_DATA</a> option. This option was introduced in 7.11.0. <p class="level1">This function will get called on all new connections made to a server, during the SSL negotiation. The SSL_CTX pointer will be a new one every time. -<p class="level1">To use this properly, a non-trivial amount of knowledge of the openssl libraries is necessary. For example, using this function allows you to use openssl callbacks to add additional validation code for certificates, and even to change the actual URI of an HTTPS request (example used in the lib509 test case). See also the example section for a replacement of the key, certificate and trust file settings. +<p class="level1">To use this properly, a non-trivial amount of knowledge of the openssl libraries is necessary. For example, using this function allows you to use openssl callbacks to add additional validation code for certificates, and even to change the actual URI of a HTTPS request (example used in the lib509 test case). See also the example section for a replacement of the key, certificate and trust file settings. <p class="level0"><a name="CURLOPTSSLCTXDATA"></a><span class="nroffip">CURLOPT_SSL_CTX_DATA</span> <p class="level1">Data pointer to pass to the ssl context callback set by the option <a class="emphasis" href="#CURLOPTSSLCTXFUNCTION">CURLOPT_SSL_CTX_FUNCTION</a>, this is the pointer you'll get as third parameter, otherwise <span Class="bold">NULL</span>. (Added in 7.11.0) <p class="level0"><a name="CURLOPTCONVTONETWORKFUNCTION"></a><span class="nroffip">CURLOPT_CONV_TO_NETWORK_FUNCTION</span> @@ -179,7 +216,7 @@ p.roffit { <p class="level0"><a name="CURLOPTCONVFROMNETWORKFUNCTION"></a><span class="nroffip">CURLOPT_CONV_FROM_NETWORK_FUNCTION</span> <p class="level1"> <p class="level0"><a name="CURLOPTCONVFROMUTF8FUNCTION"></a><span class="nroffip">CURLOPT_CONV_FROM_UTF8_FUNCTION</span> -<p class="level1">Function pointers that should match the following prototype: CURLcode function(char *ptr, size_t length); +<p class="level1">Pass a pointer to a function that matches the following prototype: <span Class="bold">CURLcode function(char *ptr, size_t length);</span> <p class="level1">These three options apply to non-ASCII platforms only. They are available only if <span Class="bold">CURL_DOES_CONVERSIONS</span> was defined when libcurl was built. When this is the case, <a class="emphasis" href="./curl_version_info.html">curl_version_info(3)</a> will return the CURL_VERSION_CONV feature bit set. <p class="level1">The data to be converted is in a buffer pointed to by the ptr parameter. The amount of data to convert is indicated by the length parameter. The converted data overlays the input data in the buffer pointed to by the ptr parameter. CURLE_OK should be returned upon successful conversion. A CURLcode return value defined by curl.h, such as CURLE_CONV_FAILED, should be returned if an error was encountered. <p class="level1"><a class="bold" href="#CURLOPTCONVTONETWORKFUNCTION">CURLOPT_CONV_TO_NETWORK_FUNCTION</a> and <a class="bold" href="#CURLOPTCONVFROMNETWORKFUNCTION">CURLOPT_CONV_FROM_NETWORK_FUNCTION</a> convert between the host encoding and the network encoding. They are used when commands or ASCII data are sent/received over the network. @@ -192,28 +229,28 @@ p.roffit { <p class="level1"> #define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" <p class="level1">You will need to override these definitions if they are different on your system. <p class="level0"><a name="CURLOPTINTERLEAVEFUNCTION"></a><span class="nroffip">CURLOPT_INTERLEAVEFUNCTION</span> -<p class="level1">Function pointer that should match the following prototype: <span class="emphasis">size_t function( void *ptr, size_t size, size_t nmemb, void *userdata)</span>. This function gets called by libcurl as soon as it has received interleaved RTP data. This function gets called for each $ block and therefore contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl writes the interleaved header as well as the included data for each call. The first byte is always an ASCII dollar sign. The dollar sign is followed by a one byte channel identifier and then a 2 byte integer length in network byte order. See <span Class="emphasis">RFC 2326 Section 10.12</span> for more information on how RTP interleaving behaves. If unset or set to NULL, curl will use the default write function. -<p class="level1">Interleaved RTP poses some challeneges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service the RTP in a timely fashion. If the RTP data is not handled quickly, subsequent response processing may become unreasonably delayed and the connection may close. The application may use <a class="emphasis" href="#CURLRTSPREQRECEIVE">CURL_RTSPREQ_RECEIVE</a> to service RTP data when no requests are desired. If the application makes a request, (e.g. <a class="emphasis" href="#CURLRTSPREQPAUSE">CURL_RTSPREQ_PAUSE</a>) then the response handler will process any pending RTP data before marking the request as finished. (Added in 7.20.0) +<p class="level1">Pass a pointer to a function that matches the following prototype: <span class="bold">size_t function( void *ptr, size_t size, size_t nmemb, void *userdata)</span>. This function gets called by libcurl as soon as it has received interleaved RTP data. This function gets called for each $ block and therefore contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl writes the interleaved header as well as the included data for each call. The first byte is always an ASCII dollar sign. The dollar sign is followed by a one byte channel identifier and then a 2 byte integer length in network byte order. See <span Class="emphasis"><a href="http://www.ietf.org/rfc/rfc2326.txt">RFC 2326</a> Section 10.12</span> for more information on how RTP interleaving behaves. If unset or set to NULL, curl will use the default write function. +<p class="level1">Interleaved RTP poses some challenges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service the RTP in a timely fashion. If the RTP data is not handled quickly, subsequent response processing may become unreasonably delayed and the connection may close. The application may use <a class="emphasis" href="#CURLRTSPREQRECEIVE">CURL_RTSPREQ_RECEIVE</a> to service RTP data when no requests are desired. If the application makes a request, (e.g. <a class="emphasis" href="#CURLRTSPREQPAUSE">CURL_RTSPREQ_PAUSE</a>) then the response handler will process any pending RTP data before marking the request as finished. (Added in 7.20.0) <p class="level0"><a name="CURLOPTINTERLEAVEDATA"></a><span class="nroffip">CURLOPT_INTERLEAVEDATA</span> <p class="level1">This is the userdata pointer that will be passed to <a class="emphasis" href="#CURLOPTINTERLEAVEFUNCTION">CURLOPT_INTERLEAVEFUNCTION</a> when interleaved RTP data is received. (Added in 7.20.0) <p class="level0"><a name="CURLOPTCHUNKBGNFUNCTION"></a><span class="nroffip">CURLOPT_CHUNK_BGN_FUNCTION</span> -<p class="level1">Function pointer that should match the following prototype: <span class="bold">long function (const void *transfer_info, void *ptr, int remains)</span>. This function gets called by libcurl before a part of the stream is going to be transferred (if the transfer supports chunks). +<p class="level1">Pass a pointer to a function that matches the following prototype: <span Class="bold">long function (const void *transfer_info, void *ptr, int remains)</span>. This function gets called by libcurl before a part of the stream is going to be transferred (if the transfer supports chunks). <p class="level1">This callback makes sense only when using the <a class="emphasis" href="#CURLOPTWILDCARDMATCH">CURLOPT_WILDCARDMATCH</a> option for now. <p class="level1">The target of transfer_info parameter is a "feature depended" structure. For the FTP wildcard download, the target is curl_fileinfo structure (see <span Class="emphasis">curl/curl.h</span>). The parameter ptr is a pointer given by <a class="emphasis" href="#CURLOPTCHUNKDATA">CURLOPT_CHUNK_DATA</a>. The parameter remains contains number of chunks remaining per the transfer. If the feature is not available, the parameter has zero value. <p class="level1">Return <span Class="emphasis">CURL_CHUNK_BGN_FUNC_OK</span> if everything is fine, <span Class="emphasis">CURL_CHUNK_BGN_FUNC_SKIP</span> if you want to skip the concrete chunk or <span Class="emphasis">CURL_CHUNK_BGN_FUNC_FAIL</span> to tell libcurl to stop if some error occurred. (This was added in 7.21.0) <p class="level0"><a name="CURLOPTCHUNKENDFUNCTION"></a><span class="nroffip">CURLOPT_CHUNK_END_FUNCTION</span> -<p class="level1">Function pointer that should match the following prototype: <span class="bold">long function(void *ptr)</span>. This function gets called by libcurl as soon as a part of the stream has been transferred (or skipped). +<p class="level1">Pass a pointer to a function that matches the following prototype: <span Class="bold">long function(void *ptr)</span>. This function gets called by libcurl as soon as a part of the stream has been transferred (or skipped). <p class="level1">Return <span Class="emphasis">CURL_CHUNK_END_FUNC_OK</span> if everything is fine or <span Class="bold">CURL_CHUNK_END_FUNC_FAIL</span> to tell the lib to stop if some error occurred. (This was added in 7.21.0) <p class="level0"><a name="CURLOPTCHUNKDATA"></a><span class="nroffip">CURLOPT_CHUNK_DATA</span> <p class="level1">Pass a pointer that will be untouched by libcurl and passed as the ptr argument to the <span Class="emphasis">CURL_CHUNK_BGN_FUNTION</span> and <span Class="emphasis">CURL_CHUNK_END_FUNTION</span>. (This was added in 7.21.0) <p class="level0"><a name="CURLOPTFNMATCHFUNCTION"></a><span class="nroffip">CURLOPT_FNMATCH_FUNCTION</span> -<p class="level1">Function pointer that should match <span class="bold">int function(void *ptr, const char *pattern, const char *string)</span> prototype (see <span Class="emphasis">curl/curl.h</span>). It is used internally for the wildcard matching feature. +<p class="level1">Pass a pointer to a function that matches the following prototype: <span class="bold">int function(void *ptr, const char *pattern, const char *string)</span> prototype (see <span Class="emphasis">curl/curl.h</span>). It is used internally for the wildcard matching feature. <p class="level1">Return <span Class="emphasis">CURL_FNMATCHFUNC_MATCH</span> if pattern matches the string, <span Class="emphasis">CURL_FNMATCHFUNC_NOMATCH</span> if not or <span Class="emphasis">CURL_FNMATCHFUNC_FAIL</span> if an error occurred. (This was added in 7.21.0) <p class="level0"><a name="CURLOPTFNMATCHDATA"></a><span class="nroffip">CURLOPT_FNMATCH_DATA</span> <p class="level1">Pass a pointer that will be untouched by libcurl and passed as the ptr argument to the <span Class="emphasis">CURL_FNMATCH_FUNCTION</span>. (This was added in 7.21.0) <a name="ERROR"></a><h2 class="nroffsh">ERROR OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTERRORBUFFER"></a><span class="nroffip">CURLOPT_ERRORBUFFER</span> -<p class="level1">Pass a char * to a buffer that the libcurl may store human readable error messages in. This may be more helpful than just the return code from <span Class="emphasis">curl_easy_perform</span>. The buffer must be at least CURL_ERROR_SIZE big. Although this argument is a 'char *', it does not describe an input string. Therefore the (probably undefined) contents of the buffer is NOT copied by the library. You should keep the associated storage available until libcurl no longer needs it. Failing to do so will cause very odd behavior or even crashes. libcurl will need it until you call <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a> or you set the same option again to use a different pointer. +<p class="level1">Pass a char * to a buffer that the libcurl may store human readable error messages in. This may be more helpful than just the return code from <span Class="emphasis">curl_easy_perform</span>. The buffer must be at least CURL_ERROR_SIZE big. Although this argument is a 'char *', it does not describe an input string. Therefore the (probably undefined) contents of the buffer is NOT copied by the library. You must keep the associated storage available until libcurl no longer needs it. Failing to do so will cause very odd behavior or even crashes. libcurl will need it until you call <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a> or you set the same option again to use a different pointer. <p class="level1">Use <a class="emphasis" href="#CURLOPTVERBOSE">CURLOPT_VERBOSE</a> and <a class="emphasis" href="#CURLOPTDEBUGFUNCTION">CURLOPT_DEBUGFUNCTION</a> to better debug/trace why errors happen. <p class="level1">If the library does not return an error, the buffer may not have been touched. Do not rely on the contents in those cases. <p class="level1"> @@ -225,10 +262,74 @@ p.roffit { <p class="level1">You might get some amounts of headers transferred before this situation is detected, like when a "100-continue" is received as a response to a POST/PUT and a 401 or 407 is received immediately afterwards. <a name="NETWORK"></a><h2 class="nroffsh">NETWORK OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTURL"></a><span class="nroffip">CURLOPT_URL</span> -<p class="level1">The actual URL to deal with. The parameter should be a char * to a zero terminated string. -<p class="level1">If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will attempt to guess which protocol to use based on the given host name. If the given protocol of the set URL is not supported, libcurl will return on error (<span Class="emphasis">CURLE_UNSUPPORTED_PROTOCOL</span>) when you call <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> or <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>. Use <a class="emphasis" href="./curl_version_info.html">curl_version_info(3)</a> for detailed info on which protocols are supported. -<p class="level1">The string given to CURLOPT_URL must be url-encoded and follow RFC 2396 (<a href="http://curl.haxx.se/rfc/rfc2396.txt">http://curl.haxx.se/rfc/rfc2396.txt</a>). -<p class="level1">Starting with version 7.20.0, the fragment part of the URI will not be send as part of the path, which was the case previously. +<p class="level1">Pass in a pointer to the actual URL to deal with. The parameter should be a char * to a zero terminated string which must be URL-encoded in the following format: +<p class="level1">scheme://host:port/path +<p class="level1">For a greater explanation of the format please see <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>. +<p class="level1">If the given URL lacks the scheme (such as "http://" or "ftp://" etc) then libcurl will attempt to resolve the protocol based on one of the following given host names: +<p class="level1">HTTP, FTP, DICT, LDAP, IMAP, POP3 or SMTP +<p class="level1">(POP3 and SMTP added in 7.31.0) +<p class="level1">Should the protocol, either that specified by the scheme or deduced by libcurl from the host name, not be supported by libcurl then (<span Class="emphasis">CURLE_UNSUPPORTED_PROTOCOL</span>) will be returned from either the <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> or <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> functions when you call them. Use <a class="emphasis" href="./curl_version_info.html">curl_version_info(3)</a> for detailed information of which protocols are supported by the build of libcurl you are using. +<p class="level1">The host part of the URL contains the address of the server that you want to connect to. This can be the fully qualified domain name of the server, the local network name of the machine on your network or the IP address of the server or machine represented by either an IPv4 or IPv6 address. For example: +<p class="level1"><a href="http://www.example.com/">http://www.example.com/</a> +<p class="level1"><a href="http://hostname/">http://hostname/</a> +<p class="level1"><a href="http://192.168.0.1/">http://192.168.0.1/</a> +<p class="level1">http://[2001:1890:1112:1::20]/ +<p class="level1">It is also possible to specify the user name, password and any supported login options as part of the host, for the following protocols, when connecting to servers that require authentication: +<p class="level1"><a href="http://user">http://user</a>:password@www.example.com +<p class="level1"><a href="ftp://user">ftp://user</a>:password@ftp.example.com +<p class="level1">imap://user:password;options@mail.example.com +<p class="level1">pop3://user:password;options@mail.example.com +<p class="level1">smtp://user:password;options@mail.example.com +<p class="level1">At present only IMAP, POP3 and SMTP support login options as part of the host. For more information about the login options in URL syntax please see <a href="http://www.ietf.org/rfc/rfc2384.txt">RFC 2384</a>, <a href="http://www.ietf.org/rfc/rfc5092.txt">RFC 5092</a> and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0). +<p class="level1">The port is optional and when not specified libcurl will use the default port based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25 for SMTP, etc. The following examples show how to specify the port: +<p class="level1"><a href="http://www.example.com">http://www.example.com</a>:8080/ - This will connect to a web server using port 8080 rather than 80. +<p class="level1">smtp://mail.example.com:587/ - This will connect to a SMTP server on the alternative mail port. +<p class="level1">The path part of the URL is protocol specific and whilst some examples are given below this list is not conclusive: +<p class="level1"><a class="bold" href="#HTTP">HTTP</a> +<p class="level1">The path part of a HTTP request specifies the file to retrieve and from what directory. If the directory is not specified then the web server's root directory is used. If the file is omitted then the default document will be retrieved for either the directory specified or the root directory. The exact resource returned for each URL is entirely dependent on the server's configuration. +<p class="level1"><a href="http://www.example.com">http://www.example.com</a> - This gets the main page from the web server. +<p class="level1"><a href="http://www.example.com/index.html">http://www.example.com/index.html</a> - This returns the main page by explicitly requesting it. +<p class="level1"><a href="http://www.example.com/contactus/">http://www.example.com/contactus/</a> - This returns the default document from the contactus directory. +<p class="level1"><a class="bold" href="#FTP">FTP</a> +<p class="level1">The path part of an FTP request specifies the file to retrieve and from what directory. If the file part is omitted then libcurl downloads the directory listing for the directory specified. If the directory is omitted then the directory listing for the root / home directory will be returned. +<p class="level1"><a href="ftp://ftp.example.com">ftp://ftp.example.com</a> - This retrieves the directory listing for the root directory. +<p class="level1"><a href="ftp://ftp.example.com/readme.txt">ftp://ftp.example.com/readme.txt</a> - This downloads the file readme.txt from the root directory. +<p class="level1"><a href="ftp://ftp.example.com/libcurl/readme.txt">ftp://ftp.example.com/libcurl/readme.txt</a> - This downloads readme.txt from the libcurl directory. +<p class="level1"><a href="ftp://user">ftp://user</a>:password@ftp.example.com/readme.txt - This retrieves the readme.txt file from the user's home directory. When a username and password is specified, everything that is specified in the path part is relative to the user's home directory. To retrieve files from the root directory or a directory underneath the root directory then the absolute path must be specified by prepending an additional forward slash to the beginning of the path. +<p class="level1"><a href="ftp://user">ftp://user</a>:password@ftp.example.com//readme.txt - This retrieves the readme.txt from the root directory when logging in as a specified user. +<p class="level1"><a class="bold" href="#SMTP">SMTP</a> +<p class="level1">The path part of a SMTP request specifies the host name to present during communication with the mail server. If the path is omitted then libcurl will attempt to resolve the local computer's host name. However, this may not return the fully qualified domain name that is required by some mail servers and specifying this path allows you to set an alternative name, such as your machine's fully qualified domain name, which you might have obtained from an external function such as gethostname or getaddrinfo. +<p class="level1">smtp://mail.example.com - This connects to the mail server at example.com and sends your local computer's host name in the HELO / EHLO command. +<p class="level1">smtp://mail.example.com/client.example.com - This will send client.example.com in the HELO / EHLO command to the mail server at example.com. +<p class="level1"><span Class="bold">POP3</span> +<p class="level1">The path part of a POP3 request specifies the message ID to retrieve. If the ID is not specified then a list of waiting messages is returned instead. +<p class="level1">pop3://user:password@mail.example.com - This lists the available messages for the user +<p class="level1">pop3://user:password@mail.example.com/1 - This retrieves the first message for the user +<p class="level1"><span Class="bold">IMAP</span> +<p class="level1">The path part of an IMAP request not only specifies the mailbox to list (Added in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the mailbox and to specify the UID and SECTION of the message to fetch (Added in 7.30.0). +<p class="level1">imap://user:password@mail.example.com - Performs a top level folder list +<p class="level1">imap://user:password@mail.example.com/INBOX - Performs a folder list on the user's inbox +<p class="level1">imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox and fetches message 1 +<p class="level1">imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches message 2 if it is +<p class="level1">imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the user's inbox and fetches message 3 with only the text portion of the message +<p class="level1">For more information about the individual components of an IMAP URL please see <a href="http://www.ietf.org/rfc/rfc5092.txt">RFC 5092</a>. +<p class="level1"><span Class="bold">SCP</span> +<p class="level1">The path part of a SCP request specifies the file to retrieve and from what directory. The file part may not be omitted. The file is taken as an absolute path from the root directory on the server. To specify a path relative to the user's home directory on the server, prepend ~/ to the path portion. If the user name is not embedded in the URL, it can be set with the <a class="emphasis" href="#CURLOPTUSERPWD">CURLOPT_USERPWD</a> or <a class="bold" href="#CURLOPTUSERNAME">CURLOPT_USERNAME</a> option. +<p class="level1">scp://user@example.com/etc/issue - This specifies the file /etc/issue +<p class="level1">scp://example.com/~/my-file - This specifies the file my-file in the user's home directory on the server +<p class="level1"><span Class="bold">SFTP</span> +<p class="level1">The path part of a SFTP request specifies the file to retrieve and from what directory. If the file part is omitted then libcurl downloads the directory listing for the directory specified. If the path ends in a / then a directory listing is returned instead of a file. If the path is omitted entirely then the directory listing for the root / home directory will be returned. If the user name is not embedded in the URL, it can be set with the <a class="emphasis" href="#CURLOPTUSERPWD">CURLOPT_USERPWD</a> or <a class="bold" href="#CURLOPTUSERNAME">CURLOPT_USERNAME</a> option. +<p class="level1">s<a href="ftp://user">ftp://user</a>:password@example.com/etc/issue - This specifies the file /etc/issue +<p class="level1">s<a href="ftp://user">ftp://user</a>@example.com/~/my-file - This specifies the file my-file in the user's home directory +<p class="level1">s<a href="ftp://ssh.example.com/">ftp://ssh.example.com/</a>~/Documents/ - This requests a directory listing of the Documents directory under the user's home directory +<p class="level1"><span Class="bold">LDAP</span> +<p class="level1">The path part of a LDAP request can be used to specify the: Distinguished Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field is separated by a question mark and when that field is not required an empty string with the question mark separator should be included. +<p class="level1">ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search with the DN as My Organisation. +<p class="level1">ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform the same search but will only return postalAddress attributes. +<p class="level1">ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN and requests information about the rootDomainNamingContext attribute for an Active Directory server. +<p class="level1">For more information about the individual components of a LDAP URL please see <a href="http://www.ietf.org/rfc/rfc4516.txt">RFC 4516</a>. +<p class="level1"><span Class="bold">NOTES</span> +<p class="level1">Starting with version 7.20.0, the fragment part of the URI will not be sent as part of the path, which was previously the case. <p class="level1"><a class="emphasis" href="#CURLOPTURL">CURLOPT_URL</a> is the only option that <span Class="bold">must</span> be set before <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> is called. <p class="level1"><a class="emphasis" href="#CURLOPTPROTOCOLS">CURLOPT_PROTOCOLS</a> can be used to limit what protocols libcurl will use for this transfer, independent of what libcurl has been compiled to support. That may be useful if you accept the URL from an external source and want to limit the accessibility. <p class="level0"><a name="CURLOPTPROTOCOLS"></a><span class="nroffip">CURLOPT_PROTOCOLS</span> @@ -237,28 +338,31 @@ p.roffit { <p class="level1">Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask limits what protocols libcurl may use in a transfer that it follows to in a redirect when <a class="emphasis" href="#CURLOPTFOLLOWLOCATION">CURLOPT_FOLLOWLOCATION</a> is enabled. This allows you to limit specific transfers to only be allowed to use a subset of protocols in redirections. By default libcurl will allow all protocols except for FILE and SCP. This is a difference compared to pre-7.19.4 versions which unconditionally would follow to all protocols supported. (Added in 7.19.4) <p class="level0"><a name="CURLOPTPROXY"></a><span class="nroffip">CURLOPT_PROXY</span> <p class="level1">Set HTTP proxy to use. The parameter should be a char * to a zero terminated string holding the host name or dotted IP address. To specify port number in this string, append :[port] to the end of the host name. The proxy string may be prefixed with [protocol]:// since any such prefix will be ignored. The proxy's port number may optionally be specified with the separate option. If not specified, libcurl will default to using port 1080 for proxies. <a class="emphasis" href="#CURLOPTPROXYPORT">CURLOPT_PROXYPORT</a>. -<p class="level1">When you tell the library to use an HTTP proxy, libcurl will transparently convert operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as <a class="emphasis" href="#CURLOPTQUOTE">CURLOPT_QUOTE</a> and similar FTP specifics that don't work unless you tunnel through the HTTP proxy. Such tunneling is activated with <a class="emphasis" href="#CURLOPTHTTPPROXYTUNNEL">CURLOPT_HTTPPROXYTUNNEL</a>. +<p class="level1">When you tell the library to use a HTTP proxy, libcurl will transparently convert operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as <a class="emphasis" href="#CURLOPTQUOTE">CURLOPT_QUOTE</a> and similar FTP specifics that don't work unless you tunnel through the HTTP proxy. Such tunneling is activated with <a class="emphasis" href="#CURLOPTHTTPPROXYTUNNEL">CURLOPT_HTTPPROXYTUNNEL</a>. <p class="level1">libcurl respects the environment variables <span Class="bold">http_proxy</span>, <span Class="bold">ftp_proxy</span>, <span Class="bold">all_proxy</span> etc, if any of those are set. The <a class="emphasis" href="#CURLOPTPROXY">CURLOPT_PROXY</a> option does however override any possibly set environment variables. <p class="level1">Setting the proxy string to "" (an empty string) will explicitly disable the use of a proxy, even if there is an environment variable set for it. <p class="level1">Since 7.14.1, the proxy host string given in environment variables can be specified the exact same way as the proxy can be set with <a class="emphasis" href="#CURLOPTPROXY">CURLOPT_PROXY</a>, include protocol prefix (http://) and embedded user + password. +<p class="level1">Since 7.21.7, the proxy string may be specified with a protocol:// prefix to specify alternative proxy protocols. Use socks4://, socks4a://, socks5:// or socks5h:// (the last one to enable socks5 and asking the proxy to do the resolving, also known as CURLPROXY_SOCKS5_HOSTNAME type) to request the specific SOCKS version to be used. No protocol specified, http:// and all others will be treated as HTTP proxies. <p class="level0"><a name="CURLOPTPROXYPORT"></a><span class="nroffip">CURLOPT_PROXYPORT</span> <p class="level1">Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string <a class="emphasis" href="#CURLOPTPROXY">CURLOPT_PROXY</a>. <p class="level0"><a name="CURLOPTPROXYTYPE"></a><span class="nroffip">CURLOPT_PROXYTYPE</span> -<p class="level1">Pass a long with this option to set type of the proxy. Available options for this are <span Class="emphasis">CURLPROXY_HTTP</span>, <span Class="emphasis">CURLPROXY_HTTP_1_0</span> (added in 7.19.4), <span Class="emphasis">CURLPROXY_SOCKS4</span> (added in 7.15.2), <span Class="emphasis">CURLPROXY_SOCKS5</span>, <span Class="emphasis">CURLPROXY_SOCKS4A</span> (added in 7.18.0) and <span Class="emphasis">CURLPROXY_SOCKS5_HOSTNAME</span> (added in 7.18.0). The HTTP type is default. (Added in 7.10) +<p class="level1">Pass a long with this option to set type of the proxy. Available options for this are <span Class="emphasis">CURLPROXY_HTTP</span>, <span Class="emphasis">CURLPROXY_HTTP_1_0</span> (added in 7.19.4), <span Class="emphasis">CURLPROXY_SOCKS4</span> (added in 7.10), <span Class="emphasis">CURLPROXY_SOCKS5</span>, <span Class="emphasis">CURLPROXY_SOCKS4A</span> (added in 7.18.0) and <span Class="emphasis">CURLPROXY_SOCKS5_HOSTNAME</span> (added in 7.18.0). The HTTP type is default. (Added in 7.10) +<p class="level1">If you set <a class="bold" href="#CURLOPTPROXYTYPE">CURLOPT_PROXYTYPE</a> to <span Class="emphasis">CURLPROXY_HTTP_1_0</span>, it will only affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version used for "regular" HTTP requests is instead controlled with <a class="emphasis" href="#CURLOPTHTTPVERSION">CURLOPT_HTTP_VERSION</a>. <p class="level0"><a name="CURLOPTNOPROXY"></a><span class="nroffip">CURLOPT_NOPROXY</span> -<p class="level1">Pass a pointer to a zero terminated string. The should be a comma- separated list of hosts which do not use a proxy, if one is specified. The only wildcard is a single * character, which matches all hosts, and effectively disables the proxy. Each name in this list is matched as either a domain which contains the hostname, or the hostname itself. For example, local.com would match local.com, local.com:80, and www.local.com, but not www.notlocal.com. (Added in 7.19.4) +<p class="level1">Pass a pointer to a zero terminated string. The string consists of a comma separated list of host names that do not require a proxy to get reached, even if one is specified. The only wildcard available is a single * character, which matches all hosts, and effectively disables the proxy. Each name in this list is matched as either a domain which contains the hostname, or the hostname itself. For example, example.com would match example.com, example.com:80, and www.example.com, but not www.notanexample.com. (Added in 7.19.4) <p class="level0"><a name="CURLOPTHTTPPROXYTUNNEL"></a><span class="nroffip">CURLOPT_HTTPPROXYTUNNEL</span> <p class="level1">Set the parameter to 1 to make the library tunnel all operations through a given HTTP proxy. There is a big difference between using a proxy and to tunnel through it. If you don't know what this means, you probably don't want this tunneling option. <p class="level0"><a name="CURLOPTSOCKS5GSSAPISERVICE"></a><span class="nroffip">CURLOPT_SOCKS5_GSSAPI_SERVICE</span> <p class="level1">Pass a char * as parameter to a string holding the name of the service. The default service name for a SOCKS5 server is rcmd/server-fqdn. This option allows you to change it. (Added in 7.19.4) <p class="level0"><a name="CURLOPTSOCKS5GSSAPINEC"></a><span class="nroffip">CURLOPT_SOCKS5_GSSAPI_NEC</span> -<p class="level1">Pass a long set to 1 to enable or 0 to disable. As part of the gssapi negotiation a protection mode is negotiated. The rfc1961 says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. If enabled, this option allows the unprotected exchange of the protection mode negotiation. (Added in 7.19.4). +<p class="level1">Pass a long set to 1 to enable or 0 to disable. As part of the gssapi negotiation a protection mode is negotiated. The <a href="http://www.ietf.org/rfc/rfc1961.txt">RFC 1961</a> says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. If enabled, this option allows the unprotected exchange of the protection mode negotiation. (Added in 7.19.4). <p class="level0"><a name="CURLOPTINTERFACE"></a><span class="nroffip">CURLOPT_INTERFACE</span> <p class="level1">Pass a char * as parameter. This sets the interface name to use as outgoing network interface. The name can be an interface name, an IP address, or a host name. +<p class="level1">Starting with 7.24.0: If the parameter starts with "if!" then it is treated as only as interface name and no attempt will ever be named to do treat it as an IP address or to do name resolution on it. If the parameter starts with "host!" it is treated as either an IP address or a hostname. Hostnames are resolved synchronously. Using the if! format is highly recommended when using the multi interfaces to avoid allowing the code to block. If "if!" is specified but the parameter does not match an existing interface, CURLE_INTERFACE_FAILED is returned. <p class="level0"><a name="CURLOPTLOCALPORT"></a><span class="nroffip">CURLOPT_LOCALPORT</span> <p class="level1">Pass a long. This sets the local port number of the socket used for connection. This can be used in combination with <a class="emphasis" href="#CURLOPTINTERFACE">CURLOPT_INTERFACE</a> and you are recommended to use <a class="emphasis" href="#CURLOPTLOCALPORTRANGE">CURLOPT_LOCALPORTRANGE</a> as well when this is set. Valid port numbers are 1 - 65535. (Added in 7.15.2) <p class="level0"><a name="CURLOPTLOCALPORTRANGE"></a><span class="nroffip">CURLOPT_LOCALPORTRANGE</span> -<p class="level1">Pass a long. This is the number of attempts libcurl should make to find a working local port number. It starts with the given <a class="emphasis" href="#CURLOPTLOCALPORT">CURLOPT_LOCALPORT</a> and adds one to the number for each retry. Setting this to 1 or below will make libcurl do only one try for the exact port number. Port numbers by nature are scarce resources that will be busy at times so setting this value to something too low might cause unnecessary connection setup failures. (Added in 7.15.2) +<p class="level1">Pass a long. This is the number of attempts libcurl will make to find a working local port number. It starts with the given <a class="emphasis" href="#CURLOPTLOCALPORT">CURLOPT_LOCALPORT</a> and adds one to the number for each retry. Setting this to 1 or below will make libcurl do only one try for the exact port number. Port numbers by nature are scarce resources that will be busy at times so setting this value to something too low might cause unnecessary connection setup failures. (Added in 7.15.2) <p class="level0"><a name="CURLOPTDNSCACHETIMEOUT"></a><span class="nroffip">CURLOPT_DNS_CACHE_TIMEOUT</span> <p class="level1">Pass a long, this sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero to completely disable caching, or set to -1 to make the cached entries remain forever. By default, libcurl caches this info for 60 seconds. <p class="level1">The name resolve functions of various libc implementations don't re-read name server information unless explicitly told so (for example, by calling <span Class="emphasis">res_init(3)</span>). This may cause libcurl to keep using the older server even if DHCP has updated the server info, and this may look like a DNS cache issue to the casual libcurl-app user. @@ -271,11 +375,17 @@ p.roffit { <p class="level0"><a name="CURLOPTPORT"></a><span class="nroffip">CURLOPT_PORT</span> <p class="level1">Pass a long specifying what remote port number to connect to, instead of the one specified in the URL or the default port for the used protocol. <p class="level0"><a name="CURLOPTTCPNODELAY"></a><span class="nroffip">CURLOPT_TCP_NODELAY</span> -<p class="level1">Pass a long specifying whether the TCP_NODELAY option should be set or cleared (1 = set, 0 = clear). The option is cleared by default. This will have no effect after the connection has been established. +<p class="level1">Pass a long specifying whether the TCP_NODELAY option is to be set or cleared (1 = set, 0 = clear). The option is cleared by default. This will have no effect after the connection has been established. <p class="level1">Setting this option will disable TCP's Nagle algorithm. The purpose of this algorithm is to try to minimize the number of small packets on the network (where "small packets" means TCP segments less than the Maximum Segment Size (MSS) for the network). <p class="level1">Maximizing the amount of data sent per TCP segment is good because it amortizes the overhead of the send. However, in some cases (most notably telnet or rlogin) small segments may need to be sent without delay. This is less efficient than sending larger amounts of data at a time, and can contribute to congestion on the network if overdone. <p class="level0"><a name="CURLOPTADDRESSSCOPE"></a><span class="nroffip">CURLOPT_ADDRESS_SCOPE</span> -<p class="level1">Pass a long specifying the scope_id value to use when connecting to IPv6 link-local or site-local addresses. (Added in 7.19.0) <a name="NAMES"></a><h2 class="nroffsh">NAMES and PASSWORDS OPTIONS (Authentication)</h2> +<p class="level1">Pass a long specifying the scope_id value to use when connecting to IPv6 link-local or site-local addresses. (Added in 7.19.0) +<p class="level0"><a name="CURLOPTTCPKEEPALIVE"></a><span class="nroffip">CURLOPT_TCP_KEEPALIVE</span> +<p class="level1">Pass a long. If set to 1, TCP keepalive probes will be sent. The delay and frequency of these probes can be controlled by the <a class="emphasis" href="#CURLOPTTCPKEEPIDLE">CURLOPT_TCP_KEEPIDLE</a> and <a class="emphasis" href="#CURLOPTTCPKEEPINTVL">CURLOPT_TCP_KEEPINTVL</a> options, provided the operating system supports them. Set to 0 (default behavior) to disable keepalive probes (Added in 7.25.0). +<p class="level0"><a name="CURLOPTTCPKEEPIDLE"></a><span class="nroffip">CURLOPT_TCP_KEEPIDLE</span> +<p class="level1">Pass a long. Sets the delay, in seconds, that the operating system will wait while the connection is idle before sending keepalive probes. Not all operating systems support this option. (Added in 7.25.0) +<p class="level0"><a name="CURLOPTTCPKEEPINTVL"></a><span class="nroffip">CURLOPT_TCP_KEEPINTVL</span> +<p class="level1">Pass a long. Sets the interval, in seconds, that the operating system will wait between sending keepalive probes. Not all operating systems support this option. (Added in 7.25.0) <a name="NAMES"></a><h2 class="nroffsh">NAMES and PASSWORDS OPTIONS (Authentication)</h2> <p class="level0"> <p class="level0"><a name="CURLOPTNETRC"></a><span class="nroffip">CURLOPT_NETRC</span> <p class="level1">This parameter controls the preference of libcurl between using user names and passwords from your <span Class="emphasis">~/.netrc</span> file, relative to user names and passwords in the URL supplied with <a class="emphasis" href="#CURLOPTURL">CURLOPT_URL</a>. @@ -295,11 +405,14 @@ p.roffit { <p class="level0"><a name="CURLOPTNETRCFILE"></a><span class="nroffip">CURLOPT_NETRC_FILE</span> <p class="level1">Pass a char * as parameter, pointing to a zero terminated string containing the full path name to the file you want libcurl to use as .netrc file. If this option is omitted, and <a class="emphasis" href="#CURLOPTNETRC">CURLOPT_NETRC</a> is set, libcurl will attempt to find a .netrc file in the current user's home directory. (Added in 7.10.9) <p class="level0"><a name="CURLOPTUSERPWD"></a><span class="nroffip">CURLOPT_USERPWD</span> -<p class="level1">Pass a char * as parameter, which should be [user name]:[password] to use for the connection. Use <a class="emphasis" href="#CURLOPTHTTPAUTH">CURLOPT_HTTPAUTH</a> to decide the authentication method. +<p class="level1">Pass a char * as parameter, pointing to a zero terminated login details string for the connection. The format of which is: [user name]:[password];[options]. <p class="level1">When using NTLM, you can set the domain by prepending it to the user name and separating the domain and name with a forward (/) or backward slash (\). Like this: "domain/user:password" or "domain\user:password". Some HTTP servers (on Windows) support this style even for Basic authentication. <p class="level1">When using HTTP and <a class="emphasis" href="#CURLOPTFOLLOWLOCATION">CURLOPT_FOLLOWLOCATION</a>, libcurl might perform several requests to possibly different hosts. libcurl will only send this user and password information to hosts using the initial host name (unless <a class="emphasis" href="#CURLOPTUNRESTRICTEDAUTH">CURLOPT_UNRESTRICTED_AUTH</a> is set), so if libcurl follows locations to other hosts it will not send the user and password to those. This is enforced to prevent accidental information leakage. +<p class="level1">At present only IMAP, POP3 and SMTP support login options as part of the details string. For more information about the login options please see <a href="http://www.ietf.org/rfc/rfc2384.txt">RFC 2384</a>, RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0). +<p class="level1">Use <a class="emphasis" href="#CURLOPTHTTPAUTH">CURLOPT_HTTPAUTH</a> to specify the authentication method for HTTP based connections. <p class="level0"><a name="CURLOPTPROXYUSERPWD"></a><span class="nroffip">CURLOPT_PROXYUSERPWD</span> -<p class="level1">Pass a char * as parameter, which should be [user name]:[password] to use for the connection to the HTTP proxy. Use <a class="emphasis" href="#CURLOPTPROXYAUTH">CURLOPT_PROXYAUTH</a> to decide the authentication method. +<p class="level1">Pass a char * as parameter, which should be [user name]:[password] to use for the connection to the HTTP proxy. +<p class="level1">Use <a class="emphasis" href="#CURLOPTPROXYAUTH">CURLOPT_PROXYAUTH</a> to specify the authentication method. <p class="level0"><a name="CURLOPTUSERNAME"></a><span class="nroffip">CURLOPT_USERNAME</span> <p class="level1">Pass a char * as parameter, which should be pointing to the zero terminated user name to use for the transfer. <p class="level1"><a class="bold" href="#CURLOPTUSERNAME">CURLOPT_USERNAME</a> sets the user name to be used in protocol authentication. You should not use this option together with the (older) CURLOPT_USERPWD option. @@ -315,20 +428,23 @@ p.roffit { <p class="level1">Pass a char * as parameter, which should be pointing to the zero terminated password to use for the transfer while connecting to Proxy. <p class="level1">The CURLOPT_PROXYPASSWORD option should be used in conjunction with the <a class="emphasis" href="#CURLOPTPROXYUSERNAME">CURLOPT_PROXYUSERNAME</a> option. (Added in 7.19.1) <p class="level0"><a name="CURLOPTHTTPAUTH"></a><span class="nroffip">CURLOPT_HTTPAUTH</span> -<p class="level1">Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use. The available bits are listed below. If more than one bit is set, libcurl will first query the site to see which authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the <a class="emphasis" href="#CURLOPTUSERPWD">CURLOPT_USERPWD</a> option or with the <a class="emphasis" href="#CURLOPTUSERNAME">CURLOPT_USERNAME</a> and the <span Class="emphasis">CURLOPT_USERPASSWORD</span> options. (Added in 7.10.6) +<p class="level1">Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use. The available bits are listed below. If more than one bit is set, libcurl will first query the site to see which authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the <a class="emphasis" href="#CURLOPTUSERPWD">CURLOPT_USERPWD</a> option or with the <a class="emphasis" href="#CURLOPTUSERNAME">CURLOPT_USERNAME</a> and the <a class="emphasis" href="#CURLOPTPASSWORD">CURLOPT_PASSWORD</a> options. (Added in 7.10.6) <p class="level2"> <p class="level1"><a name="CURLAUTHBASIC"></a><span class="nroffip">CURLAUTH_BASIC</span> <p class="level2">HTTP Basic authentication. This is the default choice, and the only method that is in wide-spread use and supported virtually everywhere. This sends the user name and password over the network in plain text, easily captured by others. <p class="level1"><a name="CURLAUTHDIGEST"></a><span class="nroffip">CURLAUTH_DIGEST</span> -<p class="level2">HTTP Digest authentication. Digest authentication is defined in RFC2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. +<p class="level2">HTTP Digest authentication. Digest authentication is defined in <a href="http://www.ietf.org/rfc/rfc2617.txt">RFC 2617</a> and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. <p class="level1"><a name="CURLAUTHDIGESTIE"></a><span class="nroffip">CURLAUTH_DIGEST_IE</span> -<p class="level2">HTTP Digest authentication with an IE flavor. Digest authentication is defined in RFC2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. The IE flavor is simply that libcurl will use a special "quirk" that IE is known to have used before version 7 and that some servers require the client to use. (This define was added in 7.19.3) +<p class="level2">HTTP Digest authentication with an IE flavor. Digest authentication is defined in <a href="http://www.ietf.org/rfc/rfc2617.txt">RFC 2617</a> and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. The IE flavor is simply that libcurl will use a special "quirk" that IE is known to have used before version 7 and that some servers require the client to use. (This define was added in 7.19.3) <p class="level1"><a name="CURLAUTHGSSNEGOTIATE"></a><span class="nroffip">CURLAUTH_GSSNEGOTIATE</span> <p class="level2">HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain "Negotiate") method was designed by Microsoft and is used in their web applications. It is primarily meant as a support for Kerberos5 authentication but may also be used along with other authentication methods. For more information see IETF draft draft-brezak-spnego-http-04.txt. <p class="level2">You need to build libcurl with a suitable GSS-API library for this to work. <p class="level1"><a name="CURLAUTHNTLM"></a><span class="nroffip">CURLAUTH_NTLM</span> <p class="level2">HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to prevent the password from being eavesdropped. -<p class="level2">You need to build libcurl with OpenSSL support for this option to work, or build libcurl on Windows. +<p class="level2">You need to build libcurl with either OpenSSL, GnuTLS or NSS support for this option to work, or build libcurl on Windows with SSPI support. +<p class="level1"><a name="CURLAUTHNTLMWB"></a><span class="nroffip">CURLAUTH_NTLM_WB</span> +<p class="level2">NTLM delegating to winbind helper. Authentication is performed by a separate binary application that is executed when needed. The name of the application is specified at compile time but is typically /usr/bin/ntlm_auth (Added in 7.22.0) +<p class="level2">Note that libcurl will fork when necessary to run the winbind application and kill it when complete, calling waitpid() to await its exit when done. On POSIX operating systems, killing the process will cause a SIGCHLD signal to be raised (regardless of whether <a class="emphasis" href="#CURLOPTNOSIGNAL">CURLOPT_NOSIGNAL</a> is set), which must be handled intelligently by the application. In particular, the application must not unconditionally call wait() in its SIGCHLD signal handler to avoid being subject to a race condition. This behavior is subject to change in future versions of libcurl. <p class="level1"><a name="CURLAUTHANY"></a><span class="nroffip">CURLAUTH_ANY</span> <p class="level2">This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. <p class="level1"><a name="CURLAUTHANYSAFE"></a><span class="nroffip">CURLAUTH_ANYSAFE</span> @@ -336,16 +452,35 @@ p.roffit { <p class="level1"><a name="CURLAUTHONLY"></a><span class="nroffip">CURLAUTH_ONLY</span> <p class="level2">This is a meta symbol. Or this value together with a single specific auth value to force libcurl to probe for un-restricted auth and if not, only that single auth algorithm is acceptable. (Added in 7.21.3) <p class="level1"> +<p class="level0"><a name="CURLOPTTLSAUTHTYPE"></a><span class="nroffip">CURLOPT_TLSAUTH_TYPE</span> +<p class="level1">Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use for TLS authentication. +<p class="level2"> +<p class="level1"><a name="CURLOPTTLSAUTHSRP"></a><span class="nroffip">CURLOPT_TLSAUTH_SRP</span> +<p class="level2">TLS-SRP authentication. Secure Remote Password authentication for TLS is defined in <a href="http://www.ietf.org/rfc/rfc5054.txt">RFC 5054</a> and provides mutual authentication if both sides have a shared secret. To use TLS-SRP, you must also set the <a class="emphasis" href="#CURLOPTTLSAUTHUSERNAME">CURLOPT_TLSAUTH_USERNAME</a> and <a class="emphasis" href="#CURLOPTTLSAUTHPASSWORD">CURLOPT_TLSAUTH_PASSWORD</a> options. +<p class="level2">You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this to work. (Added in 7.21.4) +<p class="level1"> +<p class="level0"><a name="CURLOPTTLSAUTHUSERNAME"></a><span class="nroffip">CURLOPT_TLSAUTH_USERNAME</span> +<p class="level1">Pass a char * as parameter, which should point to the zero terminated username to use for the TLS authentication method specified with the <a class="emphasis" href="#CURLOPTTLSAUTHTYPE">CURLOPT_TLSAUTH_TYPE</a> option. Requires that the <span Class="emphasis">CURLOPT_TLS_PASSWORD</span> option also be set. (Added in 7.21.4) +<p class="level0"><a name="CURLOPTTLSAUTHPASSWORD"></a><span class="nroffip">CURLOPT_TLSAUTH_PASSWORD</span> +<p class="level1">Pass a char * as parameter, which should point to the zero terminated password to use for the TLS authentication method specified with the <a class="emphasis" href="#CURLOPTTLSAUTHTYPE">CURLOPT_TLSAUTH_TYPE</a> option. Requires that the <span Class="emphasis">CURLOPT_TLS_USERNAME</span> option also be set. (Added in 7.21.4) <p class="level0"><a name="CURLOPTPROXYAUTH"></a><span class="nroffip">CURLOPT_PROXYAUTH</span> -<p class="level1">Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use for your proxy authentication. If more than one bit is set, libcurl will first query the site to see what authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the <a class="emphasis" href="#CURLOPTPROXYUSERPWD">CURLOPT_PROXYUSERPWD</a> option. The bitmask can be constructed by or'ing together the bits listed above for the <a class="emphasis" href="#CURLOPTHTTPAUTH">CURLOPT_HTTPAUTH</a> option. As of this writing, only Basic, Digest and NTLM work. (Added in 7.10.7) <a name="HTTP"></a><h2 class="nroffsh">HTTP OPTIONS</h2> +<p class="level1">Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use for your proxy authentication. If more than one bit is set, libcurl will first query the site to see what authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the <a class="emphasis" href="#CURLOPTPROXYUSERPWD">CURLOPT_PROXYUSERPWD</a> option. The bitmask can be constructed by or'ing together the bits listed above for the <a class="emphasis" href="#CURLOPTHTTPAUTH">CURLOPT_HTTPAUTH</a> option. As of this writing, only Basic, Digest and NTLM work. (Added in 7.10.7) +<p class="level0"><a name="CURLOPTSASLIR"></a><span class="nroffip">CURLOPT_SASL_IR</span> +<p class="level1">Pass a long. If the value is 1, curl will send the initial response to the server in the first authentication packet in order to reduce the number of ping pong requests. Only applicable to supporting SASL authentication mechanisms and to the IMAP, POP3 and SMTP protocols. (Added in 7.31.0) +<p class="level1">Note: Whilst IMAP supports this option there is no need to explicitly set it, as libcurl can determine the feature itself when the server supports the SASL-IR CAPABILITY. <a name="HTTP"></a><h2 class="nroffsh">HTTP OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTAUTOREFERER"></a><span class="nroffip">CURLOPT_AUTOREFERER</span> <p class="level1">Pass a parameter set to 1 to enable this. When enabled, libcurl will automatically set the Referer: field in requests where it follows a Location: redirect. -<p class="level0"><a name="CURLOPTENCODING"></a><span class="nroffip">CURLOPT_ENCODING</span> -<p class="level1">Sets the contents of the Accept-Encoding: header sent in an HTTP request, and enables decoding of a response when a Content-Encoding: header is received. Three encodings are supported: <span Class="emphasis">identity</span>, which does nothing, <span Class="emphasis">deflate</span> which requests the server to compress its response using the zlib algorithm, and <span Class="emphasis">gzip</span> which requests the gzip algorithm. If a zero-length string is set, then an Accept-Encoding: header containing all supported encodings is sent. +<p class="level0"><a name="CURLOPTACCEPTENCODING"></a><span class="nroffip">CURLOPT_ACCEPT_ENCODING</span> +<p class="level1">Sets the contents of the Accept-Encoding: header sent in a HTTP request, and enables decoding of a response when a Content-Encoding: header is received. Three encodings are supported: <span Class="emphasis">identity</span>, which does nothing, <span Class="emphasis">deflate</span> which requests the server to compress its response using the zlib algorithm, and <span Class="emphasis">gzip</span> which requests the gzip algorithm. If a zero-length string is set, then an Accept-Encoding: header containing all supported encodings is sent. <p class="level1">This is a request, not an order; the server may or may not do it. This option must be set (to any non-NULL value) or else any unsolicited encoding done by the server is ignored. See the special file lib/README.encoding for details. +<p class="level1">(This option was called CURLOPT_ENCODING before 7.21.6) +<p class="level0"><a name="CURLOPTTRANSFERENCODING"></a><span class="nroffip">CURLOPT_TRANSFER_ENCODING</span> +<p class="level1">Adds a request for compressed Transfer Encoding in the outgoing HTTP request. If the server supports this and so desires, it can respond with the HTTP response sent using a compressed Transfer-Encoding that will be automatically uncompressed by libcurl on reception. +<p class="level1">Transfer-Encoding differs slightly from the Content-Encoding you ask for with <a class="bold" href="#CURLOPTACCEPTENCODING">CURLOPT_ACCEPT_ENCODING</a> in that a Transfer-Encoding is strictly meant to be for the transfer and thus MUST be decoded before the data arrives in the client. Traditionally, Transfer-Encoding has been much less used and supported by both HTTP clients and HTTP servers. +<p class="level1">(Added in 7.21.6) <p class="level0"><a name="CURLOPTFOLLOWLOCATION"></a><span class="nroffip">CURLOPT_FOLLOWLOCATION</span> -<p class="level1">A parameter set to 1 tells the library to follow any Location: header that the server sends as part of an HTTP header. +<p class="level1">A parameter set to 1 tells the library to follow any Location: header that the server sends as part of a HTTP header. <p class="level1">This means that the library will re-send the same request on the new location and follow new Location: headers all the way until no more such headers are returned. <a class="emphasis" href="#CURLOPTMAXREDIRS">CURLOPT_MAXREDIRS</a> can be used to limit the number of redirects libcurl will follow. <p class="level1">Since 7.19.4, libcurl can limit what protocols it will automatically follow. The accepted protocols are set with <a class="emphasis" href="#CURLOPTREDIRPROTOCOLS">CURLOPT_REDIR_PROTOCOLS</a> and it excludes the FILE protocol by default. <p class="level0"><a name="CURLOPTUNRESTRICTEDAUTH"></a><span class="nroffip">CURLOPT_UNRESTRICTED_AUTH</span> @@ -353,8 +488,8 @@ p.roffit { <p class="level0"><a name="CURLOPTMAXREDIRS"></a><span class="nroffip">CURLOPT_MAXREDIRS</span> <p class="level1">Pass a long. The set number will be the redirection limit. If that many redirections have been followed, the next redirect will cause an error (<span Class="emphasis">CURLE_TOO_MANY_REDIRECTS</span>). This option only makes sense if the <a class="emphasis" href="#CURLOPTFOLLOWLOCATION">CURLOPT_FOLLOWLOCATION</a> is used at the same time. Added in 7.15.1: Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite number of redirects (which is the default) <p class="level0"><a name="CURLOPTPOSTREDIR"></a><span class="nroffip">CURLOPT_POSTREDIR</span> -<p class="level1">Pass a bitmask to control how libcurl acts on redirects after POSTs that get a 301 or 302 response back. A parameter with bit 0 set (value <span Class="bold">CURL_REDIR_POST_301</span>) tells the library to respect RFC 2616/10.3.2 and not convert POST requests into GET requests when following a 301 redirection. Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain the request method after a 302 redirect. CURL_REDIR_POST_ALL is a convenience define that sets both bits. -<p class="level1">The non-RFC behaviour is ubiquitous in web browsers, so the library does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when setting <a class="emphasis" href="#CURLOPTFOLLOWLOCATION">CURLOPT_FOLLOWLOCATION</a>. (Added in 7.17.1) (This option was known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 way before then) +<p class="level1">Pass a bitmask to control how libcurl acts on redirects after POSTs that get a 301, 302 or 303 response back. A parameter with bit 0 set (value <span Class="bold">CURL_REDIR_POST_301</span>) tells the library to respect <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>/10.3.2 and not convert POST requests into GET requests when following a 301 redirection. Setting bit 1 (value <span Class="bold">CURL_REDIR_POST_302</span>) makes libcurl maintain the request method after a 302 redirect whilst setting bit 2 (value <span Class="bold">CURL_REDIR_POST_303</span>) makes libcurl maintain the request method after a 303 redirect. The value <span Class="bold">CURL_REDIR_POST_ALL</span> is a convenience define that sets all three bits. +<p class="level1">The non-RFC behaviour is ubiquitous in web browsers, so the library does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when setting <a class="emphasis" href="#CURLOPTFOLLOWLOCATION">CURLOPT_FOLLOWLOCATION</a>. (Added in 7.17.1) (This option was known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 then) <p class="level0"><a name="CURLOPTPUT"></a><span class="nroffip">CURLOPT_PUT</span> <p class="level1">A parameter set to 1 tells the library to use HTTP PUT to transfer data. The data should be set with <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a> and <a class="emphasis" href="#CURLOPTINFILESIZE">CURLOPT_INFILESIZE</a>. <p class="level1">This option is deprecated and starting with version 7.12.1 you should instead use <a class="emphasis" href="#CURLOPTUPLOAD">CURLOPT_UPLOAD</a>. @@ -368,18 +503,18 @@ p.roffit { <p class="level1">When setting <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a> to 1, it will automatically set <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a> to 0 (since 7.14.1). <p class="level1">If you issue a POST request and then want to make a HEAD or GET using the same re-used handle, you must explicitly set the new request type using <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a> or <a class="emphasis" href="#CURLOPTHTTPGET">CURLOPT_HTTPGET</a> or similar. <p class="level0"><a name="CURLOPTPOSTFIELDS"></a><span class="nroffip">CURLOPT_POSTFIELDS</span> -<p class="level1">Pass a void * as parameter, which should be the full data to post in an HTTP POST operation. You must make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded. +<p class="level1">Pass a void * as parameter, which should be the full data to post in a HTTP POST operation. You must make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded. <p class="level1">The pointed data are NOT copied by the library: as a consequence, they must be preserved by the calling application until the transfer finishes. <p class="level1">This POST is a normal application/x-www-form-urlencoded kind (and libcurl will set that Content-Type by default when this option is used), which is the most commonly used one by HTML forms. See also the <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a>. Using <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> implies <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a>. <p class="level1">If you want to do a zero-byte POST, you need to set <a class="emphasis" href="#CURLOPTPOSTFIELDSIZE">CURLOPT_POSTFIELDSIZE</a> explicitly to zero, as simply setting <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> to NULL or "" just effectively disables the sending of the specified string. libcurl will instead assume that you'll send the POST data using the read callback! <p class="level1">Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with <a class="emphasis" href="#CURLOPTHTTPHEADER">CURLOPT_HTTPHEADER</a> as usual. -<p class="level1">To make multipart/formdata posts (aka RFC2388-posts), check out the <a class="emphasis" href="#CURLOPTHTTPPOST">CURLOPT_HTTPPOST</a> option. +<p class="level1">To make multipart/formdata posts (aka <a href="http://www.ietf.org/rfc/rfc2388.txt">RFC 2388</a>-posts), check out the <a class="emphasis" href="#CURLOPTHTTPPOST">CURLOPT_HTTPPOST</a> option. <p class="level0"><a name="CURLOPTPOSTFIELDSIZE"></a><span class="nroffip">CURLOPT_POSTFIELDSIZE</span> <p class="level1">If you want to post data to the server without letting libcurl do a strlen() to measure the data size, this option must be used. When this option is used you can post fully binary data, which otherwise is likely to fail. If this size is set to -1, the library will use strlen() to get the size. <p class="level0"><a name="CURLOPTPOSTFIELDSIZELARGE"></a><span class="nroffip">CURLOPT_POSTFIELDSIZE_LARGE</span> <p class="level1">Pass a curl_off_t as parameter. Use this to set the size of the <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> data to prevent libcurl from doing strlen() on the data to figure out the size. This is the large file version of the <a class="emphasis" href="#CURLOPTPOSTFIELDSIZE">CURLOPT_POSTFIELDSIZE</a> option. (Added in 7.11.1) <p class="level0"><a name="CURLOPTCOPYPOSTFIELDS"></a><span class="nroffip">CURLOPT_COPYPOSTFIELDS</span> -<p class="level1">Pass a char * as parameter, which should be the full data to post in an HTTP POST operation. It behaves as the <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> option, but the original data are copied by the library, allowing the application to overwrite the original data after setting this option. +<p class="level1">Pass a char * as parameter, which should be the full data to post in a HTTP POST operation. It behaves as the <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> option, but the original data are copied by the library, allowing the application to overwrite the original data after setting this option. <p class="level1">Because data are copied, care must be taken when using this option in conjunction with <a class="emphasis" href="#CURLOPTPOSTFIELDSIZE">CURLOPT_POSTFIELDSIZE</a> or <a class="emphasis" href="#CURLOPTPOSTFIELDSIZELARGE">CURLOPT_POSTFIELDSIZE_LARGE</a>: If the size has not been set prior to <a class="emphasis" href="#CURLOPTCOPYPOSTFIELDS">CURLOPT_COPYPOSTFIELDS</a>, the data are assumed to be a NUL-terminated string; else the stored size informs the library about the data byte count to copy. In any case, the size must not be changed after <a class="emphasis" href="#CURLOPTCOPYPOSTFIELDS">CURLOPT_COPYPOSTFIELDS</a>, unless another <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> or <a class="emphasis" href="#CURLOPTCOPYPOSTFIELDS">CURLOPT_COPYPOSTFIELDS</a> option is issued. (Added in 7.17.1) <p class="level0"><a name="CURLOPTHTTPPOST"></a><span class="nroffip">CURLOPT_HTTPPOST</span> <p class="level1">Tells libcurl you want a multipart/formdata HTTP POST to be made and you instruct what data to pass on to the server. Pass a pointer to a linked list of curl_httppost structs as parameter. The easiest way to create such a list, is to use <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a> as documented. The data in this list must remain intact until you close this curl handle again with <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a>. @@ -390,7 +525,8 @@ p.roffit { <p class="level0"><a name="CURLOPTUSERAGENT"></a><span class="nroffip">CURLOPT_USERAGENT</span> <p class="level1">Pass a pointer to a zero terminated string as parameter. It will be used to set the User-Agent: header in the http request sent to the remote server. This can be used to fool servers or scripts. You can also set any custom header with <a class="emphasis" href="#CURLOPTHTTPHEADER">CURLOPT_HTTPHEADER</a>. <p class="level0"><a name="CURLOPTHTTPHEADER"></a><span class="nroffip">CURLOPT_HTTPHEADER</span> -<p class="level1">Pass a pointer to a linked list of HTTP headers to pass to the server in your HTTP request. The linked list should be a fully valid list of <span class="bold">struct curl_slist</span> structs properly filled in. Use <a class="emphasis" href="./curl_slist_append.html">curl_slist_append(3)</a> to create the list and <a class="emphasis" href="./curl_slist_free_all.html">curl_slist_free_all(3)</a> to clean up an entire list. If you add a header that is otherwise generated and used by libcurl internally, your added one will be used instead. If you add a header with no content as in 'Accept:' (no data on the right side of the colon), the internally used header will get disabled. Thus, using this option you can add new headers, replace internal headers and remove internal headers. To add a header with no content, make the content be two quotes: "". The headers included in the linked list must not be CRLF-terminated, because curl adds CRLF after each header item. Failure to comply with this will result in strange bugs because the server will most likely ignore part of the headers you specified. +<p class="level1">Pass a pointer to a linked list of HTTP headers to pass to the server in your HTTP request. The linked list should be a fully valid list of <span class="bold">struct curl_slist</span> structs properly filled in. Use <a class="emphasis" href="./curl_slist_append.html">curl_slist_append(3)</a> to create the list and <a class="emphasis" href="./curl_slist_free_all.html">curl_slist_free_all(3)</a> to clean up an entire list. If you add a header that is otherwise generated and used by libcurl internally, your added one will be used instead. If you add a header with no content as in 'Accept:' (no data on the right side of the colon), the internally used header will get disabled. Thus, using this option you can add new headers, replace internal headers and remove internal headers. To add a header with no content (nothing to the right side of the colon), use the form 'MyHeader;' (note the ending semicolon). +<p class="level1">The headers included in the linked list must not be CRLF-terminated, because curl adds CRLF after each header item. Failure to comply with this will result in strange bugs because the server will most likely ignore part of the headers you specified. <p class="level1">The first line in a request (containing the method, usually a GET or POST) is not a header and cannot be replaced using this option. Only the lines following the request-line are headers. Adding this method line in this list of headers will only cause your request to send an invalid header. <p class="level1">Pass a NULL to this to reset back to no custom headers. <p class="level1">The most commonly replaced headers have "shortcuts" in the options <a class="emphasis" href="#CURLOPTCOOKIE">CURLOPT_COOKIE</a>, <a class="emphasis" href="#CURLOPTUSERAGENT">CURLOPT_USERAGENT</a> and <a class="emphasis" href="#CURLOPTREFERER">CURLOPT_REFERER</a>. @@ -401,7 +537,7 @@ p.roffit { <p class="level0"><a name="CURLOPTCOOKIE"></a><span class="nroffip">CURLOPT_COOKIE</span> <p class="level1">Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie should contain. <p class="level1">If you need to set multiple cookies, you need to set them all using a single option and thus you need to concatenate them all in one single string. Set multiple cookies in one string like this: "name1=content1; name2=content2;" etc. -<p class="level1">This option sets the cookie header explictly in the outgoing request(s). If multiple requests are done due to authentication, followed redirections or similar, they will all get this cookie passed on. +<p class="level1">This option sets the cookie header explicitly in the outgoing request(s). If multiple requests are done due to authentication, followed redirections or similar, they will all get this cookie passed on. <p class="level1">Using this option multiple times will only make the latest string override the previous ones. <p class="level0"><a name="CURLOPTCOOKIEFILE"></a><span class="nroffip">CURLOPT_COOKIEFILE</span> <p class="level1">Pass a pointer to a zero terminated string as parameter. It should contain the name of your file holding cookie data to read. The cookie data may be in Netscape / Mozilla cookie data format or just regular HTTP-style headers dumped to a file. @@ -416,7 +552,7 @@ p.roffit { <p class="level1">Pass a char * to a cookie string. Cookie can be either in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL cookie engine was not enabled it will enable its cookie engine. Passing a magic string "ALL" will erase all cookies known by cURL. (Added in 7.14.1) Passing the special string "SESS" will only erase all session cookies known by cURL. (Added in 7.15.4) Passing the special string "FLUSH" will write all cookies known by cURL to the file specified by <a class="emphasis" href="#CURLOPTCOOKIEJAR">CURLOPT_COOKIEJAR</a>. (Added in 7.17.1) <p class="level0"><a name="CURLOPTHTTPGET"></a><span class="nroffip">CURLOPT_HTTPGET</span> <p class="level1">Pass a long. If the long is 1, this forces the HTTP request to get back to GET. Usable if a POST, HEAD, PUT, or a custom request has been used previously using the same curl handle. -<p class="level1">When setting <a class="emphasis" href="#CURLOPTHTTPGET">CURLOPT_HTTPGET</a> to 1, it will automatically set <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a> to 0 (since 7.14.1). +<p class="level1">When setting <a class="emphasis" href="#CURLOPTHTTPGET">CURLOPT_HTTPGET</a> to 1, it will automatically set <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a> to 0 and <a class="emphasis" href="#CURLOPTUPLOAD">CURLOPT_UPLOAD</a> to 0. <p class="level0"><a name="CURLOPTHTTPVERSION"></a><span class="nroffip">CURLOPT_HTTP_VERSION</span> <p class="level1">Pass a long, set to one of the values described below. They force libcurl to use the specific HTTP versions. This is not sensible to do unless you have a good reason. <p class="level2"> @@ -430,20 +566,27 @@ p.roffit { <p class="level0"><a name="CURLOPTIGNORECONTENTLENGTH"></a><span class="nroffip">CURLOPT_IGNORE_CONTENT_LENGTH</span> <p class="level1">Ignore the Content-Length header. This is useful for Apache 1.x (and similar servers) which will report incorrect content length for files over 2 gigabytes. If this option is used, curl will not be able to accurately report progress, and will simply stop the download when the server ends the connection. (added in 7.14.1) <p class="level0"><a name="CURLOPTHTTPCONTENTDECODING"></a><span class="nroffip">CURLOPT_HTTP_CONTENT_DECODING</span> -<p class="level1">Pass a long to tell libcurl how to act on content decoding. If set to zero, content decoding will be disabled. If set to 1 it is enabled. Libcurl has no default content decoding but requires you to use <a class="emphasis" href="#CURLOPTENCODING">CURLOPT_ENCODING</a> for that. (added in 7.16.2) +<p class="level1">Pass a long to tell libcurl how to act on content decoding. If set to zero, content decoding will be disabled. If set to 1 it is enabled. Libcurl has no default content decoding but requires you to use <a class="emphasis" href="#CURLOPTACCEPTENCODING">CURLOPT_ACCEPT_ENCODING</a> for that. (added in 7.16.2) <p class="level0"><a name="CURLOPTHTTPTRANSFERDECODING"></a><span class="nroffip">CURLOPT_HTTP_TRANSFER_DECODING</span> <p class="level1">Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding will be disabled, if set to 1 it is enabled (default). libcurl does chunked transfer decoding by default unless this option is set to zero. (added in 7.16.2) <a name="SMTP"></a><h2 class="nroffsh">SMTP OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTMAILFROM"></a><span class="nroffip">CURLOPT_MAIL_FROM</span> -<p class="level1">Pass a pointer to a zero terminated string as parameter. It will be used to specify the sender address in a mail when sending an SMTP mail with libcurl. +<p class="level1">Pass a pointer to a zero terminated string as parameter. This should be used to specify the sender's email address when sending SMTP mail with libcurl. +<p class="level1">An originator email address should be specified with angled brackets (<>) around it, which if not specified, will be added by libcurl from version 7.21.4 onwards. Failing to provide such brackets may cause the server to reject the email. +<p class="level1">If this parameter is not specified then an empty address will be sent to the mail server which may or may not cause the email to be rejected. <p class="level1">(Added in 7.20.0) <p class="level0"><a name="CURLOPTMAILRCPT"></a><span class="nroffip">CURLOPT_MAIL_RCPT</span> -<p class="level1">Pass a pointer to a linked list of recipients to pass to the server in your SMTP mail request. The linked list should be a fully valid list of <span class="bold">struct curl_slist</span> structs properly filled in. Use <a class="emphasis" href="./curl_slist_append.html">curl_slist_append(3)</a> to create the list and <a class="emphasis" href="./curl_slist_free_all.html">curl_slist_free_all(3)</a> to clean up an entire list. -<p class="level1">Each recipient in SMTP lingo is specified with angle brackets (<>), but should you not use an angle bracket as first letter libcurl will assume you provide a single email address only and enclose that with angle brackets for you. -<p class="level1">(Added in 7.20.0) <a name="TFTP"></a><h2 class="nroffsh">TFTP OPTIONS</h2> +<p class="level1">Pass a pointer to a linked list of recipients to pass to the server in your SMTP mail request. The linked list should be a fully valid list of <span class="bold">struct curl_slist</span> structs properly filled in. Use <a class="emphasis" href="./curl_slist_append.html">curl_slist_append(3)</a> to create the list and <a class="emphasis" href="./curl_slist_free_all.html">curl_slist_free_all(3)</a> to clean up an entire list. +<p class="level1">Each recipient should be specified within a pair of angled brackets (<>), however, should you not use an angled bracket as the first character libcurl will assume you provided a single email address and enclose that address within brackets for you. +<p class="level1">(Added in 7.20.0) +<p class="level0"><a name="CURLOPTMAILAUTH"></a><span class="nroffip">CURLOPT_MAIL_AUTH</span> +<p class="level1">Pass a pointer to a zero terminated string as parameter. This will be used to specify the authentication address (identity) of a submitted message that is being relayed to another server. +<p class="level1">This optional parameter allows co-operating agents in a trusted environment to communicate the authentication of individual messages and should only be used by the application program, using libcurl, if the application is itself a mail server acting in such an environment. If the application is operating as such and the AUTH address is not known or is invalid, then an empty string should be used for this parameter. +<p class="level1">Unlike CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT, the address should not be specified within a pair of angled brackets (<>). However, if an empty string is used then a pair of brackets will be sent by libcurl as required by <a href="http://www.ietf.org/rfc/rfc2554.txt">RFC 2554</a>. +<p class="level1">(Added in 7.25.0) <a name="TFTP"></a><h2 class="nroffsh">TFTP OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTTFTPBLKSIZE"></a><span class="nroffip">CURLOPT_TFTP_BLKSIZE</span> -<p class="level1">Specify block size to use for TFTP data transmission. Valid range as per RFC 2348 is 8-65464 bytes. The default of 512 bytes will be used if this option is not specified. The specified block size will only be used pending support by the remote server. If the server does not return an option acknowledgement or returns an option acknowledgement with no blksize, the default of 512 bytes will be used. (added in 7.19.4) <a name="FTP"></a><h2 class="nroffsh">FTP OPTIONS</h2> +<p class="level1">Specify block size to use for TFTP data transmission. Valid range as per <a href="http://www.ietf.org/rfc/rfc2348.txt">RFC 2348</a> is 8-65464 bytes. The default of 512 bytes will be used if this option is not specified. The specified block size will only be used pending support by the remote server. If the server does not return an option acknowledgement or returns an option acknowledgement with no blksize, the default of 512 bytes will be used. (added in 7.19.4) <a name="FTP"></a><h2 class="nroffsh">FTP OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTFTPPORT"></a><span class="nroffip">CURLOPT_FTPPORT</span> <p class="level1">Pass a pointer to a zero terminated string as parameter. It will be used to get the IP address to use for the FTP PORT instruction. The PORT instruction tells the remote server to connect to our specified IP address. The string may be a plain IP address, a host name, a network interface name (under Unix) or just a '-' symbol to let the library use your system's default IP address. Default FTP operations are passive, and thus won't use PORT. @@ -459,11 +602,13 @@ p.roffit { <p class="level1"> <p class="level1">You disable PORT again and go back to using the passive version by setting this option to NULL. <p class="level0"><a name="CURLOPTQUOTE"></a><span class="nroffip">CURLOPT_QUOTE</span> -<p class="level1">Pass a pointer to a linked list of FTP or SFTP commands to pass to the server prior to your FTP request. This will be done before any other commands are issued (even before the CWD command for FTP). The linked list should be a fully valid list of 'struct curl_slist' structs properly filled in with text strings. Use <a class="emphasis" href="./curl_slist_append.html">curl_slist_append(3)</a> to append strings (commands) to the list, and clear the entire list afterwards with <a class="emphasis" href="./curl_slist_free_all.html">curl_slist_free_all(3)</a>. Disable this operation again by setting a NULL to this option. The set of valid FTP commands depends on the server (see RFC959 for a list of mandatory commands). The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm, rmdir, symlink (see <span Class="manpage">curl (1))</span> (SFTP support added in 7.16.3) +<p class="level1">Pass a pointer to a linked list of FTP or SFTP commands to pass to the server prior to your FTP request. This will be done before any other commands are issued (even before the CWD command for FTP). The linked list should be a fully valid list of 'struct curl_slist' structs properly filled in with text strings. Use <a class="emphasis" href="./curl_slist_append.html">curl_slist_append(3)</a> to append strings (commands) to the list, and clear the entire list afterwards with <a class="emphasis" href="./curl_slist_free_all.html">curl_slist_free_all(3)</a>. Disable this operation again by setting a NULL to this option. When speaking to a FTP (or SFTP since 7.24.0) server, prefix the command with an asterisk (*) to make libcurl continue even if the command fails as by default libcurl will stop at first failure. +<p class="level1">The set of valid FTP commands depends on the server (see <a href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</a> for a list of mandatory commands). +<p class="level1">The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm, rmdir, symlink (see <span Class="manpage">curl (1))</span> (SFTP support added in 7.16.3) <p class="level0"><a name="CURLOPTPOSTQUOTE"></a><span class="nroffip">CURLOPT_POSTQUOTE</span> <p class="level1">Pass a pointer to a linked list of FTP or SFTP commands to pass to the server after your FTP transfer request. The commands will only be run if no error occurred. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for <a class="emphasis" href="#CURLOPTQUOTE">CURLOPT_QUOTE</a>. Disable this operation again by setting a NULL to this option. <p class="level0"><a name="CURLOPTPREQUOTE"></a><span class="nroffip">CURLOPT_PREQUOTE</span> -<p class="level1">Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for <a class="emphasis" href="#CURLOPTQUOTE">CURLOPT_QUOTE</a>. Disable this operation again by setting a NULL to this option. Before version 7.15.6, if you also set <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a> to 1, this option didn't work. +<p class="level1">Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for <a class="emphasis" href="#CURLOPTQUOTE">CURLOPT_QUOTE</a>. Disable this operation again by setting a NULL to this option. Before version 7.16.0, if you also set <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a> to 1, this option didn't work. <p class="level0"><a name="CURLOPTDIRLISTONLY"></a><span class="nroffip">CURLOPT_DIRLISTONLY</span> <p class="level1">A parameter set to 1 tells the library to just list the names of files in a directory, instead of doing a full directory listing that would include file sizes, dates etc. This works for FTP and SFTP URLs. <p class="level1">This causes an FTP NLST command to be sent on an FTP server. Beware that some FTP servers list only files in their response to NLST; they might not include subdirectories and symbolic links. @@ -484,7 +629,7 @@ p.roffit { <p class="level0"><a name="CURLOPTFTPCREATEMISSINGDIRS"></a><span class="nroffip">CURLOPT_FTP_CREATE_MISSING_DIRS</span> <p class="level1">Pass a long. If the value is 1, curl will attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working directory. (Added in 7.10.7) <p class="level1">This setting also applies to SFTP-connections. curl will attempt to create the remote directory if it can't obtain a handle to the target-location. The creation will fail if a file of the same name as the directory to create already exists or lack of permissions prevents creation. (Added in 7.16.3) -<p class="level1">Starting with 7.19.4, you can also set this value to 2, which will make libcurl retry the CWD command again if the subsequent MKD command fails. This is especially useful if you're doing many simultanoes connections against the same server and they all have this option enabled, as then CWD may first fail but then another connection does MKD before this connection and thus MKD fails but trying CWD works! 7.19.4 also introduced the <span Class="emphasis">CURLFTP_CREATE_DIR</span> and <span Class="emphasis">CURLFTP_CREATE_DIR_RETRY</span> enum names for these arguments. +<p class="level1">Starting with 7.19.4, you can also set this value to 2, which will make libcurl retry the CWD command again if the subsequent MKD command fails. This is especially useful if you're doing many simultaneous connections against the same server and they all have this option enabled, as then CWD may first fail but then another connection does MKD before this connection and thus MKD fails but trying CWD works! 7.19.4 also introduced the <span Class="emphasis">CURLFTP_CREATE_DIR</span> and <span Class="emphasis">CURLFTP_CREATE_DIR_RETRY</span> enum names for these arguments. <p class="level1">Before version 7.19.4, libcurl will simply ignore arguments set to 2 and act as if 1 was selected. <p class="level0"><a name="CURLOPTFTPRESPONSETIMEOUT"></a><span class="nroffip">CURLOPT_FTP_RESPONSE_TIMEOUT</span> <p class="level1">Pass a long. Causes curl to set a timeout period (in seconds) on the amount of time that the server is allowed to take in order to generate a response message for a command before the session is considered hung. While curl is waiting for a response, this value overrides <a class="emphasis" href="#CURLOPTTIMEOUT">CURLOPT_TIMEOUT</a>. It is recommended that if used in conjunction with <a class="emphasis" href="#CURLOPTTIMEOUT">CURLOPT_TIMEOUT</a>, you set <a class="emphasis" href="#CURLOPTFTPRESPONSETIMEOUT">CURLOPT_FTP_RESPONSE_TIMEOUT</a> to a value smaller than <a class="emphasis" href="#CURLOPTTIMEOUT">CURLOPT_TIMEOUT</a>. (Added in 7.10.8) @@ -514,12 +659,12 @@ p.roffit { <p class="level2">Initiate the shutdown and wait for a reply. <p class="level1"> <p class="level0"><a name="CURLOPTFTPACCOUNT"></a><span class="nroffip">CURLOPT_FTP_ACCOUNT</span> -<p class="level1">Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP server asks for "account data" after user name and password has been provided, this data is sent off using the ACCT command. (Added in 7.13.0) +<p class="level1">Pass a pointer to a zero terminated string (or NULL to disable). When an FTP server asks for "account data" after user name and password has been provided, this data is sent off using the ACCT command. (Added in 7.13.0) <p class="level0"><a name="CURLOPTFTPFILEMETHOD"></a><span class="nroffip">CURLOPT_FTP_FILEMETHOD</span> <p class="level1">Pass a long that should have one of the following values. This option controls what method libcurl should use to reach a file on a FTP(S) server. The argument should be one of the following alternatives: <p class="level2"> <p class="level1"><a name="CURLFTPMETHODMULTICWD"></a><span class="nroffip">CURLFTPMETHOD_MULTICWD</span> -<p class="level2">libcurl does a single CWD operation for each path part in the given URL. For deep hierarchies this means many commands. This is how RFC1738 says it should be done. This is the default but the slowest behavior. +<p class="level2">libcurl does a single CWD operation for each path part in the given URL. For deep hierarchies this means many commands. This is how <a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a> says it should be done. This is the default but the slowest behavior. <p class="level1"><a name="CURLFTPMETHODNOCWD"></a><span class="nroffip">CURLFTPMETHOD_NOCWD</span> <p class="level2">libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a full path to the server for all these commands. This is the fastest behavior. <p class="level1"><a name="CURLFTPMETHODSINGLECWD"></a><span class="nroffip">CURLFTPMETHOD_SINGLECWD</span> @@ -530,11 +675,11 @@ p.roffit { <p class="level1">Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP enum values. Unless noted otherwise, commands require the Session ID to be initialized. (Added in 7.20.0) <p class="level2"> <p class="level1"><a name="CURLRTSPREQOPTIONS"></a><span class="nroffip">CURL_RTSPREQ_OPTIONS</span> -<p class="level2">Used to retrieve the available methods of the server. The application is responsbile for parsing and obeying the response. <span class="bold">(The session ID is not needed for this method.)</span> (Added in 7.20.0) +<p class="level2">Used to retrieve the available methods of the server. The application is responsible for parsing and obeying the response. <span class="bold">(The session ID is not needed for this method.)</span> (Added in 7.20.0) <p class="level1"><a name="CURLRTSPREQDESCRIBE"></a><span class="nroffip">CURL_RTSPREQ_DESCRIBE</span> <p class="level2">Used to get the low level description of a stream. The application should note what formats it understands in the <span Class="emphasis">'Accept:'</span> header. Unless set manually, libcurl will automatically fill in <span class="emphasis">'Accept: application/sdp'</span>. Time-condition headers will be added to Describe requests if the <a class="emphasis" href="#CURLOPTTIMECONDITION">CURLOPT_TIMECONDITION</a> option is active. <span class="bold">(The session ID is not needed for this method)</span> (Added in 7.20.0) <p class="level1"><a name="CURLRTSPREQANNOUNCE"></a><span class="nroffip">CURL_RTSPREQ_ANNOUNCE</span> -<p class="level2">When sent by a client, this method changes the description of the session. For example, if a client is using the server to record a meeting, the client can use Announce to inform the server of all the meta-information about the session. ANNOUNCE acts like an HTTP PUT or POST just like <a class="emphasis" href="#CURLRTSPREQSETPARAMETER">CURL_RTSPREQ_SET_PARAMETER</a> (Added in 7.20.0) +<p class="level2">When sent by a client, this method changes the description of the session. For example, if a client is using the server to record a meeting, the client can use Announce to inform the server of all the meta-information about the session. ANNOUNCE acts like a HTTP PUT or POST just like <a class="emphasis" href="#CURLRTSPREQSETPARAMETER">CURL_RTSPREQ_SET_PARAMETER</a> (Added in 7.20.0) <p class="level1"><a name="CURLRTSPREQSETUP"></a><span class="nroffip">CURL_RTSPREQ_SETUP</span> <p class="level2">Setup is used to initialize the transport layer for the session. The application must set the desired Transport options for a session by using the <a class="emphasis" href="#CURLOPTRTSPTRANSPORT">CURLOPT_RTSP_TRANSPORT</a> option prior to calling setup. If no session ID is currently set with <a class="emphasis" href="#CURLOPTRTSPSESSIONID">CURLOPT_RTSP_SESSION_ID</a>, libcurl will extract and use the session ID in the response to this request. <span class="bold">(The session ID is not needed for this method).</span> (Added in 7.20.0) <p class="level1"><a name="CURLRTSPREQPLAY"></a><span class="nroffip">CURL_RTSPREQ_PLAY</span> @@ -544,9 +689,9 @@ p.roffit { <p class="level1"><a name="CURLRTSPREQTEARDOWN"></a><span class="nroffip">CURL_RTSPREQ_TEARDOWN</span> <p class="level2">This command terminates an RTSP session. Simply closing a connection does not terminate the RTSP session since it is valid to control an RTSP session over different connections. (Added in 7.20.0) <p class="level1"><a name="CURLRTSPREQGETPARAMETER"></a><span class="nroffip">CURL_RTSPREQ_GET_PARAMETER</span> -<p class="level2">Retrieve a parameter from the server. By default, libcurl will automatically include a <span Class="emphasis">Content-Type: text/parameters</span> header on all non-empty requests unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see <a class="emphasis" href="#CURLRTSPREQSETPARAMETER">CURL_RTSPREQ_SET_PARAMETER</a>). Applications wishing to send a heartbeat message (e.g. in the presence of a server-specified timeout) should send use an empty GET_PARAMETER request. (Added in 7.20.0) +<p class="level2">Retrieve a parameter from the server. By default, libcurl will automatically include a <span Class="emphasis">Content-Type: text/parameters</span> header on all non-empty requests unless a custom one is set. GET_PARAMETER acts just like a HTTP PUT or POST (see <a class="emphasis" href="#CURLRTSPREQSETPARAMETER">CURL_RTSPREQ_SET_PARAMETER</a>). Applications wishing to send a heartbeat message (e.g. in the presence of a server-specified timeout) should send use an empty GET_PARAMETER request. (Added in 7.20.0) <p class="level1"><a name="CURLRTSPREQSETPARAMETER"></a><span class="nroffip">CURL_RTSPREQ_SET_PARAMETER</span> -<p class="level2">Set a parameter on the server. By default, libcurl will automatically include a <span Class="emphasis">Content-Type: text/parameters</span> header unless a custom one is set. The interaction with SET_PARAMTER is much like an HTTP PUT or POST. An application may either use <a class="emphasis" href="#CURLOPTUPLOAD">CURLOPT_UPLOAD</a> with <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a> like an HTTP PUT, or it may use <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> like an HTTP POST. No chunked transfers are allowed, so the application must set the <a class="emphasis" href="#CURLOPTINFILESIZE">CURLOPT_INFILESIZE</a> in the former and <a class="emphasis" href="#CURLOPTPOSTFIELDSIZE">CURLOPT_POSTFIELDSIZE</a> in the latter. Also, there is no use of multi-part POSTs within RTSP. (Added in 7.20.0) +<p class="level2">Set a parameter on the server. By default, libcurl will automatically include a <span Class="emphasis">Content-Type: text/parameters</span> header unless a custom one is set. The interaction with SET_PARAMTER is much like a HTTP PUT or POST. An application may either use <a class="emphasis" href="#CURLOPTUPLOAD">CURLOPT_UPLOAD</a> with <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a> like a HTTP PUT, or it may use <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> like a HTTP POST. No chunked transfers are allowed, so the application must set the <a class="emphasis" href="#CURLOPTINFILESIZE">CURLOPT_INFILESIZE</a> in the former and <a class="emphasis" href="#CURLOPTPOSTFIELDSIZE">CURLOPT_POSTFIELDSIZE</a> in the latter. Also, there is no use of multi-part POSTs within RTSP. (Added in 7.20.0) <p class="level1"><a name="CURLRTSPREQRECORD"></a><span class="nroffip">CURL_RTSPREQ_RECORD</span> <p class="level2">Used to tell the server to record a session. Use the <a class="emphasis" href="#CURLOPTRANGE">CURLOPT_RANGE</a> option to modify the record time. (Added in 7.20.0) <p class="level1"><a name="CURLRTSPREQRECEIVE"></a><span class="nroffip">CURL_RTSPREQ_RECEIVE</span> @@ -569,11 +714,11 @@ p.roffit { <p class="level1">A parameter set to 1 tells the library to use ASCII mode for FTP transfers, instead of the default binary transfer. For win32 systems it does not set the stdout to binary mode. This option can be usable when transferring text data between systems with different views on certain characters, such as newlines or similar. <p class="level1">libcurl does not do a complete ASCII conversion when doing ASCII transfers over FTP. This is a known limitation/flaw that nobody has rectified. libcurl simply sets the mode to ASCII and performs a standard transfer. <p class="level0"><a name="CURLOPTPROXYTRANSFERMODE"></a><span class="nroffip">CURLOPT_PROXY_TRANSFER_MODE</span> -<p class="level1">Pass a long. If the value is set to 1 (one), it tells libcurl to set the transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by appending ;type=a or ;type=i to the URL. Without this setting, or it being set to 0 (zero, the default), <a class="emphasis" href="#CURLOPTTRANSFERTEXT">CURLOPT_TRANSFERTEXT</a> has no effect when doing FTP via a proxy. Beware that not all proxies support this feature. (Added in 7.18.0) +<p class="level1">Pass a long. If the value is set to 1 (one), it tells libcurl to set the transfer mode (binary or ASCII) for FTP transfers done via a HTTP proxy, by appending ;type=a or ;type=i to the URL. Without this setting, or it being set to 0 (zero, the default), <a class="emphasis" href="#CURLOPTTRANSFERTEXT">CURLOPT_TRANSFERTEXT</a> has no effect when doing FTP via a proxy. Beware that not all proxies support this feature. (Added in 7.18.0) <p class="level0"><a name="CURLOPTCRLF"></a><span class="nroffip">CURLOPT_CRLF</span> <p class="level1">Pass a long. If the value is set to 1 (one), libcurl converts Unix newlines to CRLF newlines on transfers. Disable this option again by setting the value to 0 (zero). <p class="level0"><a name="CURLOPTRANGE"></a><span class="nroffip">CURLOPT_RANGE</span> -<p class="level1">Pass a char * as parameter, which should contain the specified range you want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in <span Class="emphasis">"X-Y,N-M"</span>. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation techniques). For RTSP, the formatting of a range should follow RFC 2326 Section 12.29. For RTSP, byte ranges are <span Class="bold">not</span> permitted. Instead, ranges should be given in npt, utc, or smpte formats. +<p class="level1">Pass a char * as parameter, which should contain the specified range you want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in <span Class="emphasis">"X-Y,N-M"</span>. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation techniques). For RTSP, the formatting of a range should follow <a href="http://www.ietf.org/rfc/rfc2326.txt">RFC 2326</a> Section 12.29. For RTSP, byte ranges are <span Class="bold">not</span> permitted. Instead, ranges should be given in npt, utc, or smpte formats. <p class="level1">Pass a NULL to this option to disable the use of ranges. <p class="level1">Ranges work on HTTP, FTP, FILE (since 7.18.0), and RTSP (since 7.20.0) transfers only. <p class="level0"><a name="CURLOPTRESUMEFROM"></a><span class="nroffip">CURLOPT_RESUME_FROM</span> @@ -582,12 +727,15 @@ p.roffit { <p class="level0"><a name="CURLOPTRESUMEFROMLARGE"></a><span class="nroffip">CURLOPT_RESUME_FROM_LARGE</span> <p class="level1">Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) <p class="level0"><a name="CURLOPTCUSTOMREQUEST"></a><span class="nroffip">CURLOPT_CUSTOMREQUEST</span> -<p class="level1">Pass a pointer to a zero terminated string as parameter. It will be used instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST when doing a FTP directory listing. This is useful for doing DELETE or other more or less obscure HTTP requests. Don't do this at will, make sure your server supports the command first. +<p class="level1">Pass a pointer to a zero terminated string as parameter. It can be used to specify the request instead of GET or HEAD when performing HTTP based requests, instead of LIST and NLST when performing FTP directory listings and instead of LIST and RETR when issuing POP3 based commands. This is particularly useful, for example, for performing a HTTP DELETE request or a POP3 DELE command. +<p class="level1">Please don't perform this at will, on HTTP based requests, by making sure your server supports the command you are sending first. <p class="level1">When you change the request method by setting <a class="bold" href="#CURLOPTCUSTOMREQUEST">CURLOPT_CUSTOMREQUEST</a> to something, you don't actually change how libcurl behaves or acts in regards to the particular request method, it will only change the actual string sent in the request. -<p class="level1">For example: if you tell libcurl to do a HEAD request, but then change the request to a "GET" with <a class="bold" href="#CURLOPTCUSTOMREQUEST">CURLOPT_CUSTOMREQUEST</a> you'll still see libcurl act as if it sent a HEAD even when it does send a GET. -<p class="level1">To switch to a proper HEAD, use <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a>, to switch to a proper POST, use <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a> or <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> and so on. +<p class="level1">For example: +<p class="level1">With the HTTP protocol when you tell libcurl to do a HEAD request, but then specify a GET though a custom request libcurl will still act as if it sent a HEAD. To switch to a proper HEAD use <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a>, to switch to a proper POST use <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a> or <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> and to switch to a proper GET use CURLOPT_HTTPGET. +<p class="level1">With the POP3 protocol when you tell libcurl to use a custom request it will behave like a LIST or RETR command was sent where it expects data to be returned by the server. As such <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a> should be used when specifying commands such as DELE and NOOP for example. <p class="level1">Restore to the internal default by setting this to NULL. <p class="level1">Many people have wrongly used this option to replace the entire request with their own, including multiple headers and POST contents. While that might work in many cases, it will cause libcurl to send invalid requests and it could possibly confuse the remote server badly. Use <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a> and <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> to set POST data. Use <a class="emphasis" href="#CURLOPTHTTPHEADER">CURLOPT_HTTPHEADER</a> to replace or extend the set of headers sent by libcurl. Use <a class="emphasis" href="#CURLOPTHTTPVERSION">CURLOPT_HTTP_VERSION</a> to change HTTP version. +<p class="level1">(Support for POP3 added in 7.26.0) <p class="level0"><a name="CURLOPTFILETIME"></a><span class="nroffip">CURLOPT_FILETIME</span> <p class="level1">Pass a long. If it is 1, libcurl will attempt to get the modification date of the remote document in this operation. This requires that the remote server sends the time or replies to a time querying command. The <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a> function with the <span Class="emphasis">CURLINFO_FILETIME</span> argument can be used after a transfer to extract the received time (if any). <p class="level0"><a name="CURLOPTNOBODY"></a><span class="nroffip">CURLOPT_NOBODY</span> @@ -596,6 +744,7 @@ p.roffit { <p class="level0"><a name="CURLOPTINFILESIZE"></a><span class="nroffip">CURLOPT_INFILESIZE</span> <p class="level1">When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a long. See also <a class="emphasis" href="#CURLOPTINFILESIZELARGE">CURLOPT_INFILESIZE_LARGE</a>. <p class="level1">For uploading using SCP, this option or <a class="emphasis" href="#CURLOPTINFILESIZELARGE">CURLOPT_INFILESIZE_LARGE</a> is mandatory. +<p class="level1">When sending emails using SMTP, this command can be used to specify the optional SIZE parameter for the MAIL FROM command. (Added in 7.23.0) <p class="level1">This option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns. <p class="level0"><a name="CURLOPTINFILESIZELARGE"></a><span class="nroffip">CURLOPT_INFILESIZE_LARGE</span> <p class="level1">When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a curl_off_t. (Added in 7.11.0) @@ -612,7 +761,7 @@ p.roffit { <p class="level1">Pass a curl_off_t as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and <span Class="emphasis">CURLE_FILESIZE_EXCEEDED</span> will be returned. (Added in 7.11.0) <p class="level1">The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. This concerns both FTP and HTTP transfers. <p class="level0"><a name="CURLOPTTIMECONDITION"></a><span class="nroffip">CURLOPT_TIMECONDITION</span> -<p class="level1">Pass a long as parameter. This defines how the <a class="emphasis" href="#CURLOPTTIMEVALUE">CURLOPT_TIMEVALUE</a> time value is treated. You can set this parameter to <span Class="emphasis">CURL_TIMECOND_IFMODSINCE</span> or <span Class="emphasis">CURL_TIMECOND_IFUNMODSINCE</span>. This feature applies to HTTP, FTP, and RTSP. +<p class="level1">Pass a long as parameter. This defines how the <a class="emphasis" href="#CURLOPTTIMEVALUE">CURLOPT_TIMEVALUE</a> time value is treated. You can set this parameter to <span Class="emphasis">CURL_TIMECOND_IFMODSINCE</span> or <span Class="emphasis">CURL_TIMECOND_IFUNMODSINCE</span>. This feature applies to HTTP, FTP, RTSP, and FILE. <p class="level1">The last modification time of a file is not always known and in such instances this feature will have no effect even if the given time condition would not have been met. <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a> with the <span Class="emphasis">CURLINFO_CONDITION_UNMET</span> option can be used after a transfer to learn if a zero-byte successful "transfer" was due to this condition not matching. <p class="level0"><a name="CURLOPTTIMEVALUE"></a><span class="nroffip">CURLOPT_TIMEVALUE</span> <p class="level1">Pass a long as parameter. This should be the time in seconds since 1 Jan 1970, and the time will be used in a condition as specified with <a class="emphasis" href="#CURLOPTTIMECONDITION">CURLOPT_TIMECONDITION</a>. <a name="CONNECTION"></a><h2 class="nroffsh">CONNECTION OPTIONS</h2> @@ -620,6 +769,7 @@ p.roffit { <p class="level0"><a name="CURLOPTTIMEOUT"></a><span class="nroffip">CURLOPT_TIMEOUT</span> <p class="level1">Pass a long as parameter containing the maximum time in seconds that you allow the libcurl transfer operation to take. Normally, name lookups can take a considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations. This option will cause curl to use the SIGALRM to enable time-outing system calls. <p class="level1">In unix-like systems, this might cause signals to be used unless <a class="emphasis" href="#CURLOPTNOSIGNAL">CURLOPT_NOSIGNAL</a> is set. +<p class="level1">Default timeout is 0 (zero) which means it never times out. <p class="level0"><a name="CURLOPTTIMEOUTMS"></a><span class="nroffip">CURLOPT_TIMEOUT_MS</span> <p class="level1">Like <a class="emphasis" href="#CURLOPTTIMEOUT">CURLOPT_TIMEOUT</a> but takes number of milliseconds instead. If libcurl is built to use the standard system name resolver, that portion of the transfer will still use full-second resolution for timeouts with a minimum timeout allowed of one second. (Added in 7.16.2) <p class="level0"><a name="CURLOPTLOWSPEEDLIMIT"></a><span class="nroffip">CURLOPT_LOW_SPEED_LIMIT</span> @@ -642,7 +792,7 @@ p.roffit { <p class="level0"><a name="CURLOPTFORBIDREUSE"></a><span class="nroffip">CURLOPT_FORBID_REUSE</span> <p class="level1">Pass a long. Set to 1 to make the next transfer explicitly close the connection when done. Normally, libcurl keeps all connections alive when done with one transfer in case a succeeding one follows that can re-use them. This option should be used with caution and only if you understand what it does. Set to 0 to have libcurl keep the connection open for possible later re-use (default behavior). <p class="level0"><a name="CURLOPTCONNECTTIMEOUT"></a><span class="nroffip">CURLOPT_CONNECTTIMEOUT</span> -<p class="level1">Pass a long. It should contain the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once it has connected, this option is of no more use. Set to zero to disable connection timeout (it will then only timeout on the system's internal timeouts). See also the <a class="emphasis" href="#CURLOPTTIMEOUT">CURLOPT_TIMEOUT</a> option. +<p class="level1">Pass a long. It should contain the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once it has connected, this option is of no more use. Set to zero to switch to the default built-in connection timeout - 300 seconds. See also the <a class="emphasis" href="#CURLOPTTIMEOUT">CURLOPT_TIMEOUT</a> option. <p class="level1">In unix-like systems, this might cause signals to be used unless <a class="emphasis" href="#CURLOPTNOSIGNAL">CURLOPT_NOSIGNAL</a> is set. <p class="level0"><a name="CURLOPTCONNECTTIMEOUTMS"></a><span class="nroffip">CURLOPT_CONNECTTIMEOUT_MS</span> <p class="level1">Like <a class="emphasis" href="#CURLOPTCONNECTTIMEOUT">CURLOPT_CONNECTTIMEOUT</a> but takes the number of milliseconds instead. If libcurl is built to use the standard system name resolver, that portion of the connect will still use full-second resolution for timeouts with a minimum timeout allowed of one second. (Added in 7.16.2) @@ -657,8 +807,8 @@ p.roffit { <p class="level2">Resolve to IPv6 addresses. <p class="level1"> <p class="level0"><a name="CURLOPTCONNECTONLY"></a><span class="nroffip">CURLOPT_CONNECT_ONLY</span> -<p class="level1">Pass a long. If the parameter equals 1, it tells the library to perform all the required proxy authentication and connection setup, but no data transfer. This option is useful only on HTTP URLs. -<p class="level1">This option is useful with the <span Class="emphasis">CURLINFO_LASTSOCKET</span> option to <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a>. The library can set up the connection and then the application can obtain the most recently used socket for special data transfers. (Added in 7.15.2) +<p class="level1">Pass a long. If the parameter equals 1, it tells the library to perform all the required proxy authentication and connection setup, but no data transfer. This option is implemented for HTTP, SMTP and POP3. +<p class="level1">The option can be used to simply test a connection to a server, but is more useful when used with the <span Class="emphasis">CURLINFO_LASTSOCKET</span> option to <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a> as the library can set up the connection and then the application can obtain the most recently used socket for special data transfers. (Added in 7.15.2) <p class="level0"><a name="CURLOPTUSESSL"></a><span class="nroffip">CURLOPT_USE_SSL</span> <p class="level1">Pass a long using one of the values from below, to make libcurl use your desired level of SSL for the transfer. (Added in 7.11.0) <p class="level1">This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. @@ -678,15 +828,26 @@ p.roffit { <p class="level1">Each single name resolve string should be written using the format HOST:PORT:ADDRESS where HOST is the name libcurl will try to resolve, PORT is the port number of the service where libcurl wants to connect to the HOST and ADDRESS is the numerical IP address. If libcurl is built to support IPv6, ADDRESS can of course be either IPv4 or IPv6 style addressing. <p class="level1">This option effectively pre-populates the DNS cache with entries for the host+port pair so redirects and everything that operations against the HOST+PORT will instead use your provided ADDRESS. <p class="level1">You can remove names from the DNS cache again, to stop providing these fake resolves, by including a string in the linked list that uses the format "-HOST:PORT". The host name must be prefixed with a dash, and the host name and port number must exactly match what was already added previously. -<p class="level1">(Added in 7.12.3) <a name="SSL"></a><h2 class="nroffsh">SSL and SECURITY OPTIONS</h2> +<p class="level1">(Added in 7.21.3) +<p class="level0"><a name="CURLOPTDNSSERVERS"></a><span class="nroffip">CURLOPT_DNS_SERVERS</span> +<p class="level1">Set the list of DNS servers to be used instead of the system default. The format of the dns servers option is: +<p class="level1">host[:port][,host[:port]]... +<p class="level1">For example: +<p class="level1">192.168.1.100,192.168.1.101,3.4.5.6 +<p class="level1">This option requires that libcurl was built with a resolver backend that supports this operation. The c-ares backend is the only such one. +<p class="level1">(Added in 7.24.0) +<p class="level0"><a name="CURLOPTACCEPTTIMEOUTMS"></a><span class="nroffip">CURLOPT_ACCEPTTIMEOUT_MS</span> +<p class="level1">Pass a long telling libcurl the maximum number of milliseconds to wait for a server to connect back to libcurl when an active FTP connection is used. If no timeout is set, the internal default of 60000 will be used. (Added in 7.24.0) <a name="SSL"></a><h2 class="nroffsh">SSL and SECURITY OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTSSLCERT"></a><span class="nroffip">CURLOPT_SSLCERT</span> <p class="level1">Pass a pointer to a zero terminated string as parameter. The string should be the file name of your certificate. The default format is "PEM" and can be changed with <a class="emphasis" href="#CURLOPTSSLCERTTYPE">CURLOPT_SSLCERTTYPE</a>. -<p class="level1">With NSS this is the nickname of the certificate you wish to authenticate with. +<p class="level1">With NSS this can also be the nickname of the certificate you wish to authenticate with. If you want to use a file from the current directory, please precede it with "./" prefix, in order to avoid confusion with a nickname. +<p class="level1">(iOS and Mac OS X only) With Secure Transport, this string must match the name of a certificate that's in the system or user keychain. You should encode this string in UTF-8 format in case it contains non-ASCII characters. The private key corresponding to the certificate, and certificate chain (if any), must also be present in the keychain. (Added in 7.31.0) <p class="level0"><a name="CURLOPTSSLCERTTYPE"></a><span class="nroffip">CURLOPT_SSLCERTTYPE</span> <p class="level1">Pass a pointer to a zero terminated string as parameter. The string should be the format of your certificate. Supported formats are "PEM" and "DER". (Added in 7.9.3) <p class="level0"><a name="CURLOPTSSLKEY"></a><span class="nroffip">CURLOPT_SSLKEY</span> <p class="level1">Pass a pointer to a zero terminated string as parameter. The string should be the file name of your private key. The default format is "PEM" and can be changed with <a class="emphasis" href="#CURLOPTSSLKEYTYPE">CURLOPT_SSLKEYTYPE</a>. +<p class="level1">(iOS and Mac OS X only) This option is ignored if curl was built against Secure Transport. Secure Transport expects the private key to be already present in the keychain containing the certificate. <p class="level0"><a name="CURLOPTSSLKEYTYPE"></a><span class="nroffip">CURLOPT_SSLKEYTYPE</span> <p class="level1">Pass a pointer to a zero terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG". <p class="level1">The format "ENG" enables you to load the private key from a crypto engine. In this case <a class="emphasis" href="#CURLOPTSSLKEY">CURLOPT_SSLKEY</a> is used as an identifier passed to the engine. You have to set the crypto engine with <a class="emphasis" href="#CURLOPTSSLENGINE">CURLOPT_SSLENGINE</a>. "DER" format key file currently does not work because of a bug in OpenSSL. @@ -713,67 +874,74 @@ p.roffit { <p class="level2">Force SSLv3 <p class="level1"> <p class="level0"><a name="CURLOPTSSLVERIFYPEER"></a><span class="nroffip">CURLOPT_SSL_VERIFYPEER</span> -<p class="level1">Pass a long as parameter. -<p class="level1">This option determines whether curl verifies the authenticity of the peer's certificate. A value of 1 means curl verifies; zero means it doesn't. The default is nonzero, but before 7.10, it was zero. -<p class="level1">When negotiating an SSL connection, the server sends a certificate indicating its identity. Curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority (CA) certificates you supply. As of 7.10, curl installs a default bundle of CA certificates and you can specify alternate certificates with the <a class="emphasis" href="#CURLOPTCAINFO">CURLOPT_CAINFO</a> option or the <a class="emphasis" href="#CURLOPTCAPATH">CURLOPT_CAPATH</a> option. -<p class="level1">When <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> is nonzero, and the verification fails to prove that the certificate is authentic, the connection fails. When the option is zero, the connection succeeds regardless. -<p class="level1">Authenticating the certificate is not by itself very useful. You typically want to ensure that the server, as authentically identified by its certificate, is the server you mean to be talking to. Use <a class="emphasis" href="#CURLOPTSSLVERIFYHOST">CURLOPT_SSL_VERIFYHOST</a> to control that. +<p class="level1">Pass a long as parameter. By default, curl assumes a value of 1. +<p class="level1">This option determines whether curl verifies the authenticity of the peer's certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't. +<p class="level1">When negotiating a SSL connection, the server sends a certificate indicating its identity. Curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority (CA) certificates you supply. curl uses a default bundle of CA certificates (the path for that is determined at build time) and you can specify alternate certificates with the <a class="emphasis" href="#CURLOPTCAINFO">CURLOPT_CAINFO</a> option or the <a class="emphasis" href="#CURLOPTCAPATH">CURLOPT_CAPATH</a> option. +<p class="level1">When <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> is nonzero, and the verification fails to prove that the certificate is authentic, the connection fails. When the option is zero, the peer certificate verification succeeds regardless. +<p class="level1">Authenticating the certificate is not by itself very useful. You typically want to ensure that the server, as authentically identified by its certificate, is the server you mean to be talking to. Use <a class="emphasis" href="#CURLOPTSSLVERIFYHOST">CURLOPT_SSL_VERIFYHOST</a> to control that. The check that the host name in the certificate is valid for the host name you're connecting to is done independently of the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option. <p class="level0"><a name="CURLOPTCAINFO"></a><span class="nroffip">CURLOPT_CAINFO</span> <p class="level1">Pass a char * to a zero terminated string naming a file holding one or more certificates to verify the peer with. This makes sense only when used in combination with the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option. If <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> is zero, <a class="emphasis" href="#CURLOPTCAINFO">CURLOPT_CAINFO</a> need not even indicate an accessible file. <p class="level1">This option is by default set to the system path where libcurl's cacert bundle is assumed to be stored, as established at build time. -<p class="level1">When built against NSS, this is the directory that the NSS certificate database resides in. +<p class="level1">If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module (libnsspem.so) needs to be available for this option to work properly. <p class="level0"><a name="CURLOPTISSUERCERT"></a><span class="nroffip">CURLOPT_ISSUERCERT</span> <p class="level1">Pass a char * to a zero terminated string naming a file holding a CA certificate in PEM format. If the option is set, an additional check against the peer certificate is performed to verify the issuer is indeed the one associated with the certificate provided by the option. This additional check is useful in multi-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree. <p class="level1">This option makes sense only when used in combination with the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option. Otherwise, the result of the check is not considered as failure. <p class="level1">A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, which is returned if the setup of the SSL/TLS session has failed due to a mismatch with the issuer of peer certificate (<a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> has to be set too for the check to fail). (Added in 7.19.0) <p class="level0"><a name="CURLOPTCAPATH"></a><span class="nroffip">CURLOPT_CAPATH</span> -<p class="level1">Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. The certificate directory must be prepared using the openssl c_rehash utility. This makes sense only when used in combination with the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option. If <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> is zero, <a class="emphasis" href="#CURLOPTCAPATH">CURLOPT_CAPATH</a> need not even indicate an accessible path. The <a class="emphasis" href="#CURLOPTCAPATH">CURLOPT_CAPATH</a> function apparently does not work in Windows due to some limitation in openssl. This option is OpenSSL-specific and does nothing if libcurl is built to use GnuTLS. +<p class="level1">Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. If libcurl is built against OpenSSL, the certificate directory must be prepared using the openssl c_rehash utility. This makes sense only when used in combination with the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option. If <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> is zero, <a class="emphasis" href="#CURLOPTCAPATH">CURLOPT_CAPATH</a> need not even indicate an accessible path. The <a class="emphasis" href="#CURLOPTCAPATH">CURLOPT_CAPATH</a> function apparently does not work in Windows due to some limitation in openssl. This option is OpenSSL-specific and does nothing if libcurl is built to use GnuTLS. NSS-powered libcurl provides the option only for backward compatibility. <p class="level0"><a name="CURLOPTCRLFILE"></a><span class="nroffip">CURLOPT_CRLFILE</span> <p class="level1">Pass a char * to a zero terminated string naming a file with the concatenation of CRL (in PEM format) to use in the certificate validation that occurs during the SSL exchange. <p class="level1">When curl is built to use NSS or GnuTLS, there is no way to influence the use of CRL passed to help in the verification process. When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the elements of the certificate chain if a CRL file is passed. <p class="level1">This option makes sense only when used in combination with the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option. <p class="level1">A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. A failure in certificate verification due to a revocation information found in the CRL does not trigger this specific error. (Added in 7.19.0) -<p class="level0"><a name="CURLOPTCERTINFO"></a><span class="nroffip">CURLOPT_CERTINFO</span> -<p class="level1">Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With this enabled, libcurl (if built with OpenSSL) will extract lots of information and data about the certificates in the certificate chain used in the SSL connection. This data is then possible to extract after a transfer using <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a> and its option <span Class="emphasis">CURLINFO_CERTINFO</span>. (Added in 7.19.1) -<p class="level0"><a name="CURLOPTRANDOMFILE"></a><span class="nroffip">CURLOPT_RANDOM_FILE</span> -<p class="level1">Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, the more secure the SSL connection will become. -<p class="level0"><a name="CURLOPTEGDSOCKET"></a><span class="nroffip">CURLOPT_EGDSOCKET</span> -<p class="level1">Pass a char * to the zero terminated path name to the Entropy Gathering Daemon socket. It will be used to seed the random engine for SSL. <p class="level0"><a name="CURLOPTSSLVERIFYHOST"></a><span class="nroffip">CURLOPT_SSL_VERIFYHOST</span> <p class="level1">Pass a long as parameter. <p class="level1">This option determines whether libcurl verifies that the server cert is for the server it is known as. <p class="level1">When negotiating a SSL connection, the server sends a certificate indicating its identity. <p class="level1">When <a class="emphasis" href="#CURLOPTSSLVERIFYHOST">CURLOPT_SSL_VERIFYHOST</a> is 2, that certificate must indicate that the server is the server to which you meant to connect, or the connection fails. <p class="level1">Curl considers the server the intended one when the Common Name field or a Subject Alternate Name field in the certificate matches the host name in the URL to which you told Curl to connect. -<p class="level1">When the value is 1, the certificate must contain a Common Name field, but it doesn't matter what name it says. (This is not ordinarily a useful setting). +<p class="level1">When the value is 1, libcurl will return a failure. It was previously (in 7.28.0 and earlier) a debug option of some sorts, but it is no longer supported due to frequently leading to programmer mistakes. <p class="level1">When the value is 0, the connection succeeds regardless of the names in the certificate. -<p class="level1">The default, since 7.10, is 2. -<p class="level1">This option controls checking the server's claimed identity. The server could be lying. To control lying, see <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a>. +<p class="level1">The default value for this option is 2. +<p class="level1">This option controls checking the server's certificate's claimed identity. The server could be lying. To control lying, see <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a>. If libcurl is built against NSS and <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> is zero, <a class="emphasis" href="#CURLOPTSSLVERIFYHOST">CURLOPT_SSL_VERIFYHOST</a> is ignored. +<p class="level1"> +<p class="level0"><a name="CURLOPTCERTINFO"></a><span class="nroffip">CURLOPT_CERTINFO</span> +<p class="level1">Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With this enabled, libcurl (if built with OpenSSL) will extract lots of information and data about the certificates in the certificate chain used in the SSL connection. This data is then possible to extract after a transfer using <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a> and its option <span Class="emphasis">CURLINFO_CERTINFO</span>. (Added in 7.19.1) +<p class="level0"><a name="CURLOPTRANDOMFILE"></a><span class="nroffip">CURLOPT_RANDOM_FILE</span> +<p class="level1">Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, the more secure the SSL connection will become. +<p class="level0"><a name="CURLOPTEGDSOCKET"></a><span class="nroffip">CURLOPT_EGDSOCKET</span> +<p class="level1">Pass a char * to the zero terminated path name to the Entropy Gathering Daemon socket. It will be used to seed the random engine for SSL. <p class="level0"><a name="CURLOPTSSLCIPHERLIST"></a><span class="nroffip">CURLOPT_SSL_CIPHER_LIST</span> <p class="level1">Pass a char *, pointing to a zero terminated string holding the list of ciphers to use for the SSL connection. The list must be syntactically correct, it consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, !, - and + can be used as operators. <p class="level1">For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', ´SHA1+DES´, 'TLSv1' and 'DEFAULT'. The default list is normally set when you compile OpenSSL. <p class="level1">You'll find more details about cipher lists on this URL: <span Class="emphasis"><a href="http://www.openssl.org/docs/apps/ciphers.html">http://www.openssl.org/docs/apps/ciphers.html</a></span> <p class="level1">For NSS, valid examples of cipher lists include 'rsa_rc4_128_md5', ´rsa_aes_128_sha´, etc. With NSS you don't add/remove ciphers. If one uses this option then all known ciphers are disabled and only those passed in are enabled. -<p class="level1">You'll find more details about the NSS cipher lists on this URL: <span Class="emphasis"><a href="http://directory.fedora.redhat.com/docs/mod_nss.html">http://directory.fedora.redhat.com/docs/mod_nss.html</a>#Directives</span> +<p class="level1">You'll find more details about the NSS cipher lists on this URL: <span Class="emphasis"><a href="http://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html">http://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html</a>#Directives</span> <p class="level1"> <p class="level0"><a name="CURLOPTSSLSESSIONIDCACHE"></a><span class="nroffip">CURLOPT_SSL_SESSIONID_CACHE</span> <p class="level1">Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set this to 1 to enable it. By default all transfers are done using the cache. While nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0) +<p class="level0"><a name="CURLOPTSSLOPTIONS"></a><span class="nroffip">CURLOPT_SSL_OPTIONS</span> +<p class="level1">Pass a long with a bitmask to tell libcurl about specific SSL behaviors. +<p class="level1">CURLSSLOPT_ALLOW_BEAST is the only supported bit and by setting this the user will tell libcurl to not attempt to use any workarounds for a security flaw in the SSL3 and TLS1.0 protocols. If this option isn't used or this bit is set to 0, the SSL layer libcurl uses may use a work-around for this flaw although it might cause interoperability problems with some (older) SSL implementations. WARNING: avoiding this work-around loosens the security, and by setting this option to 1 you ask for exactly that. (Added in 7.25.0) <p class="level0"><a name="CURLOPTKRBLEVEL"></a><span class="nroffip">CURLOPT_KRBLEVEL</span> <p class="level1">Pass a char * as parameter. Set the kerberos security level for FTP; this also enables kerberos awareness. This is a string, 'clear', 'safe', 'confidential' or 'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos support for FTP. -<p class="level1">(This option was known as CURLOPT_KRB4LEVEL up to 7.16.3) <a name="SSH"></a><h2 class="nroffsh">SSH OPTIONS</h2> +<p class="level1">(This option was known as CURLOPT_KRB4LEVEL up to 7.16.3) +<p class="level0"><a name="CURLOPTGSSAPIDELEGATION"></a><span class="nroffip">CURLOPT_GSSAPI_DELEGATION</span> +<p class="level1">Set the parameter to CURLGSSAPI_DELEGATION_FLAG to allow unconditional GSSAPI credential delegation. The delegation is disabled by default since 7.21.7. Set the parameter to CURLGSSAPI_DELEGATION_POLICY_FLAG to delegate only if the OK-AS-DELEGATE flag is set in the service ticket in case this feature is supported by the GSSAPI implementation and the definition of GSS_C_DELEG_POLICY_FLAG was available at compile-time. (Added in 7.22.0) <a name="SSH"></a><h2 class="nroffsh">SSH OPTIONS</h2> <p class="level0"> <p class="level0"><a name="CURLOPTSSHAUTHTYPES"></a><span class="nroffip">CURLOPT_SSH_AUTH_TYPES</span> -<p class="level1">Pass a long set to a bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one. (Added in 7.16.1) +<p class="level1">Pass a long set to a bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT. Set CURLSSH_AUTH_ANY to let libcurl pick a suitable one. Currently CURLSSH_AUTH_HOST has no effect. (Added in 7.16.1) If CURLSSH_AUTH_AGENT is used, libcurl attempts to connect to ssh-agent or pageant and let the agent attempt the authentication. (Added in 7.28.0) <p class="level0"><a name="CURLOPTSSHHOSTPUBLICKEYMD5"></a><span class="nroffip">CURLOPT_SSH_HOST_PUBLIC_KEY_MD5</span> <p class="level1">Pass a char * pointing to a string containing 32 hexadecimal digits. The string should be the 128 bit MD5 checksum of the remote host's public key, and libcurl will reject the connection to the host unless the md5sums match. This option is only for SCP and SFTP transfers. (Added in 7.17.1) <p class="level0"><a name="CURLOPTSSHPUBLICKEYFILE"></a><span class="nroffip">CURLOPT_SSH_PUBLIC_KEYFILE</span> -<p class="level1">Pass a char * pointing to a file name for your public key. If not used, libcurl defaults to using <span Class="bold">~/.ssh/id_dsa.pub</span>. (Added in 7.16.1) +<p class="level1">Pass a char * pointing to a file name for your public key. If not used, libcurl defaults to <span Class="bold">$HOME/.ssh/id_dsa.pub</span> if the HOME environment variable is set, and just "id_dsa.pub" in the current directory if HOME is not set. (Added in 7.16.1) If an empty string is passed, libcurl will pass no public key to libssh2 which then tries to compute it from the private key, this is known to work when libssh2 1.4.0+ is linked against OpenSSL. (Added in 7.26.0) <p class="level0"><a name="CURLOPTSSHPRIVATEKEYFILE"></a><span class="nroffip">CURLOPT_SSH_PRIVATE_KEYFILE</span> -<p class="level1">Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to using <span Class="bold">~/.ssh/id_dsa</span>. If the file is password-protected, set the password with <a class="emphasis" href="#CURLOPTKEYPASSWD">CURLOPT_KEYPASSWD</a>. (Added in 7.16.1) +<p class="level1">Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to <span Class="bold">$HOME/.ssh/id_dsa</span> if the HOME environment variable is set, and just "id_dsa" in the current directory if HOME is not set. If the file is password-protected, set the password with <a class="emphasis" href="#CURLOPTKEYPASSWD">CURLOPT_KEYPASSWD</a>. (Added in 7.16.1) <p class="level0"><a name="CURLOPTSSHKNOWNHOSTS"></a><span class="nroffip">CURLOPT_SSH_KNOWNHOSTS</span> <p class="level1">Pass a pointer to a zero terminated string holding the file name of the known_host file to use. The known_hosts file should use the OpenSSH file format as supported by libssh2. If this file is specified, libcurl will only accept connections with hosts that are known and present in that file, with a matching public key. Use <a class="emphasis" href="#CURLOPTSSHKEYFUNCTION">CURLOPT_SSH_KEYFUNCTION</a> to alter the default behavior on host and key (mis)matching. (Added in 7.19.6) <p class="level0"><a name="CURLOPTSSHKEYFUNCTION"></a><span class="nroffip">CURLOPT_SSH_KEYFUNCTION</span> -<p class="level1">Pass a pointer to a curl_sshkeycallback function. It gets called when the known_host matching has been done, to allow the application to act and decide for libcurl how to proceed. It gets passed the CURL handle, the key from the known_hosts file, the key from the remote site, info from libcurl on the matching status and a custom pointer (set with <a class="emphasis" href="#CURLOPTSSHKEYDATA">CURLOPT_SSH_KEYDATA</a>). It MUST return one of the following return codes to tell libcurl how to act: +<p class="level1">Pass a pointer to a curl_sshkeycallback function. It gets called when the known_host matching has been done, to allow the application to act and decide for libcurl how to proceed. The callback will only be called if <a class="emphasis" href="#CURLOPTSSHKNOWNHOSTS">CURLOPT_SSH_KNOWNHOSTS</a> is also set. +<p class="level1">The curl_sshkeycallback function gets passed the CURL handle, the key from the known_hosts file, the key from the remote site, info from libcurl on the matching status and a custom pointer (set with <a class="emphasis" href="#CURLOPTSSHKEYDATA">CURLOPT_SSH_KEYDATA</a>). It MUST return one of the following return codes to tell libcurl how to act: <p class="level2"> <p class="level1"><a name="CURLKHSTATFINEADDTOFILE"></a><span class="nroffip">CURLKHSTAT_FINE_ADD_TO_FILE</span> <p class="level2">The host+key is accepted and libcurl will append it to the known_hosts file before continuing with the connection. This will also add the host+key combo to the known_host pool kept in memory if it wasn't already present there. The adding of data to the file is done by completely replacing the file with a new copy, so the permissions of the file must allow this. diff --git a/docs/libcurl/curl_easy_setopt.pdf b/docs/libcurl/curl_easy_setopt.pdf Binary files differindex 9c1d9e9fe..e6d675cec 100644 --- a/docs/libcurl/curl_easy_setopt.pdf +++ b/docs/libcurl/curl_easy_setopt.pdf diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3 index 1afbd12bf..a26c9c5db 100644 --- a/docs/libcurl/curl_easy_strerror.3 +++ b/docs/libcurl/curl_easy_strerror.3 @@ -1,13 +1,31 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_easy_strerror - return string describing error code .SH SYNOPSIS -.nf -.B #include <curl/curl.h> -.BI "const char *curl_easy_strerror(CURLcode " errornum ");" +#include <curl/curl.h> + +const char *curl_easy_strerror(CURLcode errornum); .SH DESCRIPTION The curl_easy_strerror() function returns a string describing the CURLcode error code passed in the argument \fIerrornum\fP. diff --git a/docs/libcurl/curl_easy_strerror.html b/docs/libcurl/curl_easy_strerror.html index 1dcca6c70..d8cb379dc 100644 --- a/docs/libcurl/curl_easy_strerror.html +++ b/docs/libcurl/curl_easy_strerror.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_strerror man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -45,11 +47,8 @@ p.roffit { <p class="level0"><a name="NAME"></a><h2 class="nroffsh">NAME</h2> <p class="level0">curl_easy_strerror - return string describing error code <a name="SYNOPSIS"></a><h2 class="nroffsh">SYNOPSIS</h2> -<p class="level0"><pre> -<p class="level0"><span Class="bold">#include <curl/curl.h></span> -<span Class="bold">const char *curl_easy_strerror(CURLcode errornum );</span> -</pre> -<a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> +<p class="level0">#include <curl/curl.h> +<p class="level0">const char *curl_easy_strerror(CURLcode errornum); <a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> <p class="level0">The curl_easy_strerror() function returns a string describing the CURLcode error code passed in the argument <span Class="emphasis">errornum</span>. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> <p class="level0">This function was added in libcurl 7.12.0 <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">A pointer to a zero terminated string. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> diff --git a/docs/libcurl/curl_easy_strerror.pdf b/docs/libcurl/curl_easy_strerror.pdf Binary files differindex 04635280e..889e19784 100644 --- a/docs/libcurl/curl_easy_strerror.pdf +++ b/docs/libcurl/curl_easy_strerror.pdf diff --git a/docs/libcurl/curl_easy_unescape.html b/docs/libcurl/curl_easy_unescape.html index 38448625b..5d1f01819 100644 --- a/docs/libcurl/curl_easy_unescape.html +++ b/docs/libcurl/curl_easy_unescape.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_easy_unescape man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -54,6 +56,6 @@ p.roffit { <p class="level0">You must <a class="emphasis" href="./curl_free.html">curl_free(3)</a> the returned string when you're done with it. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> <p class="level0">Added in 7.15.4 and replaces the old <a class="emphasis" href="./curl_unescape.html">curl_unescape(3)</a> function. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">A pointer to a zero terminated string or NULL if it failed. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> -<p class="level0"><span Class="emphasis">curl_easy_escape(3), curl_free(3), RFC 2396</span> <p class="roffit"> +<p class="level0"><span Class="emphasis">curl_easy_escape(3), curl_free(3), <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a></span> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/libcurl/curl_easy_unescape.pdf b/docs/libcurl/curl_easy_unescape.pdf Binary files differindex 11effc788..6c334d18a 100644 --- a/docs/libcurl/curl_easy_unescape.pdf +++ b/docs/libcurl/curl_easy_unescape.pdf diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index 59906150e..75fd51f2d 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_escape 3 "6 March 2002" "libcurl 7.9" "libcurl Manual" .SH NAME curl_escape - URL encodes the given string diff --git a/docs/libcurl/curl_escape.html b/docs/libcurl/curl_escape.html index 4e1c6ffb5..6212096fb 100644 --- a/docs/libcurl/curl_escape.html +++ b/docs/libcurl/curl_escape.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_escape man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -54,6 +56,6 @@ p.roffit { <p class="level0">You must curl_free() the returned string when you're done with it. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> <p class="level0">Since 7.15.4, <a class="emphasis" href="./curl_easy_escape.html">curl_easy_escape(3)</a> should be used. This function will be removed in a future release. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">A pointer to a zero terminated string or NULL if it failed. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> -<p class="level0"><a class="manpage" href="./curl_unescape.html">curl_unescape (3)</a> <a class="manpage" href="./curl_free.html"> curl_free (3)</a> <span Class="manpage"> RFC 2396</span> <p class="roffit"> +<p class="level0"><a class="manpage" href="./curl_unescape.html">curl_unescape (3)</a> <a class="manpage" href="./curl_free.html"> curl_free (3)</a> <span Class="manpage"> <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a></span> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/libcurl/curl_escape.pdf b/docs/libcurl/curl_escape.pdf Binary files differindex 03e801cc3..888e53e1f 100644 --- a/docs/libcurl/curl_escape.pdf +++ b/docs/libcurl/curl_escape.pdf diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 06757ed0a..f03fe066e 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST @@ -12,18 +30,19 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .ad .SH DESCRIPTION curl_formadd() is used to append sections when building a multipart/formdata -HTTP POST (sometimes referred to as RFC2388-style posts). Append one section at -a time until you've added all the sections you want included and then you pass -the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. -\fIlastitem\fP is set after each call and on repeated invokes it should be -left as set to allow repeated invokes to find the end of the list faster. +HTTP POST (sometimes referred to as RFC2388-style posts). Append one section +at a time until you've added all the sections you want included and then you +pass the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. +\fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated +invokes it should be left as set to allow repeated invokes to find the end of +the list faster. After the \fIlastitem\fP pointer follow the real arguments. -The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to +The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to NULL in the first call to this function. All list-data will be allocated by -the function itself. You must call \fIcurl_formfree(3)\fP after the form post -has been done to free the resources. +the function itself. You must call \fIcurl_formfree(3)\fP on the +\fIfirstitem\fP after the form post has been done to free the resources. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. diff --git a/docs/libcurl/curl_formadd.html b/docs/libcurl/curl_formadd.html index f6557db69..8cdfe6deb 100644 --- a/docs/libcurl/curl_formadd.html +++ b/docs/libcurl/curl_formadd.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_formadd man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -48,9 +50,9 @@ p.roffit { <p class="level0"><span Class="bold">#include <curl/curl.h></span> <p class="level0"><span Class="bold">CURLFORMcode curl_formadd(struct curl_httppost ** firstitem,</span> <span Class="bold">struct curl_httppost ** lastitem, ...);</span> <p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> -<p class="level0">curl_formadd() is used to append sections when building a multipart/formdata HTTP POST (sometimes referred to as RFC2388-style posts). Append one section at a time until you've added all the sections you want included and then you pass the <span Class="emphasis">firstitem</span> pointer as parameter to <span Class="bold">CURLOPT_HTTPPOST</span>. <span Class="emphasis">lastitem</span> is set after each call and on repeated invokes it should be left as set to allow repeated invokes to find the end of the list faster. +<p class="level0">curl_formadd() is used to append sections when building a multipart/formdata HTTP POST (sometimes referred to as <a href="http://www.ietf.org/rfc/rfc2388.txt">RFC 2388</a>-style posts). Append one section at a time until you've added all the sections you want included and then you pass the <span Class="emphasis">firstitem</span> pointer as parameter to <span Class="bold">CURLOPT_HTTPPOST</span>. <span Class="emphasis">lastitem</span> is set after each <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a> call and on repeated invokes it should be left as set to allow repeated invokes to find the end of the list faster. <p class="level0">After the <span Class="emphasis">lastitem</span> pointer follow the real arguments. -<p class="level0">The pointers <span Class="emphasis">*firstitem</span> and <span Class="emphasis">*lastitem</span> should both be pointing to NULL in the first call to this function. All list-data will be allocated by the function itself. You must call <a class="emphasis" href="./curl_formfree.html">curl_formfree(3)</a> after the form post has been done to free the resources. +<p class="level0">The pointers <span Class="emphasis">firstitem</span> and <span Class="emphasis">lastitem</span> should both be pointing to NULL in the first call to this function. All list-data will be allocated by the function itself. You must call <a class="emphasis" href="./curl_formfree.html">curl_formfree(3)</a> on the <span Class="emphasis">firstitem</span> after the form post has been done to free the resources. <p class="level0">Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with <span Class="emphasis">CURLOPT_HTTPHEADER</span> as usual. <p class="level0">First, there are some basics you need to understand about multipart/formdata posts. Each part consists of at least a NAME and a CONTENTS part. If the part is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. Below, we'll discuss what options you use to set these properties in the parts you want to add to your post. <p class="level0">The options listed first are for making normal parts. The options from <a class="emphasis" href="#CURLFORMFILE">CURLFORM_FILE</a> through <a class="emphasis" href="#CURLFORMBUFFERLENGTH">CURLFORM_BUFFERLENGTH</a> are for file upload parts. <a name="OPTIONS"></a><h2 class="nroffsh">OPTIONS</h2> diff --git a/docs/libcurl/curl_formadd.pdf b/docs/libcurl/curl_formadd.pdf Binary files differindex d406931b8..3e7ac977d 100644 --- a/docs/libcurl/curl_formadd.pdf +++ b/docs/libcurl/curl_formadd.pdf diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 2fba295ab..7438a1640 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_formfree 3 "6 April 2001" "libcurl 7.7.1" "libcurl Manual" .SH NAME curl_formfree - free a previously build multipart/formdata HTTP POST chain @@ -13,6 +31,13 @@ curl_formfree - free a previously build multipart/formdata HTTP POST chain curl_formfree() is used to clean up data previously built/appended with \fIcurl_formadd(3)\fP. This must be called when the data has been used, which typically means after \fIcurl_easy_perform(3)\fP has been called. + +The pointer to free is the same pointer you passed to the +\fBCURLOPT_HTTPPOST\fP option, which is the \fIfirstitem\fP pointer from the +\fIcurl_formadd(3)\fP invoke(s). + +\fBform\fP is the pointer as returned from a previous call to +\fIcurl_formadd(3)\fP and may be NULL. .SH RETURN VALUE None .SH "SEE ALSO" diff --git a/docs/libcurl/curl_formfree.html b/docs/libcurl/curl_formfree.html index 73837b082..9ea2c743f 100644 --- a/docs/libcurl/curl_formfree.html +++ b/docs/libcurl/curl_formfree.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_formfree man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -48,7 +50,9 @@ p.roffit { <p class="level0"><span Class="bold">#include <curl/curl.h></span> <p class="level0"><span Class="bold">void curl_formfree(struct curl_httppost * form);</span> <p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> -<p class="level0">curl_formfree() is used to clean up data previously built/appended with <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a>. This must be called when the data has been used, which typically means after <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> has been called. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> +<p class="level0">curl_formfree() is used to clean up data previously built/appended with <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a>. This must be called when the data has been used, which typically means after <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> has been called. +<p class="level0">The pointer to free is the same pointer you passed to the <span Class="bold">CURLOPT_HTTPPOST</span> option, which is the <span Class="emphasis">firstitem</span> pointer from the <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a> invoke(s). +<p class="level0"><span Class="bold">form</span> is the pointer as returned from a previous call to <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a> and may be NULL. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">None <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_formadd.html">curl_formadd (3) </a> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. diff --git a/docs/libcurl/curl_formfree.pdf b/docs/libcurl/curl_formfree.pdf Binary files differindex da460c02e..8ad71fecf 100644 --- a/docs/libcurl/curl_formfree.pdf +++ b/docs/libcurl/curl_formfree.pdf diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index b0dd8fead..b52622136 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -1,28 +1,49 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_formget 3 "20 June 2006" "libcurl 7.15.5" "libcurl Manual" .SH NAME curl_formget - serialize a previously built multipart/formdata HTTP POST chain .SH SYNOPSIS +.nf .B #include <curl/curl.h> -.sp -.BI "void curl_formget(struct curl_httppost *" form, " void *" arg, -.BI " curl_formget_callback " append ");" -.ad + +void curl_formget(struct curl_httppost * form, void *userp, + curl_formget_callback append ); .SH DESCRIPTION curl_formget() is used to serialize data previously built/appended with -\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument which will be -passed to the curl_formget_callback function. +\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named +\fIuserp\fP which will be passed as the first argument to the +curl_formget_callback function. -.BI "typedef size_t (*curl_formget_callback)(void *" arg, " const char *" buf, +.BI "typedef size_t (*curl_formget_callback)(void *" userp, " const char *" buf, .BI " size_t " len ");" -.nf The curl_formget_callback will be executed for each part of the HTTP POST -chain. The void *arg pointer will be the one passed as second argument to -curl_formget(). The character buffer passed to it must not be freed. The +chain. The character buffer passed to the callback must not be freed. The callback should return the buffer length passed to it on success. + +If the \fBCURLFORM_STREAM\fP option is used in the formpost, it will prevent +\fIcurl_formget(3)\fP from working until you've performed the actual HTTP +request as only then will libcurl get the actual read callback to use! .SH RETURN VALUE 0 means everything was ok, non-zero means an error occurred .SH EXAMPLE @@ -34,6 +55,7 @@ callback should return the buffer length passed to it on success. (*(size_t *) arg) += len; return len; } + size_t print_httppost(struct curl_httppost *post) { size_t total_size = 0; diff --git a/docs/libcurl/curl_formget.html b/docs/libcurl/curl_formget.html index 0564f61bd..e5b4b2982 100644 --- a/docs/libcurl/curl_formget.html +++ b/docs/libcurl/curl_formget.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_formget man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -45,17 +47,16 @@ p.roffit { <p class="level0"><a name="NAME"></a><h2 class="nroffsh">NAME</h2> <p class="level0">curl_formget - serialize a previously built multipart/formdata HTTP POST chain <a name="SYNOPSIS"></a><h2 class="nroffsh">SYNOPSIS</h2> +<p class="level0"><pre> <p class="level0"><span Class="bold">#include <curl/curl.h></span> -<p class="level0"><span Class="bold">void curl_formget(struct curl_httppost * form, void * arg,</span> <span Class="bold"> curl_formget_callback append );</span> -<p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> -<p class="level0">curl_formget() is used to serialize data previously built/appended with <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a>. Accepts a void pointer as second argument which will be passed to the curl_formget_callback function. -<p class="level0"><span Class="bold">typedef size_t (*curl_formget_callback)(void * arg, const char * buf,</span> <span Class="bold"> size_t len );</span> <pre> -<p class="level0"><p class="level0">The curl_formget_callback will be executed for each part of the HTTP POST - chain. The void *arg pointer will be the one passed as second argument to - curl_formget(). The character buffer passed to it must not be freed. The - callback should return the buffer length passed to it on success. +<p class="level0">void curl_formget(struct curl_httppost * form, void *userp, + curl_formget_callback append ); </pre> -<a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> +<a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> +<p class="level0">curl_formget() is used to serialize data previously built/appended with <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a>. Accepts a void pointer as second argument named <span Class="emphasis">userp</span> which will be passed as the first argument to the curl_formget_callback function. +<p class="level0"><span Class="bold">typedef size_t (*curl_formget_callback)(void * userp, const char * buf,</span> <span Class="bold"> size_t len );</span> +<p class="level0">The curl_formget_callback will be executed for each part of the HTTP POST chain. The character buffer passed to the callback must not be freed. The callback should return the buffer length passed to it on success. +<p class="level0">If the <span Class="bold">CURLFORM_STREAM</span> option is used in the formpost, it will prevent <a class="emphasis" href="./curl_formget.html">curl_formget(3)</a> from working until you've performed the actual HTTP request as only then will libcurl get the actual read callback to use! <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">0 means everything was ok, non-zero means an error occurred <a name="EXAMPLE"></a><h2 class="nroffsh">EXAMPLE</h2> <p class="level0"><pre> <p class="level0"><p class="level0"> size_t print_httppost_callback(void *arg, const char *buf, size_t len) @@ -64,7 +65,7 @@ p.roffit { (*(size_t *) arg) += len; return len; } - size_t print_httppost(struct curl_httppost *post) + <p class="level0"> size_t print_httppost(struct curl_httppost *post) { size_t total_size = 0; if(curl_formget(post, &total_size, print_httppost_callback)) { diff --git a/docs/libcurl/curl_formget.pdf b/docs/libcurl/curl_formget.pdf Binary files differindex a810f8cef..ccf6e8e88 100644 --- a/docs/libcurl/curl_formget.pdf +++ b/docs/libcurl/curl_formget.pdf diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3 index f8546935f..08ec9b6b3 100644 --- a/docs/libcurl/curl_free.3 +++ b/docs/libcurl/curl_free.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_free 3 "12 Aug 2003" "libcurl 7.10" "libcurl Manual" .SH NAME curl_free - reclaim memory that has been obtained through a libcurl call diff --git a/docs/libcurl/curl_free.html b/docs/libcurl/curl_free.html index 4bffdc109..7d75c2485 100644 --- a/docs/libcurl/curl_free.html +++ b/docs/libcurl/curl_free.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_free man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_free.pdf b/docs/libcurl/curl_free.pdf Binary files differindex a3c5ea08a..041e7592a 100644 --- a/docs/libcurl/curl_free.pdf +++ b/docs/libcurl/curl_free.pdf diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 73cd3ef1d..65eed9c57 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_getdate 3 "12 Aug 2005" "libcurl 7.0" "libcurl Manual" .SH NAME curl_getdate - Convert a date string to number of seconds since January 1, diff --git a/docs/libcurl/curl_getdate.html b/docs/libcurl/curl_getdate.html index cd1612d6b..f2ece2390 100644 --- a/docs/libcurl/curl_getdate.html +++ b/docs/libcurl/curl_getdate.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_getdate man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -83,7 +85,7 @@ p.roffit { </pre> <p class="level0"><a name="STANDARDS"></a><h2 class="nroffsh">STANDARDS</h2> -<p class="level0">This parser was written to handle date formats specified in RFC 822 (including the update in RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by RFC 1036) and ANSI C's asctime() format. These formats are the only ones RFC2616 says HTTP applications may use. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> +<p class="level0">This parser was written to handle date formats specified in <a href="http://www.ietf.org/rfc/rfc822.txt">RFC 822</a> (including the update in <a href="http://www.ietf.org/rfc/rfc1123.txt">RFC 1123</a>) using time zone name or time zone delta and RFC 850 (obsoleted by <a href="http://www.ietf.org/rfc/rfc1036.txt">RFC 1036</a>) and ANSI C's asctime() format. These formats are the only ones <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> says HTTP applications may use. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">This function returns -1 when it fails to parse the date string. Otherwise it returns the number of seconds as described. <p class="level0">If the year is larger than 2037 on systems with 32 bit time_t, this function will return 0x7fffffff (since that is the largest possible signed 32 bit number). <p class="level0">Having a 64 bit time_t is not a guarantee that dates beyond 03:14:07 UTC, January 19, 2038 will work fine. On systems with a 64 bit time_t but with a crippled mktime(), <span Class="emphasis">curl_getdate</span> will return -1 in this case. <a name="REWRITE"></a><h2 class="nroffsh">REWRITE</h2> diff --git a/docs/libcurl/curl_getdate.pdf b/docs/libcurl/curl_getdate.pdf Binary files differindex 3222f7fcb..c683cc0f9 100644 --- a/docs/libcurl/curl_getdate.pdf +++ b/docs/libcurl/curl_getdate.pdf diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 index 74132921a..33554476a 100644 --- a/docs/libcurl/curl_getenv.3 +++ b/docs/libcurl/curl_getenv.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_getenv 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_getenv - return value for environment name diff --git a/docs/libcurl/curl_getenv.html b/docs/libcurl/curl_getenv.html index be1a007bb..fcab4e093 100644 --- a/docs/libcurl/curl_getenv.html +++ b/docs/libcurl/curl_getenv.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_getenv man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_getenv.pdf b/docs/libcurl/curl_getenv.pdf Binary files differindex 98e477b68..e1f5fb69e 100644 --- a/docs/libcurl/curl_getenv.pdf +++ b/docs/libcurl/curl_getenv.pdf diff --git a/docs/libcurl/curl_global_cleanup.3 b/docs/libcurl/curl_global_cleanup.3 index 9ca11d6ff..83a54e467 100644 --- a/docs/libcurl/curl_global_cleanup.3 +++ b/docs/libcurl/curl_global_cleanup.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_global_cleanup 3 "17 Feb 2006" "libcurl 7.8" "libcurl Manual" .SH NAME curl_global_cleanup - global libcurl cleanup diff --git a/docs/libcurl/curl_global_cleanup.html b/docs/libcurl/curl_global_cleanup.html index ac8cad857..afee7bcf3 100644 --- a/docs/libcurl/curl_global_cleanup.html +++ b/docs/libcurl/curl_global_cleanup.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_global_cleanup man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_global_cleanup.pdf b/docs/libcurl/curl_global_cleanup.pdf Binary files differindex 9ea39d8dd..9a73cf68a 100644 --- a/docs/libcurl/curl_global_cleanup.pdf +++ b/docs/libcurl/curl_global_cleanup.pdf diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index e732911f8..8e1cc180b 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_global_init 3 "11 May 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_global_init - Global libcurl initialisation @@ -38,7 +56,8 @@ details of how to use this function. .SH FLAGS .TP 5 .B CURL_GLOBAL_ALL -Initialize everything possible. This sets all known bits. +Initialize everything possible. This sets all known bits except +\fBCURL_GLOBAL_ACK_EINTR\fP. .TP .B CURL_GLOBAL_SSL Initialize SSL @@ -48,6 +67,14 @@ Initialize the Win32 socket libraries. .TP .B CURL_GLOBAL_NOTHING Initialise nothing extra. This sets no bit. +.TP +.B CURL_GLOBAL_DEFAULT +A sensible default. It will init both SSL and Win32. Right now, this equals +the functionality of the \fBCURL_GLOBAL_ALL\fP mask. +.TP +.B CURL_GLOBAL_ACK_EINTR +When this flag is set, curl will acknowledge EINTR condition when connecting +or when waiting for data. Otherwise, curl waits until full timeout elapses. .SH RETURN VALUE If this function returns non-zero, something went wrong and you cannot use the other curl functions. diff --git a/docs/libcurl/curl_global_init.html b/docs/libcurl/curl_global_init.html index e54ced3ac..26a120074 100644 --- a/docs/libcurl/curl_global_init.html +++ b/docs/libcurl/curl_global_init.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_global_init man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -55,10 +57,12 @@ p.roffit { <p class="level0">See the description in <span Class="bold">libcurl</span>(3) of global environment requirements for details of how to use this function. <p class="level0"><a name="FLAGS"></a><h2 class="nroffsh">FLAGS</h2> <p class="level0"> -<p class="level0"><span Class="bold">CURL_GLOBAL_ALL</span> Initialize everything possible. This sets all known bits. +<p class="level0"><span Class="bold">CURL_GLOBAL_ALL</span> Initialize everything possible. This sets all known bits except <span Class="bold">CURL_GLOBAL_ACK_EINTR</span>. <p class="level0"><span Class="bold">CURL_GLOBAL_SSL</span> Initialize SSL <p class="level0"><span Class="bold">CURL_GLOBAL_WIN32</span> Initialize the Win32 socket libraries. -<p class="level0"><span Class="bold">CURL_GLOBAL_NOTHING</span> Initialise nothing extra. This sets no bit. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> +<p class="level0"><span Class="bold">CURL_GLOBAL_NOTHING</span> Initialise nothing extra. This sets no bit. +<p class="level0"><span Class="bold">CURL_GLOBAL_DEFAULT</span> A sensible default. It will init both SSL and Win32. Right now, this equals the functionality of the <span Class="bold">CURL_GLOBAL_ALL</span> mask. +<p class="level0"><span Class="bold">CURL_GLOBAL_ACK_EINTR</span> When this flag is set, curl will acknowledge EINTR condition when connecting or when waiting for data. Otherwise, curl waits until full timeout elapses. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">If this function returns non-zero, something went wrong and you cannot use the other curl functions. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_global_init_mem.html">curl_global_init_mem (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_global_cleanup.html">curl_global_cleanup (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_easy_init.html">curl_easy_init (3) </a> <a class="manpage" href="./libcurl.html">libcurl (3) </a> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. diff --git a/docs/libcurl/curl_global_init.pdf b/docs/libcurl/curl_global_init.pdf Binary files differindex 9ec6bb594..989774a8b 100644 --- a/docs/libcurl/curl_global_init.pdf +++ b/docs/libcurl/curl_global_init.pdf diff --git a/docs/libcurl/curl_global_init_mem.3 b/docs/libcurl/curl_global_init_mem.3 index 57ae6aeea..9cddef7c3 100644 --- a/docs/libcurl/curl_global_init_mem.3 +++ b/docs/libcurl/curl_global_init_mem.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_global_init_mem 3 "10 May 2004" "libcurl 7.12.0" "libcurl Manual" .SH NAME curl_global_init_mem - Global libcurl initialisation with memory callbacks @@ -34,7 +52,7 @@ To replace strdup() .IP "void *calloc_callback(size_t nmemb, size_t size);" To replace calloc() .SH "CAUTION" -Manipulating these gives considerable powers to the application to severly +Manipulating these gives considerable powers to the application to severely screw things up for libcurl. Take care! .SH "SEE ALSO" .BR curl_global_init "(3), " diff --git a/docs/libcurl/curl_global_init_mem.html b/docs/libcurl/curl_global_init_mem.html index 055d9dbbc..eed8fad0f 100644 --- a/docs/libcurl/curl_global_init_mem.html +++ b/docs/libcurl/curl_global_init_mem.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_global_init_mem man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -67,7 +69,7 @@ p.roffit { <p class="level1">To replace strdup() <p class="level0"><a name="void"></a><span class="nroffip">void *calloc_callback(size_t nmemb, size_t size);</span> <p class="level1">To replace calloc() <a name="CAUTION"></a><h2 class="nroffsh">CAUTION</h2> -<p class="level0">Manipulating these gives considerable powers to the application to severly screw things up for libcurl. Take care! <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> +<p class="level0">Manipulating these gives considerable powers to the application to severely screw things up for libcurl. Take care! <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_global_init.html">curl_global_init (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_global_cleanup.html">curl_global_cleanup (3)</a> <span Class="manpage"> </span> <p class="level0"><p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. diff --git a/docs/libcurl/curl_global_init_mem.pdf b/docs/libcurl/curl_global_init_mem.pdf Binary files differindex d5b35448b..a9ea24b55 100644 --- a/docs/libcurl/curl_global_init_mem.pdf +++ b/docs/libcurl/curl_global_init_mem.pdf diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index ade7f65f5..cbf10e1ab 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_printf 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf diff --git a/docs/libcurl/curl_mprintf.html b/docs/libcurl/curl_mprintf.html index 5a16d5743..9bc97908b 100644 --- a/docs/libcurl/curl_mprintf.html +++ b/docs/libcurl/curl_mprintf.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_printf man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_mprintf.pdf b/docs/libcurl/curl_mprintf.pdf Binary files differindex 77b042882..35713e0f8 100644 --- a/docs/libcurl/curl_mprintf.pdf +++ b/docs/libcurl/curl_mprintf.pdf diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index 85f199ed9..506ea41f4 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_add_handle 3 "4 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_add_handle - add an easy handle to a multi session @@ -9,9 +29,9 @@ CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); .ad .SH DESCRIPTION Adds a standard easy handle to the multi stack. This function call will make -this \fImulti_handle\fP control the specified \fIeasy_handle\fP. -Furthermore, libcurl now initiates the connection associated with the -specified \fIeasy_handle\fP. +this \fImulti_handle\fP control the specified \fIeasy_handle\fP. Furthermore, +libcurl now initiates the connection associated with the specified +\fIeasy_handle\fP. When an easy handle has been added to a multi stack, you can not and you must not use \fIcurl_easy_perform(3)\fP on that handle! @@ -21,6 +41,12 @@ cache (CURLOPT_DNS_USE_GLOBAL_CACHE), it will be made to use the DNS cache that is shared between all easy handles within the multi handle when \fIcurl_multi_add_handle(3)\fP is called. +If you have CURLMOPT_TIMERFUNCTION set in the multi handle (and you really +should if you're working event-based with \fIcurl_multi_socket_action(3)\fP +and friends), that callback will be called from within this function to ask +for an updated timer so that your main event loop will get the activity on +this handle to get started. + The easy handle will remain added until you remove it again with \fIcurl_multi_remove_handle(3)\fP. You should remove the easy handle from the multi stack before you terminate first the easy handle and then the multi diff --git a/docs/libcurl/curl_multi_add_handle.html b/docs/libcurl/curl_multi_add_handle.html index 75ca27193..765249409 100644 --- a/docs/libcurl/curl_multi_add_handle.html +++ b/docs/libcurl/curl_multi_add_handle.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_add_handle man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -48,9 +50,10 @@ p.roffit { <p class="level0">#include <curl/curl.h> <p class="level0">CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); <p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> -<p class="level0">Adds a standard easy handle to the multi stack. This function call will make this <span Class="emphasis">multi_handle</span> control the specified <span Class="emphasis">easy_handle</span>. Furthermore, libcurl now initiates the connection associated with the specified <span Class="emphasis">easy_handle</span>. +<p class="level0">Adds a standard easy handle to the multi stack. This function call will make this <span Class="emphasis">multi_handle</span> control the specified <span Class="emphasis">easy_handle</span>. Furthermore, libcurl now initiates the connection associated with the specified <span Class="emphasis">easy_handle</span>. <p class="level0">When an easy handle has been added to a multi stack, you can not and you must not use <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> on that handle! <p class="level0">If the easy handle is not set to use a shared (CURLOPT_SHARE) or global DNS cache (CURLOPT_DNS_USE_GLOBAL_CACHE), it will be made to use the DNS cache that is shared between all easy handles within the multi handle when <a class="emphasis" href="./curl_multi_add_handle.html">curl_multi_add_handle(3)</a> is called. +<p class="level0">If you have CURLMOPT_TIMERFUNCTION set in the multi handle (and you really should if you're working event-based with <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> and friends), that callback will be called from within this function to ask for an updated timer so that your main event loop will get the activity on this handle to get started. <p class="level0">The easy handle will remain added until you remove it again with <a class="emphasis" href="./curl_multi_remove_handle.html">curl_multi_remove_handle(3)</a>. You should remove the easy handle from the multi stack before you terminate first the easy handle and then the multi handle: <p class="level0">1 - <a class="emphasis" href="./curl_multi_remove_handle.html">curl_multi_remove_handle(3)</a> <p class="level0">2 - <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a> diff --git a/docs/libcurl/curl_multi_add_handle.pdf b/docs/libcurl/curl_multi_add_handle.pdf Binary files differindex 4eb18c39e..46a1d1701 100644 --- a/docs/libcurl/curl_multi_add_handle.pdf +++ b/docs/libcurl/curl_multi_add_handle.pdf diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3 index 3e15d73e6..0b580fe27 100644 --- a/docs/libcurl/curl_multi_assign.3 +++ b/docs/libcurl/curl_multi_assign.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_assign 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_assign \- set data to association with an internal socket diff --git a/docs/libcurl/curl_multi_assign.html b/docs/libcurl/curl_multi_assign.html index e560218af..fc468076f 100644 --- a/docs/libcurl/curl_multi_assign.html +++ b/docs/libcurl/curl_multi_assign.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_assign man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_multi_assign.pdf b/docs/libcurl/curl_multi_assign.pdf Binary files differindex 84b1ad940..a1b05a48f 100644 --- a/docs/libcurl/curl_multi_assign.pdf +++ b/docs/libcurl/curl_multi_assign.pdf diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3 index d40173c99..50bc8adbd 100644 --- a/docs/libcurl/curl_multi_cleanup.3 +++ b/docs/libcurl/curl_multi_cleanup.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_cleanup 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_cleanup - close down a multi session @@ -21,6 +41,7 @@ handle is no longer connected to the multi handle 3 - \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are removed .SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. +CURLMcode type, general libcurl multi interface error code. On success, +CURLM_OK is returned. .SH "SEE ALSO" .BR curl_multi_init "(3)," curl_easy_cleanup "(3)," curl_easy_init "(3)" diff --git a/docs/libcurl/curl_multi_cleanup.html b/docs/libcurl/curl_multi_cleanup.html index 40381fda0..f6b9a1cb3 100644 --- a/docs/libcurl/curl_multi_cleanup.html +++ b/docs/libcurl/curl_multi_cleanup.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_cleanup man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -52,7 +54,7 @@ p.roffit { <p class="level0">1 - <a class="emphasis" href="./curl_multi_remove_handle.html">curl_multi_remove_handle(3)</a> before any easy handles are cleaned up <p class="level0">2 - <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a> can now be called independently since the easy handle is no longer connected to the multi handle <p class="level0">3 - <a class="emphasis" href="./curl_multi_cleanup.html">curl_multi_cleanup(3)</a> should be called when all easy handles are removed <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> -<p class="level0">CURLMcode type, general libcurl multi interface error code. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> +<p class="level0">CURLMcode type, general libcurl multi interface error code. On success, CURLM_OK is returned. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_multi_init.html">curl_multi_init (3)</a> <a class="manpage" href="./curl_easy_cleanup.html"> curl_easy_cleanup (3)</a> <a class="manpage" href="./curl_easy_init.html"> curl_easy_init (3)</a> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/libcurl/curl_multi_cleanup.pdf b/docs/libcurl/curl_multi_cleanup.pdf Binary files differindex 88f18d1e9..0dc13c212 100644 --- a/docs/libcurl/curl_multi_cleanup.pdf +++ b/docs/libcurl/curl_multi_cleanup.pdf diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 79281056e..3dbdc4504 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_fdset 3 "2 Jan 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_fdset - extracts file descriptor information from a multi handle @@ -20,19 +40,28 @@ but be sure to FD_ZERO them before calling this function as otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should be called as soon as one of them is ready to be read from or written to. -To be sure to have up-to-date results, you should call -\fIcurl_multi_perform\fP until it does not return CURLM_CALL_MULTI_PERFORM -prior to calling \fIcurl_multi_fdset\fP. This will make sure that libcurl has -updated the handles' socket states. - If no file descriptors are set by libcurl, \fImax_fd\fP will contain -1 when this function returns. Otherwise it will contain the higher descriptor number -libcurl set. +libcurl set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl +currently does something that isn't possible for your application to monitor +with a socket and unfortunately you can then not know exactly when the current +action is completed using select(). When max_fd returns with -1, you need to +wait a while and then proceed and call \fIcurl_multi_perform\fP anyway. How +long to wait? I would suggest 100 milliseconds at least, but you may want to +test it out in your own particular conditions to find a suitable value. When doing select(), you should use \fBcurl_multi_timeout\fP to figure out how long to wait for action. Call \fIcurl_multi_perform\fP even if no activity has been seen on the fd_sets after the timeout expires as otherwise internal retries and timeouts may not work as you'd think and want. + +If one of the sockets used by libcurl happens to be larger than what can be +set in an fd_set, which on POSIX systems means that the file descriptor is +larger than FD_SETSIZE, then libcurl will try to not set it. Setting a too +large file descriptor in an fd_set implies an out of bounds write which can +cause crashes, or worse. The effect of NOT storing it will possibly save you +from the crash, but will make your program NOT wait for sockets it should wait +for... .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. See \fIlibcurl-errors(3)\fP diff --git a/docs/libcurl/curl_multi_fdset.html b/docs/libcurl/curl_multi_fdset.html index 51e444cf8..2f0e16977 100644 --- a/docs/libcurl/curl_multi_fdset.html +++ b/docs/libcurl/curl_multi_fdset.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_fdset man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -55,9 +57,9 @@ p.roffit { <p class="level0"></pre> <a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> <p class="level0">This function extracts file descriptor information from a given multi_handle. libcurl returns its fd_set sets. The application can use these to select() on, but be sure to FD_ZERO them before calling this function as <a class="emphasis" href="./curl_multi_fdset.html">curl_multi_fdset(3)</a> only adds its own descriptors, it doesn't zero or otherwise remove any others. The <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> function should be called as soon as one of them is ready to be read from or written to. -<p class="level0">To be sure to have up-to-date results, you should call <span Class="emphasis">curl_multi_perform</span> until it does not return CURLM_CALL_MULTI_PERFORM prior to calling <span Class="emphasis">curl_multi_fdset</span>. This will make sure that libcurl has updated the handles' socket states. -<p class="level0">If no file descriptors are set by libcurl, <span Class="emphasis">max_fd</span> will contain -1 when this function returns. Otherwise it will contain the higher descriptor number libcurl set. -<p class="level0">When doing select(), you should use <span Class="bold">curl_multi_timeout</span> to figure out how long to wait for action. Call <span Class="emphasis">curl_multi_perform</span> even if no activity has been seen on the fd_sets after the timeout expires as otherwise internal retries and timeouts may not work as you'd think and want. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> +<p class="level0">If no file descriptors are set by libcurl, <span Class="emphasis">max_fd</span> will contain -1 when this function returns. Otherwise it will contain the higher descriptor number libcurl set. When libcurl returns -1 in <span Class="emphasis">max_fd</span>, it is because libcurl currently does something that isn't possible for your application to monitor with a socket and unfortunately you can then not know exactly when the current action is completed using select(). When max_fd returns with -1, you need to wait a while and then proceed and call <span Class="emphasis">curl_multi_perform</span> anyway. How long to wait? I would suggest 100 milliseconds at least, but you may want to test it out in your own particular conditions to find a suitable value. +<p class="level0">When doing select(), you should use <span Class="bold">curl_multi_timeout</span> to figure out how long to wait for action. Call <span Class="emphasis">curl_multi_perform</span> even if no activity has been seen on the fd_sets after the timeout expires as otherwise internal retries and timeouts may not work as you'd think and want. +<p class="level0">If one of the sockets used by libcurl happens to be larger than what can be set in an fd_set, which on POSIX systems means that the file descriptor is larger than FD_SETSIZE, then libcurl will try to not set it. Setting a too large file descriptor in an fd_set implies an out of bounds write which can cause crashes, or worse. The effect of NOT storing it will possibly save you from the crash, but will make your program NOT wait for sockets it should wait for... <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">CURLMcode type, general libcurl multi interface error code. See <span Class="emphasis">libcurl-errors(3)</span> <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_multi_cleanup.html">curl_multi_cleanup (3)</a> <a class="manpage" href="./curl_multi_init.html"> curl_multi_init (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_multi_timeout.html">curl_multi_timeout (3)</a> <a class="manpage" href="./curl_multi_perform.html"> curl_multi_perform (3) </a> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. diff --git a/docs/libcurl/curl_multi_fdset.pdf b/docs/libcurl/curl_multi_fdset.pdf Binary files differindex df1efa298..c9e63f34f 100644 --- a/docs/libcurl/curl_multi_fdset.pdf +++ b/docs/libcurl/curl_multi_fdset.pdf diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 9ff08e707..875176486 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_info_read 3 "18 Dec 2004" "libcurl 7.10.3" "libcurl Manual" .SH NAME curl_multi_info_read - read multi stack informationals diff --git a/docs/libcurl/curl_multi_info_read.html b/docs/libcurl/curl_multi_info_read.html index 2f53e6d88..2e91faec5 100644 --- a/docs/libcurl/curl_multi_info_read.html +++ b/docs/libcurl/curl_multi_info_read.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_info_read man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_multi_info_read.pdf b/docs/libcurl/curl_multi_info_read.pdf Binary files differindex bccf1063e..1156c7c28 100644 --- a/docs/libcurl/curl_multi_info_read.pdf +++ b/docs/libcurl/curl_multi_info_read.pdf diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 index 0ac298efd..ca9374e15 100644 --- a/docs/libcurl/curl_multi_init.3 +++ b/docs/libcurl/curl_multi_init.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_init 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_init - create a multi handle diff --git a/docs/libcurl/curl_multi_init.html b/docs/libcurl/curl_multi_init.html index cf9b30490..f1c708661 100644 --- a/docs/libcurl/curl_multi_init.html +++ b/docs/libcurl/curl_multi_init.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_init man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_multi_init.pdf b/docs/libcurl/curl_multi_init.pdf Binary files differindex a35330175..780c16c83 100644 --- a/docs/libcurl/curl_multi_init.pdf +++ b/docs/libcurl/curl_multi_init.pdf diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index ede23905f..304197b1a 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_perform 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_perform - reads/writes available data from each easy handle @@ -8,21 +28,24 @@ curl_multi_perform - reads/writes available data from each easy handle CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles); .ad .SH DESCRIPTION -When the app thinks there's data available for the multi_handle, it should -call this function to read/write whatever there is to read or write right -now. curl_multi_perform() returns as soon as the reads/writes are done. This +This function handles transfers on all the added handles that need attention +in an non-blocking fashion. + +When an application has found out there's data available for the multi_handle +or a timeout has elapsed, the application should call this function to +read/write whatever there is to read or write right now etc. +curl_multi_perform() returns as soon as the reads/writes are done. This function does not require that there actually is any data available for reading or that data can be written, it can be called just in case. It will write the number of handles that still transfer data in the second argument's integer-pointer. -When you call curl_multi_perform() and the amount of \fIrunning_handles\fP is -changed from the previous call (or is less than the amount of easy handles -you've added to the multi handle), you know that there is one or more -transfers less "running". You can then call \fIcurl_multi_info_read(3)\fP to -get information about each individual completed transfer, and that returned -info includes CURLcode and more. If an added handle fails very quickly, it may -never be counted as a running_handle. +If the amount of \fIrunning_handles\fP is changed from the previous call (or +is less than the amount of easy handles you've added to the multi handle), you +know that there is one or more transfers less "running". You can then call +\fIcurl_multi_info_read(3)\fP to get information about each individual +completed transfer, and that returned info includes CURLcode and more. If an +added handle fails very quickly, it may never be counted as a running_handle. When \fIrunning_handles\fP is set to zero (0) on the return of this function, there is no longer any transfers in progress. @@ -41,12 +64,14 @@ need to wait for \&"action" and then call this function again. This function only returns errors etc regarding the whole multi stack. Problems still might have occurred on individual transfers even when this -function returns \fICURLM_OK\fP. +function returns \fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure +out how individual transfers did. .SH "TYPICAL USAGE" Most applications will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's -file descriptors, then it'll wait for action on them using \fBselect(3)\fP and -as soon as one or more of them are ready, \fIcurl_multi_perform(3)\fP gets -called. +file descriptors, and \fIcurl_multi_timeout(3)\fP to get a suitable timeout +period, then it'll wait for action on the file descriptors using +\fBselect(3)\fP. As soon as one or more file descriptor is ready, +\fIcurl_multi_perform(3)\fP gets called. .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " diff --git a/docs/libcurl/curl_multi_perform.html b/docs/libcurl/curl_multi_perform.html index 46fc22698..832d928a6 100644 --- a/docs/libcurl/curl_multi_perform.html +++ b/docs/libcurl/curl_multi_perform.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_perform man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -48,13 +50,14 @@ p.roffit { <p class="level0">#include <curl/curl.h> <p class="level0">CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles); <p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> -<p class="level0">When the app thinks there's data available for the multi_handle, it should call this function to read/write whatever there is to read or write right now. curl_multi_perform() returns as soon as the reads/writes are done. This function does not require that there actually is any data available for reading or that data can be written, it can be called just in case. It will write the number of handles that still transfer data in the second argument's integer-pointer. -<p class="level0">When you call curl_multi_perform() and the amount of <span Class="emphasis">running_handles</span> is changed from the previous call (or is less than the amount of easy handles you've added to the multi handle), you know that there is one or more transfers less "running". You can then call <a class="emphasis" href="./curl_multi_info_read.html">curl_multi_info_read(3)</a> to get information about each individual completed transfer, and that returned info includes CURLcode and more. If an added handle fails very quickly, it may never be counted as a running_handle. +<p class="level0">This function handles transfers on all the added handles that need attention in an non-blocking fashion. +<p class="level0">When an application has found out there's data available for the multi_handle or a timeout has elapsed, the application should call this function to read/write whatever there is to read or write right now etc. curl_multi_perform() returns as soon as the reads/writes are done. This function does not require that there actually is any data available for reading or that data can be written, it can be called just in case. It will write the number of handles that still transfer data in the second argument's integer-pointer. +<p class="level0">If the amount of <span Class="emphasis">running_handles</span> is changed from the previous call (or is less than the amount of easy handles you've added to the multi handle), you know that there is one or more transfers less "running". You can then call <a class="emphasis" href="./curl_multi_info_read.html">curl_multi_info_read(3)</a> to get information about each individual completed transfer, and that returned info includes CURLcode and more. If an added handle fails very quickly, it may never be counted as a running_handle. <p class="level0">When <span Class="emphasis">running_handles</span> is set to zero (0) on the return of this function, there is no longer any transfers in progress. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">CURLMcode type, general libcurl multi interface error code. <p class="level0">Before version 7.20.0: If you receive <span Class="emphasis">CURLM_CALL_MULTI_PERFORM</span>, this basically means that you should call <span Class="emphasis">curl_multi_perform</span> again, before you select() on more actions. You don't have to do it immediately, but the return code means that libcurl may have more data available to return or that there may be more data to send off before it is "satisfied". Do note that <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> will return <span Class="emphasis">CURLM_CALL_MULTI_PERFORM</span> only when it wants to be called again <span Class="bold">immediately</span>. When things are fine and there is nothing immediate it wants done, it'll return <span Class="emphasis">CURLM_OK</span> and you need to wait for "action" and then call this function again. -<p class="level0">This function only returns errors etc regarding the whole multi stack. Problems still might have occurred on individual transfers even when this function returns <span Class="emphasis">CURLM_OK</span>. <a name="TYPICAL"></a><h2 class="nroffsh">TYPICAL USAGE</h2> -<p class="level0">Most applications will use <a class="emphasis" href="./curl_multi_fdset.html">curl_multi_fdset(3)</a> to get the multi_handle's file descriptors, then it'll wait for action on them using <span Class="bold">select(3)</span> and as soon as one or more of them are ready, <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> gets called. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> +<p class="level0">This function only returns errors etc regarding the whole multi stack. Problems still might have occurred on individual transfers even when this function returns <span Class="emphasis">CURLM_OK</span>. Use <a class="emphasis" href="./curl_multi_info_read.html">curl_multi_info_read(3)</a> to figure out how individual transfers did. <a name="TYPICAL"></a><h2 class="nroffsh">TYPICAL USAGE</h2> +<p class="level0">Most applications will use <a class="emphasis" href="./curl_multi_fdset.html">curl_multi_fdset(3)</a> to get the multi_handle's file descriptors, and <a class="emphasis" href="./curl_multi_timeout.html">curl_multi_timeout(3)</a> to get a suitable timeout period, then it'll wait for action on the file descriptors using <span Class="bold">select(3)</span>. As soon as one or more file descriptor is ready, <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> gets called. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_multi_cleanup.html">curl_multi_cleanup (3)</a> <a class="manpage" href="./curl_multi_init.html"> curl_multi_init (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_multi_fdset.html">curl_multi_fdset (3)</a> <a class="manpage" href="./curl_multi_info_read.html"> curl_multi_info_read (3)</a> <span Class="manpage"> </span> <span Class="manpage">libcurl-errors (3)</span> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/libcurl/curl_multi_perform.pdf b/docs/libcurl/curl_multi_perform.pdf Binary files differindex 13ed10643..6257e39eb 100644 --- a/docs/libcurl/curl_multi_perform.pdf +++ b/docs/libcurl/curl_multi_perform.pdf diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 index efecb109e..ad6d2bac8 100644 --- a/docs/libcurl/curl_multi_remove_handle.3 +++ b/docs/libcurl/curl_multi_remove_handle.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_remove_handle 3 "6 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_remove_handle - remove an easy handle from a multi session diff --git a/docs/libcurl/curl_multi_remove_handle.html b/docs/libcurl/curl_multi_remove_handle.html index 15bd02b70..fb4c499ee 100644 --- a/docs/libcurl/curl_multi_remove_handle.html +++ b/docs/libcurl/curl_multi_remove_handle.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_remove_handle man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_multi_remove_handle.pdf b/docs/libcurl/curl_multi_remove_handle.pdf Binary files differindex 7e0591af7..6d84a5b97 100644 --- a/docs/libcurl/curl_multi_remove_handle.pdf +++ b/docs/libcurl/curl_multi_remove_handle.pdf diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index a1cbb70dc..99984cf49 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_setopt 3 "10 Oct 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_setopt \- set options for a curl multi handle @@ -29,7 +49,7 @@ argument with \fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for more callback details. .IP CURLMOPT_SOCKETDATA Pass a pointer to whatever you want passed to the \fBcurl_socket_callback\fP's -forth argument, the userp pointer. This is not used by libcurl but only +fourth argument, the userp pointer. This is not used by libcurl but only passed-thru as-is. Set the callback pointer with \fICURLMOPT_SOCKETFUNCTION\fP. .IP CURLMOPT_PIPELINING @@ -41,14 +61,17 @@ on the same connection rather than being executed in parallel. (Added in 7.16.0) .IP CURLMOPT_TIMERFUNCTION Pass a pointer to a function matching the \fBcurl_multi_timer_callback\fP -prototype. This function will then be called when the timeout value +prototype: int curl_multi_timer_callback(CURLM *multi /* multi handle */, +long timeout_ms /* timeout in milliseconds */, void *userp /* TIMERDATA */). +This function will then be called when the timeout value changes. The timeout value is at what latest time the application should call one of the \&"performing" functions of the multi interface (\fIcurl_multi_socket_action(3)\fP and \fIcurl_multi_perform(3)\fP) - to allow libcurl to keep timeouts and retries etc to work. A timeout value of -1 means that there is no timeout at all, and 0 means that the timeout is already reached. Libcurl attempts to limit calling this only when the fixed future -timeout time actually changes. See also \fICURLMOPT_TIMERDATA\fP. This +timeout time actually changes. See also \fICURLMOPT_TIMERDATA\fP. The callback +should return 0 on success, and -1 on error. This callback can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP. (Added in 7.16.0) .IP CURLMOPT_TIMERDATA @@ -72,6 +95,112 @@ This option is for the multi handle's use only, when using the easy interface you should instead use the \fICURLOPT_MAXCONNECTS\fP option. (Added in 7.16.3) +.IP CURLMOPT_MAX_HOST_CONNECTIONS +Pass a long. The set number will be used as the maximum amount of +simultaneously open connections to a single host. For each new session to +a host, libcurl will open a new connection up to the limit set by +CURLMOPT_MAX_HOST_CONNECTIONS. When the limit is reached, the sessions will +be pending until there are available connections. If CURLMOPT_PIPELINING is +1, libcurl will try to pipeline if the host is capable of it. + +The default value is 0, which means that there is no limit. +However, for backwards compatibility, setting it to 0 when CURLMOPT_PIPELINING +is 1 will not be treated as unlimited. Instead it will open only 1 connection +and try to pipeline on it. + +(Added in 7.30.0) +.IP CURLMOPT_MAX_PIPELINE_LENGTH +Pass a long. The set number will be used as the maximum amount of requests +in a pipelined connection. When this limit is reached, libcurl will use another +connection to the same host (see CURLMOPT_MAX_HOST_CONNECTIONS), or queue the +requests until one of the pipelines to the host is ready to accept a request. +Thus, the total number of requests in-flight is CURLMOPT_MAX_HOST_CONNECTIONS * +CURLMOPT_MAX_PIPELINE_LENGTH. +The default value is 5. + +(Added in 7.30.0) +.IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE +Pass a long. If a pipelined connection is currently processing a request +with a Content-Length larger than CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, that +connection will not be considered for additional requests, even if it is +shorter than CURLMOPT_MAX_PIPELINE_LENGTH. +The default value is 0, which means that the penalization is inactive. + +(Added in 7.30.0) +.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE +Pass a long. If a pipelined connection is currently processing a +chunked (Transfer-encoding: chunked) request with a current chunk length +larger than CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, that connection will not be +considered for additional requests, even if it is shorter than +CURLMOPT_MAX_PIPELINE_LENGTH. +The default value is 0, which means that the penalization is inactive. + +(Added in 7.30.0) +.IP CURLMOPT_PIPELINING_SITE_BL +Pass an array of char *, ending with NULL. This is a list of sites that are +blacklisted from pipelining, i.e sites that are known to not support HTTP +pipelining. The array is copied by libcurl. + +The default value is NULL, which means that there is no blacklist. + +Pass a NULL pointer to clear the blacklist. + +Example: + +.nf + site_blacklist[] = + { + "www.haxx.se", + "www.example.com:1234", + NULL + }; + + curl_multi_setopt(m, CURLMOPT_PIPELINE_SITE_BL, site_blacklist); +.fi + +(Added in 7.30.0) +.IP CURLMOPT_PIPELINING_SERVER_BL +Pass an array of char *, ending with NULL. This is a list of server types +prefixes (in the Server: HTTP header) that are blacklisted from pipelining, +i.e server types that are known to not support HTTP pipelining. The array is +copied by libcurl. + +Note that the comparison matches if the Server: header begins with the string +in the blacklist, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can +both be blacklisted by having "Ninja" in the backlist. + +The default value is NULL, which means that there is no blacklist. + +Pass a NULL pointer to clear the blacklist. + +Example: + +.nf + server_blacklist[] = + { + "Microsoft-IIS/6.0", + "nginx/0.8.54", + NULL + }; + + curl_multi_setopt(m, CURLMOPT_PIPELINE_SERVER_BL, server_blacklist); +.fi + +(Added in 7.30.0) +.IP CURLMOPT_MAX_TOTAL_CONNECTIONS +Pass a long. The set number will be used as the maximum amount of +simultaneously open connections in total. For each new session, libcurl +will open a new connection up to the limit set by +CURLMOPT_MAX_TOTAL_CONNECTIONS. When the limit is reached, the sessions will +be pending until there are available connections. If CURLMOPT_PIPELINING is +1, libcurl will try to pipeline if the host is capable of it. + +The default value is 0, which means that there is no limit. +However, for backwards compatibility, setting it to 0 when CURLMOPT_PIPELINING +is 1 will not be treated as unlimited. Instead it will open only 1 connection +and try to pipeline on it. + +(Added in 7.30.0) .SH RETURNS The standard CURLMcode for multi interface error codes. Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl diff --git a/docs/libcurl/curl_multi_setopt.html b/docs/libcurl/curl_multi_setopt.html index 1e6758222..b95192b56 100644 --- a/docs/libcurl/curl_multi_setopt.html +++ b/docs/libcurl/curl_multi_setopt.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_setopt man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -53,11 +55,11 @@ p.roffit { <p class="level0"><a name="CURLMOPTSOCKETFUNCTION"></a><span class="nroffip">CURLMOPT_SOCKETFUNCTION</span> <p class="level1">Pass a pointer to a function matching the <span Class="bold">curl_socket_callback</span> prototype. The <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> function informs the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the curl_socket_callback given in the <span Class="bold">param</span> argument. They update the status with changes since the previous time a <a class="emphasis" href="./curl_multi_socket.html">curl_multi_socket(3)</a> function was called. If the given callback pointer is NULL, no callback will be called. Set the callback's <span Class="bold">userp</span> argument with <a class="emphasis" href="#CURLMOPTSOCKETDATA">CURLMOPT_SOCKETDATA</a>. See <a class="emphasis" href="./curl_multi_socket.html">curl_multi_socket(3)</a> for more callback details. <p class="level0"><a name="CURLMOPTSOCKETDATA"></a><span class="nroffip">CURLMOPT_SOCKETDATA</span> -<p class="level1">Pass a pointer to whatever you want passed to the <span Class="bold">curl_socket_callback</span>'s forth argument, the userp pointer. This is not used by libcurl but only passed-thru as-is. Set the callback pointer with <a class="emphasis" href="#CURLMOPTSOCKETFUNCTION">CURLMOPT_SOCKETFUNCTION</a>. +<p class="level1">Pass a pointer to whatever you want passed to the <span Class="bold">curl_socket_callback</span>'s fourth argument, the userp pointer. This is not used by libcurl but only passed-thru as-is. Set the callback pointer with <a class="emphasis" href="#CURLMOPTSOCKETFUNCTION">CURLMOPT_SOCKETFUNCTION</a>. <p class="level0"><a name="CURLMOPTPIPELINING"></a><span class="nroffip">CURLMOPT_PIPELINING</span> <p class="level1">Pass a long set to 1 to enable or 0 to disable. Enabling pipelining on a multi handle will make it attempt to perform HTTP Pipelining as far as possible for transfers using this handle. This means that if you add a second request that can use an already existing connection, the second request will be "piped" on the same connection rather than being executed in parallel. (Added in 7.16.0) <p class="level0"><a name="CURLMOPTTIMERFUNCTION"></a><span class="nroffip">CURLMOPT_TIMERFUNCTION</span> -<p class="level1">Pass a pointer to a function matching the <span Class="bold">curl_multi_timer_callback</span> prototype. This function will then be called when the timeout value changes. The timeout value is at what latest time the application should call one of the "performing" functions of the multi interface (<a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> and <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>) - to allow libcurl to keep timeouts and retries etc to work. A timeout value of -1 means that there is no timeout at all, and 0 means that the timeout is already reached. Libcurl attempts to limit calling this only when the fixed future timeout time actually changes. See also <a class="emphasis" href="#CURLMOPTTIMERDATA">CURLMOPT_TIMERDATA</a>. This callback can be used instead of, or in addition to, <a class="emphasis" href="./curl_multi_timeout.html">curl_multi_timeout(3)</a>. (Added in 7.16.0) +<p class="level1">Pass a pointer to a function matching the <span Class="bold">curl_multi_timer_callback</span> prototype: int curl_multi_timer_callback(CURLM *multi /* multi handle */, long timeout_ms /* timeout in milliseconds */, void *userp /* TIMERDATA */). This function will then be called when the timeout value changes. The timeout value is at what latest time the application should call one of the "performing" functions of the multi interface (<a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> and <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>) - to allow libcurl to keep timeouts and retries etc to work. A timeout value of -1 means that there is no timeout at all, and 0 means that the timeout is already reached. Libcurl attempts to limit calling this only when the fixed future timeout time actually changes. See also <a class="emphasis" href="#CURLMOPTTIMERDATA">CURLMOPT_TIMERDATA</a>. The callback should return 0 on success, and -1 on error. This callback can be used instead of, or in addition to, <a class="emphasis" href="./curl_multi_timeout.html">curl_multi_timeout(3)</a>. (Added in 7.16.0) <p class="level0"><a name="CURLMOPTTIMERDATA"></a><span class="nroffip">CURLMOPT_TIMERDATA</span> <p class="level1">Pass a pointer to whatever you want passed to the <span Class="bold">curl_multi_timer_callback</span>'s third argument, the userp pointer. This is not used by libcurl but only passed-thru as-is. Set the callback pointer with <a class="emphasis" href="#CURLMOPTTIMERFUNCTION">CURLMOPT_TIMERFUNCTION</a>. (Added in 7.16.0) <p class="level0"><a name="CURLMOPTMAXCONNECTS"></a><span class="nroffip">CURLMOPT_MAXCONNECTS</span> @@ -65,7 +67,59 @@ p.roffit { <p class="level1">By setting this option, you can prevent the cache size from growing beyond the limit set by you. <p class="level1">When the cache is full, curl closes the oldest one in the cache to prevent the number of open connections from increasing. <p class="level1">This option is for the multi handle's use only, when using the easy interface you should instead use the <span Class="emphasis">CURLOPT_MAXCONNECTS</span> option. -<p class="level1">(Added in 7.16.3) <a name="RETURNS"></a><h2 class="nroffsh">RETURNS</h2> +<p class="level1">(Added in 7.16.3) +<p class="level0"><a name="CURLMOPTMAXHOSTCONNECTIONS"></a><span class="nroffip">CURLMOPT_MAX_HOST_CONNECTIONS</span> +<p class="level1">Pass a long. The set number will be used as the maximum amount of simultaneously open connections to a single host. For each new session to a host, libcurl will open a new connection up to the limit set by CURLMOPT_MAX_HOST_CONNECTIONS. When the limit is reached, the sessions will be pending until there are available connections. If CURLMOPT_PIPELINING is 1, libcurl will try to pipeline if the host is capable of it. +<p class="level1">The default value is 0, which means that there is no limit. However, for backwards compatibility, setting it to 0 when CURLMOPT_PIPELINING is 1 will not be treated as unlimited. Instead it will open only 1 connection and try to pipeline on it. +<p class="level1">(Added in 7.30.0) +<p class="level0"><a name="CURLMOPTMAXPIPELINELENGTH"></a><span class="nroffip">CURLMOPT_MAX_PIPELINE_LENGTH</span> +<p class="level1">Pass a long. The set number will be used as the maximum amount of requests in a pipelined connection. When this limit is reached, libcurl will use another connection to the same host (see CURLMOPT_MAX_HOST_CONNECTIONS), or queue the requests until one of the pipelines to the host is ready to accept a request. Thus, the total number of requests in-flight is CURLMOPT_MAX_HOST_CONNECTIONS * CURLMOPT_MAX_PIPELINE_LENGTH. The default value is 5. +<p class="level1">(Added in 7.30.0) +<p class="level0"><a name="CURLMOPTCONTENTLENGTHPENALTYSIZE"></a><span class="nroffip">CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE</span> +<p class="level1">Pass a long. If a pipelined connection is currently processing a request with a Content-Length larger than CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, that connection will not be considered for additional requests, even if it is shorter than CURLMOPT_MAX_PIPELINE_LENGTH. The default value is 0, which means that the penalization is inactive. +<p class="level1">(Added in 7.30.0) +<p class="level0"><a name="CURLMOPTCHUNKLENGTHPENALTYSIZE"></a><span class="nroffip">CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE</span> +<p class="level1">Pass a long. If a pipelined connection is currently processing a chunked (Transfer-encoding: chunked) request with a current chunk length larger than CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, that connection will not be considered for additional requests, even if it is shorter than CURLMOPT_MAX_PIPELINE_LENGTH. The default value is 0, which means that the penalization is inactive. +<p class="level1">(Added in 7.30.0) +<p class="level0"><a name="CURLMOPTPIPELININGSITEBL"></a><span class="nroffip">CURLMOPT_PIPELINING_SITE_BL</span> +<p class="level1">Pass an array of char *, ending with NULL. This is a list of sites that are blacklisted from pipelining, i.e sites that are known to not support HTTP pipelining. The array is copied by libcurl. +<p class="level1">The default value is NULL, which means that there is no blacklist. +<p class="level1">Pass a NULL pointer to clear the blacklist. +<p class="level1">Example: +<p class="level1"><pre> +<p class="level1"> site_blacklist[] = + { + "www.haxx.se", + "www.example.com:1234", + NULL + }; + <p class="level1"> curl_multi_setopt(m, CURLMOPT_PIPELINE_SITE_BL, site_blacklist); + </pre> + +<p class="level1"> +<p class="level1">(Added in 7.30.0) +<p class="level0"><a name="CURLMOPTPIPELININGSERVERBL"></a><span class="nroffip">CURLMOPT_PIPELINING_SERVER_BL</span> +<p class="level1">Pass an array of char *, ending with NULL. This is a list of server types prefixes (in the Server: HTTP header) that are blacklisted from pipelining, i.e server types that are known to not support HTTP pipelining. The array is copied by libcurl. +<p class="level1">Note that the comparison matches if the Server: header begins with the string in the blacklist, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can both be blacklisted by having "Ninja" in the backlist. +<p class="level1">The default value is NULL, which means that there is no blacklist. +<p class="level1">Pass a NULL pointer to clear the blacklist. +<p class="level1">Example: +<p class="level1"><pre> +<p class="level1"> server_blacklist[] = + { + "Microsoft-IIS/6.0", + "nginx/0.8.54", + NULL + }; + <p class="level1"> curl_multi_setopt(m, CURLMOPT_PIPELINE_SERVER_BL, server_blacklist); + </pre> + +<p class="level1"> +<p class="level1">(Added in 7.30.0) +<p class="level0"><a name="CURLMOPTMAXTOTALCONNECTIONS"></a><span class="nroffip">CURLMOPT_MAX_TOTAL_CONNECTIONS</span> +<p class="level1">Pass a long. The set number will be used as the maximum amount of simultaneously open connections in total. For each new session, libcurl will open a new connection up to the limit set by CURLMOPT_MAX_TOTAL_CONNECTIONS. When the limit is reached, the sessions will be pending until there are available connections. If CURLMOPT_PIPELINING is 1, libcurl will try to pipeline if the host is capable of it. +<p class="level1">The default value is 0, which means that there is no limit. However, for backwards compatibility, setting it to 0 when CURLMOPT_PIPELINING is 1 will not be treated as unlimited. Instead it will open only 1 connection and try to pipeline on it. +<p class="level1">(Added in 7.30.0) <a name="RETURNS"></a><h2 class="nroffsh">RETURNS</h2> <p class="level0">The standard CURLMcode for multi interface error codes. Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl doesn't know of. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> <p class="level0">This function was added in libcurl 7.15.4. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_multi_cleanup.html">curl_multi_cleanup (3)</a> <a class="manpage" href="./curl_multi_init.html"> curl_multi_init (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_multi_socket.html">curl_multi_socket (3)</a> <a class="manpage" href="./curl_multi_info_read.html"> curl_multi_info_read (3)</a> <p class="roffit"> diff --git a/docs/libcurl/curl_multi_setopt.pdf b/docs/libcurl/curl_multi_setopt.pdf Binary files differindex 0b354a763..37e327955 100644 --- a/docs/libcurl/curl_multi_setopt.pdf +++ b/docs/libcurl/curl_multi_setopt.pdf diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 18b571c1c..6b262f292 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_socket 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_socket \- reads/writes available data diff --git a/docs/libcurl/curl_multi_socket.html b/docs/libcurl/curl_multi_socket.html index 72d803f69..2e92236ea 100644 --- a/docs/libcurl/curl_multi_socket.html +++ b/docs/libcurl/curl_multi_socket.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_socket man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_multi_socket.pdf b/docs/libcurl/curl_multi_socket.pdf Binary files differindex 5e93029fa..277295d18 100644 --- a/docs/libcurl/curl_multi_socket.pdf +++ b/docs/libcurl/curl_multi_socket.pdf diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index 94e6f10a5..45b61058d 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_socket_action 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_socket_action \- reads/writes available data given an action @@ -18,7 +38,9 @@ can be passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and -libcurl will test the descriptor internally. +libcurl will test the descriptor internally. It is also permissible to pass +CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the +whole process or when a timeout occurs. At return, the integer \fBrunning_handles\fP points to will contain the number of running easy handles within the multi handle. When this number reaches @@ -51,7 +73,10 @@ The socket \fBcallback\fP function uses a prototype like this curl_socket_t s, /* socket */ int action, /* see values below */ void *userp, /* private callback pointer */ - void *socketp); /* private socket pointer */ + void *socketp); /* private socket pointer, + \fBNULL\fP if not + previously assigned with + \fBcurl_multi_assign(3)\fP */ .fi The callback MUST return 0. @@ -112,15 +137,15 @@ timeout value to use when waiting for socket activities. them for activity. This can be done through your application code, or by way of an external library such as libevent or glib. -6. Call curl_multi_socket_action() to kickstart everything. To get one or more -callbacks called. +6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...) +to kickstart everything. To get one or more callbacks called. 7. Wait for activity on any of libcurl's sockets, use the timeout value your -callback has been told +callback has been told. 8, When activity is detected, call curl_multi_socket_action() for the socket(s) that got action. If no activity is detected and the timeout expires, -call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP +call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP. .SH AVAILABILITY This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_multi_socket_action.html b/docs/libcurl/curl_multi_socket_action.html index eee2bdef3..626f6f102 100644 --- a/docs/libcurl/curl_multi_socket_action.html +++ b/docs/libcurl/curl_multi_socket_action.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_socket_action man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -53,7 +55,7 @@ p.roffit { </pre> <p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> -<p class="level0">When the application has detected action on a socket handled by libcurl, it should call <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> with the <span Class="bold">sockfd</span> argument set to the socket with the action. When the events on a socket are known, they can be passed as an events bitmask <span Class="bold">ev_bitmask</span> by first setting <span Class="bold">ev_bitmask</span> to 0, and then adding using bitwise OR (|) any combination of events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and libcurl will test the descriptor internally. +<p class="level0">When the application has detected action on a socket handled by libcurl, it should call <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> with the <span Class="bold">sockfd</span> argument set to the socket with the action. When the events on a socket are known, they can be passed as an events bitmask <span Class="bold">ev_bitmask</span> by first setting <span Class="bold">ev_bitmask</span> to 0, and then adding using bitwise OR (|) any combination of events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and libcurl will test the descriptor internally. It is also permissible to pass CURL_SOCKET_TIMEOUT to the <span Class="bold">sockfd</span> parameter in order to initiate the whole process or when a timeout occurs. <p class="level0">At return, the integer <span Class="bold">running_handles</span> points to will contain the number of running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done. When you call <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use <a class="emphasis" href="./curl_multi_info_read.html">curl_multi_info_read(3)</a> to figure out which easy handle that completed. <p class="level0">The <a class="bold" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> functions inform the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the socket callback function set with the CURLMOPT_SOCKETFUNCTION option to <a class="emphasis" href="./curl_multi_setopt.html">curl_multi_setopt(3)</a>. They update the status with changes since the previous time the callback was called. <p class="level0">Get the timeout time by setting the <span Class="emphasis">CURLMOPT_TIMERFUNCTION</span> option with <a class="emphasis" href="./curl_multi_setopt.html">curl_multi_setopt(3)</a>. Your application will then get called with information on how long to wait for socket actions at most before doing the timeout action: call the <a class="bold" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> function with the <span Class="bold">sockfd</span> argument set to CURL_SOCKET_TIMEOUT. You can also use the <a class="emphasis" href="./curl_multi_timeout.html">curl_multi_timeout(3)</a> function to poll the value at any given time, but for an event-based system using the callback is far better than relying on polling the timeout value. <a name="CALLBACK"></a><h2 class="nroffsh">CALLBACK DETAILS</h2> @@ -63,7 +65,10 @@ p.roffit { curl_socket_t s, /* socket */ int action, /* see values below */ void *userp, /* private callback pointer */ - void *socketp); /* private socket pointer */ + void *socketp); /* private socket pointer, + <span Class="bold">NULL</span> if not + previously assigned with + <a class="bold" href="./curl_multi_assign.html">curl_multi_assign(3)</a> */ <p class="level0"></pre> <p class="level0">The callback MUST return 0. @@ -92,9 +97,9 @@ p.roffit { <p class="level0">3. Set the timeout callback with CURLMOPT_TIMERFUNCTION, to get to know what timeout value to use when waiting for socket activities. <p class="level0">4. Add easy handles with curl_multi_add_handle() <p class="level0">5. Provide some means to manage the sockets libcurl is using, so you can check them for activity. This can be done through your application code, or by way of an external library such as libevent or glib. -<p class="level0">6. Call curl_multi_socket_action() to kickstart everything. To get one or more callbacks called. -<p class="level0">7. Wait for activity on any of libcurl's sockets, use the timeout value your callback has been told -<p class="level0">8, When activity is detected, call curl_multi_socket_action() for the socket(s) that got action. If no activity is detected and the timeout expires, call <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> with <span Class="emphasis">CURL_SOCKET_TIMEOUT</span> <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> +<p class="level0">6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...) to kickstart everything. To get one or more callbacks called. +<p class="level0">7. Wait for activity on any of libcurl's sockets, use the timeout value your callback has been told. +<p class="level0">8, When activity is detected, call curl_multi_socket_action() for the socket(s) that got action. If no activity is detected and the timeout expires, call <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> with <span Class="emphasis">CURL_SOCKET_TIMEOUT</span>. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> <p class="level0">This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_multi_cleanup.html">curl_multi_cleanup (3)</a> <a class="manpage" href="./curl_multi_init.html"> curl_multi_init (3)</a> <span Class="manpage"> </span> <a class="manpage" href="./curl_multi_fdset.html">curl_multi_fdset (3)</a> <a class="manpage" href="./curl_multi_info_read.html"> curl_multi_info_read (3)</a> <span Class="manpage"> </span> <span Class="manpage">the hiperfifo.c example</span> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. diff --git a/docs/libcurl/curl_multi_socket_action.pdf b/docs/libcurl/curl_multi_socket_action.pdf Binary files differindex d6ca6b03f..6a8187b76 100644 --- a/docs/libcurl/curl_multi_socket_action.pdf +++ b/docs/libcurl/curl_multi_socket_action.pdf diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3 index 2d9801d6a..40d0974c5 100644 --- a/docs/libcurl/curl_multi_strerror.3 +++ b/docs/libcurl/curl_multi_strerror.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_multi_strerror - return string describing error code diff --git a/docs/libcurl/curl_multi_strerror.html b/docs/libcurl/curl_multi_strerror.html index ac885aa94..198a1a58e 100644 --- a/docs/libcurl/curl_multi_strerror.html +++ b/docs/libcurl/curl_multi_strerror.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_strerror man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_multi_strerror.pdf b/docs/libcurl/curl_multi_strerror.pdf Binary files differindex b2cebb150..3d848cf51 100644 --- a/docs/libcurl/curl_multi_strerror.pdf +++ b/docs/libcurl/curl_multi_strerror.pdf diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index 9e53d0b8a..e18b935cc 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_timeout 3 "2 Jan 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_timeout \- how long to wait for action before proceeding @@ -22,7 +42,7 @@ of milliseconds at this very moment. If 0, it means you should proceed immediately without waiting for anything. If it returns -1, there's no timeout at all set. -An application that uses the multi_socket API SHOULD not use this function, but +An application that uses the multi_socket API SHOULD NOT use this function, but SHOULD instead use \fIcurl_multi_setopt(3)\fP and its \fPCURLMOPT_TIMERFUNCTION\fP option for proper and desired behavior. diff --git a/docs/libcurl/curl_multi_timeout.html b/docs/libcurl/curl_multi_timeout.html index 78a383f24..676d776cc 100644 --- a/docs/libcurl/curl_multi_timeout.html +++ b/docs/libcurl/curl_multi_timeout.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_multi_timeout man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -51,7 +53,7 @@ p.roffit { <p class="level0">An application using the libcurl multi interface should call <a class="bold" href="./curl_multi_timeout.html">curl_multi_timeout(3)</a> to figure out how long it should wait for socket actions - at most - before proceeding. <p class="level0">Proceeding means either doing the socket-style timeout action: call the <a class="bold" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> function with the <span Class="bold">sockfd</span> argument set to CURL_SOCKET_TIMEOUT, or call <a class="bold" href="./curl_multi_perform.html">curl_multi_perform(3)</a> if you're using the simpler and older multi interface approach. <p class="level0">The timeout value returned in the long <span Class="bold">timeout</span> points to, is in number of milliseconds at this very moment. If 0, it means you should proceed immediately without waiting for anything. If it returns -1, there's no timeout at all set. -<p class="level0">An application that uses the multi_socket API SHOULD not use this function, but SHOULD instead use <a class="emphasis" href="./curl_multi_setopt.html">curl_multi_setopt(3)</a> and its </span>CURLMOPT_TIMERFUNCTION</span> option for proper and desired behavior. +<p class="level0">An application that uses the multi_socket API SHOULD NOT use this function, but SHOULD instead use <a class="emphasis" href="./curl_multi_setopt.html">curl_multi_setopt(3)</a> and its </span>CURLMOPT_TIMERFUNCTION</span> option for proper and desired behavior. <p class="level0">Note: if libcurl returns a -1 timeout here, it just means that libcurl currently has no stored timeout value. You must not wait too long (more than a few seconds perhaps) before you call curl_multi_perform() again. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">The standard CURLMcode for multi interface error codes. <a name="TYPICAL"></a><h2 class="nroffsh">TYPICAL USAGE</h2> <p class="level0">Call <a class="bold" href="./curl_multi_timeout.html">curl_multi_timeout(3)</a>, then wait for action on the sockets. You figure out which sockets to wait for by calling <a class="bold" href="./curl_multi_fdset.html">curl_multi_fdset(3)</a> or by a previous call to <a class="bold" href="./curl_multi_socket.html">curl_multi_socket(3)</a>. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> diff --git a/docs/libcurl/curl_multi_timeout.pdf b/docs/libcurl/curl_multi_timeout.pdf Binary files differindex 1e1afbd04..9a542c1ea 100644 --- a/docs/libcurl/curl_multi_timeout.pdf +++ b/docs/libcurl/curl_multi_timeout.pdf diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 new file mode 100644 index 000000000..21ade930b --- /dev/null +++ b/docs/libcurl/curl_multi_wait.3 @@ -0,0 +1,80 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_multi_wait 3 "12 Jul 2012" "libcurl 7.28.0" "libcurl Manual" +.SH NAME +curl_multi_wait - polls on all easy handles in a multi handle +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLMcode curl_multi_wait(CURLM *multi_handle, + struct curl_waitfd extra_fds[], + unsigned int extra_nfds, + int timeout_ms, + int *numfds); +.ad +.SH DESCRIPTION +This function polls on all file descriptors used by the curl easy handles +contained in the given multi handle set. It will block until activity is +detected on at least one of the handles or \fItimeout_ms\fP has passed. +Alternatively, if the multi handle has a pending internal timeout that has a +shorter expiry time than \fItimeout_ms\fP, that shorter time will be used +instead to make sure timeout accuracy is reasonably kept. + +The calling application may pass additional curl_waitfd structures which are +similar to \fIpoll(2)\fP's pollfd structure to be waited on in the same call. + +On completion, if \fInumfds\fP is supplied, it will be populated with the +total number of file descriptors on which interesting events occured. This +number can include both libcurl internal descriptors as well as descriptors +provided in \fIextra_fds\fP. + +If no extra file descriptors are provided and libcurl has no file descriptor +to offer to wait for, this function will return immediately. + +This function is encouraged to be used instead of select(3) when using the +multi interface to allow applications to easier circumvent the common problem +with 1024 maximum file descriptors. +.SH curl_waitfd +.nf +struct curl_waitfd { + curl_socket_t fd; + short events; + short revents; +}; +.fi +.IP CURL_WAIT_POLLIN +Bit flag to curl_waitfd.events indicating the socket should poll on read +events such as new data received. +.IP CURL_WAIT_POLLPRI +Bit flag to curl_waitfd.events indicating the socket should poll on high +priority read events such as out of band data. +.IP CURL_WAIT_POLLOUT +Bit flag to curl_waitfd.events indicating the socket should poll on write +events such as the socket being clear to write without blocking. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. See +\fIlibcurl-errors(3)\fP +.SH AVAILABILITY +This function was added in libcurl 7.28.0. +.SH "SEE ALSO" +.BR curl_multi_fdset "(3), " curl_multi_perform "(3)" diff --git a/docs/libcurl/curl_multi_wait.html b/docs/libcurl/curl_multi_wait.html new file mode 100644 index 000000000..7d43abdd3 --- /dev/null +++ b/docs/libcurl/curl_multi_wait.html @@ -0,0 +1,83 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<html><head> +<title>curl_multi_wait man page</title> +<meta name="generator" content="roffit"> +<STYLE type="text/css"> +P.level0 { + padding-left: 2em; +} + +P.level1 { + padding-left: 4em; +} + +P.level2 { + padding-left: 6em; +} + +span.emphasis { + font-style: italic; +} + +span.bold { + font-weight: bold; +} + +span.manpage { + font-weight: bold; +} + +h2.nroffsh { + background-color: #e0e0e0; +} + +span.nroffip { + font-weight: bold; + font-size: 120%; + font-family: monospace; +} + +p.roffit { + text-align: center; + font-size: 80%; +} +</STYLE> +</head><body> + +<p class="level0"><a name="NAME"></a><h2 class="nroffsh">NAME</h2> +<p class="level0">curl_multi_wait - polls on all easy handles in a multi handle <a name="SYNOPSIS"></a><h2 class="nroffsh">SYNOPSIS</h2> +<p class="level0"><pre> +<p class="level0">#include <curl/curl.h> + <p class="level0">CURLMcode curl_multi_wait(CURLM *multi_handle, + struct curl_waitfd extra_fds[], + unsigned int extra_nfds, + int timeout_ms, + int *numfds); + <p class="level0"></pre> +<a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> +<p class="level0">This function polls on all file descriptors used by the curl easy handles contained in the given multi handle set. It will block until activity is detected on at least one of the handles or <span Class="emphasis">timeout_ms</span> has passed. Alternatively, if the multi handle has a pending internal timeout that has a shorter expiry time than <span Class="emphasis">timeout_ms</span>, that shorter time will be used instead to make sure timeout accuracy is reasonably kept. +<p class="level0">The calling application may pass additional curl_waitfd structures which are similar to <span Class="emphasis">poll(2)</span>'s pollfd structure to be waited on in the same call. +<p class="level0">On completion, if <span Class="emphasis">numfds</span> is supplied, it will be populated with the total number of file descriptors on which interesting events occured. This number can include both libcurl internal descriptors as well as descriptors provided in <span Class="emphasis">extra_fds</span>. +<p class="level0">If no extra file descriptors are provided and libcurl has no file descriptor to offer to wait for, this function will return immediately. +<p class="level0">This function is encouraged to be used instead of select(3) when using the multi interface to allow applications to easier circumvent the common problem with 1024 maximum file descriptors. <a name="curlwaitfd"></a><h2 class="nroffsh">curl_waitfd</h2> +<p class="level0"><pre> +<p class="level0">struct curl_waitfd { + curl_socket_t fd; + short events; + short revents; + }; + </pre> + +<p class="level0"> +<p class="level0"><a name="CURLWAITPOLLIN"></a><span class="nroffip">CURL_WAIT_POLLIN</span> +<p class="level1">Bit flag to curl_waitfd.events indicating the socket should poll on read events such as new data received. +<p class="level0"><a name="CURLWAITPOLLPRI"></a><span class="nroffip">CURL_WAIT_POLLPRI</span> +<p class="level1">Bit flag to curl_waitfd.events indicating the socket should poll on high priority read events such as out of band data. +<p class="level0"><a name="CURLWAITPOLLOUT"></a><span class="nroffip">CURL_WAIT_POLLOUT</span> +<p class="level1">Bit flag to curl_waitfd.events indicating the socket should poll on write events such as the socket being clear to write without blocking. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> +<p class="level0">CURLMcode type, general libcurl multi interface error code. See <span Class="emphasis">libcurl-errors(3)</span> <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> +<p class="level0">This function was added in libcurl 7.28.0. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> +<p class="level0"><a class="manpage" href="./curl_multi_fdset.html">curl_multi_fdset (3)</a> <a class="manpage" href="./curl_multi_perform.html"> curl_multi_perform (3)</a> <p class="roffit"> + This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. +</body></html> diff --git a/docs/libcurl/curl_multi_wait.pdf b/docs/libcurl/curl_multi_wait.pdf Binary files differnew file mode 100644 index 000000000..cb23594c1 --- /dev/null +++ b/docs/libcurl/curl_multi_wait.pdf diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3 index 222197cc8..3af1707bb 100644 --- a/docs/libcurl/curl_share_cleanup.3 +++ b/docs/libcurl/curl_share_cleanup.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_share_cleanup 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME curl_share_cleanup - Clean up a shared object diff --git a/docs/libcurl/curl_share_cleanup.html b/docs/libcurl/curl_share_cleanup.html index 758f1e9a9..3e1e6370f 100644 --- a/docs/libcurl/curl_share_cleanup.html +++ b/docs/libcurl/curl_share_cleanup.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_share_cleanup man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_share_cleanup.pdf b/docs/libcurl/curl_share_cleanup.pdf Binary files differindex 300b15c37..3b1f5c948 100644 --- a/docs/libcurl/curl_share_cleanup.pdf +++ b/docs/libcurl/curl_share_cleanup.pdf diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 index 871519cb9..ce00d958e 100644 --- a/docs/libcurl/curl_share_init.3 +++ b/docs/libcurl/curl_share_init.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_share_init 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME curl_share_init - Create a shared object diff --git a/docs/libcurl/curl_share_init.html b/docs/libcurl/curl_share_init.html index cbc8231c2..ebf555be4 100644 --- a/docs/libcurl/curl_share_init.html +++ b/docs/libcurl/curl_share_init.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_share_init man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_share_init.pdf b/docs/libcurl/curl_share_init.pdf Binary files differindex f8ff5b988..0427da679 100644 --- a/docs/libcurl/curl_share_init.pdf +++ b/docs/libcurl/curl_share_init.pdf diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index 351360da9..c196743ff 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_share_setopt 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME curl_share_setopt - Set options for a shared object @@ -44,6 +64,11 @@ Cached DNS hosts will be shared across the easy handles using this shared object. Note that when you use the multi interface, all easy handles added to the same multi handle will share DNS cache by default without this having to be used! +.IP CURL_LOCK_DATA_SSL_SESSION +SSL session IDs will be shared across the easy handles using this shared +object. This will reduce the time spent in the SSL handshake when reconnecting +to the same server. Note SSL session IDs are reused within the same easy handle +by default. .RE .IP CURLSHOPT_UNSHARE This option does the opposite of \fICURLSHOPT_SHARE\fP. It specifies that diff --git a/docs/libcurl/curl_share_setopt.html b/docs/libcurl/curl_share_setopt.html index 439238786..14b367702 100644 --- a/docs/libcurl/curl_share_setopt.html +++ b/docs/libcurl/curl_share_setopt.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_share_setopt man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -68,6 +70,8 @@ p.roffit { <p class="level2">Cookie data will be shared across the easy handles using this shared object. <p class="level1"><a name="CURLLOCKDATADNS"></a><span class="nroffip">CURL_LOCK_DATA_DNS</span> <p class="level2">Cached DNS hosts will be shared across the easy handles using this shared object. Note that when you use the multi interface, all easy handles added to the same multi handle will share DNS cache by default without this having to be used! +<p class="level1"><a name="CURLLOCKDATASSLSESSION"></a><span class="nroffip">CURL_LOCK_DATA_SSL_SESSION</span> +<p class="level2">SSL session IDs will be shared across the easy handles using this shared object. This will reduce the time spent in the SSL handshake when reconnecting to the same server. Note SSL session IDs are reused within the same easy handle by default. <p class="level1"> <p class="level0"><a name="CURLSHOPTUNSHARE"></a><span class="nroffip">CURLSHOPT_UNSHARE</span> <p class="level1">This option does the opposite of <a class="emphasis" href="#CURLSHOPTSHARE">CURLSHOPT_SHARE</a>. It specifies that the specified <span Class="emphasis">parameter</span> will no longer be shared. Valid values are the same as those for <a class="emphasis" href="#CURLSHOPTSHARE">CURLSHOPT_SHARE</a>. diff --git a/docs/libcurl/curl_share_setopt.pdf b/docs/libcurl/curl_share_setopt.pdf Binary files differindex 37e49f29d..0c4f4323e 100644 --- a/docs/libcurl/curl_share_setopt.pdf +++ b/docs/libcurl/curl_share_setopt.pdf diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3 index 69087dbf2..f1bc39867 100644 --- a/docs/libcurl/curl_share_strerror.3 +++ b/docs/libcurl/curl_share_strerror.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_share_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_share_strerror - return string describing error code diff --git a/docs/libcurl/curl_share_strerror.html b/docs/libcurl/curl_share_strerror.html index 0b5b0503a..f09b0e069 100644 --- a/docs/libcurl/curl_share_strerror.html +++ b/docs/libcurl/curl_share_strerror.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_share_strerror man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_share_strerror.pdf b/docs/libcurl/curl_share_strerror.pdf Binary files differindex 5de438a8f..d301a6e8a 100644 --- a/docs/libcurl/curl_share_strerror.pdf +++ b/docs/libcurl/curl_share_strerror.pdf diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3 index 5cca9b72e..529560e8a 100644 --- a/docs/libcurl/curl_slist_append.3 +++ b/docs/libcurl/curl_slist_append.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_slist_append 3 "19 Jun 2003" "libcurl 7.10.4" "libcurl Manual" .SH NAME curl_slist_append - add a string to an slist diff --git a/docs/libcurl/curl_slist_append.html b/docs/libcurl/curl_slist_append.html index 50436e801..0b77859ab 100644 --- a/docs/libcurl/curl_slist_append.html +++ b/docs/libcurl/curl_slist_append.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_slist_append man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_slist_append.pdf b/docs/libcurl/curl_slist_append.pdf Binary files differindex 38c1db918..3025e438c 100644 --- a/docs/libcurl/curl_slist_append.pdf +++ b/docs/libcurl/curl_slist_append.pdf diff --git a/docs/libcurl/curl_slist_free_all.3 b/docs/libcurl/curl_slist_free_all.3 index ec1b3607b..fab3d6080 100644 --- a/docs/libcurl/curl_slist_free_all.3 +++ b/docs/libcurl/curl_slist_free_all.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_slist_free_all 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" .SH NAME curl_slist_free_all - free an entire curl_slist list diff --git a/docs/libcurl/curl_slist_free_all.html b/docs/libcurl/curl_slist_free_all.html index 76a0a9dec..0bd7418ec 100644 --- a/docs/libcurl/curl_slist_free_all.html +++ b/docs/libcurl/curl_slist_free_all.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_slist_free_all man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_slist_free_all.pdf b/docs/libcurl/curl_slist_free_all.pdf index 693f895db..f233108dc 100644 --- a/docs/libcurl/curl_slist_free_all.pdf +++ b/docs/libcurl/curl_slist_free_all.pdf @@ -3,16 +3,14 @@ 5 0 obj <</Length 6 0 R/Filter /FlateDecode>> stream -xœ…Së‹Ó@ÿž¿bÀnÄlg7Ù<P„ªAîèãls‚´RriÚFÓ´—GÅÿÞÝdKSì!K6agfç÷˜<R¨–~'{c0ó`[_ä³5ž
Ö&€~%{øÉ$_ D£«càqð ¢½Á˜OQ@ôÛX¤)óU•gU½Ú”iºŠó|Iì¥ yö¤b¦ÅRDŒã¢‰sx©ÀüÝRΈÙ?ýi Û…hdÉÐ|-!Ë(T¶„
2Íèg0Gê ã*Œ -ç-˜`ú„¸€´¨³2íAµu·ö`X‡Å\ê·mçß'Ó‡ùÝü’¦¡êÆäUV$y³Nὺx 6ºû Ò-冤Á–×épæÐ #µ ÙúZ*S‰ŽžOΚUuÙ$u ô›VÃÁŒáÙ:סèj™TÊÒ|÷/+Ž²mŸÙçpþiv÷ÝM'×ÊöÈÝ´QÚ^¦ûÙ¢hBF=Oc8¥*Æ©èÈr?ð ªbêÜEêÛÈÎJH«ê2NÒ -ˆáX¦&J ›œ²CSåàÉäHš,¯¯=,~™ »ÌtÝzJµD}þLxÔ.üdF³ |3™íHiŽ C]yC‹É¡ÞeÅ–þo`†£ùôÅéi i±¾Vß“Cïz@HûÓ¼m¥fŒQ!^Ø\·Ò? x{‚s -XW/ƽ]jK't .“ pDÖV:HÝóµ'ad|•ë/zë Ïendstream +xœ…SYÓ0~ϯ‰ DܱSç©@ Šz,m µ¨Ê¦iHÓnŽ®ø÷؉æ¢+dɉ<3žï?R¨–þÆGc°pa_{ãÑ`Mô'>ÂÇP&xê Üm
—ƒëÛÔó!<Œy„OÆŠÄu‘mÊ,-«Í®H’M”ekb¯MÈÒ3-."ºdåu”ÁKæð‹a!åLöˆ%_B ¾P(l‰Af#óµD-£LPáÛY¸5È40ß=Ì é]°WaT8oÁ Ô/D9$y•I¨½µÃ’8,æP¯i»ü>›ß-ÇËç4
U7&¯Ò<ÎêmïÕŵÑÕn)3$
>lx]N /Ÿú-©I·×R™Jtt=ÒiVVE W}Ðo
†{΢£eR)kóÝ¿¬8ʶ}fŸƒå§Åø. Ïg×ÊöÈÝ´QÚ^$ÇSGQ4V!£®«1\ãT´d¹ç{C *#jÝEêÙÈ:%¤UUÅI § Dp.“ ¥…M.é©.³ßð`r$ušU× æ¿L†mf²m<¥Z¢>&\5Øù¯È"ï3øf2{(¥ad4¹tå
-f§êæ{ú¿ M–ó¦§it>'ùöZ}W½ãë!Í£yÛHÍ£B¼°¹n¥ ¸{‚s +X[/¦Ïz;Ô–Nè@TÄàˆ¬© "uº jN‚Ðø*× z Ñendstream endobj 6 0 obj -547 +546 endobj 4 0 obj -<</Type/Page/MediaBox [0 0 612 792] +<</Type/Page/MediaBox [0 0 595 842] /Rotate 0/Parent 3 0 R /Resources<</ProcSet[/PDF /Text] /ExtGState 11 0 R @@ -59,17 +57,17 @@ endobj endobj 13 0 obj <</Type/Metadata -/Subtype/XML/Length 1321>>stream +/Subtype/XML/Length 1346>>stream <?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?> <?adobe-xap-filters esc="CRLF"?> <x:xmpmeta xmlns:x='adobe:ns:meta/' x:xmptk='XMP toolkit 2.9.1-13, framework 1.6'> <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#' xmlns:iX='http://ns.adobe.com/iX/1.0/'> -<rdf:Description rdf:about='3e2370bc-4071-11eb-0000-0d90648fa894' xmlns:pdf='http://ns.adobe.com/pdf/1.3/' pdf:Producer='GPL Ghostscript 8.71'/> -<rdf:Description rdf:about='3e2370bc-4071-11eb-0000-0d90648fa894' xmlns:xmp='http://ns.adobe.com/xap/1.0/'><xmp:ModifyDate>2010-12-15T15:07:47+01:00</xmp:ModifyDate> -<xmp:CreateDate>2010-12-15T15:07:47+01:00</xmp:CreateDate> -<xmp:CreatorTool>groff version 1.20.1</xmp:CreatorTool></rdf:Description> -<rdf:Description rdf:about='3e2370bc-4071-11eb-0000-0d90648fa894' xmlns:xapMM='http://ns.adobe.com/xap/1.0/mm/' xapMM:DocumentID='3e2370bc-4071-11eb-0000-0d90648fa894'/> -<rdf:Description rdf:about='3e2370bc-4071-11eb-0000-0d90648fa894' xmlns:dc='http://purl.org/dc/elements/1.1/' dc:format='application/pdf'><dc:title><rdf:Alt><rdf:li xml:lang='x-default'>Untitled</rdf:li></rdf:Alt></dc:title></rdf:Description> +<rdf:Description rdf:about='uuid:075b48f7-381b-11ee-0000-224f381b10d2' xmlns:pdf='http://ns.adobe.com/pdf/1.3/' pdf:Producer='GPL Ghostscript 9.05'/> +<rdf:Description rdf:about='uuid:075b48f7-381b-11ee-0000-224f381b10d2' xmlns:xmp='http://ns.adobe.com/xap/1.0/'><xmp:ModifyDate>2013-08-08T09:45:22+02:00</xmp:ModifyDate> +<xmp:CreateDate>2013-08-08T09:45:22+02:00</xmp:CreateDate> +<xmp:CreatorTool>groff version 1.22.2</xmp:CreatorTool></rdf:Description> +<rdf:Description rdf:about='uuid:075b48f7-381b-11ee-0000-224f381b10d2' xmlns:xapMM='http://ns.adobe.com/xap/1.0/mm/' xapMM:DocumentID='uuid:075b48f7-381b-11ee-0000-224f381b10d2'/> +<rdf:Description rdf:about='uuid:075b48f7-381b-11ee-0000-224f381b10d2' xmlns:dc='http://purl.org/dc/elements/1.1/' dc:format='application/pdf'><dc:title><rdf:Alt><rdf:li xml:lang='x-default'>Untitled</rdf:li></rdf:Alt></dc:title></rdf:Description> </rdf:RDF> </x:xmpmeta> @@ -78,30 +76,30 @@ endobj endstream endobj 2 0 obj -<</Producer(GPL Ghostscript 8.71) -/CreationDate(D:20101215150747+01'00') -/ModDate(D:20101215150747+01'00') -/Creator(groff version 1.20.1)>>endobj +<</Producer(GPL Ghostscript 9.05) +/CreationDate(D:20130808094522+02'00') +/ModDate(D:20130808094522+02'00') +/Creator(groff version 1.22.2)>>endobj xref 0 14 0000000000 65535 f -0000000870 00000 n -0000002653 00000 n -0000000811 00000 n -0000000651 00000 n +0000000869 00000 n +0000002677 00000 n +0000000810 00000 n +0000000650 00000 n 0000000015 00000 n -0000000632 00000 n -0000000935 00000 n -0000001189 00000 n -0000001124 00000 n -0000001056 00000 n -0000000976 00000 n -0000001006 00000 n -0000001255 00000 n +0000000631 00000 n +0000000934 00000 n +0000001188 00000 n +0000001123 00000 n +0000001055 00000 n +0000000975 00000 n +0000001005 00000 n +0000001254 00000 n trailer << /Size 14 /Root 1 0 R /Info 2 0 R -/ID [<D43E949F03B6608F551A21E4ED709EA6><D43E949F03B6608F551A21E4ED709EA6>] +/ID [(\n>Bte\216\016U%\t=b.w\370\357)(\n>Bte\216\016U%\t=b.w\370\357)] >> startxref -2807 +2831 %%EOF diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 index 8ab4234bc..ce575d7ac 100644 --- a/docs/libcurl/curl_strequal.3 +++ b/docs/libcurl/curl_strequal.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_strequal 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_strequal, curl_strnequal - case insensitive string comparisons diff --git a/docs/libcurl/curl_strequal.html b/docs/libcurl/curl_strequal.html index eefdf10a2..c4f6b550e 100644 --- a/docs/libcurl/curl_strequal.html +++ b/docs/libcurl/curl_strequal.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_strequal man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/curl_strequal.pdf b/docs/libcurl/curl_strequal.pdf Binary files differindex 89827bbea..e9ed9eb02 100644 --- a/docs/libcurl/curl_strequal.pdf +++ b/docs/libcurl/curl_strequal.pdf diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index 9bb470f4e..2a24866d3 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_unescape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" .SH NAME curl_unescape - URL decodes the given string diff --git a/docs/libcurl/curl_unescape.html b/docs/libcurl/curl_unescape.html index 5e34606ef..b8e434c01 100644 --- a/docs/libcurl/curl_unescape.html +++ b/docs/libcurl/curl_unescape.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_unescape man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -54,6 +56,6 @@ p.roffit { <p class="level0">You must curl_free() the returned string when you're done with it. <a name="AVAILABILITY"></a><h2 class="nroffsh">AVAILABILITY</h2> <p class="level0">Since 7.15.4, <a class="emphasis" href="./curl_easy_unescape.html">curl_easy_unescape(3)</a> should be used. This function will be removed in a future release. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> <p class="level0">A pointer to a zero terminated string or NULL if it failed. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> -<p class="level0"><span Class="emphasis">curl_easy_escape(3), curl_easy_unescape(3), curl_free(3), RFC 2396</span> <p class="roffit"> +<p class="level0"><span Class="emphasis">curl_easy_escape(3), curl_easy_unescape(3), curl_free(3), <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a></span> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/libcurl/curl_unescape.pdf b/docs/libcurl/curl_unescape.pdf Binary files differindex b1085c512..cbadf5e96 100644 --- a/docs/libcurl/curl_unescape.pdf +++ b/docs/libcurl/curl_unescape.pdf diff --git a/docs/libcurl/curl_version.3 b/docs/libcurl/curl_version.3 index 24793caeb..f66e38d14 100644 --- a/docs/libcurl/curl_version.3 +++ b/docs/libcurl/curl_version.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_version 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" .SH NAME curl_version - returns the libcurl version string @@ -13,6 +31,7 @@ curl_version - returns the libcurl version string Returns a human readable string with the version number of libcurl and some of its important components (like OpenSSL version). .SH RETURN VALUE -A pointer to a zero terminated string. +A pointer to a zero terminated string. The string resides in a statically +allocated buffer and must not be freed by the caller. .SH "SEE ALSO" .BR curl_version_info "(3)" diff --git a/docs/libcurl/curl_version.html b/docs/libcurl/curl_version.html index d2f1032a4..aca7ecca7 100644 --- a/docs/libcurl/curl_version.html +++ b/docs/libcurl/curl_version.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_version man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -49,7 +51,7 @@ p.roffit { <p class="level0"><span Class="bold">char *curl_version( );</span> <p class="level0"><a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> <p class="level0">Returns a human readable string with the version number of libcurl and some of its important components (like OpenSSL version). <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2> -<p class="level0">A pointer to a zero terminated string. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> +<p class="level0">A pointer to a zero terminated string. The string resides in a statically allocated buffer and must not be freed by the caller. <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> <p class="level0"><a class="manpage" href="./curl_version_info.html">curl_version_info (3)</a> <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/libcurl/curl_version.pdf b/docs/libcurl/curl_version.pdf Binary files differindex 0f058b097..d54b3d7bf 100644 --- a/docs/libcurl/curl_version.pdf +++ b/docs/libcurl/curl_version.pdf diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index 4481830a3..ccb202834 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -128,6 +128,11 @@ the app having to pass them on. (Added in 7.13.2) .IP CURL_VERSION_CONV libcurl was built with support for character conversions, as provided by the CURLOPT_CONV_* callbacks. (Added in 7.15.4) +.IP CURL_VERSION_TLSAUTH_SRP +libcurl was built with support for TLS-SRP. (Added in 7.21.4) +.IP CURL_VERSION_NTLM_WB +libcurl was built with support for NTLM delegation to a winbind helper. +(Added in 7.22.0) .RE \fIssl_version\fP is an ASCII string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. diff --git a/docs/libcurl/curl_version_info.html b/docs/libcurl/curl_version_info.html index b6602bf2f..6da3aaa7b 100644 --- a/docs/libcurl/curl_version_info.html +++ b/docs/libcurl/curl_version_info.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>curl_version_info man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -101,7 +103,7 @@ p.roffit { <p class="level0"><a name="CURLVERSIONASYNCHDNS"></a><span class="nroffip">CURL_VERSION_ASYNCHDNS</span> <p class="level1">libcurl was built with support for asynchronous name lookups, which allows more exact timeouts (even on Windows) and less blocking when using the multi interface. (added in 7.10.7) <p class="level0"><a name="CURLVERSIONSPNEGO"></a><span class="nroffip">CURL_VERSION_SPNEGO</span> -<p class="level1">libcurl was built with support for SPNEGO authentication (Simple and Protected GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8) +<p class="level1">libcurl was built with support for SPNEGO authentication (Simple and Protected GSS-API Negotiation Mechanism, defined in <a href="http://www.ietf.org/rfc/rfc2478.txt">RFC 2478</a>.) (added in 7.10.8) <p class="level0"><a name="CURLVERSIONLARGEFILE"></a><span class="nroffip">CURL_VERSION_LARGEFILE</span> <p class="level1">libcurl was built with support for large files. (Added in 7.11.1) <p class="level0"><a name="CURLVERSIONIDN"></a><span class="nroffip">CURL_VERSION_IDN</span> @@ -110,6 +112,10 @@ p.roffit { <p class="level1">libcurl was built with support for SSPI. This is only available on Windows and makes libcurl use Windows-provided functions for NTLM authentication. It also allows libcurl to use the current user and the current user's password without the app having to pass them on. (Added in 7.13.2) <p class="level0"><a name="CURLVERSIONCONV"></a><span class="nroffip">CURL_VERSION_CONV</span> <p class="level1">libcurl was built with support for character conversions, as provided by the CURLOPT_CONV_* callbacks. (Added in 7.15.4) +<p class="level0"><a name="CURLVERSIONTLSAUTHSRP"></a><span class="nroffip">CURL_VERSION_TLSAUTH_SRP</span> +<p class="level1">libcurl was built with support for TLS-SRP. (Added in 7.21.4) +<p class="level0"><a name="CURLVERSIONNTLMWB"></a><span class="nroffip">CURL_VERSION_NTLM_WB</span> +<p class="level1">libcurl was built with support for NTLM delegation to a winbind helper. (Added in 7.22.0) <p class="level0"><span Class="emphasis">ssl_version</span> is an ASCII string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. <p class="level0"><span Class="emphasis">ssl_version_num</span> is the numerical OpenSSL version value as defined by the OpenSSL project. If libcurl has no SSL support, this is 0. <p class="level0"><span Class="emphasis">libz_version</span> is an ASCII string (there is no numerical version). If libcurl has no libz support, this is NULL. diff --git a/docs/libcurl/curl_version_info.pdf b/docs/libcurl/curl_version_info.pdf Binary files differindex 0ade732b3..3ca916bfb 100644 --- a/docs/libcurl/curl_version_info.pdf +++ b/docs/libcurl/curl_version_info.pdf diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index 287a2dd69..ca773135b 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -21,40 +21,49 @@ <H2>Library Functions (A-Z)</H2> <a href="curl_easy_cleanup.html">curl_easy_cleanup</A> <br><a href="curl_easy_duphandle.html">curl_easy_duphandle</A> +<br><a href="curl_easy_escape.html">curl_easy_escape</A> <br><a href="curl_easy_getinfo.html">curl_easy_getinfo</A> <br><a href="curl_easy_init.html">curl_easy_init</A> +<br><a href="curl_easy_pause.html">curl_easy_pause</A> <br><a href="curl_easy_perform.html">curl_easy_perform</A> <br><a href="curl_easy_recv.html">curl_easy_recv</A> <br><a href="curl_easy_reset.html">curl_easy_reset</A> <br><a href="curl_easy_send.html">curl_easy_send</A> <br><a href="curl_easy_setopt.html">curl_easy_setopt</A> <br><a href="curl_easy_strerror.html">curl_easy_strerror</A> -<br><a href="curl_escape.html">curl_escape</A> +<br><a href="curl_easy_unescape.html">curl_easy_unescape</A> +<br><a href="curl_escape.html">curl_escape</A> (deprecated) <br><a href="curl_formadd.html">curl_formadd</A> <br><a href="curl_formfree.html">curl_formfree</A> +<br><a href="curl_formget.html">curl_formget</A> <br><a href="curl_free.html">curl_free</A> <br><a href="curl_getdate.html">curl_getdate</A> -<br><a href="curl_getenv.html">curl_getenv</A> +<br><a href="curl_getenv.html">curl_getenv</A> (deprecated) <br><a href="curl_global_cleanup.html">curl_global_cleanup</A> <br><a href="curl_global_init.html">curl_global_init</A> <br><a href="curl_global_init_mem.html">curl_global_init_mem</A> -<br><a href="curl_mprintf.html">curl_mprintf</A> +<br><a href="curl_mprintf.html">curl_mprintf</A> (deprecated) <br><a href="curl_multi_add_handle.html">curl_multi_add_handle</a> +<br><a href="curl_multi_assign.html">curl_multi_assign</a> <br><a href="curl_multi_cleanup.html">curl_multi_cleanup</a> <br><a href="curl_multi_fdset.html">curl_multi_fdset</a> <br><a href="curl_multi_info_read.html">curl_multi_info_read</a> <br><a href="curl_multi_init.html">curl_multi_init</a> <br><a href="curl_multi_perform.html">curl_multi_perform</a> <br><a href="curl_multi_remove_handle.html">curl_multi_remove_handle</a> -<br><a href="curl_multi_strerror.html">curl_multi_strerror.html</a> +<br><a href="curl_multi_setopt.html">curl_multi_setopt</a> +<br><a href="curl_multi_socket.html">curl_multi_socket</a> (deprecated) +<br><a href="curl_multi_socket_action.html">curl_multi_socket_action</a> +<br><a href="curl_multi_strerror.html">curl_multi_strerror</a> +<br><a href="curl_multi_timeout.html">curl_multi_timeout</a> (deprecated) <br><a href="curl_share_cleanup.html">curl_share_cleanup</A> <br><a href="curl_share_init.html">curl_share_init</A> <br><a href="curl_share_setopt.html">curl_share_setopt</A> -<br><a href="curl_share_strerror.html">curl_share_strerror.html</a> +<br><a href="curl_share_strerror.html">curl_share_strerror</a> <br><a href="curl_slist_append.html">curl_slist_append</A> <br><a href="curl_slist_free_all.html">curl_slist_free_all</A> <br><a href="curl_strequal.html">curl_strequal and curl_strnequal</A> -<br><a href="curl_unescape.html">curl_unescape</A> +<br><a href="curl_unescape.html">curl_unescape</A> (deprecated) <br><a href="curl_version.html">curl_version</A> <br><a href="curl_version_info.html">curl_version_info</A> diff --git a/docs/libcurl/libcurl-easy.3 b/docs/libcurl/libcurl-easy.3 index 803e54244..698a4ce72 100644 --- a/docs/libcurl/libcurl-easy.3 +++ b/docs/libcurl/libcurl-easy.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH libcurl 3 "12 Aug 2003" "libcurl 7.10.7" "libcurl easy interface" .SH NAME libcurl-easy \- easy interface overview diff --git a/docs/libcurl/libcurl-easy.html b/docs/libcurl/libcurl-easy.html index 8c9f5e51c..e10411fb3 100644 --- a/docs/libcurl/libcurl-easy.html +++ b/docs/libcurl/libcurl-easy.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>libcurl man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/libcurl-easy.pdf b/docs/libcurl/libcurl-easy.pdf Binary files differindex 9a2b9ddb7..01bf41d15 100644 --- a/docs/libcurl/libcurl-easy.pdf +++ b/docs/libcurl/libcurl-easy.pdf diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index c3c854e90..7b6823735 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -44,9 +44,15 @@ can be a misspelled protocol string or just a protocol libcurl has no code for. .IP "CURLE_FAILED_INIT (2)" Very early initialization code failed. This is likely to be an internal error -or problem. +or problem, or a resource problem where something fundamental couldn't get +done at init time. .IP "CURLE_URL_MALFORMAT (3)" The URL was not properly formatted. +.IP "CURLE_NOT_BUILT_IN (4)" +A requested feature, protocol or option was not found built-in in this libcurl +due to a build-time decision. This means that a feature or option was not +enabled or explicitly disabled when libcurl was built and in order to get it +to function you have to get a rebuilt libcurl. .IP "CURLE_COULDNT_RESOLVE_PROXY (5)" Couldn't resolve proxy. The given proxy host could not be resolved. .IP "CURLE_COULDNT_RESOLVE_HOST (6)" @@ -60,20 +66,21 @@ remote server is probably not an OK FTP server. .IP "CURLE_REMOTE_ACCESS_DENIED (9)" We were denied access to the resource given in the URL. For FTP, this occurs while trying to change to the remote directory. +.IP "CURLE_FTP_ACCEPT_FAILED (10)" +While waiting for the server to connect back when an active FTP session is +used, an error code was sent over the control connection or similar. .IP "CURLE_FTP_WEIRD_PASS_REPLY (11)" After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. +.IP "CURLE_FTP_ACCEPT_TIMEOUT (12)" +During an active FTP session while waiting for the server to connect, the +\fICURLOPT_ACCEPTTIMOUT_MS\fP (or the internal default) timeout expired. .IP "CURLE_FTP_WEIRD_PASV_REPLY (13)" libcurl failed to get a sensible result back from the server as a response to either a PASV or a EPSV command. The server is flawed. .IP "CURLE_FTP_WEIRD_227_FORMAT (14)" FTP servers return a 227-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back. -.IP "CURLE_FTP_PRET_FAILED (84)" -The FTP server does not understand the PRET command at all or does not support -the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST\fP, a -custom LIST command will be sent with PRET CMD before PASV as well. (Added in -7.20.0) .IP "CURLE_FTP_CANT_GET_HOST (15)" An internal failure to lookup the host used for the new connection. .IP "CURLE_FTP_COULDNT_SET_TYPE (17)" @@ -145,9 +152,11 @@ CURLOPT_INTERFACE. .IP "CURLE_TOO_MANY_REDIRECTS (47)" Too many redirects. When following redirects, libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS. -.IP "CURLE_UNKNOWN_TELNET_OPTION (48)" -An option set with CURLOPT_TELNETOPTIONS was not recognized/known. Refer to -the appropriate documentation. +.IP "CURLE_UNKNOWN_OPTION (48)" +An option passed to libcurl is not recognized/known. Refer to the appropriate +documentation. This is most likely a problem in the program that uses +libcurl. The error buffer might contain more specific information about which +exact option it concerns. .IP "CURLE_TELNET_OPTION_SYNTAX (49)" A telnet option string was Illegally formatted. .IP "CURLE_PEER_FAILED_VERIFICATION (51)" @@ -219,7 +228,10 @@ Failed to load CRL file (Added in 7.19.0) .IP "CURLE_SSL_ISSUER_ERROR (83)" Issuer check failed (Added in 7.19.0) .IP "CURLE_FTP_PRET_FAILED (84)" -PRET command failed +The FTP server does not understand the PRET command at all or does not support +the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST\fP, a +custom LIST command will be sent with PRET CMD before PASV as well. (Added in +7.20.0) .IP "CURLE_RTSP_CSEQ_ERROR (85)" Mismatch of RTSP CSeq numbers. .IP "CURLE_RTSP_SESSION_ERROR (86)" @@ -228,6 +240,9 @@ Mismatch of RTSP Session Identifiers. Unable to parse FTP file list (during FTP wildcard downloading). .IP "CURLE_CHUNK_FAILED (88)" Chunk callback reported error. +.IP "CURLE_NO_CONNECTION_AVAILABLE (89)" +(For internal use only, will never be returned by libcurl) No connection +available, the session will be queued. (added in 7.30.0) .IP "CURLE_OBSOLETE*" These error codes will never be returned. They were used in an old libcurl version and are currently unused. @@ -236,7 +251,10 @@ This is the generic return code used by functions in the libcurl multi interface. Also consider \fIcurl_multi_strerror(3)\fP. .IP "CURLM_CALL_MULTI_PERFORM (-1)" This is not really an error. It means you should call -\fIcurl_multi_perform(3)\fP again without doing select() or similar in between. +\fIcurl_multi_perform(3)\fP again without doing select() or similar in +between. Before version 7.20.0 this could be returned by +\fIcurl_multi_perform(3)\fP, but in later versions this return code is never +used. .IP "CURLM_OK (0)" Things are fine. .IP "CURLM_BAD_HANDLE (1)" @@ -269,3 +287,6 @@ An invalid share object was passed to the function. .IP "CURLSHE_NOMEM (4)" Not enough memory was available. (Added in 7.12.0) +.IP "CURLSHE_NOT_BUILT_IN (5)" +The requested sharing could not be done because the library you use don't have +that particular feature enabled. (Added in 7.23.0) diff --git a/docs/libcurl/libcurl-errors.html b/docs/libcurl/libcurl-errors.html index 0a2cf7081..194b15002 100644 --- a/docs/libcurl/libcurl-errors.html +++ b/docs/libcurl/libcurl-errors.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>libcurl-errors man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -53,9 +55,11 @@ p.roffit { <p class="level0"><a name="CURLEUNSUPPORTEDPROTOCOL"></a><span class="nroffip">CURLE_UNSUPPORTED_PROTOCOL (1)</span> <p class="level1">The URL you passed to libcurl used a protocol that this libcurl does not support. The support might be a compile-time option that you didn't use, it can be a misspelled protocol string or just a protocol libcurl has no code for. <p class="level0"><a name="CURLEFAILEDINIT"></a><span class="nroffip">CURLE_FAILED_INIT (2)</span> -<p class="level1">Very early initialization code failed. This is likely to be an internal error or problem. +<p class="level1">Very early initialization code failed. This is likely to be an internal error or problem, or a resource problem where something fundamental couldn't get done at init time. <p class="level0"><a name="CURLEURLMALFORMAT"></a><span class="nroffip">CURLE_URL_MALFORMAT (3)</span> <p class="level1">The URL was not properly formatted. +<p class="level0"><a name="CURLENOTBUILTIN"></a><span class="nroffip">CURLE_NOT_BUILT_IN (4)</span> +<p class="level1">A requested feature, protocol or option was not found built-in in this libcurl due to a build-time decision. This means that a feature or option was not enabled or explicitly disabled when libcurl was built and in order to get it to function you have to get a rebuilt libcurl. <p class="level0"><a name="CURLECOULDNTRESOLVEPROXY"></a><span class="nroffip">CURLE_COULDNT_RESOLVE_PROXY (5)</span> <p class="level1">Couldn't resolve proxy. The given proxy host could not be resolved. <p class="level0"><a name="CURLECOULDNTRESOLVEHOST"></a><span class="nroffip">CURLE_COULDNT_RESOLVE_HOST (6)</span> @@ -66,14 +70,16 @@ p.roffit { <p class="level1">After connecting to a FTP server, libcurl expects to get a certain reply back. This error code implies that it got a strange or bad reply. The given remote server is probably not an OK FTP server. <p class="level0"><a name="CURLEREMOTEACCESSDENIED"></a><span class="nroffip">CURLE_REMOTE_ACCESS_DENIED (9)</span> <p class="level1">We were denied access to the resource given in the URL. For FTP, this occurs while trying to change to the remote directory. +<p class="level0"><a name="CURLEFTPACCEPTFAILED"></a><span class="nroffip">CURLE_FTP_ACCEPT_FAILED (10)</span> +<p class="level1">While waiting for the server to connect back when an active FTP session is used, an error code was sent over the control connection or similar. <p class="level0"><a name="CURLEFTPWEIRDPASSREPLY"></a><span class="nroffip">CURLE_FTP_WEIRD_PASS_REPLY (11)</span> <p class="level1">After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. +<p class="level0"><a name="CURLEFTPACCEPTTIMEOUT"></a><span class="nroffip">CURLE_FTP_ACCEPT_TIMEOUT (12)</span> +<p class="level1">During an active FTP session while waiting for the server to connect, the <span Class="emphasis">CURLOPT_ACCEPTTIMOUT_MS</span> (or the internal default) timeout expired. <p class="level0"><a name="CURLEFTPWEIRDPASVREPLY"></a><span class="nroffip">CURLE_FTP_WEIRD_PASV_REPLY (13)</span> <p class="level1">libcurl failed to get a sensible result back from the server as a response to either a PASV or a EPSV command. The server is flawed. <p class="level0"><a name="CURLEFTPWEIRD227FORMAT"></a><span class="nroffip">CURLE_FTP_WEIRD_227_FORMAT (14)</span> <p class="level1">FTP servers return a 227-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back. -<p class="level0"><a name="CURLEFTPPRETFAILED"></a><span class="nroffip">CURLE_FTP_PRET_FAILED (84)</span> -<p class="level1">The FTP server does not understand the PRET command at all or does not support the given argument. Be careful when using <span Class="emphasis">CURLOPT_CUSTOMREQUEST</span>, a custom LIST command will be sent with PRET CMD before PASV as well. (Added in 7.20.0) <p class="level0"><a name="CURLEFTPCANTGETHOST"></a><span class="nroffip">CURLE_FTP_CANT_GET_HOST (15)</span> <p class="level1">An internal failure to lookup the host used for the new connection. <p class="level0"><a name="CURLEFTPCOULDNTSETTYPE"></a><span class="nroffip">CURLE_FTP_COULDNT_SET_TYPE (17)</span> @@ -124,8 +130,8 @@ p.roffit { <p class="level1">Interface error. A specified outgoing interface could not be used. Set which interface to use for outgoing connections' source IP address with CURLOPT_INTERFACE. <p class="level0"><a name="CURLETOOMANYREDIRECTS"></a><span class="nroffip">CURLE_TOO_MANY_REDIRECTS (47)</span> <p class="level1">Too many redirects. When following redirects, libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS. -<p class="level0"><a name="CURLEUNKNOWNTELNETOPTION"></a><span class="nroffip">CURLE_UNKNOWN_TELNET_OPTION (48)</span> -<p class="level1">An option set with CURLOPT_TELNETOPTIONS was not recognized/known. Refer to the appropriate documentation. +<p class="level0"><a name="CURLEUNKNOWNOPTION"></a><span class="nroffip">CURLE_UNKNOWN_OPTION (48)</span> +<p class="level1">An option passed to libcurl is not recognized/known. Refer to the appropriate documentation. This is most likely a problem in the program that uses libcurl. The error buffer might contain more specific information about which exact option it concerns. <p class="level0"><a name="CURLETELNETOPTIONSYNTAX"></a><span class="nroffip">CURLE_TELNET_OPTION_SYNTAX (49)</span> <p class="level1">A telnet option string was Illegally formatted. <p class="level0"><a name="CURLEPEERFAILEDVERIFICATION"></a><span class="nroffip">CURLE_PEER_FAILED_VERIFICATION (51)</span> @@ -193,7 +199,7 @@ p.roffit { <p class="level0"><a name="CURLESSLISSUERERROR"></a><span class="nroffip">CURLE_SSL_ISSUER_ERROR (83)</span> <p class="level1">Issuer check failed (Added in 7.19.0) <p class="level0"><a name="CURLEFTPPRETFAILED"></a><span class="nroffip">CURLE_FTP_PRET_FAILED (84)</span> -<p class="level1">PRET command failed +<p class="level1">The FTP server does not understand the PRET command at all or does not support the given argument. Be careful when using <span Class="emphasis">CURLOPT_CUSTOMREQUEST</span>, a custom LIST command will be sent with PRET CMD before PASV as well. (Added in 7.20.0) <p class="level0"><a name="CURLERTSPCSEQERROR"></a><span class="nroffip">CURLE_RTSP_CSEQ_ERROR (85)</span> <p class="level1">Mismatch of RTSP CSeq numbers. <p class="level0"><a name="CURLERTSPSESSIONERROR"></a><span class="nroffip">CURLE_RTSP_SESSION_ERROR (86)</span> @@ -202,11 +208,13 @@ p.roffit { <p class="level1">Unable to parse FTP file list (during FTP wildcard downloading). <p class="level0"><a name="CURLECHUNKFAILED"></a><span class="nroffip">CURLE_CHUNK_FAILED (88)</span> <p class="level1">Chunk callback reported error. +<p class="level0"><a name="CURLENOCONNECTIONAVAILABLE"></a><span class="nroffip">CURLE_NO_CONNECTION_AVAILABLE (89)</span> +<p class="level1">(For internal use only, will never be returned by libcurl) No connection available, the session will be queued. (added in 7.30.0) <p class="level0"><a name="CURLEOBSOLETE"></a><span class="nroffip">CURLE_OBSOLETE*</span> <p class="level1">These error codes will never be returned. They were used in an old libcurl version and are currently unused. <a name="CURLMcode"></a><h2 class="nroffsh">CURLMcode</h2> <p class="level0">This is the generic return code used by functions in the libcurl multi interface. Also consider <a class="emphasis" href="./curl_multi_strerror.html">curl_multi_strerror(3)</a>. <p class="level0"><a name="CURLMCALLMULTIPERFORM"></a><span class="nroffip">CURLM_CALL_MULTI_PERFORM (-1)</span> -<p class="level1">This is not really an error. It means you should call <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> again without doing select() or similar in between. +<p class="level1">This is not really an error. It means you should call <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> again without doing select() or similar in between. Before version 7.20.0 this could be returned by <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>, but in later versions this return code is never used. <p class="level0"><a name="CURLMOK"></a><span class="nroffip">CURLM_OK (0)</span> <p class="level1">Things are fine. <p class="level0"><a name="CURLMBADHANDLE"></a><span class="nroffip">CURLM_BAD_HANDLE (1)</span> @@ -231,6 +239,8 @@ p.roffit { <p class="level0"><a name="CURLSHEINVALID"></a><span class="nroffip">CURLSHE_INVALID (3)</span> <p class="level1">An invalid share object was passed to the function. <p class="level0"><a name="CURLSHENOMEM"></a><span class="nroffip">CURLSHE_NOMEM (4)</span> -<p class="level1">Not enough memory was available. (Added in 7.12.0) <p class="roffit"> +<p class="level1">Not enough memory was available. (Added in 7.12.0) +<p class="level0"><a name="CURLSHENOTBUILTIN"></a><span class="nroffip">CURLSHE_NOT_BUILT_IN (5)</span> +<p class="level1">The requested sharing could not be done because the library you use don't have that particular feature enabled. (Added in 7.23.0) <p class="roffit"> This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. </body></html> diff --git a/docs/libcurl/libcurl-errors.pdf b/docs/libcurl/libcurl-errors.pdf Binary files differindex 0566c3673..42c116227 100644 --- a/docs/libcurl/libcurl-errors.pdf +++ b/docs/libcurl/libcurl-errors.pdf diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index d84bafcad..2af029961 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -82,14 +82,6 @@ might need attention. This also makes it very easy for your program to wait for input on your own private file descriptors at the same time or perhaps timeout every now and then, should you want that. -A little note here about the return codes from the multi functions, and -especially the \fIcurl_multi_perform(3)\fP: if you receive -\fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you should call -\fIcurl_multi_perform(3)\fP again, before you select() on more actions. You -don't have to do it immediately, but the return code means that libcurl may -have more data available to return or that there may be more data to send off -before it is "satisfied". - \fIcurl_multi_perform(3)\fP stores the number of still running transfers in one of its input arguments, and by reading that you can figure out when all the transfers in the multi handles are done. 'done' does not mean @@ -118,23 +110,40 @@ If you want to re-use an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re-add it again (possibly after having altered some options at your own choice). .SH "MULTI_SOCKET" -Since 7.16.0, the \fIcurl_multi_socket_action(3)\fP function offers a way for -applications to not only avoid being forced to use select(), but it also -offers a much more high-performance API that will make a significant -difference for applications using large numbers of simultaneous connections. - -\fIcurl_multi_socket_action(3)\fP is then used -instead of \fIcurl_multi_perform(3)\fP. +\fIcurl_multi_socket_action(3)\fP function offers a way for applications to +not only avoid being forced to use select(), but it also offers a much more +high-performance API that will make a significant difference for applications +using large numbers of simultaneous connections. + +\fIcurl_multi_socket_action(3)\fP is then used instead of +\fIcurl_multi_perform(3)\fP. + +When using this API, you add easy handles to the multi handle just as with the +normal multi interface. Then you also set two callbacks with the +CURLMOPT_SOCKETFUNCTION and CURLMOPT_TIMERFUNCTION options to +\fIcurl_multi_setopt(3)\fP. + +The API is then designed to inform your application about which sockets +libcurl is currently using and for what activities (read and/or write) on +those sockets your application is expected to wait for. + +Your application must then make sure to receive all sockets informed about in +the CURLMOPT_SOCKETFUNCTION callback and make sure it reacts on the given +activity on them. When a socket has the given activity, you call +\fIcurl_multi_socket_action(3)\fP specifying which socket and action there +are. + +The CURLMOPT_TIMERFUNCTION callback is called to set a timeout. When that +timeout expires, your application should call the +\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout. .SH "BLOCKING" A few areas in the code are still using blocking code, even when used from the multi interface. While we certainly want and intend for these to get fixed in the future, you should be aware of the following current restrictions: .nf - - Name resolves on non-windows unless c-ares is used - - GnuTLS SSL connections + - Name resolves unless the c-ares or threaded-resolver backends are used - NSS SSL connections - - Active FTP connections - HTTP proxy CONNECT operations - SOCKS proxy handshakes - file:// transfers diff --git a/docs/libcurl/libcurl-multi.html b/docs/libcurl/libcurl-multi.html index 70601d1b3..c43061675 100644 --- a/docs/libcurl/libcurl-multi.html +++ b/docs/libcurl/libcurl-multi.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>libcurl-multi man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -57,20 +59,21 @@ p.roffit { <p class="level0">Should you change your mind, the easy handle is again removed from the multi stack using <a class="emphasis" href="./curl_multi_remove_handle.html">curl_multi_remove_handle(3)</a>. Once removed from the multi handle, you can again use other easy interface functions like <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> on the handle or whatever you think is necessary. <p class="level0">Adding the easy handle to the multi handle does not start the transfer. Remember that one of the main ideas with this interface is to let your application drive. You drive the transfers by invoking <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>. libcurl will then transfer data if there is anything available to transfer. It'll use the callbacks and everything else you have setup in the individual easy handles. It'll transfer data on all current transfers in the multi stack that are ready to transfer anything. It may be all, it may be none. <p class="level0">Your application can acquire knowledge from libcurl when it would like to get invoked to transfer data, so that you don't have to busy-loop and call that <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> like crazy. <a class="emphasis" href="./curl_multi_fdset.html">curl_multi_fdset(3)</a> offers an interface using which you can extract fd_sets from libcurl to use in select() or poll() calls in order to get to know when the transfers in the multi stack might need attention. This also makes it very easy for your program to wait for input on your own private file descriptors at the same time or perhaps timeout every now and then, should you want that. -<p class="level0">A little note here about the return codes from the multi functions, and especially the <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>: if you receive <span Class="emphasis">CURLM_CALL_MULTI_PERFORM</span>, this basically means that you should call <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> again, before you select() on more actions. You don't have to do it immediately, but the return code means that libcurl may have more data available to return or that there may be more data to send off before it is "satisfied". <p class="level0"><a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> stores the number of still running transfers in one of its input arguments, and by reading that you can figure out when all the transfers in the multi handles are done. 'done' does not mean successful. One or more of the transfers may have failed. Tracking when this number changes, you know when one or more transfers are done. <p class="level0">To get information about completed transfers, to figure out success or not and similar, <a class="emphasis" href="./curl_multi_info_read.html">curl_multi_info_read(3)</a> should be called. It can return a message about a current or previous transfer. Repeated invokes of the function get more messages until the message queue is empty. The information you receive there includes an easy handle pointer which you may use to identify which easy handle the information regards. <p class="level0">When a single transfer is completed, the easy handle is still left added to the multi stack. You need to first remove the easy handle with <a class="emphasis" href="./curl_multi_remove_handle.html">curl_multi_remove_handle(3)</a> and then close it with <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a>, or possibly set new options to it and add it again with <a class="emphasis" href="./curl_multi_add_handle.html">curl_multi_add_handle(3)</a> to start another transfer. <p class="level0">When all transfers in the multi stack are done, cleanup the multi handle with <a class="emphasis" href="./curl_multi_cleanup.html">curl_multi_cleanup(3)</a>. Be careful and please note that you <span Class="bold">MUST</span> invoke separate <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a> calls on every single easy handle to clean them up properly. <p class="level0">If you want to re-use an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re-add it again (possibly after having altered some options at your own choice). <a name="MULTISOCKET"></a><h2 class="nroffsh">MULTI_SOCKET</h2> -<p class="level0">Since 7.16.0, the <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> function offers a way for applications to not only avoid being forced to use select(), but it also offers a much more high-performance API that will make a significant difference for applications using large numbers of simultaneous connections. -<p class="level0"><a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> is then used instead of <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>. <a name="BLOCKING"></a><h2 class="nroffsh">BLOCKING</h2> +<p class="level0"><a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> function offers a way for applications to not only avoid being forced to use select(), but it also offers a much more high-performance API that will make a significant difference for applications using large numbers of simultaneous connections. +<p class="level0"><a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> is then used instead of <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>. +<p class="level0">When using this API, you add easy handles to the multi handle just as with the normal multi interface. Then you also set two callbacks with the CURLMOPT_SOCKETFUNCTION and CURLMOPT_TIMERFUNCTION options to <a class="emphasis" href="./curl_multi_setopt.html">curl_multi_setopt(3)</a>. +<p class="level0">The API is then designed to inform your application about which sockets libcurl is currently using and for what activities (read and/or write) on those sockets your application is expected to wait for. +<p class="level0">Your application must then make sure to receive all sockets informed about in the CURLMOPT_SOCKETFUNCTION callback and make sure it reacts on the given activity on them. When a socket has the given activity, you call <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> specifying which socket and action there are. +<p class="level0">The CURLMOPT_TIMERFUNCTION callback is called to set a timeout. When that timeout expires, your application should call the <a class="emphasis" href="./curl_multi_socket_action.html">curl_multi_socket_action(3)</a> function saying it was due to a timeout. <a name="BLOCKING"></a><h2 class="nroffsh">BLOCKING</h2> <p class="level0">A few areas in the code are still using blocking code, even when used from the multi interface. While we certainly want and intend for these to get fixed in the future, you should be aware of the following current restrictions: <p class="level0"><pre> -<p class="level0"> - Name resolves on non-windows unless c-ares is used - - GnuTLS SSL connections +<p class="level0"> - Name resolves unless the c-ares or threaded-resolver backends are used - NSS SSL connections - - Active FTP connections - HTTP proxy CONNECT operations - SOCKS proxy handshakes - file:// transfers diff --git a/docs/libcurl/libcurl-multi.pdf b/docs/libcurl/libcurl-multi.pdf Binary files differindex a897e93ba..1ae952796 100644 --- a/docs/libcurl/libcurl-multi.pdf +++ b/docs/libcurl/libcurl-multi.pdf diff --git a/docs/libcurl/libcurl-share.3 b/docs/libcurl/libcurl-share.3 index 2e58c0ba6..1e6c1392f 100644 --- a/docs/libcurl/libcurl-share.3 +++ b/docs/libcurl/libcurl-share.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH libcurl-share 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl share interface" .SH NAME libcurl-share \- how to use the share interface @@ -16,15 +34,16 @@ The share interface was added to enable sharing of data between curl \&"handles". .SH "ONE SET OF DATA - MANY TRANSFERS" You can have multiple easy handles share data between them. Have them update -and use the \fBsame\fP cookie database or DNS cache! This way, each single -transfer will take advantage from data updates made by the other transfer(s). +and use the \fBsame\fP cookie database, DNS cache, TLS session cache! This +way, each single transfer will take advantage from data updates made by the +other transfer(s). The sharing interface, however, does not share active or +persistent connections between different easy handles. .SH "SHARE OBJECT" You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle for a newly created one. You tell the shared object what data you want it to share by using -\fIcurl_share_setopt(3)\fP. Currently you can only share DNS and/or COOKIE -data. +\fIcurl_share_setopt(3)\fP. Since you can use this share from multiple threads, and libcurl has no internal thread synchronization, you must provide mutex callbacks if you're diff --git a/docs/libcurl/libcurl-share.html b/docs/libcurl/libcurl-share.html index 6a66f3267..196853eb8 100644 --- a/docs/libcurl/libcurl-share.html +++ b/docs/libcurl/libcurl-share.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>libcurl-share man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -49,9 +51,9 @@ p.roffit { <p class="level0">All functions in the share interface are prefixed with curl_share. <p class="level0"><a name="OBJECTIVES"></a><h2 class="nroffsh">OBJECTIVES</h2> <p class="level0">The share interface was added to enable sharing of data between curl "handles". <a name="ONE"></a><h2 class="nroffsh">ONE SET OF DATA - MANY TRANSFERS</h2> -<p class="level0">You can have multiple easy handles share data between them. Have them update and use the <span Class="bold">same</span> cookie database or DNS cache! This way, each single transfer will take advantage from data updates made by the other transfer(s). <a name="SHARE"></a><h2 class="nroffsh">SHARE OBJECT</h2> +<p class="level0">You can have multiple easy handles share data between them. Have them update and use the <span Class="bold">same</span> cookie database, DNS cache, TLS session cache! This way, each single transfer will take advantage from data updates made by the other transfer(s). The sharing interface, however, does not share active or persistent connections between different easy handles. <a name="SHARE"></a><h2 class="nroffsh">SHARE OBJECT</h2> <p class="level0">You create a shared object with <a class="emphasis" href="./curl_share_init.html">curl_share_init(3)</a>. It returns a handle for a newly created one. -<p class="level0">You tell the shared object what data you want it to share by using <a class="emphasis" href="./curl_share_setopt.html">curl_share_setopt(3)</a>. Currently you can only share DNS and/or COOKIE data. +<p class="level0">You tell the shared object what data you want it to share by using <a class="emphasis" href="./curl_share_setopt.html">curl_share_setopt(3)</a>. <p class="level0">Since you can use this share from multiple threads, and libcurl has no internal thread synchronization, you must provide mutex callbacks if you're using this multi-threaded. You set lock and unlock functions with <a class="emphasis" href="./curl_share_setopt.html">curl_share_setopt(3)</a> too. <p class="level0">Then, you make an easy handle to use this share, you set the <span Class="emphasis">CURLOPT_SHARE</span> option with <a class="emphasis" href="./curl_easy_setopt.html">curl_easy_setopt(3)</a>, and pass in share handle. You can make any number of easy handles share the same share handle. <p class="level0">To make an easy handle stop using that particular share, you set <span Class="emphasis">CURLOPT_SHARE</span> to NULL for that easy handle. To make a handle stop sharing a particular data, you can <span Class="emphasis">CURLSHOPT_UNSHARE</span> it. diff --git a/docs/libcurl/libcurl-share.pdf b/docs/libcurl/libcurl-share.pdf Binary files differindex dc2b36576..0b8ebb978 100644 --- a/docs/libcurl/libcurl-share.pdf +++ b/docs/libcurl/libcurl-share.pdf diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 72f002963..eb44502f3 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -249,9 +249,11 @@ complication for you. Given simply the URL to a file, libcurl will take care of all the details needed to get the file moved from one machine to another. .SH "Multi-threading Issues" -The first basic rule is that you must \fBnever\fP share a libcurl handle (be -it easy or multi or whatever) between multiple threads. Only use one handle in -one thread at a time. +The first basic rule is that you must \fBnever\fP simultaneously share a +libcurl handle (be it easy or multi or whatever) between multiple +threads. Only use one handle in one thread at any time. You can pass the +handles around among threads, but you must never use a single handle from more +than one thread at any given time. libcurl is completely thread safe, except for two issues: signals and SSL/TLS handlers. Signals are used for timing out name resolves (during DNS lookup) - @@ -283,6 +285,14 @@ yassl Required actions unknown. +axTLS + + Required actions unknown. + +Secure Transport + + The engine is fully thread-safe, and no additional steps are required. + When using multiple threads you should set the CURLOPT_NOSIGNAL option to 1 for all handles. Everything will or might work fine except that timeouts are not honored during the DNS lookup - which you can work around by building @@ -811,10 +821,6 @@ This header is required by HTTP 1.1 and even many 1.0 servers and should be the name of the server we want to talk to. This includes the port number if anything but default. -.IP "Pragma" -\&"no-cache". Tells a possible proxy to not grab a copy from the cache but to -fetch a fresh one. - .IP "Accept" \&"*/*". @@ -1151,13 +1157,13 @@ and install a CURLOPT_OPENSOCKETFUNCTION callback function in which addresses are sanitized before use. .IP "Private Resources" -A user who can control the DNS server of a domain being passed in within -a URL can change the address of the host to a local, private address -which the libcurl application will then use. e.g. The innocuous URL -http://fuzzybunnies.example.com/ could actually resolve to the IP address -of a server behind a firewall, such as 127.0.0.1 or 10.1.2.3 -Apps can mitigate against this by setting a CURLOPT_OPENSOCKETFUNCTION -and checking the address before a connection. +A user who can control the DNS server of a domain being passed in within a URL +can change the address of the host to a local, private address which a +server-side libcurl-using application could then use. e.g. the innocuous URL +http://fuzzybunnies.example.com/ could actually resolve to the IP address of a +server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Apps can mitigate +against this by setting a CURLOPT_OPENSOCKETFUNCTION and checking the address +before a connection. All the malicious scenarios regarding redirected URLs apply just as well to non-redirected URLs, if the user is allowed to specify an arbitrary URL @@ -1172,6 +1178,19 @@ IP address and port number for a server local to the app running libcurl but behind a firewall. Apps can mitigate against this by using the CURLOPT_FTP_SKIP_PASV_IP option or CURLOPT_FTPPORT. +.IP "IPv6 Addresses" +libcurl will normally handle IPv6 addresses transparently and just as easily +as IPv4 addresses. That means that a sanitizing function that filters out +addressses like 127.0.0.1 isn't sufficient--the equivalent IPv6 addresses ::1, +::, 0:00::0:1, ::127.0.0.1 and ::ffff:7f00:1 supplied somehow by an attacker +would all bypass a naive filter and could allow access to undesired local +resources. IPv6 also has special address blocks like link-local and site-local +that generally shouldn't be accessed by a server-side libcurl-using +application. A poorly-configured firewall installed in a data center, +organization or server may also be configured to limit IPv4 connections but +leave IPv6 connections wide open. In some cases, the CURL_IPRESOLVE_V4 option +can be used to limit resolved addresses to IPv4 only and bypass these issues. + .IP Uploads When uploading, a redirect can cause a local (or remote) file to be overwritten. Apps must not allow any unsanitized URL to be passed in @@ -1244,7 +1263,7 @@ using the Content-disposition: header to generate a file name. An application could also use CURLINFO_EFFECTIVE_URL to generate a file name from a server-supplied redirect URL. Special care must be taken to sanitize such names to avoid the possibility of a malicious server supplying one like -"/etc/passwd", "\autoexec.bat" or even ".bashrc". +"/etc/passwd", "\\autoexec.bat", "prn:" or even ".bashrc". .IP "Server Certificates" A secure application should never use the CURLOPT_SSL_VERIFYPEER option to @@ -1257,10 +1276,15 @@ validated certificates is potentially as insecure as a plain HTTP connection. On a related issue, be aware that even in situations like when you have problems with libcurl and ask someone for help, everything you reveal in order to get best possible help might also impose certain security related -risks. Host names, user names, paths, operating system specifics, etc (not to +risks. Host names, user names, paths, operating system specifics, etc. (not to mention passwords of course) may in fact be used by intruders to gain additional information of a potential target. +Be sure to limit access to application logs if they could hold private or +security-related data. Besides the obvious candidates like user names and +passwords, things like URLs, cookies or even file names could also hold +sensitive data. + To avoid this problem, you must of course use your common sense. Often, you can just edit out the sensitive data or just search/replace your true information with faked data. @@ -1297,9 +1321,7 @@ ones at any time), you start the transfers by calling \fIcurl_multi_perform(3)\fP is asynchronous. It will only execute as little as possible and then return back control to your program. It is designed to never -block. If it returns CURLM_CALL_MULTI_PERFORM you better call it again soon, -as that is a signal that it still has local data to send or remote data to -receive. +block. The best usage of this interface is when you do a select() on all possible file descriptors or sockets to know when to call libcurl again. This also @@ -1335,9 +1357,21 @@ to figure out success on each individual transfer. [ seeding, passwords, keys, certificates, ENGINE, ca certs ] .SH "Sharing Data Between Easy Handles" +You can share some data between easy handles when the easy interface is used, +and some data is share automatically when you use the multi interface. + +When you add easy handles to a multi handle, these easy handles will +automatically share a lot of the data that otherwise would be kept on a +per-easy handle basis when the easy interface is used. - [ fill in ] +The DNS cache is shared between handles within a multi handle, making +subsequent name resolving faster, and the connection pool that is kept to +better allow persistent connections and connection re-use is also shared. If +you're using the easy interface, you can still share these between specific +easy handles by using the share interface, see \fIlibcurl-share(3)\fP. +Some things are never shared automatically, not within multi handles, like for +example cookies so the only way to share that is with the share interface. .SH "Footnotes" .IP "[1]" diff --git a/docs/libcurl/libcurl-tutorial.html b/docs/libcurl/libcurl-tutorial.html index 593d191d5..56a0205d1 100644 --- a/docs/libcurl/libcurl-tutorial.html +++ b/docs/libcurl/libcurl-tutorial.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>libcurl-tutorial man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; @@ -116,7 +118,7 @@ p.roffit { <p class="level0">If you then want to transfer another file, the handle is ready to be used again. Mind you, it is even preferred that you re-use an existing handle if you intend to make another transfer. libcurl will then attempt to re-use the previous connection. <p class="level0">For some protocols, downloading a file can involve a complicated process of logging in, setting the transfer mode, changing the current directory and finally transferring the file data. libcurl takes care of all that complication for you. Given simply the URL to a file, libcurl will take care of all the details needed to get the file moved from one machine to another. <p class="level0"><a name="Multi-threading"></a><h2 class="nroffsh">Multi-threading Issues</h2> -<p class="level0">The first basic rule is that you must <span Class="bold">never</span> share a libcurl handle (be it easy or multi or whatever) between multiple threads. Only use one handle in one thread at a time. +<p class="level0">The first basic rule is that you must <span Class="bold">never</span> simultaneously share a libcurl handle (be it easy or multi or whatever) between multiple threads. Only use one handle in one thread at any time. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time. <p class="level0">libcurl is completely thread safe, except for two issues: signals and SSL/TLS handlers. Signals are used for timing out name resolves (during DNS lookup) - when built without c-ares support and not on Windows. <p class="level0">If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are then of course using the underlying SSL library multi-threaded and those libs might have their own requirements on this issue. Basically, you need to provide one or two functions to allow it to function properly. For all details, see this: <p class="level0">OpenSSL @@ -129,6 +131,10 @@ p.roffit { <p class="level0"> Required actions unknown. <p class="level0">yassl <p class="level0"> Required actions unknown. +<p class="level0">axTLS +<p class="level0"> Required actions unknown. +<p class="level0">Secure Transport +<p class="level0"> The engine is fully thread-safe, and no additional steps are required. <p class="level0">When using multiple threads you should set the CURLOPT_NOSIGNAL option to 1 for all handles. Everything will or might work fine except that timeouts are not honored during the DNS lookup - which you can work around by building libcurl with c-ares support. c-ares is a library that provides asynchronous name resolves. On some platforms, libcurl simply will not function properly multi-threaded unless this option is set. <p class="level0">Also, note that CURLOPT_DNS_USE_GLOBAL_CACHE is not thread-safe. <p class="level0"><a name="When"></a><h2 class="nroffsh">When It Doesn't Work</h2> @@ -214,7 +220,7 @@ p.roffit { </pre> <p class="level0"> -<p class="level0">While the simple examples above cover the majority of all cases where HTTP POST operations are required, they don't do multi-part formposts. Multi-part formposts were introduced as a better way to post (possibly large) binary data and were first documented in the RFC1867 (updated in RFC2388). They're called multi-part because they're built by a chain of parts, each part being a single unit of data. Each part has its own name and contents. You can in fact create and post a multi-part formpost with the regular libcurl POST support described above, but that would require that you build a formpost yourself and provide to libcurl. To make that easier, libcurl provides <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a>. Using this function, you add parts to the form. When you're done adding parts, you post the whole form. +<p class="level0">While the simple examples above cover the majority of all cases where HTTP POST operations are required, they don't do multi-part formposts. Multi-part formposts were introduced as a better way to post (possibly large) binary data and were first documented in the <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> (updated in RFC2388). They're called multi-part because they're built by a chain of parts, each part being a single unit of data. Each part has its own name and contents. You can in fact create and post a multi-part formpost with the regular libcurl POST support described above, but that would require that you build a formpost yourself and provide to libcurl. To make that easier, libcurl provides <a class="emphasis" href="./curl_formadd.html">curl_formadd(3)</a>. Using this function, you add parts to the form. When you're done adding parts, you post the whole form. <p class="level0">The following example sets two simple text parts with plain textual contents, and then a file with binary contents and uploads the whole thing. <p class="level0"><pre> <p class="level0"> struct curl_httppost *post=NULL; @@ -349,9 +355,6 @@ p.roffit { <p class="level0"><a name="Host"></a><span class="nroffip">Host</span> <p class="level1">This header is required by HTTP 1.1 and even many 1.0 servers and should be the name of the server we want to talk to. This includes the port number if anything but default. <p class="level1"> -<p class="level0"><a name="Pragma"></a><span class="nroffip">Pragma</span> -<p class="level1">"no-cache". Tells a possible proxy to not grab a copy from the cache but to fetch a fresh one. -<p class="level1"> <p class="level0"><a name="Accept"></a><span class="nroffip">Accept</span> <p class="level1">"*/*". <p class="level1"> @@ -405,7 +408,7 @@ p.roffit { <p class="level0"><a name="FTP"></a><span class="nroffip">FTP Custom Commands</span> <p class="level1"> <p class="level1">Not all protocols are HTTP-like, and thus the above may not help you when you want to make, for example, your FTP transfers to behave differently. -<p class="level1">Sending custom commands to a FTP server means that you need to send the commands exactly as the FTP server expects them (RFC959 is a good guide here), and you can only use commands that work on the control-connection alone. All kinds of commands that require data interchange and thus need a data-connection must be left to libcurl's own judgement. Also be aware that libcurl will do its very best to change directory to the target directory before doing any transfer, so if you change directory (with CWD or similar) you might confuse libcurl and then it might not attempt to transfer the file in the correct remote directory. +<p class="level1">Sending custom commands to a FTP server means that you need to send the commands exactly as the FTP server expects them (<a href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</a> is a good guide here), and you can only use commands that work on the control-connection alone. All kinds of commands that require data interchange and thus need a data-connection must be left to libcurl's own judgement. Also be aware that libcurl will do its very best to change directory to the target directory before doing any transfer, so if you change directory (with CWD or similar) you might confuse libcurl and then it might not attempt to transfer the file in the correct remote directory. <p class="level1">A little example that deletes a given file before an operation: <p class="level1"><pre> <p class="level1"> headers = curl_slist_append(headers, "DELE file-to-remove"); @@ -477,10 +480,13 @@ p.roffit { <p class="level1">Apps can mitigate against this by disabling CURLOPT_FOLLOWLOCATION and handling redirects itself, sanitizing URLs as necessary. Alternately, an app could leave CURLOPT_FOLLOWLOCATION enabled but set CURLOPT_REDIR_PROTOCOLS and install a CURLOPT_OPENSOCKETFUNCTION callback function in which addresses are sanitized before use. <p class="level1"> <p class="level0"><a name="Private"></a><span class="nroffip">Private Resources</span> -<p class="level1">A user who can control the DNS server of a domain being passed in within a URL can change the address of the host to a local, private address which the libcurl application will then use. e.g. The innocuous URL <a href="http://fuzzybunnies.example.com/">http://fuzzybunnies.example.com/</a> could actually resolve to the IP address of a server behind a firewall, such as 127.0.0.1 or 10.1.2.3 Apps can mitigate against this by setting a CURLOPT_OPENSOCKETFUNCTION and checking the address before a connection. +<p class="level1">A user who can control the DNS server of a domain being passed in within a URL can change the address of the host to a local, private address which a server-side libcurl-using application could then use. e.g. the innocuous URL <a href="http://fuzzybunnies.example.com/">http://fuzzybunnies.example.com/</a> could actually resolve to the IP address of a server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Apps can mitigate against this by setting a CURLOPT_OPENSOCKETFUNCTION and checking the address before a connection. <p class="level1">All the malicious scenarios regarding redirected URLs apply just as well to non-redirected URLs, if the user is allowed to specify an arbitrary URL that could point to a private resource. For example, a web app providing a translation service might happily translate file://localhost/etc/passwd and display the result. Apps can mitigate against this with the CURLOPT_PROTOCOLS option as well as by similar mitigation techniques for redirections. <p class="level1">A malicious FTP server could in response to the PASV command return an IP address and port number for a server local to the app running libcurl but behind a firewall. Apps can mitigate against this by using the CURLOPT_FTP_SKIP_PASV_IP option or CURLOPT_FTPPORT. <p class="level1"> +<p class="level0"><a name="IPv6"></a><span class="nroffip">IPv6 Addresses</span> +<p class="level1">libcurl will normally handle IPv6 addresses transparently and just as easily as IPv4 addresses. That means that a sanitizing function that filters out addressses like 127.0.0.1 isn't sufficient--the equivalent IPv6 addresses ::1, ::, 0:00::0:1, ::127.0.0.1 and ::ffff:7f00:1 supplied somehow by an attacker would all bypass a naive filter and could allow access to undesired local resources. IPv6 also has special address blocks like link-local and site-local that generally shouldn't be accessed by a server-side libcurl-using application. A poorly-configured firewall installed in a data center, organization or server may also be configured to limit IPv4 connections but leave IPv6 connections wide open. In some cases, the CURL_IPRESOLVE_V4 option can be used to limit resolved addresses to IPv4 only and bypass these issues. +<p class="level1"> <p class="level0"><a name="Uploads"></a><span class="nroffip">Uploads</span> <p class="level1">When uploading, a redirect can cause a local (or remote) file to be overwritten. Apps must not allow any unsanitized URL to be passed in for uploads. Also, CURLOPT_FOLLOWLOCATION should not be used on uploads. Instead, the app should handle redirects itself, sanitizing each URL first. <p class="level1"> @@ -505,13 +511,14 @@ p.roffit { <p class="level1">User-supplied data must be sanitized when used in options like CURLOPT_USERAGENT, CURLOPT_HTTPHEADER, CURLOPT_POSTFIELDS and others that are used to generate structured data. Characters like embedded carriage returns or ampersands could allow the user to create additional headers or fields that could cause malicious transactions. <p class="level1"> <p class="level0"><a name="Server-supplied"></a><span class="nroffip">Server-supplied Names</span> -<p class="level1">A server can supply data which the application may, in some cases, use as a file name. The curl command-line tool does this with --remote-header-name, using the Content-disposition: header to generate a file name. An application could also use CURLINFO_EFFECTIVE_URL to generate a file name from a server-supplied redirect URL. Special care must be taken to sanitize such names to avoid the possibility of a malicious server supplying one like "/etc/passwd", "autoexec.bat" or even ".bashrc". +<p class="level1">A server can supply data which the application may, in some cases, use as a file name. The curl command-line tool does this with --remote-header-name, using the Content-disposition: header to generate a file name. An application could also use CURLINFO_EFFECTIVE_URL to generate a file name from a server-supplied redirect URL. Special care must be taken to sanitize such names to avoid the possibility of a malicious server supplying one like "/etc/passwd", "\autoexec.bat", "prn:" or even ".bashrc". <p class="level1"> <p class="level0"><a name="Server"></a><span class="nroffip">Server Certificates</span> <p class="level1">A secure application should never use the CURLOPT_SSL_VERIFYPEER option to disable certificate validation. There are numerous attacks that are enabled by apps that fail to properly validate server TLS/SSL certificates, thus enabling a malicious server to spoof a legitimate one. HTTPS without validated certificates is potentially as insecure as a plain HTTP connection. <p class="level1"> <p class="level0"><a name="Showing"></a><span class="nroffip">Showing What You Do</span> -<p class="level1">On a related issue, be aware that even in situations like when you have problems with libcurl and ask someone for help, everything you reveal in order to get best possible help might also impose certain security related risks. Host names, user names, paths, operating system specifics, etc (not to mention passwords of course) may in fact be used by intruders to gain additional information of a potential target. +<p class="level1">On a related issue, be aware that even in situations like when you have problems with libcurl and ask someone for help, everything you reveal in order to get best possible help might also impose certain security related risks. Host names, user names, paths, operating system specifics, etc. (not to mention passwords of course) may in fact be used by intruders to gain additional information of a potential target. +<p class="level1">Be sure to limit access to application logs if they could hold private or security-related data. Besides the obvious candidates like user names and passwords, things like URLs, cookies or even file names could also hold sensitive data. <p class="level1">To avoid this problem, you must of course use your common sense. Often, you can just edit out the sensitive data or just search/replace your true information with faked data. <p class="level1"><a name="Multiple"></a><h2 class="nroffsh">Multiple Transfers Using the multi Interface</h2> <p class="level0"> @@ -520,7 +527,7 @@ p.roffit { <p class="level0">To use this interface, you are better off if you first understand the basics of how to use the easy interface. The multi interface is simply a way to make multiple transfers at the same time by adding up multiple easy handles into a "multi stack". <p class="level0">You create the easy handles you want and you set all the options just like you have been told above, and then you create a multi handle with <a class="emphasis" href="./curl_multi_init.html">curl_multi_init(3)</a> and add all those easy handles to that multi handle with <a class="emphasis" href="./curl_multi_add_handle.html">curl_multi_add_handle(3)</a>. <p class="level0">When you've added the handles you have for the moment (you can still add new ones at any time), you start the transfers by calling <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>. -<p class="level0"><a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> is asynchronous. It will only execute as little as possible and then return back control to your program. It is designed to never block. If it returns CURLM_CALL_MULTI_PERFORM you better call it again soon, as that is a signal that it still has local data to send or remote data to receive. +<p class="level0"><a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> is asynchronous. It will only execute as little as possible and then return back control to your program. It is designed to never block. <p class="level0">The best usage of this interface is when you do a select() on all possible file descriptors or sockets to know when to call libcurl again. This also makes it easy for you to wait and respond to actions on your own application's sockets/handles. You figure out what to select() for by using <a class="emphasis" href="./curl_multi_fdset.html">curl_multi_fdset(3)</a>, that fills in a set of fd_set variables for you with the particular file descriptors libcurl uses for the moment. <p class="level0">When you then call select(), it'll return when one of the file handles signal action and you then call <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a> to allow libcurl to do what it wants to do. Take note that libcurl does also feature some time-out code so we advise you to never use very long timeouts on select() before you call <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>, which thus should be called unconditionally every now and then even if none of its file descriptors have signaled ready. Another precaution you should use: always call <a class="emphasis" href="./curl_multi_fdset.html">curl_multi_fdset(3)</a> immediately before the select() call since the current set of file descriptors may change when calling a curl function. <p class="level0">If you want to stop the transfer of one of the easy handles in the stack, you can use <a class="emphasis" href="./curl_multi_remove_handle.html">curl_multi_remove_handle(3)</a> to remove individual easy handles. Remember that easy handles should be <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a>ed. @@ -530,9 +537,10 @@ p.roffit { <p class="level0"> <p class="level0"> [ seeding, passwords, keys, certificates, ENGINE, ca certs ] <p class="level0"><a name="Sharing"></a><h2 class="nroffsh">Sharing Data Between Easy Handles</h2> -<p class="level0"> -<p class="level0"> [ fill in ] -<p class="level0"><a name="Footnotes"></a><h2 class="nroffsh">Footnotes</h2> +<p class="level0">You can share some data between easy handles when the easy interface is used, and some data is share automatically when you use the multi interface. +<p class="level0">When you add easy handles to a multi handle, these easy handles will automatically share a lot of the data that otherwise would be kept on a per-easy handle basis when the easy interface is used. +<p class="level0">The DNS cache is shared between handles within a multi handle, making subsequent name resolving faster, and the connection pool that is kept to better allow persistent connections and connection re-use is also shared. If you're using the easy interface, you can still share these between specific easy handles by using the share interface, see <span Class="emphasis">libcurl-share(3)</span>. +<p class="level0">Some things are never shared automatically, not within multi handles, like for example cookies so the only way to share that is with the share interface. <a name="Footnotes"></a><h2 class="nroffsh">Footnotes</h2> <p class="level0"> <p class="level0"> <p class="level0"><a name="1"></a><span class="nroffip">[1]</span> diff --git a/docs/libcurl/libcurl-tutorial.pdf b/docs/libcurl/libcurl-tutorial.pdf Binary files differindex c538d193e..ab87af131 100644 --- a/docs/libcurl/libcurl-tutorial.pdf +++ b/docs/libcurl/libcurl-tutorial.pdf diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index c0b221fe7..d2dcd7838 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH libcurl 3 "19 March 2002" "libcurl 7.9.6" "libcurl overview" .SH NAME libcurl \- client-side URL transfers diff --git a/docs/libcurl/libcurl.html b/docs/libcurl/libcurl.html index 43b9bdd0c..e1c00f0d3 100644 --- a/docs/libcurl/libcurl.html +++ b/docs/libcurl/libcurl.html @@ -1,6 +1,8 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> <html><head> <title>libcurl man page</title> -<meta name="generator" content="roffit 0.7"> +<meta name="generator" content="roffit"> <STYLE type="text/css"> P.level0 { padding-left: 2em; diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index 952b79f4e..d7d5a5259 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -146,7 +146,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], _libcurl_save_libs=$LIBS LIBS="$LIBCURL $LIBS" - AC_LINK_IFELSE(AC_LANG_PROGRAM([#include <curl/curl.h>],[ + AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <curl/curl.h>]],[[ /* Try and use a few common options to force a failure if we are missing symbols or can't link. */ int x; @@ -157,7 +157,8 @@ x=CURLOPT_FILE; x=CURLOPT_ERRORBUFFER; x=CURLOPT_STDERR; x=CURLOPT_VERBOSE; -]),libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no) +if (x) ; +]])],libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no) CPPFLAGS=$_libcurl_save_cppflags LIBS=$_libcurl_save_libs diff --git a/docs/libcurl/libcurl.pdf b/docs/libcurl/libcurl.pdf Binary files differindex 0f777df07..4099137b0 100644 --- a/docs/libcurl/libcurl.pdf +++ b/docs/libcurl/libcurl.pdf diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index e22b6251e..e61cbbee9 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -20,6 +20,7 @@ CURLAUTH_DIGEST_IE 7.19.3 CURLAUTH_GSSNEGOTIATE 7.10.6 CURLAUTH_NONE 7.10.6 CURLAUTH_NTLM 7.10.6 +CURLAUTH_NTLM_WB 7.22.0 CURLAUTH_ONLY 7.21.3 CURLCLOSEPOLICY_CALLBACK 7.7 CURLCLOSEPOLICY_LEAST_RECENTLY_USED 7.7 @@ -34,8 +35,8 @@ CURLE_BAD_CALLING_ORDER 7.1 7.17.0 CURLE_BAD_CONTENT_ENCODING 7.10 CURLE_BAD_DOWNLOAD_RESUME 7.10 CURLE_BAD_FUNCTION_ARGUMENT 7.1 -CURLE_BAD_PASSWORD_ENTERED - 7.17.0 -CURLE_CHUNK_FAILED 7.20.1 +CURLE_BAD_PASSWORD_ENTERED 7.4.2 7.17.0 +CURLE_CHUNK_FAILED 7.21.0 CURLE_CONV_FAILED 7.15.4 CURLE_CONV_REQD 7.15.4 CURLE_COULDNT_CONNECT 7.1 @@ -44,10 +45,11 @@ CURLE_COULDNT_RESOLVE_PROXY 7.1 CURLE_FAILED_INIT 7.1 CURLE_FILESIZE_EXCEEDED 7.10.8 CURLE_FILE_COULDNT_READ_FILE 7.1 +CURLE_FTP_ACCEPT_FAILED 7.24.0 +CURLE_FTP_ACCEPT_TIMEOUT 7.24.0 CURLE_FTP_ACCESS_DENIED 7.1 -CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 7.1 -CURLE_FTP_BAD_FILE_LIST 7.20.1 +CURLE_FTP_BAD_FILE_LIST 7.21.0 CURLE_FTP_CANT_GET_HOST 7.1 CURLE_FTP_CANT_RECONNECT 7.1 7.17.0 CURLE_FTP_COULDNT_GET_SIZE 7.1 7.17.0 @@ -61,7 +63,7 @@ CURLE_FTP_PARTIAL_FILE 7.1 7.1 CURLE_FTP_PORT_FAILED 7.1 CURLE_FTP_PRET_FAILED 7.20.0 CURLE_FTP_QUOTE_ERROR 7.1 7.17.0 -CURLE_FTP_SSL_FAILED - 7.17.0 +CURLE_FTP_SSL_FAILED 7.11.0 7.17.0 CURLE_FTP_USER_PASSWORD_INCORRECT 7.1 7.17.0 CURLE_FTP_WEIRD_227_FORMAT 7.1 CURLE_FTP_WEIRD_PASS_REPLY 7.1 @@ -72,7 +74,7 @@ CURLE_FTP_WRITE_ERROR 7.1 7.17.0 CURLE_FUNCTION_NOT_FOUND 7.1 CURLE_GOT_NOTHING 7.9.1 CURLE_HTTP_NOT_FOUND 7.1 -CURLE_HTTP_PORT_FAILED - 7.12.0 +CURLE_HTTP_PORT_FAILED 7.3 7.12.0 CURLE_HTTP_POST_ERROR 7.1 CURLE_HTTP_RANGE_ERROR 7.1 7.17.0 CURLE_HTTP_RETURNED_ERROR 7.10.3 @@ -83,8 +85,10 @@ CURLE_LDAP_SEARCH_FAILED 7.1 CURLE_LIBRARY_NOT_FOUND 7.1 7.17.0 CURLE_LOGIN_DENIED 7.13.1 CURLE_MALFORMAT_USER 7.1 7.17.0 +CURLE_NO_CONNECTION_AVAILABLE 7.30.0 +CURLE_NOT_BUILT_IN 7.21.5 CURLE_OK 7.1 -CURLE_OPERATION_TIMEDOUT 7.17.0 +CURLE_OPERATION_TIMEDOUT 7.10.2 CURLE_OPERATION_TIMEOUTED 7.1 7.17.0 CURLE_OUT_OF_MEMORY 7.1 CURLE_PARTIAL_FILE 7.1 @@ -92,16 +96,16 @@ CURLE_PEER_FAILED_VERIFICATION 7.17.1 CURLE_QUOTE_ERROR 7.17.0 CURLE_RANGE_ERROR 7.17.0 CURLE_READ_ERROR 7.1 -CURLE_RECV_ERROR 7.13.0 +CURLE_RECV_ERROR 7.10 CURLE_REMOTE_ACCESS_DENIED 7.17.0 CURLE_REMOTE_DISK_FULL 7.17.0 CURLE_REMOTE_FILE_EXISTS 7.17.0 CURLE_REMOTE_FILE_NOT_FOUND 7.16.1 CURLE_RTSP_CSEQ_ERROR 7.20.0 CURLE_RTSP_SESSION_ERROR 7.20.0 -CURLE_SEND_ERROR 7.13.0 +CURLE_SEND_ERROR 7.10 CURLE_SEND_FAIL_REWIND 7.12.3 -CURLE_SHARE_IN_USE - 7.17.0 +CURLE_SHARE_IN_USE 7.9.6 7.17.0 CURLE_SSH 7.16.1 CURLE_SSL_CACERT 7.10 CURLE_SSL_CACERT_BADFILE 7.16.0 @@ -109,11 +113,11 @@ CURLE_SSL_CERTPROBLEM 7.10 CURLE_SSL_CIPHER 7.10 CURLE_SSL_CONNECT_ERROR 7.1 CURLE_SSL_CRL_BADFILE 7.19.0 -CURLE_SSL_ENGINE_INITFAILED 7.13.0 +CURLE_SSL_ENGINE_INITFAILED 7.12.3 CURLE_SSL_ENGINE_NOTFOUND 7.9.3 CURLE_SSL_ENGINE_SETFAILED 7.9.3 CURLE_SSL_ISSUER_ERROR 7.19.0 -CURLE_SSL_PEER_CERTIFICATE - 7.17.1 +CURLE_SSL_PEER_CERTIFICATE 7.8 7.17.1 CURLE_SSL_SHUTDOWN_FAILED 7.16.1 CURLE_TELNET_OPTION_SYNTAX 7.7 CURLE_TFTP_DISKFULL 7.15.0 7.17.0 @@ -124,6 +128,7 @@ CURLE_TFTP_NOTFOUND 7.15.0 CURLE_TFTP_PERM 7.15.0 CURLE_TFTP_UNKNOWNID 7.15.0 CURLE_TOO_MANY_REDIRECTS 7.5 +CURLE_UNKNOWN_OPTION 7.21.5 CURLE_UNKNOWN_TELNET_OPTION 7.7 CURLE_UNSUPPORTED_PROTOCOL 7.1 CURLE_UPLOAD_FAILED 7.16.3 @@ -149,36 +154,35 @@ CURLFINFOFLAG_KNOWN_SIZE 7.21.0 CURLFINFOFLAG_KNOWN_TIME 7.21.0 CURLFINFOFLAG_KNOWN_UID 7.21.0 CURLFORM_ARRAY 7.9.1 +CURLFORM_ARRAY_END 7.9.1 7.9.5 7.9.6 +CURLFORM_ARRAY_START 7.9.1 7.9.5 7.9.6 CURLFORM_BUFFER 7.9.8 CURLFORM_BUFFERLENGTH 7.9.8 CURLFORM_BUFFERPTR 7.9.8 CURLFORM_CONTENTHEADER 7.9.3 -CURLFORM_CONTENTSLENGTH 7.9.1 -CURLFORM_CONTENTTYPE 7.9.1 -CURLFORM_COPYCONTENTS 7.9.1 -CURLFORM_COPYNAME 7.9.1 -CURLFORM_END 7.9.1 -CURLFORM_FILE 7.9.1 +CURLFORM_CONTENTSLENGTH 7.9 +CURLFORM_CONTENTTYPE 7.9 +CURLFORM_COPYCONTENTS 7.9 +CURLFORM_COPYNAME 7.9 +CURLFORM_END 7.9 +CURLFORM_FILE 7.9 CURLFORM_FILECONTENT 7.9.1 CURLFORM_FILENAME 7.9.6 -CURLFORM_NAMELENGTH 7.9.1 -CURLFORM_NOTHING 7.9.1 -CURLFORM_PTRCONTENTS 7.9.1 -CURLFORM_PTRNAME 7.9.1 +CURLFORM_NAMELENGTH 7.9 +CURLFORM_NOTHING 7.9 +CURLFORM_PTRCONTENTS 7.9 +CURLFORM_PTRNAME 7.9 CURLFORM_STREAM 7.18.2 CURLFTPAUTH_DEFAULT 7.12.2 -CURLFTPAUTH_DEFAULT 7.12.2 -CURLFTPAUTH_SSL 7.12.2 CURLFTPAUTH_SSL 7.12.2 CURLFTPAUTH_TLS 7.12.2 -CURLFTPAUTH_TLS 7.12.2 -CURLFTPMETHOD_DEFAULT 7.15.1 -CURLFTPMETHOD_MULTICWD 7.15.1 -CURLFTPMETHOD_NOCWD 7.15.1 -CURLFTPMETHOD_SINGLECWD 7.15.1 -CURLFTPSSL_ALL - 7.17.0 -CURLFTPSSL_CCC_ACTIVE 7.16.1 -CURLFTPSSL_CCC_NONE 7.16.1 +CURLFTPMETHOD_DEFAULT 7.15.3 +CURLFTPMETHOD_MULTICWD 7.15.3 +CURLFTPMETHOD_NOCWD 7.15.3 +CURLFTPMETHOD_SINGLECWD 7.15.3 +CURLFTPSSL_ALL 7.11.0 7.17.0 +CURLFTPSSL_CCC_ACTIVE 7.16.2 +CURLFTPSSL_CCC_NONE 7.16.2 CURLFTPSSL_CCC_PASSIVE 7.16.1 CURLFTPSSL_CONTROL 7.11.0 7.17.0 CURLFTPSSL_NONE 7.11.0 7.17.0 @@ -186,6 +190,9 @@ CURLFTPSSL_TRY 7.11.0 7.17.0 CURLFTP_CREATE_DIR 7.19.4 CURLFTP_CREATE_DIR_NONE 7.19.4 CURLFTP_CREATE_DIR_RETRY 7.19.4 +CURLGSSAPI_DELEGATION_FLAG 7.22.0 +CURLGSSAPI_DELEGATION_NONE 7.22.0 +CURLGSSAPI_DELEGATION_POLICY_FLAG 7.22.0 CURLINFO_APPCONNECT_TIME 7.19.0 CURLINFO_CERTINFO 7.19.1 CURLINFO_CONDITION_UNMET 7.19.4 @@ -197,8 +204,8 @@ CURLINFO_COOKIELIST 7.14.1 CURLINFO_DATA_IN 7.9.6 CURLINFO_DATA_OUT 7.9.6 CURLINFO_DOUBLE 7.4.1 -CURLINFO_EFFECTIVE_URL 7.3 -CURLINFO_END 7.4.1 +CURLINFO_EFFECTIVE_URL 7.4 +CURLINFO_END 7.9.6 CURLINFO_FILETIME 7.5 CURLINFO_FTP_ENTRY_PATH 7.15.4 CURLINFO_HEADER_IN 7.9.6 @@ -221,7 +228,6 @@ CURLINFO_PRETRANSFER_TIME 7.4.1 CURLINFO_PRIMARY_IP 7.19.0 CURLINFO_PRIMARY_PORT 7.21.0 CURLINFO_PRIVATE 7.10.3 -CURLINFO_PRIVATE 7.10.3 CURLINFO_PROXYAUTH_AVAIL 7.10.8 CURLINFO_REDIRECT_COUNT 7.9.7 CURLINFO_REDIRECT_TIME 7.9.7 @@ -262,8 +268,15 @@ CURLKHTYPE_DSS 7.19.6 CURLKHTYPE_RSA 7.19.6 CURLKHTYPE_RSA1 7.19.6 CURLKHTYPE_UNKNOWN 7.19.6 +CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 7.30.0 +CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 7.30.0 +CURLMOPT_MAX_HOST_CONNECTIONS 7.30.0 +CURLMOPT_MAX_PIPELINE_LENGTH 7.30.0 +CURLMOPT_MAX_TOTAL_CONNECTIONS 7.30.0 CURLMOPT_MAXCONNECTS 7.16.3 CURLMOPT_PIPELINING 7.16.0 +CURLMOPT_PIPELINING_SERVER_BL 7.30.0 +CURLMOPT_PIPELINING_SITE_BL 7.30.0 CURLMOPT_SOCKETDATA 7.15.4 CURLMOPT_SOCKETFUNCTION 7.15.4 CURLMOPT_TIMERDATA 7.16.0 @@ -283,8 +296,10 @@ CURLOPTTYPE_FUNCTIONPOINT 7.1 CURLOPTTYPE_LONG 7.1 CURLOPTTYPE_OBJECTPOINT 7.1 CURLOPTTYPE_OFF_T 7.11.0 +CURLOPT_ACCEPTTIMEOUT_MS 7.24.0 +CURLOPT_ACCEPT_ENCODING 7.21.6 CURLOPT_ADDRESS_SCOPE 7.19.0 -CURLOPT_APPEND 7.16.4 +CURLOPT_APPEND 7.17.0 CURLOPT_AUTOREFERER 7.1 CURLOPT_BUFFERSIZE 7.10 CURLOPT_CAINFO 7.4.2 @@ -293,8 +308,10 @@ CURLOPT_CERTINFO 7.19.1 CURLOPT_CHUNK_BGN_FUNCTION 7.21.0 CURLOPT_CHUNK_DATA 7.21.0 CURLOPT_CHUNK_END_FUNCTION 7.21.0 -CURLOPT_CLOSEFUNCTION 7.7 7.11.1 7.15.4 +CURLOPT_CLOSEFUNCTION 7.7 7.11.1 7.15.5 CURLOPT_CLOSEPOLICY 7.7 7.16.1 +CURLOPT_CLOSESOCKETDATA 7.21.7 +CURLOPT_CLOSESOCKETFUNCTION 7.21.7 CURLOPT_CONNECTTIMEOUT 7.7 CURLOPT_CONNECTTIMEOUT_MS 7.16.2 CURLOPT_CONNECT_ONLY 7.15.2 @@ -304,7 +321,7 @@ CURLOPT_CONV_TO_NETWORK_FUNCTION 7.15.4 CURLOPT_COOKIE 7.1 CURLOPT_COOKIEFILE 7.1 CURLOPT_COOKIEJAR 7.9 -CURLOPT_COOKIELIST 7.17.1 +CURLOPT_COOKIELIST 7.14.1 CURLOPT_COOKIESESSION 7.9.7 CURLOPT_COPYPOSTFIELDS 7.17.1 CURLOPT_CRLF 7.1 @@ -312,27 +329,27 @@ CURLOPT_CRLFILE 7.19.0 CURLOPT_CUSTOMREQUEST 7.1 CURLOPT_DEBUGDATA 7.9.6 CURLOPT_DEBUGFUNCTION 7.9.6 -CURLOPT_DIRLISTONLY 7.16.4 +CURLOPT_DIRLISTONLY 7.17.0 CURLOPT_DNS_CACHE_TIMEOUT 7.9.3 +CURLOPT_DNS_SERVERS 7.24.0 CURLOPT_DNS_USE_GLOBAL_CACHE 7.9.3 7.11.1 CURLOPT_EGDSOCKET 7.7 -CURLOPT_ENCODING 7.12.2 +CURLOPT_ENCODING 7.10 CURLOPT_ERRORBUFFER 7.1 CURLOPT_FAILONERROR 7.1 CURLOPT_FILE 7.1 7.9.7 CURLOPT_FILETIME 7.5 -CURLOPT_FLAGS 7.1 - 7.9.2 CURLOPT_FNMATCH_DATA 7.21.0 CURLOPT_FNMATCH_FUNCTION 7.21.0 CURLOPT_FOLLOWLOCATION 7.1 CURLOPT_FORBID_REUSE 7.7 CURLOPT_FRESH_CONNECT 7.7 CURLOPT_FTPAPPEND 7.1 7.16.4 -CURLOPT_FTPASCII 7.1 7.11.1 7.15.4 +CURLOPT_FTPASCII 7.1 7.11.1 7.15.5 CURLOPT_FTPLISTONLY 7.1 7.16.4 CURLOPT_FTPPORT 7.1 CURLOPT_FTPSSLAUTH 7.12.2 -CURLOPT_FTP_ACCOUNT 7.13.1 +CURLOPT_FTP_ACCOUNT 7.13.0 CURLOPT_FTP_ALTERNATIVE_TO_USER 7.15.5 CURLOPT_FTP_CREATE_MISSING_DIRS 7.10.7 CURLOPT_FTP_FILEMETHOD 7.15.1 @@ -343,6 +360,7 @@ CURLOPT_FTP_SSL_CCC 7.16.1 CURLOPT_FTP_USE_EPRT 7.10.5 CURLOPT_FTP_USE_EPSV 7.9.2 CURLOPT_FTP_USE_PRET 7.20.0 +CURLOPT_GSSAPI_DELEGATION 7.22.0 CURLOPT_HEADER 7.1 CURLOPT_HEADERDATA 7.10 CURLOPT_HEADERFUNCTION 7.7.2 @@ -352,7 +370,7 @@ CURLOPT_HTTPGET 7.8.1 CURLOPT_HTTPHEADER 7.1 CURLOPT_HTTPPOST 7.1 CURLOPT_HTTPPROXYTUNNEL 7.3 -CURLOPT_HTTPREQUEST 7.1 - 7.15.4 +CURLOPT_HTTPREQUEST 7.1 - 7.15.5 CURLOPT_HTTP_CONTENT_DECODING 7.16.2 CURLOPT_HTTP_TRANSFER_DECODING 7.16.2 CURLOPT_HTTP_VERSION 7.9.1 @@ -369,11 +387,12 @@ CURLOPT_IPRESOLVE 7.10.8 CURLOPT_ISSUERCERT 7.19.0 CURLOPT_KEYPASSWD 7.17.0 CURLOPT_KRB4LEVEL 7.3 7.17.0 -CURLOPT_KRBLEVEL 7.17.0 +CURLOPT_KRBLEVEL 7.16.4 CURLOPT_LOCALPORT 7.15.2 CURLOPT_LOCALPORTRANGE 7.15.2 CURLOPT_LOW_SPEED_LIMIT 7.1 CURLOPT_LOW_SPEED_TIME 7.1 +CURLOPT_MAIL_AUTH 7.25.0 CURLOPT_MAIL_FROM 7.20.0 CURLOPT_MAIL_RCPT 7.20.0 CURLOPT_MAXCONNECTS 7.7 @@ -382,7 +401,7 @@ CURLOPT_MAXFILESIZE_LARGE 7.11.0 CURLOPT_MAXREDIRS 7.5 CURLOPT_MAX_RECV_SPEED_LARGE 7.15.5 CURLOPT_MAX_SEND_SPEED_LARGE 7.15.5 -CURLOPT_MUTE 7.1 7.8 7.15.4 +CURLOPT_MUTE 7.1 7.8 7.15.5 CURLOPT_NETRC 7.1 CURLOPT_NETRC_FILE 7.11.0 CURLOPT_NEW_DIRECTORY_PERMS 7.16.4 @@ -391,12 +410,13 @@ CURLOPT_NOBODY 7.1 CURLOPT_NOPROGRESS 7.1 CURLOPT_NOPROXY 7.19.4 CURLOPT_NOSIGNAL 7.10 +CURLOPT_NOTHING 7.1.1 7.11.1 7.11.0 CURLOPT_OPENSOCKETDATA 7.17.1 CURLOPT_OPENSOCKETFUNCTION 7.17.1 -CURLOPT_PASSWDDATA 7.1 7.11.1 7.15.4 -CURLOPT_PASSWDFUNCTION 7.1 7.11.1 7.15.4 +CURLOPT_PASSWDDATA 7.4.2 7.11.1 7.15.5 +CURLOPT_PASSWDFUNCTION 7.4.2 7.11.1 7.15.5 CURLOPT_PASSWORD 7.19.1 -CURLOPT_PASV_POST 7.12.1 - 7.13.0 +CURLOPT_PASV_HOST 7.12.1 7.16.0 7.15.5 CURLOPT_PORT 7.1 CURLOPT_POST 7.1 CURLOPT_POST301 7.17.1 7.19.1 @@ -408,8 +428,7 @@ CURLOPT_POSTREDIR 7.19.1 CURLOPT_PREQUOTE 7.9.5 CURLOPT_PRIVATE 7.10.3 CURLOPT_PROGRESSDATA 7.1 -CURLOPT_PROGRESSFUNCTION 7.1 -CURLOPT_PROGRESSMODE 7.1 - 7.9.2 +CURLOPT_PROGRESSFUNCTION 7.1 7.32.0 CURLOPT_PROTOCOLS 7.19.4 CURLOPT_PROXY 7.1 CURLOPT_PROXYAUTH 7.10.7 @@ -437,22 +456,23 @@ CURLOPT_RTSP_SERVER_CSEQ 7.20.0 CURLOPT_RTSP_SESSION_ID 7.20.0 CURLOPT_RTSP_STREAM_URI 7.20.0 CURLOPT_RTSP_TRANSPORT 7.20.0 -CURLOPT_SEEKDATA 7.18.1 -CURLOPT_SEEKFUNCTION 7.18.1 +CURLOPT_SASL_IR 7.31.0 +CURLOPT_SEEKDATA 7.18.0 +CURLOPT_SEEKFUNCTION 7.18.0 CURLOPT_SERVER_RESPONSE_TIMEOUT 7.20.0 CURLOPT_SHARE 7.10 CURLOPT_SOCKOPTDATA 7.16.0 CURLOPT_SOCKOPTFUNCTION 7.16.0 CURLOPT_SOCKS5_GSSAPI_NEC 7.19.4 CURLOPT_SOCKS5_GSSAPI_SERVICE 7.19.4 -CURLOPT_SOURCE_HOST 7.12.1 - 7.13.0 -CURLOPT_SOURCE_PATH 7.12.1 - 7.13.0 -CURLOPT_SOURCE_PORT 7.12.1 - 7.13.0 -CURLOPT_SOURCE_POSTQUOTE 7.12.1 - 7.15.4 -CURLOPT_SOURCE_PREQUOTE 7.12.1 - 7.15.4 -CURLOPT_SOURCE_QUOTE 7.13.0 - 7.15.4 -CURLOPT_SOURCE_URL 7.13.0 - 7.15.4 -CURLOPT_SOURCE_USERPWD 7.12.1 - 7.15.4 +CURLOPT_SOURCE_HOST 7.12.1 - 7.15.5 +CURLOPT_SOURCE_PATH 7.12.1 - 7.15.5 +CURLOPT_SOURCE_PORT 7.12.1 - 7.15.5 +CURLOPT_SOURCE_POSTQUOTE 7.12.1 - 7.15.5 +CURLOPT_SOURCE_PREQUOTE 7.12.1 - 7.15.5 +CURLOPT_SOURCE_QUOTE 7.13.0 - 7.15.5 +CURLOPT_SOURCE_URL 7.13.0 - 7.15.5 +CURLOPT_SOURCE_USERPWD 7.12.1 - 7.15.5 CURLOPT_SSH_AUTH_TYPES 7.16.1 CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 7.17.1 CURLOPT_SSH_KEYDATA 7.19.6 @@ -461,22 +481,25 @@ CURLOPT_SSH_KNOWNHOSTS 7.19.6 CURLOPT_SSH_PRIVATE_KEYFILE 7.16.1 CURLOPT_SSH_PUBLIC_KEYFILE 7.16.1 CURLOPT_SSLCERT 7.1 -CURLOPT_SSLCERTPASSWD 7.17.0 +CURLOPT_SSLCERTPASSWD 7.1.1 7.17.0 CURLOPT_SSLCERTTYPE 7.9.3 CURLOPT_SSLENGINE 7.9.3 CURLOPT_SSLENGINE_DEFAULT 7.9.3 CURLOPT_SSLKEY 7.9.3 -CURLOPT_SSLKEYPASSWD 7.17.0 -CURLOPT_SSLKEYPASSWD 7.17.0 +CURLOPT_SSLKEYPASSWD 7.9.3 7.17.0 CURLOPT_SSLKEYTYPE 7.9.3 CURLOPT_SSLVERSION 7.1 CURLOPT_SSL_CIPHER_LIST 7.9 CURLOPT_SSL_CTX_DATA 7.10.6 CURLOPT_SSL_CTX_FUNCTION 7.10.6 +CURLOPT_SSL_OPTIONS 7.25.0 CURLOPT_SSL_SESSIONID_CACHE 7.16.0 CURLOPT_SSL_VERIFYHOST 7.8.1 CURLOPT_SSL_VERIFYPEER 7.4.2 CURLOPT_STDERR 7.1 +CURLOPT_TCP_KEEPALIVE 7.25.0 +CURLOPT_TCP_KEEPIDLE 7.25.0 +CURLOPT_TCP_KEEPINTVL 7.25.0 CURLOPT_TCP_NODELAY 7.11.2 CURLOPT_TELNETOPTIONS 7.7 CURLOPT_TFTP_BLKSIZE 7.19.4 @@ -484,7 +507,11 @@ CURLOPT_TIMECONDITION 7.1 CURLOPT_TIMEOUT 7.1 CURLOPT_TIMEOUT_MS 7.16.2 CURLOPT_TIMEVALUE 7.1 -CURLOPT_TRANSFERTEXT 7.11.1 +CURLOPT_TLSAUTH_PASSWORD 7.21.4 +CURLOPT_TLSAUTH_TYPE 7.21.4 +CURLOPT_TLSAUTH_USERNAME 7.21.4 +CURLOPT_TRANSFERTEXT 7.1.1 +CURLOPT_TRANSFER_ENCODING 7.21.6 CURLOPT_UNRESTRICTED_AUTH 7.10.4 CURLOPT_UPLOAD 7.1 CURLOPT_URL 7.1 @@ -498,6 +525,8 @@ CURLOPT_WRITEDATA 7.9.7 CURLOPT_WRITEFUNCTION 7.1 CURLOPT_WRITEHEADER 7.1 CURLOPT_WRITEINFO 7.1 +CURLOPT_XFERINFODATA 7.32.0 +CURLOPT_XFERINFOFUNCTION 7.32.0 CURLPAUSE_ALL 7.18.0 CURLPAUSE_CONT 7.18.0 CURLPAUSE_RECV 7.18.0 @@ -540,7 +569,8 @@ CURLPROXY_SOCKS5_HOSTNAME 7.18.0 CURLSHE_BAD_OPTION 7.10.3 CURLSHE_INVALID 7.10.3 CURLSHE_IN_USE 7.10.3 -CURLSHE_NOMEM 7.10.3 +CURLSHE_NOMEM 7.12.0 +CURLSHE_NOT_BUILT_IN 7.23.0 CURLSHE_OK 7.10.3 CURLSHOPT_LOCKFUNC 7.10.3 CURLSHOPT_NONE 7.10.3 @@ -548,7 +578,9 @@ CURLSHOPT_SHARE 7.10.3 CURLSHOPT_UNLOCKFUNC 7.10.3 CURLSHOPT_UNSHARE 7.10.3 CURLSHOPT_USERDATA 7.10.3 -CURLSOCKTYPE_IPCXN 7.15.6 +CURLSOCKTYPE_ACCEPT 7.28.0 +CURLSOCKTYPE_IPCXN 7.16.0 +CURLSSH_AUTH_AGENT 7.28.0 CURLSSH_AUTH_ANY 7.16.1 CURLSSH_AUTH_DEFAULT 7.16.1 CURLSSH_AUTH_HOST 7.16.1 @@ -556,13 +588,10 @@ CURLSSH_AUTH_KEYBOARD 7.16.1 CURLSSH_AUTH_NONE 7.16.1 CURLSSH_AUTH_PASSWORD 7.16.1 CURLSSH_AUTH_PUBLICKEY 7.16.1 +CURLSSLOPT_ALLOW_BEAST 7.25.0 CURLUSESSL_ALL 7.17.0 -CURLUSESSL_ALL 7.17.0 -CURLUSESSL_CONTROL 7.17.0 CURLUSESSL_CONTROL 7.17.0 CURLUSESSL_NONE 7.17.0 -CURLUSESSL_NONE 7.17.0 -CURLUSESSL_TRY 7.17.0 CURLUSESSL_TRY 7.17.0 CURLVERSION_FIRST 7.10 CURLVERSION_FOURTH 7.16.1 @@ -577,6 +606,8 @@ CURL_CHUNK_END_FUNC_OK 7.21.0 CURL_CSELECT_ERR 7.16.3 CURL_CSELECT_IN 7.16.3 CURL_CSELECT_OUT 7.16.3 +CURL_EASY_NONE 7.14.0 - 7.15.4 +CURL_EASY_TIMEOUT 7.14.0 - 7.15.4 CURL_ERROR_SIZE 7.1 CURL_FNMATCHFUNC_FAIL 7.21.0 CURL_FNMATCHFUNC_MATCH 7.21.0 @@ -594,6 +625,7 @@ CURL_GLOBAL_DEFAULT 7.8 CURL_GLOBAL_NOTHING 7.8 CURL_GLOBAL_SSL 7.8 CURL_GLOBAL_WIN32 7.8.1 +CURL_GLOBAL_ACK_EINTR 7.30.0 CURL_HTTP_VERSION_1_0 7.9.1 CURL_HTTP_VERSION_1_1 7.9.1 CURL_HTTP_VERSION_NONE 7.9.1 @@ -609,6 +641,11 @@ CURL_LOCK_DATA_DNS 7.10.3 CURL_LOCK_DATA_NONE 7.10.3 CURL_LOCK_DATA_SHARE 7.10.4 CURL_LOCK_DATA_SSL_SESSION 7.10.3 +CURL_LOCK_TYPE_CONNECT 7.10 - 7.10.2 +CURL_LOCK_TYPE_COOKIE 7.10 - 7.10.2 +CURL_LOCK_TYPE_DNS 7.10 - 7.10.2 +CURL_LOCK_TYPE_NONE 7.10 - 7.10.2 +CURL_LOCK_TYPE_SSL_SESSION 7.10 - 7.10.2 CURL_MAX_HTTP_HEADER 7.19.7 CURL_MAX_WRITE_SIZE 7.9.7 CURL_NETRC_IGNORED 7.9.8 @@ -619,11 +656,14 @@ CURL_POLL_INOUT 7.14.0 CURL_POLL_NONE 7.14.0 CURL_POLL_OUT 7.14.0 CURL_POLL_REMOVE 7.14.0 +CURL_PROGRESS_BAR 7.1.1 - 7.4.1 +CURL_PROGRESS_STATS 7.1.1 - 7.4.1 CURL_READFUNC_ABORT 7.12.1 CURL_READFUNC_PAUSE 7.18.0 CURL_REDIR_GET_ALL 7.19.1 CURL_REDIR_POST_301 7.19.1 CURL_REDIR_POST_302 7.19.1 +CURL_REDIR_POST_303 7.25.1 CURL_REDIR_POST_ALL 7.19.1 CURL_RTSPREQ_ANNOUNCE 7.20.0 CURL_RTSPREQ_DESCRIBE 7.20.0 @@ -642,6 +682,9 @@ CURL_SEEKFUNC_FAIL 7.19.5 CURL_SEEKFUNC_OK 7.19.5 CURL_SOCKET_BAD 7.14.0 CURL_SOCKET_TIMEOUT 7.14.0 +CURL_SOCKOPT_ALREADY_CONNECTED 7.21.5 +CURL_SOCKOPT_ERROR 7.21.5 +CURL_SOCKOPT_OK 7.21.5 CURL_SSLVERSION_DEFAULT 7.9.2 CURL_SSLVERSION_SSLv2 7.9.2 CURL_SSLVERSION_SSLv3 7.9.2 @@ -650,6 +693,8 @@ CURL_TIMECOND_IFMODSINCE 7.9.7 CURL_TIMECOND_IFUNMODSINCE 7.9.7 CURL_TIMECOND_LASTMOD 7.9.7 CURL_TIMECOND_NONE 7.9.7 +CURL_TLSAUTH_NONE 7.21.4 +CURL_TLSAUTH_SRP 7.21.4 CURL_VERSION_ASYNCHDNS 7.10.7 CURL_VERSION_CONV 7.15.4 CURL_VERSION_CURLDEBUG 7.19.6 @@ -661,7 +706,12 @@ CURL_VERSION_KERBEROS4 7.10 CURL_VERSION_LARGEFILE 7.11.1 CURL_VERSION_LIBZ 7.10 CURL_VERSION_NTLM 7.10.6 +CURL_VERSION_NTLM_WB 7.22.0 CURL_VERSION_SPNEGO 7.10.8 CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 +CURL_VERSION_TLSAUTH_SRP 7.21.4 +CURL_WAIT_POLLIN 7.28.0 +CURL_WAIT_POLLOUT 7.28.0 +CURL_WAIT_POLLPRI 7.28.0 CURL_WRITEFUNC_PAUSE 7.18.0 diff --git a/docs/libcurl/symbols.pl b/docs/libcurl/symbols.pl new file mode 100755 index 000000000..d1ff7a656 --- /dev/null +++ b/docs/libcurl/symbols.pl @@ -0,0 +1,100 @@ +#!/usr/bin/perl +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| +# +# Copyright (C) 2011, Daniel Stenberg, <daniel@haxx.se>, et al. +# +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### +# +# Experience has shown that the symbols-in-versions file is very useful to +# applications that want to build with a wide range of libcurl versions. +# It is however easy to get it wrong and the source gets a bit messy with all +# the fixed numerical comparisions. +# +# The point of this script is to provide an easy-to-use macro for libcurl- +# using applications to do preprocessor checks for specific libcurl defines, +# and yet make the code clearly show what the macro is used for. +# +# Run this script and generate libcurl-symbols.h and then use that header in +# a fashion similar to: +# +# #include "libcurl-symbols.h" +# +# #if LIBCURL_HAS(CURLOPT_MUTE) +# has mute +# #else +# no mute +# #endif +# +# +open F, "<symbols-in-versions"; + +sub str2num { + my ($str)=@_; + if($str =~ /([0-9]*)\.([0-9]*)\.*([0-9]*)/) { + return sprintf("0x%06x", $1<<16 | $2 << 8 | $3); + } +} + +print <<EOS + +#include <curl/curl.h> + +#define LIBCURL_HAS(x) \\ + (defined(x ## _FIRST) && (x ## _FIRST <= LIBCURL_VERSION_NUM) && \\ + (!defined(x ## _LAST) || ( x ## _LAST >= LIBCURL_VERSION_NUM))) + +EOS + ; + +while(<F>) { + if(/^(CURL[^ ]*)[ \t]*(.*)/) { + my ($sym, $vers)=($1, $2); + + my $intr; + my $rm; + my $dep; + + # is there removed info? + if($vers =~ /([\d.]+)[ \t-]+([\d.]+)[ \t]+([\d.]+)/) { + ($intr, $dep, $rm)=($1, $2, $3); + } + # is it a dep-only line? + elsif($vers =~ /([\d.]+)[ \t-]+([\d.]+)/) { + ($intr, $dep)=($1, $2); + } + else { + $intr = $vers; + } + + my $inum = str2num($intr); + + print <<EOS +#define ${sym}_FIRST $inum /* Added in $intr */ +EOS +; + my $irm = str2num($rm); + if($rm) { + print <<EOS +#define ${sym}_LAST $irm /* Last featured in $rm */ +EOS +; + } + + } +} diff --git a/docs/mk-ca-bundle.html b/docs/mk-ca-bundle.html new file mode 100644 index 000000000..fbdd58957 --- /dev/null +++ b/docs/mk-ca-bundle.html @@ -0,0 +1,82 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<html><head> +<title>mk-ca-bundle man page</title> +<meta name="generator" content="roffit"> +<STYLE type="text/css"> +P.level0 { + padding-left: 2em; +} + +P.level1 { + padding-left: 4em; +} + +P.level2 { + padding-left: 6em; +} + +span.emphasis { + font-style: italic; +} + +span.bold { + font-weight: bold; +} + +span.manpage { + font-weight: bold; +} + +h2.nroffsh { + background-color: #e0e0e0; +} + +span.nroffip { + font-weight: bold; + font-size: 120%; + font-family: monospace; +} + +p.roffit { + text-align: center; + font-size: 80%; +} +</STYLE> +</head><body> + +<p class="level0"><a name="NAME"></a><h2 class="nroffsh">NAME</h2> +<p class="level0">mk-ca-bundle - convert mozilla's certdata.txt to PEM format <a name="SYNOPSIS"></a><h2 class="nroffsh">SYNOPSIS</h2> +<p class="level0">mk-ca-bundle [bilnqtuv] <span Class="emphasis">[outputfile]</span> <a name="DESCRIPTION"></a><h2 class="nroffsh">DESCRIPTION</h2> +<p class="level0">The mk-ca-bundle tool downloads the certdata.txt file from Mozilla's source tree over HTTP, then parses certdata.txt and extracts CA Root Certificates into PEM format. These are then processed with the OpenSSL commandline tool to produce the final ca-bundle file. +<p class="level0">The default <span Class="emphasis">outputfile</span> name is <span Class="bold">ca-bundle.crt</span>. By setting it to '-' (a single dash) you will get the output sent to STDOUT instead of a file. +<p class="level0">The PEM format this scripts uses for output makes the result readily available for use by just about all OpenSSL or GnuTLS powered applications, such as curl, wget and more. <a name="OPTIONS"></a><h2 class="nroffsh">OPTIONS</h2> +<p class="level0">The following options are supported: +<p class="level0"><a name="-b"></a><span class="nroffip">-b</span> +<p class="level1">backup an existing version of <span Class="emphasis">outputfilename</span> +<p class="level0"><a name="-f"></a><span class="nroffip">-f</span> +<p class="level1">force rebuild even if certdata.txt is current (Added in version 1.17) +<p class="level0"><a name="-i"></a><span class="nroffip">-i</span> +<p class="level1">print version info about used modules +<p class="level0"><a name="-l"></a><span class="nroffip">-l</span> +<p class="level1">print license info about certdata.txt +<p class="level0"><a name="-n"></a><span class="nroffip">-n</span> +<p class="level1">no download of certdata.txt (to use existing) +<p class="level0"><a name="-q"></a><span class="nroffip">-q</span> +<p class="level1">be really quiet (no progress output at all) +<p class="level0"><a name="-t"></a><span class="nroffip">-t</span> +<p class="level1">include plain text listing of certificates +<p class="level0"><a name="-u"></a><span class="nroffip">-u</span> +<p class="level1">unlink (remove) certdata.txt after processing +<p class="level0"><a name="-v"></a><span class="nroffip">-v</span> +<p class="level1">be verbose and print out processed CAs <a name="EXIT"></a><h2 class="nroffsh">EXIT STATUS</h2> +<p class="level0">Returns 0 on success. Returns 1 if it fails to download data. <a name="CERTDATA"></a><h2 class="nroffsh">CERTDATA FORMAT</h2> +<p class="level0">The file format used by Mozilla for this trust information seems to be documented here: <pre> +<p class="level0"><a href="http://p11-glue.freedesktop.org/doc/storing-trust-policy/storing-trust-existing.html">http://p11-glue.freedesktop.org/doc/storing-trust-policy/storing-trust-existing.html</a> + </pre> + +<p class="level0"><a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2> +<p class="level0"><span Class="manpage">curl (1)</span> <a name="HISTORY"></a><h2 class="nroffsh">HISTORY</h2> +<p class="level0"><span Class="bold">mk-ca-bundle</span> is a command line tool that is shipped as part of every curl and libcurl release (see <a href="http://curl.haxx.se/">http://curl.haxx.se/</a>). It was originally based on the parse-certs script written by Roland Krikava and was later much improved by Guenter Knauf. This manual page was initially written by Jan Schaumann <jschauma@netmeister.org>. <p class="roffit"> + This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>. +</body></html> diff --git a/docs/mk-ca-bundle.pdf b/docs/mk-ca-bundle.pdf Binary files differnew file mode 100644 index 000000000..5fe5224e7 --- /dev/null +++ b/docs/mk-ca-bundle.pdf |