5
5
.\" * | (__| |_| | _ <| |___
6
6
.\" * \___|\___/|_| \_\_____|
8
.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, <daniel@haxx.se>, et al.
8
.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, <daniel@haxx.se>, et al.
10
10
.\" * This software is licensed as described in the file COPYING, which
11
11
.\" * you should have received as part of this distribution. The terms
18
18
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19
19
.\" * KIND, either express or implied.
21
.\" * $Id: libcurl-tutorial.3,v 1.14 2007-08-30 20:34:57 danf Exp $
21
.\" * $Id: libcurl-tutorial.3,v 1.22 2008-12-29 21:26:11 bagder Exp $
22
22
.\" **************************************************************************
24
.TH libcurl-tutorial 3 "27 Feb 2007" "libcurl" "libcurl programming"
24
.TH libcurl-tutorial 3 "17 Nov 2008" "libcurl" "libcurl programming"
26
26
libcurl-tutorial \- libcurl programming tutorial
36
36
source code that you write that is using libcurl for transfers. The program
37
37
is outside libcurl and libcurl is outside of the program.
39
To get the more details on all options and functions described herein, please
39
To get more details on all options and functions described herein, please
40
40
refer to their respective man pages.
43
43
There are many different ways to build C programs. This chapter will assume a
44
unix-style build process. If you use a different build system, you can still
44
UNIX-style build process. If you use a different build system, you can still
45
45
read this to get general information that may apply to your environment as
47
47
.IP "Compiling the Program"
72
72
$ curl-config --feature
74
74
And if SSL is supported, the keyword 'SSL' will be written to stdout,
75
possibly together with a few other features that can be on and off on
75
possibly together with a few other features that could be either on or off on
76
for different libcurls.
78
78
See also the "Features libcurl Provides" further down.
79
79
.IP "autoconf macro"
87
87
on a large amount of different operating systems and environments.
89
89
You program libcurl the same way on all platforms that libcurl runs on. There
90
are only very few minor considerations that differs. If you just make sure to
90
are only very few minor considerations that differ. If you just make sure to
91
91
write your code portable enough, you may very well create yourself a very
92
92
portable program. libcurl shouldn't stop you from that.
113
113
.IP CURL_GLOBAL_SSL
114
114
which only does anything on libcurls compiled and built SSL-enabled. On these
115
115
systems, this will make libcurl initialize the SSL library properly for this
116
application. This is only needed to do once for each application so if your
116
application. This only needs to be done once for each application so if your
117
117
program or another library already does this, this bit should not be needed.
167
167
the same options.
169
169
Many of the options you set in libcurl are "strings", pointers to data
170
terminated with a zero byte. Keep in mind that when you set strings with
171
\fIcurl_easy_setopt(3)\fP, libcurl will not copy the data. It will merely
172
point to the data. You MUST make sure that the data remains available for
173
libcurl to use until finished or until you use the same option again to point
170
terminated with a zero byte. When you set strings with
171
\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they don't
172
need to be kept around in your application after being set[4].
176
174
One of the most basic properties to set in the handle is the URL. You set
177
175
your preferred URL to transfer with CURLOPT_URL in a manner similar to:
194
192
curl_easy_setopt(easyhandle, CURLOPT_WRITEFUNCTION, write_data);
196
You can control what data your function get in the forth argument by setting
194
You can control what data your callback function gets in the fourth argument
195
by setting another property:
199
197
curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct);
245
243
you intend to make another transfer. libcurl will then attempt to re-use the
246
244
previous connection.
246
For some protocols, downloading a file can involve a complicated process of
247
logging in, setting the transfer mode, changing the current directory and
248
finally transferring the file data. libcurl takes care of all that
249
complication for you. Given simply the URL to a file, libcurl will take care
250
of all the details needed to get the file moved from one machine to another.
248
252
.SH "Multi-threading Issues"
249
253
The first basic rule is that you must \fBnever\fP share a libcurl handle (be
250
254
it easy or multi or whatever) between multiple threads. Only use one handle in
251
255
one thread at a time.
253
257
libcurl is completely thread safe, except for two issues: signals and SSL/TLS
254
handlers. Signals are used timeouting name resolves (during DNS lookup) - when
255
built without c-ares support and not on Windows..
258
handlers. Signals are used for timing out name resolves (during DNS lookup) -
259
when built without c-ares support and not on Windows.
257
261
If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
258
262
then of course using the underlying SSL library multi-threaded and those libs
273
is claimed to be thread-safe already without anything required
277
is claimed to be thread-safe already without anything required.
277
Required actions unknown
281
Required actions unknown.
279
When using multiple threads you should set the CURLOPT_NOSIGNAL option to TRUE
283
When using multiple threads you should set the CURLOPT_NOSIGNAL option to 1
280
284
for all handles. Everything will or might work fine except that timeouts are
281
285
not honored during the DNS lookup - which you can work around by building
282
286
libcurl with c-ares support. c-ares is a library that provides asynchronous
283
name resolves. Unfortunately, c-ares does not yet fully support IPv6. On some
284
platforms, libcurl simply will not function properly multi-threaded unless
287
name resolves. On some platforms, libcurl simply will not function properly
288
multi-threaded unless this option is set.
287
290
Also, note that CURLOPT_DNS_USE_GLOBAL_CACHE is not thread-safe.
293
296
confuse the library which then confuses your program.
295
298
There's one golden rule when these things occur: set the CURLOPT_VERBOSE
296
option to TRUE. It'll cause the library to spew out the entire protocol
299
option to 1. It'll cause the library to spew out the entire protocol
297
300
details it sends, some internal info and some received protocol data as well
298
301
(especially when using FTP). If you're using HTTP, adding the headers in the
299
302
received output to study is also a clever way to get a better understanding
300
303
why the server behaves the way it does. Include headers in the normal body
301
output with CURLOPT_HEADER set TRUE.
304
output with CURLOPT_HEADER set 1.
303
Of course there are bugs left. We need to get to know about them to be able
306
Of course, there are bugs left. We need to know about them to be able
304
307
to fix them, so we're quite dependent on your bug reports! When you do report
305
suspected bugs in libcurl, please include as much details you possibly can: a
308
suspected bugs in libcurl, please include as many details as you possibly can: a
306
309
protocol dump that CURLOPT_VERBOSE produces, library version, as much as
307
310
possible of your code that uses libcurl, operating system name and version,
308
311
compiler name and version etc.
340
343
curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, read_function);
342
curl_easy_setopt(easyhandle, CURLOPT_INFILE, &filedata);
345
curl_easy_setopt(easyhandle, CURLOPT_READDATA, &filedata);
344
347
Tell libcurl that we want to upload:
346
curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, TRUE);
349
curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, 1L);
348
351
A few protocols won't behave properly when uploads are done without any prior
349
352
knowledge of the expected file size. So, set the upload file size using the
350
353
CURLOPT_INFILESIZE_LARGE for all known file sizes like this[1]:
353
/* in this example, file_size must be an off_t variable */
356
/* in this example, file_size must be an curl_off_t variable */
354
357
curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size);
390
393
curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
392
There's a long time unix "standard" way of storing ftp user names and
395
There's a long time UNIX "standard" way of storing ftp user names and
393
396
passwords, namely in the $HOME/.netrc file. The file should be made private
394
397
so that only the user may read it (see also the "Security Considerations"
395
398
chapter), as it might contain the password in plain text. libcurl has the
398
401
libcurl also supports this file for non-FTP protocols such as HTTP. To make
399
402
curl use this file, use the CURLOPT_NETRC option:
401
curl_easy_setopt(easyhandle, CURLOPT_NETRC, TRUE);
404
curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L);
403
406
And a very basic example of how such a .netrc file may look like:
421
424
The previous chapter showed how to set user name and password for getting
422
425
URLs that require authentication. When using the HTTP protocol, there are
423
426
many different ways a client can provide those credentials to the server and
424
you can control what way libcurl will (attempt to) use. The default HTTP
427
you can control which way libcurl will (attempt to) use them. The default HTTP
425
428
authentication method is called 'Basic', which is sending the name and
426
429
password in clear-text in the HTTP request, base64-encoded. This is insecure.
428
At the time of this writing libcurl can be built to use: Basic, Digest, NTLM,
431
At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM,
429
432
Negotiate, GSS-Negotiate and SPNEGO. You can tell libcurl which one to use
430
433
with CURLOPT_HTTPAUTH as in:
472
475
upcoming request.
474
477
Ok, so what if you want to post binary data that also requires you to set the
475
Content-Type: header of the post? Well, binary posts prevents libcurl from
478
Content-Type: header of the post? Well, binary posts prevent libcurl from
476
479
being able to do strlen() on the data to figure out the size, so therefore we
477
480
must tell libcurl the size of the post data. Setting headers in libcurl
478
481
requests are done in a generic way, by building a list of our own headers and
486
489
curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, binaryptr);
488
491
/* set the size of the postfields data */
489
curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23);
492
curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23L);
491
494
/* pass our list of custom made headers */
492
495
curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
499
502
While the simple examples above cover the majority of all cases where HTTP
500
503
POST operations are required, they don't do multi-part formposts. Multi-part
501
504
formposts were introduced as a better way to post (possibly large) binary data
502
and was first documented in the RFC1867. They're called multi-part because
505
and were first documented in the RFC1867. They're called multi-part because
503
506
they're built by a chain of parts, each being a single unit. Each part has its
504
507
own name and contents. You can in fact create and post a multi-part formpost
505
508
with the regular libcurl POST support described above, but that would require
508
511
parts to the form. When you're done adding parts, you post the whole form.
510
513
The following example sets two simple text parts with plain textual contents,
511
and then a file with binary contents and upload the whole thing.
514
and then a file with binary contents and uploads the whole thing.
514
517
struct curl_httppost *post=NULL;
537
540
that describe the individual content-type, size etc. To enable your
538
541
application to handicraft this formpost even more, libcurl allows you to
539
542
supply your own set of custom headers to such an individual form part. You can
540
of course supply headers to as many parts you like, but this little example
543
of course supply headers to as many parts as you like, but this little example
541
544
will show how you set headers to one specific part when you add that to the
560
563
Since all options on an easyhandle are "sticky", they remain the same until
561
564
changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell
562
curl to go back to a plain GET request if you intend to do such a one as your
563
next request. You force an easyhandle to back to GET by using the
565
curl to go back to a plain GET request if you intend to do one as your
566
next request. You force an easyhandle to go back to GET by using the
564
567
CURLOPT_HTTPGET option:
566
curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, TRUE);
569
curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L);
568
571
Just setting CURLOPT_POSTFIELDS to "" or NULL will *not* stop libcurl from
569
572
doing a POST. It will just make it POST without any data to send!
571
574
.SH "Showing Progress"
573
576
For historical and traditional reasons, libcurl has a built-in progress meter
574
that can be switched on and then makes it presents a progress meter in your
577
that can be switched on and then makes it present a progress meter in your
577
Switch on the progress meter by, oddly enough, set CURLOPT_NOPROGRESS to
578
FALSE. This option is set to TRUE by default.
580
Switch on the progress meter by, oddly enough, setting CURLOPT_NOPROGRESS to
581
zero. This option is set to 1 by default.
580
583
For most applications however, the built-in progress meter is useless and
581
584
what instead is interesting is the ability to specify a progress
639
642
HTTP URL will be still be passed to the HTTP proxy to deliver back to
640
643
libcurl. This happens transparently, and an application may not need to
641
644
know. I say "may", because at times it is very important to understand that
642
all operations over a HTTP proxy is using the HTTP protocol. For example, you
645
all operations over a HTTP proxy use the HTTP protocol. For example, you
643
646
can't invoke your own custom FTP commands or even proper FTP directory
726
729
Tell libcurl to use proxy tunneling like this:
728
curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, TRUE);
731
curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, 1L);
730
733
In fact, there might even be times when you want to do plain HTTP
731
734
operations using a tunnel like this, as it then enables you to operate on
770
773
host again, will benefit from libcurl's session ID cache that drastically
771
774
reduces re-connection time.
773
FTP connections that are kept alive saves a lot of time, as the command-
776
FTP connections that are kept alive save a lot of time, as the command-
774
777
response round-trips are skipped, and also you don't risk getting blocked
775
778
without permission to login again like on many FTP servers only allowing N
776
779
persons to be logged in at the same time.
784
787
Each easy handle will attempt to keep the last few connections alive for a
785
788
while in case they are to be used again. You can set the size of this "cache"
786
with the CURLOPT_MAXCONNECTS option. Default is 5. It is very seldom any
789
with the CURLOPT_MAXCONNECTS option. Default is 5. There is very seldom any
787
790
point in changing this value, and if you think of changing this it is often
788
791
just a matter of thinking again.
790
793
To force your upcoming request to not use an already existing connection (it
791
794
will even close one first if there happens to be one alive to the same host
792
795
you're about to operate on), you can do that by setting CURLOPT_FRESH_CONNECT
793
to TRUE. In a similar spirit, you can also forbid the upcoming request to be
796
to 1. In a similar spirit, you can also forbid the upcoming request to be
794
797
"lying" around and possibly get re-used after the request by setting
795
CURLOPT_FORBID_REUSE to TRUE.
798
CURLOPT_FORBID_REUSE to 1.
797
800
.SH "HTTP Headers Used by libcurl"
798
801
When you use libcurl to do HTTP requests, it'll pass along a series of headers
799
automatically. It might be good for you to know and understand these ones. You
802
automatically. It might be good for you to know and understand these. You
800
803
can replace or remove them by using the CURLOPT_HTTPHEADER option.
820
823
.SH "Customizing Operations"
821
824
There is an ongoing development today where more and more protocols are built
822
825
upon HTTP for transport. This has obvious benefits as HTTP is a tested and
823
reliable protocol that is widely deployed and have excellent proxy-support.
826
reliable protocol that is widely deployed and has excellent proxy-support.
825
828
When you use one of these protocols, and even when doing other kinds of
826
829
programming you may need to change the traditional HTTP (or FTP or...)
836
839
curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNRUQUEST");
838
841
When using the custom request, you change the request keyword of the actual
839
request you are performing. Thus, by default you make GET request but you can
842
request you are performing. Thus, by default you make a GET request but you can
840
843
also make a POST operation (as described before) and then replace the POST
841
844
keyword if you want to. You're the boss.
843
846
.IP "Modify Headers"
844
847
HTTP-like protocols pass a series of headers to the server when doing the
845
848
request, and you're free to pass any amount of extra headers that you
846
think fit. Adding headers are this easy:
849
think fit. Adding headers is this easy:
849
852
struct curl_slist *headers=NULL; /* init to NULL is important */
871
874
.IP "Delete Headers"
872
875
If you replace an existing header with one with no contents, you will prevent
873
the header from being sent. Like if you want to completely prevent the
874
\&"Accept:" header to be sent, you can disable it with code similar to this:
876
the header from being sent. For instance, if you want to completely prevent the
877
\&"Accept:" header from being sent, you can disable it with code similar to this:
876
879
headers = curl_slist_append(headers, "Accept:");
890
893
.IP "HTTP Version"
892
895
All HTTP requests includes the version number to tell the server which version
893
we support. libcurl speak HTTP 1.1 by default. Some very old servers don't
896
we support. libcurl speaks HTTP 1.1 by default. Some very old servers don't
894
897
like getting 1.1-requests and when dealing with stubborn old things like that,
895
898
you can tell libcurl to use 1.0 instead by doing something like this:
899
902
.IP "FTP Custom Commands"
901
904
Not all protocols are HTTP-like, and thus the above may not help you when
902
you want to make for example your FTP transfers to behave differently.
905
you want to make, for example, your FTP transfers to behave differently.
904
907
Sending custom commands to a FTP server means that you need to send the
905
908
commands exactly as the FTP server expects them (RFC959 is a good guide
906
909
here), and you can only use commands that work on the control-connection
907
alone. All kinds of commands that requires data interchange and thus needs
910
alone. All kinds of commands that require data interchange and thus need
908
911
a data-connection must be left to libcurl's own judgment. Also be aware
909
912
that libcurl will do its very best to change directory to the target
910
913
directory before doing any transfer, so if you change directory (with CWD
935
938
commands before a transfer, no transfer will actually take place when a quote
936
939
command has failed.
938
If you set the CURLOPT_HEADER to true, you will tell libcurl to get
941
If you set the CURLOPT_HEADER to 1, you will tell libcurl to get
939
942
information about the target file and output "headers" about it. The headers
940
943
will be in "HTTP-style", looking like they do in HTTP.
944
947
transfer will be performed.
946
949
.IP "FTP Custom CUSTOMREQUEST"
947
If you do what list the contents of a FTP directory using your own defined FTP
950
If you do want to list the contents of a FTP directory using your own defined FTP
948
951
command, CURLOPT_CUSTOMREQUEST will do just that. "NLST" is the default one
949
952
for listing directories but you're free to pass in your idea of a good
956
959
set. The conditions include that the domain name and path match and that the
957
960
cookie hasn't become too old.
959
In real-world cases, servers send new cookies to replace existing one to
962
In real-world cases, servers send new cookies to replace existing ones to
960
963
update them. Server use cookies to "track" users and to keep "sessions".
962
965
Cookies are sent from server to clients with the header Set-Cookie: and
970
973
In many cases, that is not enough. You might want to dynamically save
971
974
whatever cookies the remote server passes to you, and make sure those cookies
972
are then use accordingly on later requests.
975
are then used accordingly on later requests.
974
977
One way to do this, is to save all headers you receive in a plain file and
975
978
when you make a request, you tell libcurl to read the previous headers to
976
figure out which cookies to use. Set header file to read cookies from with
979
figure out which cookies to use. Set the header file to read cookies from with
977
980
CURLOPT_COOKIEFILE.
979
982
The CURLOPT_COOKIEFILE option also automatically enables the cookie parser in
982
985
parser is enabled the cookies will be understood and the cookies will be kept
983
986
in memory and used properly in subsequent requests when the same handle is
984
987
used. Many times this is enough, and you may not have to save the cookies to
985
disk at all. Note that the file you specify to CURLOPT_COOKIEFILE doesn't
986
have to exist to enable the parser, so a common way to just enable the parser
987
and not read able might be to use a file name you know doesn't exist.
988
disk at all. Note that the file you specify to CURLOPT_COOKIEFILE doesn't have
989
to exist to enable the parser, so a common way to just enable the parser and
990
not read any cookies is to use the name of a file you know doesn't exist.
989
If you rather use existing cookies that you've previously received with your
990
Netscape or Mozilla browsers, you can make libcurl use that cookie file as
991
input. The CURLOPT_COOKIEFILE is used for that too, as libcurl will
992
If you would rather use existing cookies that you've previously received with
993
your Netscape or Mozilla browsers, you can make libcurl use that cookie file
994
as input. The CURLOPT_COOKIEFILE is used for that too, as libcurl will
992
995
automatically find out what kind of file it is and act accordingly.
994
The perhaps most advanced cookie operation libcurl offers, is saving the
997
Perhaps the most advanced cookie operation libcurl offers, is saving the
995
998
entire internal cookie state back into a Netscape/Mozilla formatted cookie
996
999
file. We call that the cookie-jar. When you set a file name with
997
1000
CURLOPT_COOKIEJAR, that file name will be created and all received cookies
998
will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enabled
1001
will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables
999
1002
cookies to get passed on properly between multiple handles without any
1000
1003
information getting lost.
1004
1007
FTP transfers use a second TCP/IP connection for the data transfer. This is
1005
1008
usually a fact you can forget and ignore but at times this fact will come
1006
back to haunt you. libcurl offers several different ways to custom how the
1009
back to haunt you. libcurl offers several different ways to customize how the
1007
1010
second connection is being made.
1009
1012
libcurl can either connect to the server a second time or tell the server to
1015
1018
and does not exist nor work on all FTP servers.)
1017
1020
You can prevent libcurl from first trying the EPSV command by setting
1018
CURLOPT_FTP_USE_EPSV to FALSE.
1021
CURLOPT_FTP_USE_EPSV to zero.
1020
1023
In some cases, you will prefer to have the server connect back to you for the
1021
1024
second connection. This might be when the server is perhaps behind a firewall
1030
1033
When doing the "PORT" approach, libcurl will attempt to use the EPRT and the
1031
1034
LPRT before trying PORT, as they work with more protocols. You can disable
1032
this behavior by setting CURLOPT_FTP_USE_EPRT to FALSE.
1035
this behavior by setting CURLOPT_FTP_USE_EPRT to zero.
1034
1037
.SH "Headers Equal Fun"
1036
1039
Some protocols provide "headers", meta-data separated from the normal
1037
1040
data. These headers are by default not included in the normal data stream,
1038
1041
but you can make them appear in the data stream by setting CURLOPT_HEADER to
1041
1044
What might be even more useful, is libcurl's ability to separate the headers
1042
1045
from the data and thus make the callbacks differ. You can for example set a
1090
1093
clear text (HTTP Basic authentication, FTP, TELNET etc). It is very easy for
1091
1094
anyone on your network or a network nearby yours, to just fire up a network
1092
1095
analyzer tool and eavesdrop on your passwords. Don't let the fact that HTTP
1093
uses base64 encoded passwords fool you. They may not look readable at a first
1094
glance, but they very easily "deciphered" by anyone within seconds.
1096
To avoid this problem, use protocols that don't let snoopers see your
1097
password: HTTPS, FTPS and FTP-kerberos are a few examples. HTTP Digest
1098
authentication allows this too, but isn't supported by libcurl as of this
1096
Basic uses base64 encoded passwords fool you. They may not look readable at a
1097
first glance, but they very easily "deciphered" by anyone within seconds.
1099
To avoid this problem, use HTTP athentication methods or other protocols that
1100
don't let snoopers see your password: HTTP with Digest, NTLM or GSS
1101
authentication, HTTPS, FTPS, SCP, SFTP and FTP-kerberos are a few examples.
1101
1102
.IP "Showing What You Do"
1102
1103
On a related issue, be aware that even in situations like when you have
1103
1104
problems with libcurl and ask someone for help, everything you reveal in order
1104
1105
to get best possible help might also impose certain security related
1105
risks. Host names, user names, paths, operating system specifics etc (not to
1106
risks. Host names, user names, paths, operating system specifics, etc (not to
1106
1107
mention passwords of course) may in fact be used by intruders to gain
1107
1108
additional information of a potential target.
1113
1114
.SH "Multiple Transfers Using the multi Interface"
1115
1116
The easy interface as described in detail in this document is a synchronous
1116
interface that transfers one file at a time and doesn't return until its
1117
interface that transfers one file at a time and doesn't return until it is
1119
The multi interface on the other hand, allows your program to transfer
1120
multiple files in both directions at the same time, without forcing you to
1121
use multiple threads.
1120
The multi interface, on the other hand, allows your program to transfer
1121
multiple files in both directions at the same time, without forcing you
1122
to use multiple threads. The name might make it seem that the multi
1123
interface is for multi-threaded programs, but the truth is almost the
1124
reverse. The multi interface can allow a single-threaded application
1125
to perform the same kinds of multiple, simultaneous transfers that
1126
multi-threaded programs can perform. It allows many of the benefits
1127
of multi-threaded transfers without the complexity of managing and
1128
synchronizing many threads.
1123
1130
To use this interface, you are better off if you first understand the basics
1124
1131
of how to use the easy interface. The multi interface is simply a way to make
1125
multiple transfers at the same time, by adding up multiple easy handles in to
1132
multiple transfers at the same time by adding up multiple easy handles into
1126
1133
a "multi stack".
1128
1135
You create the easy handles you want and you set all the options just like you
1131
1138
with \fIcurl_multi_add_handle(3)\fP.
1133
1140
When you've added the handles you have for the moment (you can still add new
1134
ones at any time), you start the transfers by call
1141
ones at any time), you start the transfers by calling
1135
1142
\fIcurl_multi_perform(3)\fP.
1137
1144
\fIcurl_multi_perform(3)\fP is asynchronous. It will only execute as little as
1150
1157
When you then call select(), it'll return when one of the file handles signal
1151
1158
action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do
1152
1159
what it wants to do. Take note that libcurl does also feature some time-out
1153
code so we advice you to never use very long timeouts on select() before you
1160
code so we advise you to never use very long timeouts on select() before you
1154
1161
call \fIcurl_multi_perform(3)\fP, which thus should be called unconditionally
1155
1162
every now and then even if none of its file descriptors have signaled
1156
1163
ready. Another precaution you should use: always call
1183
1190
libcurl 7.10.3 and later have the ability to switch over to chunked
1184
Transfer-Encoding in cases were HTTP uploads are done with data of an unknown
1191
Transfer-Encoding in cases where HTTP uploads are done with data of an unknown
1187
1194
This happens on Windows machines when libcurl is built and used as a
1188
1195
DLL. However, you can still do this on Windows if you link with a static
1191
The curl-config tool is generated at build-time (on unix-like systems) and
1198
The curl-config tool is generated at build-time (on UNIX-like systems) and
1192
1199
should be installed with the 'make install' or similar instruction that
1193
1200
installs the library, header files, man pages etc.
1202
This behavior was different in versions before 7.17.0, where strings had to
1203
remain valid past the end of the \fIcurl_easy_setopt(3)\fP call.
added
removed
docs/libcurl/libcurl-tutorial.3
