generic-library/curl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Anthony Bryan's man page cleanup in language and spelling

Browse Source
This commit is contained in:
Daniel Stenberg
2008-12-28 21:56:56 +00:00
parent 27b8a5fd84
commit f61cfc5931
22 changed files with 199 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/libcurl/libcurl-tutorial.3
View File

@@ -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