1libcurl-tutorial(3) libcurl programming libcurl-tutorial(3)
2
6 libcurl-tutorial - libcurl programming tutorial
7
9 This document attempts to describe the general principles and some
10 basic approaches to consider when programming with libcurl. The text
11 will focus mainly on the C interface but might apply fairly well on
12 other interfaces as well as they usually follow the C one pretty
13 closely.
14 This document will refer to 'the user' as the person writing the source
16 code that uses libcurl. That would probably be you or someone in your
17 position. What will be generally referred to as 'the program' will be
18 the collected source code that you write that is using libcurl for
19 transfers. The program is outside libcurl and libcurl is outside of the
20 program.
21 To get more details on all options and functions described herein,
23 please refer to their respective man pages.
24
27 There are many different ways to build C programs. This chapter will
28 assume a Unix style build process. If you use a different build system,
29 you can still read this to get general information that may apply to
30 your environment as well.
31 Compiling the Program
33 Your compiler needs to know where the libcurl headers are
34 located. Therefore you must set your compiler's include path to
35 point to the directory where you installed them. The 'curl-con‐
36 fig'[3] tool can be used to get this information:
37 $ curl-config --cflags
39 Linking the Program with libcurl
42 When having compiled the program, you need to link your object
43 files to create a single executable. For that to succeed, you
44 need to link with libcurl and possibly also with other libraries
45 that libcurl itself depends on. Like the OpenSSL libraries, but
46 even some standard OS libraries may be needed on the command
47 line. To figure out which flags to use, once again the 'curl-
48 config' tool comes to the rescue:
49 $ curl-config --libs
51 SSL or Not
54 libcurl can be built and customized in many ways. One of the
55 things that varies from different libraries and builds is the
56 support for SSL-based transfers, like HTTPS and FTPS. If a sup‐
57 ported SSL library was detected properly at build-time, libcurl
58 will be built with SSL support. To figure out if an installed
59 libcurl has been built with SSL support enabled, use 'curl-con‐
60 fig' like this:
61 $ curl-config --feature
63 And if SSL is supported, the keyword 'SSL' will be written to
65 stdout, possibly together with a few other features that could
66 be either on or off on for different libcurls.
67 See also the "Features libcurl Provides" further down.
69 autoconf macro
71 When you write your configure script to detect libcurl and setup
72 variables accordingly, we offer a prewritten macro that probably
73 does everything you need in this area. See
74 docs/libcurl/libcurl.m4 file - it includes docs on how to use
75 it.
76
79 The people behind libcurl have put a considerable effort to make
80 libcurl work on a large amount of different operating systems and envi‐
81 ronments.
82 You program libcurl the same way on all platforms that libcurl runs on.
84 There are only very few minor considerations that differ. If you just
85 make sure to write your code portable enough, you may very well create
86 yourself a very portable program. libcurl shouldn't stop you from that.
87
90 The program must initialize some of the libcurl functionality globally.
91 That means it should be done exactly once, no matter how many times you
92 intend to use the library. Once for your program's entire life time.
93 This is done using
94 curl_global_init()
96 and it takes one parameter which is a bit pattern that tells libcurl
98 what to initialize. Using CURL_GLOBAL_ALL will make it initialize all
99 known internal sub modules, and might be a good default option. The
100 current two bits that are specified are:
101 CURL_GLOBAL_WIN32
103 which only does anything on Windows machines. When used
104 on a Windows machine, it'll make libcurl initialize the
105 win32 socket stuff. Without having that initialized prop‐
106 erly, your program cannot use sockets properly. You
107 should only do this once for each application, so if your
108 program already does this or of another library in use
109 does it, you should not tell libcurl to do this as well.
110 CURL_GLOBAL_SSL
112 which only does anything on libcurls compiled and built
113 SSL-enabled. On these systems, this will make libcurl
114 initialize the SSL library properly for this application.
115 This only needs to be done once for each application so
116 if your program or another library already does this,
117 this bit should not be needed.
118 libcurl has a default protection mechanism that detects if
120 curl_global_init(3) hasn't been called by the time curl_easy_perform(3)
121 is called and if that is the case, libcurl runs the function itself
122 with a guessed bit pattern. Please note that depending solely on this
123 is not considered nice nor very good.
124 When the program no longer uses libcurl, it should call
126 curl_global_cleanup(3), which is the opposite of the init call. It will
127 then do the reversed operations to cleanup the resources the
128 curl_global_init(3) call initialized.
129 Repeated calls to curl_global_init(3) and curl_global_cleanup(3) should
131 be avoided. They should only be called once each.
132
135 It is considered best-practice to determine libcurl features at run-
136 time rather than at build-time (if possible of course). By calling
137 curl_version_info(3) and checking out the details of the returned
138 struct, your program can figure out exactly what the currently running
139 libcurl supports.
140
143 libcurl first introduced the so called easy interface. All operations
144 in the easy interface are prefixed with 'curl_easy'. The easy interface
145 lets you do single transfers with a synchronous and blocking function
146 call.
147 libcurl also offers another interface that allows multiple simultaneous
149 transfers in a single thread, the so called multi interface. More about
150 that interface is detailed in a separate chapter further down. You
151 still need to understand the easy interface first, so please continue
152 reading for better understanding.
153
155 To use the easy interface, you must first create yourself an easy han‐
156 dle. You need one handle for each easy session you want to perform.
157 Basically, you should use one handle for every thread you plan to use
158 for transferring. You must never share the same handle in multiple
159 threads.
160 Get an easy handle with
162 easyhandle = curl_easy_init();
164 It returns an easy handle. Using that you proceed to the next step:
166 setting up your preferred actions. A handle is just a logic entity for
167 the upcoming transfer or series of transfers.
168 You set properties and options for this handle using
170 curl_easy_setopt(3). They control how the subsequent transfer or trans‐
171 fers will be made. Options remain set in the handle until set again to
172 something different. They are sticky. Multiple requests using the same
173 handle will use the same options.
174 If you at any point would like to blank all previously set options for
176 a single easy handle, you can call curl_easy_reset(3) and you can also
177 make a clone of an easy handle (with all its set options) using
178 curl_easy_duphandle(3).
179 Many of the options you set in libcurl are "strings", pointers to data
181 terminated with a zero byte. When you set strings with
182 curl_easy_setopt(3), libcurl makes its own copy so that they don't need
183 to be kept around in your application after being set[4].
184 One of the most basic properties to set in the handle is the URL. You
186 set your preferred URL to transfer with CURLOPT_URL(3) in a manner sim‐
187 ilar to:
188 curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/");
190 Let's assume for a while that you want to receive data as the URL iden‐
192 tifies a remote resource you want to get here. Since you write a sort
193 of application that needs this transfer, I assume that you would like
194 to get the data passed to you directly instead of simply getting it
195 passed to stdout. So, you write your own function that matches this
196 prototype:
197 size_t write_data(void *buffer, size_t size, size_t nmemb, void
199 *userp);
200 You tell libcurl to pass all data to this function by issuing a func‐
202 tion similar to this:
203 curl_easy_setopt(easyhandle, CURLOPT_WRITEFUNCTION, write_data);
205 You can control what data your callback function gets in the fourth
207 argument by setting another property:
208 curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct);
210 Using that property, you can easily pass local data between your appli‐
212 cation and the function that gets invoked by libcurl. libcurl itself
213 won't touch the data you pass with CURLOPT_WRITEDATA(3).
214 libcurl offers its own default internal callback that will take care of
216 the data if you don't set the callback with CURLOPT_WRITEFUNCTION(3).
217 It will then simply output the received data to stdout. You can have
218 the default callback write the data to a different file handle by pass‐
219 ing a 'FILE *' to a file opened for writing with the CURLOPT_WRITE‐
220 DATA(3) option.
221 Now, we need to take a step back and have a deep breath. Here's one of
223 those rare platform-dependent nitpicks. Did you spot it? On some plat‐
224 forms[2], libcurl won't be able to operate on files opened by the pro‐
225 gram. Thus, if you use the default callback and pass in an open file
226 with CURLOPT_WRITEDATA(3), it will crash. You should therefore avoid
227 this to make your program run fine virtually everywhere.
228 (CURLOPT_WRITEDATA(3) was formerly known as CURLOPT_FILE. Both names
230 still work and do the same thing).
231 If you're using libcurl as a win32 DLL, you MUST use the CURLOPT_WRITE‐
233 FUNCTION(3) if you set CURLOPT_WRITEDATA(3) - or you will experience
234 crashes.
235 There are of course many more options you can set, and we'll get back
237 to a few of them later. Let's instead continue to the actual transfer:
238 success = curl_easy_perform(easyhandle);
240 curl_easy_perform(3) will connect to the remote site, do the necessary
242 commands and receive the transfer. Whenever it receives data, it calls
243 the callback function we previously set. The function may get one byte
244 at a time, or it may get many kilobytes at once. libcurl delivers as
245 much as possible as often as possible. Your callback function should
246 return the number of bytes it "took care of". If that is not the exact
247 same amount of bytes that was passed to it, libcurl will abort the
248 operation and return with an error code.
249 When the transfer is complete, the function returns a return code that
251 informs you if it succeeded in its mission or not. If a return code
252 isn't enough for you, you can use the CURLOPT_ERRORBUFFER(3) to point
253 libcurl to a buffer of yours where it'll store a human readable error
254 message as well.
255 If you then want to transfer another file, the handle is ready to be
257 used again. Mind you, it is even preferred that you re-use an existing
258 handle if you intend to make another transfer. libcurl will then
259 attempt to re-use the previous connection.
260 For some protocols, downloading a file can involve a complicated
262 process of logging in, setting the transfer mode, changing the current
263 directory and finally transferring the file data. libcurl takes care of
264 all that complication for you. Given simply the URL to a file, libcurl
265 will take care of all the details needed to get the file moved from one
266 machine to another.
267
270 libcurl is thread safe but there are a few exceptions. Refer to
271 libcurl-thread(3) for more information.
272
275 There will always be times when the transfer fails for some reason. You
276 might have set the wrong libcurl option or misunderstood what the
277 libcurl option actually does, or the remote server might return non-
278 standard replies that confuse the library which then confuses your pro‐
279 gram.
280 There's one golden rule when these things occur: set the CURLOPT_VER‐
282 BOSE(3) option to 1. It'll cause the library to spew out the entire
283 protocol details it sends, some internal info and some received proto‐
284 col data as well (especially when using FTP). If you're using HTTP,
285 adding the headers in the received output to study is also a clever way
286 to get a better understanding why the server behaves the way it does.
287 Include headers in the normal body output with CURLOPT_HEADER(3) set 1.
288 Of course, there are bugs left. We need to know about them to be able
290 to fix them, so we're quite dependent on your bug reports! When you do
291 report suspected bugs in libcurl, please include as many details as you
292 possibly can: a protocol dump that CURLOPT_VERBOSE(3) produces, library
293 version, as much as possible of your code that uses libcurl, operating
294 system name and version, compiler name and version etc.
295 If CURLOPT_VERBOSE(3) is not enough, you increase the level of debug
297 data your application receive by using the CURLOPT_DEBUGFUNCTION(3).
298 Getting some in-depth knowledge about the protocols involved is never
300 wrong, and if you're trying to do funny things, you might very well
301 understand libcurl and how to use it better if you study the appropri‐
302 ate RFC documents at least briefly.
303
306 libcurl tries to keep a protocol independent approach to most trans‐
307 fers, thus uploading to a remote FTP site is very similar to uploading
308 data to an HTTP server with a PUT request.
309 Of course, first you either create an easy handle or you re-use one
311 existing one. Then you set the URL to operate on just like before. This
312 is the remote URL, that we now will upload.
313 Since we write an application, we most likely want libcurl to get the
315 upload data by asking us for it. To make it do that, we set the read
316 callback and the custom pointer libcurl will pass to our read callback.
317 The read callback should have a prototype similar to:
318 size_t function(char *bufptr, size_t size, size_t nitems, void
320 *userp);
321 Where bufptr is the pointer to a buffer we fill in with data to upload
323 and size*nitems is the size of the buffer and therefore also the maxi‐
324 mum amount of data we can return to libcurl in this call. The 'userp'
325 pointer is the custom pointer we set to point to a struct of ours to
326 pass private data between the application and the callback.
327 curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, read_function);
329 curl_easy_setopt(easyhandle, CURLOPT_READDATA, &filedata);
331 Tell libcurl that we want to upload:
333 curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, 1L);
335 A few protocols won't behave properly when uploads are done without any
337 prior knowledge of the expected file size. So, set the upload file size
338 using the CURLOPT_INFILESIZE_LARGE(3) for all known file sizes like
339 this[1]:
340 /* in this example, file_size must be an curl_off_t variable */
342 curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size);
343 When you call curl_easy_perform(3) this time, it'll perform all the
345 necessary operations and when it has invoked the upload it'll call your
346 supplied callback to get the data to upload. The program should return
347 as much data as possible in every invoke, as that is likely to make the
348 upload perform as fast as possible. The callback should return the num‐
349 ber of bytes it wrote in the buffer. Returning 0 will signal the end of
350 the upload.
351
354 Many protocols use or even require that user name and password are pro‐
355 vided to be able to download or upload the data of your choice. libcurl
356 offers several ways to specify them.
357 Most protocols support that you specify the name and password in the
359 URL itself. libcurl will detect this and use them accordingly. This is
360 written like this:
361 protocol://user:password@example.com/path/
363 If you need any odd letters in your user name or password, you should
365 enter them URL encoded, as %XX where XX is a two-digit hexadecimal num‐
366 ber.
367 libcurl also provides options to set various passwords. The user name
369 and password as shown embedded in the URL can instead get set with the
370 CURLOPT_USERPWD(3) option. The argument passed to libcurl should be a
371 char * to a string in the format "user:password". In a manner like
372 this:
373 curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret");
375 Another case where name and password might be needed at times, is for
377 those users who need to authenticate themselves to a proxy they use.
378 libcurl offers another option for this, the CURLOPT_PROXYUSERPWD(3). It
379 is used quite similar to the CURLOPT_USERPWD(3) option like this:
380 curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:these‐
382 cret");
383 There's a long time Unix "standard" way of storing FTP user names and
385 passwords, namely in the $HOME/.netrc file. The file should be made
386 private so that only the user may read it (see also the "Security Con‐
387 siderations" chapter), as it might contain the password in plain text.
388 libcurl has the ability to use this file to figure out what set of user
389 name and password to use for a particular host. As an extension to the
390 normal functionality, libcurl also supports this file for non-FTP pro‐
391 tocols such as HTTP. To make curl use this file, use the CUR‐
392 LOPT_NETRC(3) option:
393 curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L);
395 And a very basic example of how such a .netrc file may look like:
397 machine myhost.mydomain.com
399 login userlogin
400 password secretword
401 All these examples have been cases where the password has been
403 optional, or at least you could leave it out and have libcurl attempt
404 to do its job without it. There are times when the password isn't
405 optional, like when you're using an SSL private key for secure trans‐
406 fers.
407 To pass the known private key password to libcurl:
409 curl_easy_setopt(easyhandle, CURLOPT_KEYPASSWD, "keypassword");
411
414 The previous chapter showed how to set user name and password for get‐
415 ting URLs that require authentication. When using the HTTP protocol,
416 there are many different ways a client can provide those credentials to
417 the server and you can control which way libcurl will (attempt to) use
418 them. The default HTTP authentication method is called 'Basic', which
419 is sending the name and password in clear-text in the HTTP request,
420 base64-encoded. This is insecure.
421 At the time of this writing, libcurl can be built to use: Basic,
423 Digest, NTLM, Negotiate (SPNEGO). You can tell libcurl which one to use
424 with CURLOPT_HTTPAUTH(3) as in:
425 curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
427 And when you send authentication to a proxy, you can also set authenti‐
429 cation type the same way but instead with CURLOPT_PROXYAUTH(3):
430 curl_easy_setopt(easyhandle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
432 Both these options allow you to set multiple types (by ORing them
434 together), to make libcurl pick the most secure one out of the types
435 the server/proxy claims to support. This method does however add a
436 round-trip since libcurl must first ask the server what it supports:
437 curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH,
439 CURLAUTH_DIGEST|CURLAUTH_BASIC);
440 For convenience, you can use the 'CURLAUTH_ANY' define (instead of a
442 list with specific types) which allows libcurl to use whatever method
443 it wants.
444 When asking for multiple types, libcurl will pick the available one it
446 considers "best" in its own internal order of preference.
447
450 We get many questions regarding how to issue HTTP POSTs with libcurl
451 the proper way. This chapter will thus include examples using both dif‐
452 ferent versions of HTTP POST that libcurl supports.
453 The first version is the simple POST, the most common version, that
455 most HTML pages using the <form> tag uses. We provide a pointer to the
456 data and tell libcurl to post it all to the remote site:
457 char *data="name=daniel&project=curl";
459 curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, data);
460 curl_easy_setopt(easyhandle, CURLOPT_URL, "http://posthere.com/");
461 curl_easy_perform(easyhandle); /* post away! */
463 Simple enough, huh? Since you set the POST options with the CUR‐
465 LOPT_POSTFIELDS(3), this automatically switches the handle to use POST
466 in the upcoming request.
467 Ok, so what if you want to post binary data that also requires you to
469 set the Content-Type: header of the post? Well, binary posts prevent
470 libcurl from being able to do strlen() on the data to figure out the
471 size, so therefore we must tell libcurl the size of the post data. Set‐
472 ting headers in libcurl requests are done in a generic way, by building
473 a list of our own headers and then passing that list to libcurl.
474 struct curl_slist *headers=NULL;
476 headers = curl_slist_append(headers, "Content-Type: text/xml");
477 /* post binary data */
479 curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, binaryptr);
480 /* set the size of the postfields data */
482 curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23L);
483 /* pass our list of custom made headers */
485 curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
486 curl_easy_perform(easyhandle); /* post away! */
488 curl_slist_free_all(headers); /* free the header list */
490 While the simple examples above cover the majority of all cases where
492 HTTP POST operations are required, they don't do multi-part formposts.
493 Multi-part formposts were introduced as a better way to post (possibly
494 large) binary data and were first documented in the RFC1867 (updated in
495 RFC2388). They're called multi-part because they're built by a chain of
496 parts, each part being a single unit of data. Each part has its own
497 name and contents. You can in fact create and post a multi-part form‐
498 post with the regular libcurl POST support described above, but that
499 would require that you build a formpost yourself and provide to
500 libcurl. To make that easier, libcurl provides a MIME API consisting in
501 several functions: using those, you can create and fill a multi-part
502 form. Function curl_mime_init(3) creates a multi-part body; you can
503 then append new parts to a multi-part body using curl_mime_addpart(3).
504 There are three possible data sources for a part: memory using
505 curl_mime_data(3), file using curl_mime_filedata(3) and user-defined
506 data read callback using curl_mime_data_cb(3). curl_mime_name(3) sets
507 a part's (i.e.: form field) name, while curl_mime_filename(3) fills in
508 the remote file name. With curl_mime_type(3), you can tell the MIME
509 type of a part, curl_mime_headers(3) allows defining the part's head‐
510 ers. When a multi-part body is no longer needed, you can destroy it
511 using curl_mime_free(3).
512 The following example sets two simple text parts with plain textual
514 contents, and then a file with binary contents and uploads the whole
515 thing.
516 curl_mime *multipart = curl_mime_init(easyhandle);
518 curl_mimepart *part = curl_mime_addpart(multipart);
519 curl_mime_name(part, "name");
520 curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
521 part = curl_mime_addpart(multipart);
522 curl_mime_name(part, "project");
523 curl_mime_data(part, "curl", CURL_ZERO_TERMINATED);
524 part = curl_mime_addpart(multipart);
525 curl_mime_name(part, "logotype-image");
526 curl_mime_filedata(part, "curl.png");
527 /* Set the form info */
529 curl_easy_setopt(easyhandle, CURLOPT_MIMEPOST, multipart);
530 curl_easy_perform(easyhandle); /* post away! */
532 /* free the post data again */
534 curl_mime_free(multipart);
535 To post multiple files for a single form field, you must supply each
537 file in a separate part, all with the same field name. Although func‐
538 tion curl_mime_subparts(3) implements nested multi-parts, this way of
539 multiple files posting is deprecated by RFC 7578, chapter 4.3.
540 To set the data source from an already opened FILE pointer, use:
542 curl_mime_data_cb(part, filesize, (curl_read_callback) fread,
544 (curl_seek_callback) fseek, NULL, filepointer);
545 A deprecated curl_formadd(3) function is still supported in libcurl.
547 It should however not be used anymore for new designs and programs
548 using it ought to be converted to the MIME API. It is however described
549 here as an aid to conversion.
550 Using curl_formadd, you add parts to the form. When you're done adding
552 parts, you post the whole form.
553 The MIME API example above is expressed as follows using this function:
555 struct curl_httppost *post=NULL;
557 struct curl_httppost *last=NULL;
558 curl_formadd(&post, &last,
559 CURLFORM_COPYNAME, "name",
560 CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
561 curl_formadd(&post, &last,
562 CURLFORM_COPYNAME, "project",
563 CURLFORM_COPYCONTENTS, "curl", CURLFORM_END);
564 curl_formadd(&post, &last,
565 CURLFORM_COPYNAME, "logotype-image",
566 CURLFORM_FILECONTENT, "curl.png", CURLFORM_END);
567 /* Set the form info */
569 curl_easy_setopt(easyhandle, CURLOPT_HTTPPOST, post);
570 curl_easy_perform(easyhandle); /* post away! */
572 /* free the post data again */
574 curl_formfree(post);
575 Multipart formposts are chains of parts using MIME-style separators and
577 headers. It means that each one of these separate parts get a few head‐
578 ers set that describe the individual content-type, size etc. To enable
579 your application to handicraft this formpost even more, libcurl allows
580 you to supply your own set of custom headers to such an individual form
581 part. You can of course supply headers to as many parts as you like,
582 but this little example will show how you set headers to one specific
583 part when you add that to the post handle:
584 struct curl_slist *headers=NULL;
586 headers = curl_slist_append(headers, "Content-Type: text/xml");
587 curl_formadd(&post, &last,
589 CURLFORM_COPYNAME, "logotype-image",
590 CURLFORM_FILECONTENT, "curl.xml",
591 CURLFORM_CONTENTHEADER, headers,
592 CURLFORM_END);
593 curl_easy_perform(easyhandle); /* post away! */
595 curl_formfree(post); /* free post */
597 curl_slist_free_all(headers); /* free custom header list */
598 Since all options on an easyhandle are "sticky", they remain the same
600 until changed even if you do call curl_easy_perform(3), you may need to
601 tell curl to go back to a plain GET request if you intend to do one as
602 your next request. You force an easyhandle to go back to GET by using
603 the CURLOPT_HTTPGET(3) option:
604 curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L);
606 Just setting CURLOPT_POSTFIELDS(3) to "" or NULL will *not* stop
608 libcurl from doing a POST. It will just make it POST without any data
609 to send!
610
613 Four rules have to be respected in building the multi-part:
614 - The easy handle must be created before building the multi-part.
615 - The multi-part is always created by a call to curl_mime_init(easyhan‐
616 dle).
617 - Each part is created by a call to curl_mime_addpart(multipart).
618 - When complete, the multi-part must be bound to the easy handle using
619 CURLOPT_MIMEPOST(3) instead of CURLOPT_HTTPPOST(3).
620 Here are some example of curl_formadd calls to MIME API sequences:
622 curl_formadd(&post, &last,
624 CURLFORM_COPYNAME, "id",
625 CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
626 CURLFORM_CONTENTHEADER, headers,
627 CURLFORM_END);
628 becomes:
629 part = curl_mime_addpart(multipart);
630 curl_mime_name(part, "id");
631 curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
632 curl_mime_headers(part, headers, FALSE);
633 Setting the last curl_mime_headers argument to TRUE would have caused
635 the headers to be automatically released upon destroyed the multi-part,
636 thus saving a clean-up call to curl_slist_free_all(3).
637 curl_formadd(&post, &last,
639 CURLFORM_PTRNAME, "logotype-image",
640 CURLFORM_FILECONTENT, "-",
641 CURLFORM_END);
642 becomes:
643 part = curl_mime_addpart(multipart);
644 curl_mime_name(part, "logotype-image");
645 curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin);
646 curl_mime_name always copies the field name. The special file name "-"
648 is not supported by curl_mime_file: to read an open file, use a call‐
649 back source using fread(). The transfer will be chunked since the data
650 size is unknown.
651 curl_formadd(&post, &last,
653 CURLFORM_COPYNAME, "datafile[]",
654 CURLFORM_FILE, "file1",
655 CURLFORM_FILE, "file2",
656 CURLFORM_END);
657 becomes:
658 part = curl_mime_addpart(multipart);
659 curl_mime_name(part, "datafile[]");
660 curl_mime_filedata(part, "file1");
661 part = curl_mime_addpart(multipart);
662 curl_mime_name(part, "datafile[]");
663 curl_mime_filedata(part, "file2");
664 The deprecated multipart/mixed implementation of multiple files field
666 is translated to two distinct parts with the same name.
667 curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, myreadfunc);
669 curl_formadd(&post, &last,
670 CURLFORM_COPYNAME, "stream",
671 CURLFORM_STREAM, arg,
672 CURLFORM_CONTENTLEN, (curl_off_t) datasize,
673 CURLFORM_FILENAME, "archive.zip",
674 CURLFORM_CONTENTTYPE, "application/zip",
675 CURLFORM_END);
676 becomes:
677 part = curl_mime_addpart(multipart);
678 curl_mime_name(part, "stream");
679 curl_mime_data_cb(part, (curl_off_t) datasize,
680 myreadfunc, NULL, NULL, arg);
681 curl_mime_filename(part, "archive.zip");
682 curl_mime_type(part, "application/zip");
683 CURLOPT_READFUNCTION callback is not used: it is replace by directly
685 setting the part source data from the callback read function.
686 curl_formadd(&post, &last,
688 CURLFORM_COPYNAME, "memfile",
689 CURLFORM_BUFFER, "memfile.bin",
690 CURLFORM_BUFFERPTR, databuffer,
691 CURLFORM_BUFFERLENGTH, (long) sizeof databuffer,
692 CURLFORM_END);
693 becomes:
694 part = curl_mime_addpart(multipart);
695 curl_mime_name(part, "memfile");
696 curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer);
697 curl_mime_filename(part, "memfile.bin");
698 curl_mime_data always copies the initial data: data buffer is thus free
700 for immediate reuse.
701 curl_formadd(&post, &last,
703 CURLFORM_COPYNAME, "message",
704 CURLFORM_FILECONTENT, "msg.txt",
705 CURLFORM_END);
706 becomes:
707 part = curl_mime_addpart(multipart);
708 curl_mime_name(part, "message");
709 curl_mime_filedata(part, "msg.txt");
710 curl_mime_filename(part, NULL);
711 Use of curl_mime_filedata sets the remote file name as a side effect:
713 it is therefore necessary to clear it for CURLFORM_FILECONTENT emula‐
714 tion.
715
718 For historical and traditional reasons, libcurl has a built-in progress
719 meter that can be switched on and then makes it present a progress
720 meter in your terminal.
721 Switch on the progress meter by, oddly enough, setting CUR‐
723 LOPT_NOPROGRESS(3) to zero. This option is set to 1 by default.
724 For most applications however, the built-in progress meter is useless
726 and what instead is interesting is the ability to specify a progress
727 callback. The function pointer you pass to libcurl will then be called
728 on irregular intervals with information about the current transfer.
729 Set the progress callback by using CURLOPT_PROGRESSFUNCTION(3). And
731 pass a pointer to a function that matches this prototype:
732 int progress_callback(void *clientp,
734 double dltotal,
735 double dlnow,
736 double ultotal,
737 double ulnow);
738 If any of the input arguments is unknown, a 0 will be passed. The first
740 argument, the 'clientp' is the pointer you pass to libcurl with CUR‐
741 LOPT_PROGRESSDATA(3). libcurl won't touch it.
742
745 There's basically only one thing to keep in mind when using C++ instead
746 of C when interfacing libcurl:
747 The callbacks CANNOT be non-static class member functions
749 Example C++ code:
751 class AClass {
753 static size_t write_data(void *ptr, size_t size, size_t nmemb,
754 void *ourpointer)
755 {
756 /* do what you want with the data */
757 }
758 }
759
762 What "proxy" means according to Merriam-Webster: "a person authorized
763 to act for another" but also "the agency, function, or office of a
764 deputy who acts as a substitute for another".
765 Proxies are exceedingly common these days. Companies often only offer
767 Internet access to employees through their proxies. Network clients or
768 user-agents ask the proxy for documents, the proxy does the actual
769 request and then it returns them.
770 libcurl supports SOCKS and HTTP proxies. When a given URL is wanted,
772 libcurl will ask the proxy for it instead of trying to connect to the
773 actual host identified in the URL.
774 If you're using a SOCKS proxy, you may find that libcurl doesn't quite
776 support all operations through it.
777 For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain
779 restrictions on what can actually happen. A requested URL that might
780 not be a HTTP URL will be still be passed to the HTTP proxy to deliver
781 back to libcurl. This happens transparently, and an application may not
782 need to know. I say "may", because at times it is very important to
783 understand that all operations over an HTTP proxy use the HTTP proto‐
784 col. For example, you can't invoke your own custom FTP commands or even
785 proper FTP directory listings.
786 Proxy Options
789 To tell libcurl to use a proxy at a given port number:
791 curl_easy_setopt(easyhandle, CURLOPT_PROXY, "proxy-
793 host.com:8080");
794 Some proxies require user authentication before allowing a
796 request, and you pass that information similar to this:
797 curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "user:pass‐
799 word");
800 If you want to, you can specify the host name only in the CUR‐
802 LOPT_PROXY(3) option, and set the port number separately with
803 CURLOPT_PROXYPORT(3).
804 Tell libcurl what kind of proxy it is with CURLOPT_PROXYTYPE(3)
806 (if not, it will default to assume an HTTP proxy):
807 curl_easy_setopt(easyhandle, CURLOPT_PROXYTYPE, CURL‐
809 PROXY_SOCKS4);
810 Environment Variables
813 libcurl automatically checks and uses a set of environment vari‐
815 ables to know what proxies to use for certain protocols. The
816 names of the variables are following an ancient de facto stan‐
817 dard and are built up as "[protocol]_proxy" (note the lower cas‐
818 ing). Which makes the variable 'http_proxy' checked for a name
819 of a proxy to use when the input URL is HTTP. Following the same
820 rule, the variable named 'ftp_proxy' is checked for FTP URLs.
821 Again, the proxies are always HTTP proxies, the different names
822 of the variables simply allows different HTTP proxies to be
823 used.
824 The proxy environment variable contents should be in the format
826 "[protocol://][user:password@]machine[:port]". Where the proto‐
827 col:// part is simply ignored if present (so http://proxy and
828 bluerk://proxy will do the same) and the optional port number
829 specifies on which port the proxy operates on the host. If not
830 specified, the internal default port number will be used and
831 that is most likely *not* the one you would like it to be.
832 There are two special environment variables. 'all_proxy' is what
834 sets proxy for any URL in case the protocol specific variable
835 wasn't set, and 'no_proxy' defines a list of hosts that should
836 not use a proxy even though a variable may say so. If 'no_proxy'
837 is a plain asterisk ("*") it matches all hosts.
838 To explicitly disable libcurl's checking for and using the proxy
840 environment variables, set the proxy name to "" - an empty
841 string - with CURLOPT_PROXY(3).
842 SSL and Proxies
844 SSL is for secure point-to-point connections. This involves
846 strong encryption and similar things, which effectively makes it
847 impossible for a proxy to operate as a "man in between" which
848 the proxy's task is, as previously discussed. Instead, the only
849 way to have SSL work over an HTTP proxy is to ask the proxy to
850 tunnel trough everything without being able to check or fiddle
851 with the traffic.
852 Opening an SSL connection over an HTTP proxy is therefore a mat‐
854 ter of asking the proxy for a straight connection to the target
855 host on a specified port. This is made with the HTTP request
856 CONNECT. ("please mr proxy, connect me to that remote host").
857 Because of the nature of this operation, where the proxy has no
859 idea what kind of data that is passed in and out through this
860 tunnel, this breaks some of the very few advantages that come
861 from using a proxy, such as caching. Many organizations prevent
862 this kind of tunneling to other destination port numbers than
863 443 (which is the default HTTPS port number).
864 Tunneling Through Proxy
867 As explained above, tunneling is required for SSL to work and
868 often even restricted to the operation intended for SSL; HTTPS.
869 This is however not the only time proxy-tunneling might offer
871 benefits to you or your application.
872 As tunneling opens a direct connection from your application to
874 the remote machine, it suddenly also re-introduces the ability
875 to do non-HTTP operations over an HTTP proxy. You can in fact
876 use things such as FTP upload or FTP custom commands this way.
877 Again, this is often prevented by the administrators of proxies
879 and is rarely allowed.
880 Tell libcurl to use proxy tunneling like this:
882 curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, 1L);
884 In fact, there might even be times when you want to do plain
886 HTTP operations using a tunnel like this, as it then enables you
887 to operate on the remote server instead of asking the proxy to
888 do so. libcurl will not stand in the way for such innovative
889 actions either!
890 Proxy Auto-Config
893 Netscape first came up with this. It is basically a web page
895 (usually using a .pac extension) with a Javascript that when
896 executed by the browser with the requested URL as input, returns
897 information to the browser on how to connect to the URL. The
898 returned information might be "DIRECT" (which means no proxy
899 should be used), "PROXY host:port" (to tell the browser where
900 the proxy for this particular URL is) or "SOCKS host:port" (to
901 direct the browser to a SOCKS proxy).
902 libcurl has no means to interpret or evaluate Javascript and
904 thus it doesn't support this. If you get yourself in a position
905 where you face this nasty invention, the following advice have
906 been mentioned and used in the past:
907 - Depending on the Javascript complexity, write up a script that
909 translates it to another language and execute that.
910 - Read the Javascript code and rewrite the same logic in another
912 language.
913 - Implement a Javascript interpreter; people have successfully
915 used the Mozilla Javascript engine in the past.
916 - Ask your admins to stop this, for a static proxy setup or sim‐
918 ilar.
919
922 Re-cycling the same easy handle several times when doing multiple
923 requests is the way to go.
924 After each single curl_easy_perform(3) operation, libcurl will keep the
926 connection alive and open. A subsequent request using the same easy
927 handle to the same host might just be able to use the already open con‐
928 nection! This reduces network impact a lot.
929 Even if the connection is dropped, all connections involving SSL to the
931 same host again, will benefit from libcurl's session ID cache that
932 drastically reduces re-connection time.
933 FTP connections that are kept alive save a lot of time, as the command-
935 response round-trips are skipped, and also you don't risk getting
936 blocked without permission to login again like on many FTP servers only
937 allowing N persons to be logged in at the same time.
938 libcurl caches DNS name resolving results, to make lookups of a previ‐
940 ously looked up name a lot faster.
941 Other interesting details that improve performance for subsequent
943 requests may also be added in the future.
944 Each easy handle will attempt to keep the last few connections alive
946 for a while in case they are to be used again. You can set the size of
947 this "cache" with the CURLOPT_MAXCONNECTS(3) option. Default is 5.
948 There is very seldom any point in changing this value, and if you think
949 of changing this it is often just a matter of thinking again.
950 To force your upcoming request to not use an already existing connec‐
952 tion (it will even close one first if there happens to be one alive to
953 the same host you're about to operate on), you can do that by setting
954 CURLOPT_FRESH_CONNECT(3) to 1. In a similar spirit, you can also forbid
955 the upcoming request to be "lying" around and possibly get re-used
956 after the request by setting CURLOPT_FORBID_REUSE(3) to 1.
957
960 When you use libcurl to do HTTP requests, it'll pass along a series of
961 headers automatically. It might be good for you to know and understand
962 these. You can replace or remove them by using the CURLOPT_HTTP‐
963 HEADER(3) option.
964 Host This header is required by HTTP 1.1 and even many 1.0 servers
967 and should be the name of the server we want to talk to. This
968 includes the port number if anything but default.
969 Accept "*/*".
972 Expect When doing POST requests, libcurl sets this header to "100-con‐
975 tinue" to ask the server for an "OK" message before it proceeds
976 with sending the data part of the post. If the POSTed data
977 amount is deemed "small", libcurl will not use this header.
978
981 There is an ongoing development today where more and more protocols are
982 built upon HTTP for transport. This has obvious benefits as HTTP is a
983 tested and reliable protocol that is widely deployed and has excellent
984 proxy-support.
985 When you use one of these protocols, and even when doing other kinds of
987 programming you may need to change the traditional HTTP (or FTP or...)
988 manners. You may need to change words, headers or various data.
989 libcurl is your friend here too.
991 CUSTOMREQUEST
994 If just changing the actual HTTP request keyword is what you
995 want, like when GET, HEAD or POST is not good enough for you,
996 CURLOPT_CUSTOMREQUEST(3) is there for you. It is very simple to
997 use:
998 curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNRE‐
1000 QUEST");
1001 When using the custom request, you change the request keyword of
1003 the actual request you are performing. Thus, by default you make
1004 a GET request but you can also make a POST operation (as
1005 described before) and then replace the POST keyword if you want
1006 to. You're the boss.
1007 Modify Headers
1010 HTTP-like protocols pass a series of headers to the server when
1011 doing the request, and you're free to pass any amount of extra
1012 headers that you think fit. Adding headers is this easy:
1013 struct curl_slist *headers=NULL; /* init to NULL is important */
1015 headers = curl_slist_append(headers, "Hey-server-hey: how are you?");
1017 headers = curl_slist_append(headers, "X-silly-content: yes");
1018 /* pass our list of custom made headers */
1020 curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
1021 curl_easy_perform(easyhandle); /* transfer http */
1023 curl_slist_free_all(headers); /* free the header list */
1025 ... and if you think some of the internally generated headers,
1027 such as Accept: or Host: don't contain the data you want them to
1028 contain, you can replace them by simply setting them too:
1029 headers = curl_slist_append(headers, "Accept: Agent-007");
1031 headers = curl_slist_append(headers, "Host: munged.host.line");
1032 Delete Headers
1035 If you replace an existing header with one with no contents, you
1036 will prevent the header from being sent. For instance, if you
1037 want to completely prevent the "Accept:" header from being sent,
1038 you can disable it with code similar to this:
1039 headers = curl_slist_append(headers, "Accept:");
1041 Both replacing and canceling internal headers should be done
1043 with careful consideration and you should be aware that you may
1044 violate the HTTP protocol when doing so.
1045 Enforcing chunked transfer-encoding
1048 By making sure a request uses the custom header "Transfer-Encod‐
1050 ing: chunked" when doing a non-GET HTTP operation, libcurl will
1051 switch over to "chunked" upload, even though the size of the
1052 data to upload might be known. By default, libcurl usually
1053 switches over to chunked upload automatically if the upload data
1054 size is unknown.
1055 HTTP Version
1058 All HTTP requests includes the version number to tell the server
1060 which version we support. libcurl speaks HTTP 1.1 by default.
1061 Some very old servers don't like getting 1.1-requests and when
1062 dealing with stubborn old things like that, you can tell libcurl
1063 to use 1.0 instead by doing something like this:
1064 curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION,
1066 CURL_HTTP_VERSION_1_0);
1067 FTP Custom Commands
1070 Not all protocols are HTTP-like, and thus the above may not help
1072 you when you want to make, for example, your FTP transfers to
1073 behave differently.
1074 Sending custom commands to an FTP server means that you need to
1076 send the commands exactly as the FTP server expects them (RFC959
1077 is a good guide here), and you can only use commands that work
1078 on the control-connection alone. All kinds of commands that
1079 require data interchange and thus need a data-connection must be
1080 left to libcurl's own judgement. Also be aware that libcurl will
1081 do its very best to change directory to the target directory
1082 before doing any transfer, so if you change directory (with CWD
1083 or similar) you might confuse libcurl and then it might not
1084 attempt to transfer the file in the correct remote directory.
1085 A little example that deletes a given file before an operation:
1087 headers = curl_slist_append(headers, "DELE file-to-remove");
1089 /* pass the list of custom commands to the handle */
1091 curl_easy_setopt(easyhandle, CURLOPT_QUOTE, headers);
1092 curl_easy_perform(easyhandle); /* transfer ftp data! */
1094 curl_slist_free_all(headers); /* free the header list */
1096 If you would instead want this operation (or chain of opera‐
1098 tions) to happen _after_ the data transfer took place the option
1099 to curl_easy_setopt(3) would instead be called CUR‐
1100 LOPT_POSTQUOTE(3) and used the exact same way.
1101 The custom FTP command will be issued to the server in the same
1103 order they are added to the list, and if a command gets an error
1104 code returned back from the server, no more commands will be
1105 issued and libcurl will bail out with an error code
1106 (CURLE_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE(3) to
1107 send commands before a transfer, no transfer will actually take
1108 place when a quote command has failed.
1109 If you set the CURLOPT_HEADER(3) to 1, you will tell libcurl to
1111 get information about the target file and output "headers" about
1112 it. The headers will be in "HTTP-style", looking like they do in
1113 HTTP.
1114 The option to enable headers or to run custom FTP commands may
1116 be useful to combine with CURLOPT_NOBODY(3). If this option is
1117 set, no actual file content transfer will be performed.
1118 FTP Custom CUSTOMREQUEST
1121 If you do want to list the contents of an FTP directory using
1122 your own defined FTP command, CURLOPT_CUSTOMREQUEST(3) will do
1123 just that. "NLST" is the default one for listing directories but
1124 you're free to pass in your idea of a good alternative.
1125
1128 In the HTTP sense, a cookie is a name with an associated value. A
1129 server sends the name and value to the client, and expects it to get
1130 sent back on every subsequent request to the server that matches the
1131 particular conditions set. The conditions include that the domain name
1132 and path match and that the cookie hasn't become too old.
1133 In real-world cases, servers send new cookies to replace existing ones
1135 to update them. Server use cookies to "track" users and to keep "ses‐
1136 sions".
1137 Cookies are sent from server to clients with the header Set-Cookie: and
1139 they're sent from clients to servers with the Cookie: header.
1140 To just send whatever cookie you want to a server, you can use CUR‐
1142 LOPT_COOKIE(3) to set a cookie string like this:
1143 curl_easy_setopt(easyhandle, CURLOPT_COOKIE, "name1=var1;
1145 name2=var2;");
1146 In many cases, that is not enough. You might want to dynamically save
1148 whatever cookies the remote server passes to you, and make sure those
1149 cookies are then used accordingly on later requests.
1150 One way to do this, is to save all headers you receive in a plain file
1152 and when you make a request, you tell libcurl to read the previous
1153 headers to figure out which cookies to use. Set the header file to read
1154 cookies from with CURLOPT_COOKIEFILE(3).
1155 The CURLOPT_COOKIEFILE(3) option also automatically enables the cookie
1157 parser in libcurl. Until the cookie parser is enabled, libcurl will not
1158 parse or understand incoming cookies and they will just be ignored.
1159 However, when the parser is enabled the cookies will be understood and
1160 the cookies will be kept in memory and used properly in subsequent
1161 requests when the same handle is used. Many times this is enough, and
1162 you may not have to save the cookies to disk at all. Note that the file
1163 you specify to CURLOPT_COOKIEFILE(3) doesn't have to exist to enable
1164 the parser, so a common way to just enable the parser and not read any
1165 cookies is to use the name of a file you know doesn't exist.
1166 If you would rather use existing cookies that you've previously
1168 received with your Netscape or Mozilla browsers, you can make libcurl
1169 use that cookie file as input. The CURLOPT_COOKIEFILE(3) is used for
1170 that too, as libcurl will automatically find out what kind of file it
1171 is and act accordingly.
1172 Perhaps the most advanced cookie operation libcurl offers, is saving
1174 the entire internal cookie state back into a Netscape/Mozilla formatted
1175 cookie file. We call that the cookie-jar. When you set a file name with
1176 CURLOPT_COOKIEJAR(3), that file name will be created and all received
1177 cookies will be stored in it when curl_easy_cleanup(3) is called. This
1178 enables cookies to get passed on properly between multiple handles
1179 without any information getting lost.
1180
1183 FTP transfers use a second TCP/IP connection for the data transfer.
1184 This is usually a fact you can forget and ignore but at times this fact
1185 will come back to haunt you. libcurl offers several different ways to
1186 customize how the second connection is being made.
1187 libcurl can either connect to the server a second time or tell the
1189 server to connect back to it. The first option is the default and it is
1190 also what works best for all the people behind firewalls, NATs or IP-
1191 masquerading setups. libcurl then tells the server to open up a new
1192 port and wait for a second connection. This is by default attempted
1193 with EPSV first, and if that doesn't work it tries PASV instead. (EPSV
1194 is an extension to the original FTP spec and does not exist nor work on
1195 all FTP servers.)
1196 You can prevent libcurl from first trying the EPSV command by setting
1198 CURLOPT_FTP_USE_EPSV(3) to zero.
1199 In some cases, you will prefer to have the server connect back to you
1201 for the second connection. This might be when the server is perhaps
1202 behind a firewall or something and only allows connections on a single
1203 port. libcurl then informs the remote server which IP address and port
1204 number to connect to. This is made with the CURLOPT_FTPPORT(3) option.
1205 If you set it to "-", libcurl will use your system's "default IP
1206 address". If you want to use a particular IP, you can set the full IP
1207 address, a host name to resolve to an IP address or even a local net‐
1208 work interface name that libcurl will get the IP address from.
1209 When doing the "PORT" approach, libcurl will attempt to use the EPRT
1211 and the LPRT before trying PORT, as they work with more protocols. You
1212 can disable this behavior by setting CURLOPT_FTP_USE_EPRT(3) to zero.
1213
1216 In addition to support HTTP multi-part form fields, the MIME API can be
1217 used to build structured e-mail messages and send them via SMTP or
1218 append such messages to IMAP directories.
1219 A structured e-mail message may contain several parts: some are dis‐
1221 played inline by the MUA, some are attachments. Parts can also be
1222 structured as multi-part, for example to include another e-mail message
1223 or to offer several text formats alternatives. This can be nested to
1224 any level.
1225 To build such a message, you prepare the nth-level multi-part and then
1227 include it as a source to the parent multi-part using function
1228 curl_mime_subparts(3). Once it has been bound to its parent multi-part,
1229 a nth-level multi-part belongs to it and should not be freed explic‐
1230 itly.
1231 E-mail messages data is not supposed to be non-ascii and line length is
1233 limited: fortunately, some transfer encodings are defined by the stan‐
1234 dards to support the transmission of such incompatible data. Function
1235 curl_mime_encoder(3) tells a part that its source data must be encoded
1236 before being sent. It also generates the corresponding header for that
1237 part. If the part data you want to send is already encoded in such a
1238 scheme, do not use this function (this would over-encode it), but
1239 explicitly set the corresponding part header.
1240 Upon sending such a message, libcurl prepends it with the header list
1242 set with CURLOPT_HTTPHEADER(3), as 0th-level mime part headers.
1243 Here is an example building an e-mail message with an inline plain/html
1245 text alternative and a file attachment encoded in base64:
1246 curl_mime *message = curl_mime_init(easyhandle);
1248 /* The inline part is an alternative proposing the html and the text
1250 versions of the e-mail. */
1251 curl_mime *alt = curl_mime_init(easyhandle);
1252 /* HTML message. */
1254 curl_mimepart *part = curl_mime_addpart(alt);
1255 curl_mime_data(part, "<html><body><p>This is HTML</p></body></html>",
1256 CURL_ZERO_TERMINATED);
1257 curl_mime_type(part, "text/html");
1258 /* Text message. */
1260 part = curl_mime_addpart(alt);
1261 curl_mime_data(part, "This is plain text message",
1262 CURL_ZERO_TERMINATED);
1263 /* Create the inline part. */
1265 part = curl_mime_addpart(message);
1266 curl_mime_subparts(part, alt);
1267 curl_mime_type(part, "multipart/alternative");
1268 struct curl_slist *headers = curl_slist_append(NULL,
1269 "Content-Disposition: inline");
1270 curl_mime_headers(part, headers, TRUE);
1271 /* Add the attachment. */
1273 part = curl_mime_addpart(message);
1274 curl_mime_filedata(part, "manual.pdf");
1275 curl_mime_encoder(part, "base64");
1276 /* Build the mail headers. */
1278 headers = curl_slist_append(NULL, "From: me@example.com");
1279 headers = curl_slist_append(headers, "To: you@example.com");
1280 /* Set these into the easy handle. */
1282 curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
1283 curl_easy_setopt(easyhandle, CURLOPT_MIMEPOST, mime);
1284 It should be noted that appending a message to an IMAP directory
1286 requires the message size to be known prior upload. It is therefore not
1287 possible to include parts with unknown data size in this context.
1288
1291 Some protocols provide "headers", meta-data separated from the normal
1292 data. These headers are by default not included in the normal data
1293 stream, but you can make them appear in the data stream by setting CUR‐
1294 LOPT_HEADER(3) to 1.
1295 What might be even more useful, is libcurl's ability to separate the
1297 headers from the data and thus make the callbacks differ. You can for
1298 example set a different pointer to pass to the ordinary write callback
1299 by setting CURLOPT_HEADERDATA(3).
1300 Or, you can set an entirely separate function to receive the headers,
1302 by using CURLOPT_HEADERFUNCTION(3).
1303 The headers are passed to the callback function one by one, and you can
1305 depend on that fact. It makes it easier for you to add custom header
1306 parsers etc.
1307 "Headers" for FTP transfers equal all the FTP server responses. They
1309 aren't actually true headers, but in this case we pretend they are! ;-)
1310
1313 See curl_easy_getinfo(3).
1314
1316 The easy interface as described in detail in this document is a syn‐
1317 chronous interface that transfers one file at a time and doesn't return
1318 until it is done.
1319 The multi interface, on the other hand, allows your program to transfer
1321 multiple files in both directions at the same time, without forcing you
1322 to use multiple threads. The name might make it seem that the multi
1323 interface is for multi-threaded programs, but the truth is almost the
1324 reverse. The multi interface allows a single-threaded application to
1325 perform the same kinds of multiple, simultaneous transfers that multi-
1326 threaded programs can perform. It allows many of the benefits of
1327 multi-threaded transfers without the complexity of managing and syn‐
1328 chronizing many threads.
1329 To complicate matters somewhat more, there are even two versions of the
1331 multi interface. The event based one, also called multi_socket and the
1332 "normal one" designed for using with select(). See the libcurl-multi.3
1333 man page for details on the multi_socket event based API, this descrip‐
1334 tion here is for the select() oriented one.
1335 To use this interface, you are better off if you first understand the
1337 basics of how to use the easy interface. The multi interface is simply
1338 a way to make multiple transfers at the same time by adding up multiple
1339 easy handles into a "multi stack".
1340 You create the easy handles you want, one for each concurrent transfer,
1342 and you set all the options just like you learned above, and then you
1343 create a multi handle with curl_multi_init(3) and add all those easy
1344 handles to that multi handle with curl_multi_add_handle(3).
1345 When you've added the handles you have for the moment (you can still
1347 add new ones at any time), you start the transfers by calling
1348 curl_multi_perform(3).
1349 curl_multi_perform(3) is asynchronous. It will only perform what can be
1351 done now and then return back control to your program. It is designed
1352 to never block. You need to keep calling the function until all trans‐
1353 fers are completed.
1354 The best usage of this interface is when you do a select() on all pos‐
1356 sible file descriptors or sockets to know when to call libcurl again.
1357 This also makes it easy for you to wait and respond to actions on your
1358 own application's sockets/handles. You figure out what to select() for
1359 by using curl_multi_fdset(3), that fills in a set of fd_set variables
1360 for you with the particular file descriptors libcurl uses for the
1361 moment.
1362 When you then call select(), it'll return when one of the file handles
1364 signal action and you then call curl_multi_perform(3) to allow libcurl
1365 to do what it wants to do. Take note that libcurl does also feature
1366 some time-out code so we advise you to never use very long timeouts on
1367 select() before you call curl_multi_perform(3) again. curl_multi_time‐
1368 out(3) is provided to help you get a suitable timeout period.
1369 Another precaution you should use: always call curl_multi_fdset(3)
1371 immediately before the select() call since the current set of file
1372 descriptors may change in any curl function invoke.
1373 If you want to stop the transfer of one of the easy handles in the
1375 stack, you can use curl_multi_remove_handle(3) to remove individual
1376 easy handles. Remember that easy handles should be
1377 curl_easy_cleanup(3)ed.
1378 When a transfer within the multi stack has finished, the counter of
1380 running transfers (as filled in by curl_multi_perform(3)) will
1381 decrease. When the number reaches zero, all transfers are done.
1382 curl_multi_info_read(3) can be used to get information about completed
1384 transfers. It then returns the CURLcode for each easy transfer, to
1385 allow you to figure out success on each individual transfer.
1386
1389 [ seeding, passwords, keys, certificates, ENGINE, ca certs ]
1390
1393 You can share some data between easy handles when the easy interface is
1394 used, and some data is share automatically when you use the multi
1395 interface.
1396 When you add easy handles to a multi handle, these easy handles will
1398 automatically share a lot of the data that otherwise would be kept on a
1399 per-easy handle basis when the easy interface is used.
1400 The DNS cache is shared between handles within a multi handle, making
1402 subsequent name resolving faster, and the connection pool that is kept
1403 to better allow persistent connections and connection re-use is also
1404 shared. If you're using the easy interface, you can still share these
1405 between specific easy handles by using the share interface, see
1406 libcurl-share(3).
1407 Some things are never shared automatically, not within multi handles,
1409 like for example cookies so the only way to share that is with the
1410 share interface.
1411
1413 [1] libcurl 7.10.3 and later have the ability to switch over to
1414 chunked Transfer-Encoding in cases where HTTP uploads are done
1415 with data of an unknown size.
1416 [2] This happens on Windows machines when libcurl is built and used
1418 as a DLL. However, you can still do this on Windows if you link
1419 with a static library.
1420 [3] The curl-config tool is generated at build-time (on Unix-like
1422 systems) and should be installed with the 'make install' or sim‐
1423 ilar instruction that installs the library, header files, man
1424 pages etc.
1425 [4] This behavior was different in versions before 7.17.0, where
1427 strings had to remain valid past the end of the
1428 curl_easy_setopt(3) call.
1429
1431 libcurl-errors(3), libcurl-multi(3), libcurl-easy(3)
1432libcurl 7.71.1 October 31, 2019 libcurl-tutorial(3)