diff options
Diffstat (limited to 'docs/libcurl/libcurl-tutorial.3')
| -rw-r--r-- | docs/libcurl/libcurl-tutorial.3 | 92 |
1 files changed, 46 insertions, 46 deletions
diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index dd4be66c4..10474be4a 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -36,7 +36,7 @@ What will be generally referred to as 'the program' will be the collected source code that you write that is using libcurl for transfers. The program is outside libcurl and libcurl is outside of the program. -To get the more details on all options and functions described herein, please +To get more details on all options and functions described herein, please refer to their respective man pages. .SH "Building" @@ -72,8 +72,8 @@ if an installed libcurl has been built with SSL support enabled, use $ curl-config --feature And if SSL is supported, the keyword 'SSL' will be written to stdout, -possibly together with a few other features that can be on and off on -different libcurls. +possibly together with a few other features that could be either on or off on +for different libcurls. See also the "Features libcurl Provides" further down. .IP "autoconf macro" @@ -87,7 +87,7 @@ The people behind libcurl have put a considerable effort to make libcurl work on a large amount of different operating systems and environments. You program libcurl the same way on all platforms that libcurl runs on. There -are only very few minor considerations that differs. If you just make sure to +are only very few minor considerations that differ. If you just make sure to write your code portable enough, you may very well create yourself a very portable program. libcurl shouldn't stop you from that. @@ -113,7 +113,7 @@ should not tell libcurl to do this as well. .IP CURL_GLOBAL_SSL which only does anything on libcurls compiled and built SSL-enabled. On these systems, this will make libcurl initialize the SSL library properly for this -application. This is only needed to do once for each application so if your +application. This only needs to be done once for each application so if your program or another library already does this, this bit should not be needed. .RE @@ -256,7 +256,7 @@ one thread at a 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) - -when built without c-ares support and not on Windows.. +when built without c-ares support and not on Windows. 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 @@ -274,11 +274,11 @@ GnuTLS NSS - is claimed to be thread-safe already without anything required + is claimed to be thread-safe already without anything required. yassl - Required actions unknown + Required actions unknown. 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 @@ -303,9 +303,9 @@ received output to study is also a clever way to get a better understanding why the server behaves the way it does. Include headers in the normal body output with CURLOPT_HEADER set 1. -Of course there are bugs left. We need to get to know about them to be able +Of course, there are bugs left. We need to know about them to be able to fix them, so we're quite dependent on your bug reports! When you do report -suspected bugs in libcurl, please include as much details you possibly can: a +suspected bugs in libcurl, please include as many details as you possibly can: a protocol dump that CURLOPT_VERBOSE produces, library version, as much as possible of your code that uses libcurl, operating system name and version, compiler name and version etc. @@ -424,11 +424,11 @@ To pass the known private key password to libcurl: The previous chapter showed how to set user name and password for getting URLs that require authentication. When using the HTTP protocol, there are many different ways a client can provide those credentials to the server and -you can control what way libcurl will (attempt to) use. The default HTTP +you can control which way libcurl will (attempt to) use them. The default HTTP authentication method is called 'Basic', which is sending the name and password in clear-text in the HTTP request, base64-encoded. This is insecure. -At the time of this writing libcurl can be built to use: Basic, Digest, NTLM, +At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM, Negotiate, GSS-Negotiate and SPNEGO. You can tell libcurl which one to use with CURLOPT_HTTPAUTH as in: @@ -475,7 +475,7 @@ CURLOPT_POSTFIELDS, this automatically switches the handle to use POST in the upcoming request. Ok, so what if you want to post binary data that also requires you to set the -Content-Type: header of the post? Well, binary posts prevents libcurl from +Content-Type: header of the post? Well, binary posts prevent libcurl from being able to do strlen() on the data to figure out the size, so therefore we must tell libcurl the size of the post data. Setting headers in libcurl requests are done in a generic way, by building a list of our own headers and @@ -502,7 +502,7 @@ then passing that list to libcurl. 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 was first documented in the RFC1867. They're called multi-part because +and were first documented in the RFC1867. They're called multi-part because they're built by a chain of parts, each being a single unit. 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 @@ -511,7 +511,7 @@ easier, libcurl provides \fIcurl_formadd(3)\fP. Using this function, you add parts to the form. When you're done adding parts, you post the whole form. The following example sets two simple text parts with plain textual contents, -and then a file with binary contents and upload the whole thing. +and then a file with binary contents and uploads the whole thing. .nf struct curl_httppost *post=NULL; @@ -540,7 +540,7 @@ headers. It means that each one of these separate parts get a few headers set that describe the individual content-type, size etc. To enable your application to handicraft this formpost even more, libcurl allows you to supply your own set of custom headers to such an individual form part. You can -of course supply headers to as many parts you like, but this little example +of course supply headers to as many parts as you like, but this little example will show how you set headers to one specific part when you add that to the post handle: @@ -562,8 +562,8 @@ post handle: Since all options on an easyhandle are "sticky", they remain the same until changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell -curl to go back to a plain GET request if you intend to do such a one as your -next request. You force an easyhandle to back to GET by using the +curl to go back to a plain GET request if you intend to do one as your +next request. You force an easyhandle to go back to GET by using the CURLOPT_HTTPGET option: curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L); @@ -574,10 +574,10 @@ doing a POST. It will just make it POST without any data to send! .SH "Showing Progress" For historical and traditional reasons, libcurl has a built-in progress meter -that can be switched on and then makes it presents a progress meter in your +that can be switched on and then makes it present a progress meter in your terminal. -Switch on the progress meter by, oddly enough, set CURLOPT_NOPROGRESS to +Switch on the progress meter by, oddly enough, setting CURLOPT_NOPROGRESS to zero. This option is set to 1 by default. For most applications however, the built-in progress meter is useless and @@ -642,7 +642,7 @@ restrictions on what can actually happen. A requested URL that might not be a HTTP URL will be still be passed to the HTTP proxy to deliver back to libcurl. This happens transparently, and an application may not need to know. I say "may", because at times it is very important to understand that -all operations over a HTTP proxy is using the HTTP protocol. For example, you +all operations over a HTTP proxy use the HTTP protocol. For example, you can't invoke your own custom FTP commands or even proper FTP directory listings. @@ -773,7 +773,7 @@ Even if the connection is dropped, all connections involving SSL to the same host again, will benefit from libcurl's session ID cache that drastically reduces re-connection time. -FTP connections that are kept alive saves a lot of time, as the command- +FTP connections that are kept alive save a lot of time, as the command- response round-trips are skipped, and also you don't risk getting blocked without permission to login again like on many FTP servers only allowing N persons to be logged in at the same time. @@ -786,7 +786,7 @@ may also be added in the future. Each easy handle will attempt to keep the last few connections alive for a while in case they are to be used again. You can set the size of this "cache" -with the CURLOPT_MAXCONNECTS option. Default is 5. It is very seldom any +with the CURLOPT_MAXCONNECTS option. Default is 5. There is very seldom any point in changing this value, and if you think of changing this it is often just a matter of thinking again. @@ -799,7 +799,7 @@ CURLOPT_FORBID_REUSE to 1. .SH "HTTP Headers Used by libcurl" When you use libcurl to do HTTP requests, it'll pass along a series of headers -automatically. It might be good for you to know and understand these ones. You +automatically. It might be good for you to know and understand these. You can replace or remove them by using the CURLOPT_HTTPHEADER option. .IP "Host" @@ -823,7 +823,7 @@ this header. .SH "Customizing Operations" There is an ongoing development today where more and more protocols are built upon HTTP for transport. This has obvious benefits as HTTP is a tested and -reliable protocol that is widely deployed and have excellent proxy-support. +reliable protocol that is widely deployed and has excellent proxy-support. When you use one of these protocols, and even when doing other kinds of programming you may need to change the traditional HTTP (or FTP or...) @@ -839,14 +839,14 @@ for you. It is very simple to use: curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNRUQUEST"); When using the custom request, you change the request keyword of the actual -request you are performing. Thus, by default you make GET request but you can +request you are performing. Thus, by default you make a GET request but you can also make a POST operation (as described before) and then replace the POST keyword if you want to. You're the boss. .IP "Modify Headers" HTTP-like protocols pass a series of headers to the server when doing the request, and you're free to pass any amount of extra headers that you -think fit. Adding headers are this easy: +think fit. Adding headers is this easy: .nf struct curl_slist *headers=NULL; /* init to NULL is important */ @@ -873,8 +873,8 @@ replace them by simply setting them too: .IP "Delete Headers" If you replace an existing header with one with no contents, you will prevent -the header from being sent. Like if you want to completely prevent the -\&"Accept:" header to be sent, you can disable it with code similar to this: +the header from being sent. For instance, if you want to completely prevent the +\&"Accept:" header from being sent, you can disable it with code similar to this: headers = curl_slist_append(headers, "Accept:"); @@ -893,7 +893,7 @@ data size is unknown. .IP "HTTP Version" All HTTP requests includes the version number to tell the server which version -we support. libcurl speak HTTP 1.1 by default. Some very old servers don't +we support. libcurl speaks HTTP 1.1 by default. Some very old servers don't like getting 1.1-requests and when dealing with stubborn old things like that, you can tell libcurl to use 1.0 instead by doing something like this: @@ -902,12 +902,12 @@ you can tell libcurl to use 1.0 instead by doing something like this: .IP "FTP Custom Commands" 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. +you want to make, for example, your FTP transfers to behave differently. 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 requires data interchange and thus needs +alone. All kinds of commands that require data interchange and thus need a data-connection must be left to libcurl's own judgment. 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 @@ -947,7 +947,7 @@ combine with CURLOPT_NOBODY. If this option is set, no actual file content transfer will be performed. .IP "FTP Custom CUSTOMREQUEST" -If you do what list the contents of a FTP directory using your own defined FTP +If you do want to list the contents of a FTP directory using your own defined FTP command, CURLOPT_CUSTOMREQUEST will do just that. "NLST" is the default one for listing directories but you're free to pass in your idea of a good alternative. @@ -959,7 +959,7 @@ subsequent request to the server that matches the particular conditions set. The conditions include that the domain name and path match and that the cookie hasn't become too old. -In real-world cases, servers send new cookies to replace existing one to +In real-world cases, servers send new cookies to replace existing ones to update them. Server use cookies to "track" users and to keep "sessions". Cookies are sent from server to clients with the header Set-Cookie: and @@ -972,7 +972,7 @@ to set a cookie string like this: In many cases, that is not enough. You might want to dynamically save whatever cookies the remote server passes to you, and make sure those cookies -are then use accordingly on later requests. +are then used accordingly on later requests. One way to do this, is to save all headers you receive in a plain file and when you make a request, you tell libcurl to read the previous headers to @@ -989,16 +989,16 @@ disk at all. Note that the file you specify to CURLOPT_COOKIEFILE doesn't have to exist to enable the parser, so a common way to just enable the parser and not read any cookies is to use a the name of a file you know doesn't exist. -If you rather use existing cookies that you've previously received with your +If you would rather use existing cookies that you've previously received with your Netscape or Mozilla browsers, you can make libcurl use that cookie file as input. The CURLOPT_COOKIEFILE is used for that too, as libcurl will automatically find out what kind of file it is and act accordingly. -The perhaps most advanced cookie operation libcurl offers, is saving the +Perhaps the most advanced cookie operation libcurl offers, is saving the entire internal cookie state back into a Netscape/Mozilla formatted cookie file. We call that the cookie-jar. When you set a file name with CURLOPT_COOKIEJAR, that file name will be created and all received cookies -will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enabled +will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables cookies to get passed on properly between multiple handles without any information getting lost. @@ -1006,7 +1006,7 @@ information getting lost. FTP transfers use a second TCP/IP connection for the data transfer. This is usually a fact you can forget and ignore but at times this fact will come -back to haunt you. libcurl offers several different ways to custom how the +back to haunt you. libcurl offers several different ways to customize how the second connection is being made. libcurl can either connect to the server a second time or tell the server to @@ -1103,7 +1103,7 @@ authentication, HTTPS, FTPS, SCP, SFTP and FTP-kerberos are a few examples. 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. @@ -1114,10 +1114,10 @@ information with faked data. .SH "Multiple Transfers Using the multi Interface" The easy interface as described in detail in this document is a synchronous -interface that transfers one file at a time and doesn't return until its +interface that transfers one file at a time and doesn't return until it is done. -The multi interface on the other hand, allows your program to transfer +The multi interface, on the other hand, allows your program to transfer multiple files in both directions at the same time, without forcing you to use multiple threads. The name might make it seem that the multi interface is for multi-threaded programs, but the truth is almost the @@ -1129,7 +1129,7 @@ synchronizing many threads. 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 in to +multiple transfers at the same time by adding up multiple easy handles into a "multi stack". You create the easy handles you want and you set all the options just like you @@ -1138,7 +1138,7 @@ have been told above, and then you create a multi handle with with \fIcurl_multi_add_handle(3)\fP. 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 call +ones at any time), you start the transfers by calling \fIcurl_multi_perform(3)\fP. \fIcurl_multi_perform(3)\fP is asynchronous. It will only execute as little as @@ -1157,7 +1157,7 @@ with the particular file descriptors libcurl uses for the moment. When you then call select(), it'll return when one of the file handles signal action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do what it wants to do. Take note that libcurl does also feature some time-out -code so we advice you to never use very long timeouts on select() before you +code so we advise you to never use very long timeouts on select() before you call \fIcurl_multi_perform(3)\fP, 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 @@ -1188,7 +1188,7 @@ to figure out success on each individual transfer. .IP "[1]" libcurl 7.10.3 and later have the ability to switch over to chunked -Transfer-Encoding in cases were HTTP uploads are done with data of an unknown +Transfer-Encoding in cases where HTTP uploads are done with data of an unknown size. .IP "[2]" This happens on Windows machines when libcurl is built and used as a |