1libcurl-tutorial(3) libcurl libcurl-tutorial(3)
2
6 libcurl-tutorial - libcurl programming tutorial
7
9 This document attempts to describe the general principles and some ba‐
10 sic approaches to consider when programming with libcurl. The text will
11 focus mainly on the C interface but might apply fairly well on other
12 interfaces as well as they usually follow the C one pretty closely.
13 This document will refer to 'the user' as the person writing the source
15 code that uses libcurl. That would probably be you or someone in your
16 position. What will be generally referred to as 'the program' will be
17 the collected source code that you write that is using libcurl for
18 transfers. The program is outside libcurl and libcurl is outside of the
19 program.
20 To get more details on all options and functions described herein,
22 please refer to their respective man pages.
23
26 There are many different ways to build C programs. This chapter will
27 assume a Unix style build process. If you use a different build system,
28 you can still read this to get general information that may apply to
29 your environment as well.
30 Compiling the Program
32 Your compiler needs to know where the libcurl headers are lo‐
33 cated. Therefore you must set your compiler's include path to
34 point to the directory where you installed them. The 'curl-con‐
35 fig'[3] tool can be used to get this information:
36 $ curl-config --cflags
37 Linking the Program with libcurl
39 When having compiled the program, you need to link your object
40 files to create a single executable. For that to succeed, you
41 need to link with libcurl and possibly also with other libraries
42 that libcurl itself depends on. Like the OpenSSL libraries, but
43 even some standard OS libraries may be needed on the command
44 line. To figure out which flags to use, once again the 'curl-
45 config' tool comes to the rescue:
46 $ curl-config --libs
47 SSL or Not
49 libcurl can be built and customized in many ways. One of the
50 things that varies from different libraries and builds is the
51 support for SSL-based transfers, like HTTPS and FTPS. If a sup‐
52 ported SSL library was detected properly at build-time, libcurl
53 will be built with SSL support. To figure out if an installed
54 libcurl has been built with SSL support enabled, use 'curl-con‐
55 fig' like this:
56 $ curl-config --feature
57 And if SSL is supported, the keyword SSL will be written to std‐
58 out, possibly together with a few other features that could be
59 either on or off on for different libcurls.
60 See also the "Features libcurl Provides" further down.
62 autoconf macro
64 When you write your configure script to detect libcurl and setup
65 variables accordingly, we offer a macro that probably does ev‐
66 erything you need in this area. See docs/libcurl/libcurl.m4 file
67 - it includes docs on how to use it.
68
71 The people behind libcurl have put a considerable effort to make
72 libcurl work on a large amount of different operating systems and envi‐
73 ronments.
74 You program libcurl the same way on all platforms that libcurl runs on.
76 There are only a few minor details that differ. If you just make sure
77 to write your code portable enough, you can create a portable program.
78 libcurl should not stop you from that.
79
82 The program must initialize some of the libcurl functionality globally.
83 That means it should be done exactly once, no matter how many times you
84 intend to use the library. Once for your program's entire life time.
85 This is done using
86 curl_global_init()
87 and it takes one parameter which is a bit pattern that tells libcurl
88 what to initialize. Using CURL_GLOBAL_ALL will make it initialize all
89 known internal sub modules, and might be a good default option. The
90 current two bits that are specified are:
91 CURL_GLOBAL_WIN32
93 which only does anything on Windows machines. When used
94 on a Windows machine, it will make libcurl initialize the
95 win32 socket stuff. Without having that initialized prop‐
96 erly, your program cannot use sockets properly. You
97 should only do this once for each application, so if your
98 program already does this or of another library in use
99 does it, you should not tell libcurl to do this as well.
100 CURL_GLOBAL_SSL
102 which only does anything on libcurls compiled and built
103 SSL-enabled. On these systems, this will make libcurl
104 initialize the SSL library properly for this application.
105 This only needs to be done once for each application so
106 if your program or another library already does this,
107 this bit should not be needed.
108 libcurl has a default protection mechanism that detects if
110 curl_global_init(3) has not been called by the time curl_easy_per‐
111 form(3) is called and if that is the case, libcurl runs the function
112 itself with a guessed bit pattern. Please note that depending solely on
113 this is not considered nice nor good.
114 When the program no longer uses libcurl, it should call
116 curl_global_cleanup(3), which is the opposite of the init call. It will
117 then do the reversed operations to cleanup the resources the
118 curl_global_init(3) call initialized.
119 Repeated calls to curl_global_init(3) and curl_global_cleanup(3) should
121 be avoided. They should only be called once each.
122
125 It is considered best-practice to determine libcurl features at runtime
126 rather than at build-time (if possible of course). By calling curl_ver‐
127 sion_info(3) and checking out the details of the returned struct, your
128 program can figure out exactly what the currently running libcurl sup‐
129 ports.
130
133 libcurl first introduced the so called easy interface. All operations
134 in the easy interface are prefixed with 'curl_easy'. The easy interface
135 lets you do single transfers with a synchronous and blocking function
136 call.
137 libcurl also offers another interface that allows multiple simultaneous
139 transfers in a single thread, the so called multi interface. More about
140 that interface is detailed in a separate chapter further down. You
141 still need to understand the easy interface first, so please continue
142 reading for better understanding.
143
145 To use the easy interface, you must first create yourself an easy han‐
146 dle. You need one handle for each easy session you want to perform. Ba‐
147 sically, you should use one handle for every thread you plan to use for
148 transferring. You must never share the same handle in multiple threads.
149 Get an easy handle with
151 handle = curl_easy_init();
152 It returns an easy handle. Using that you proceed to the next step:
153 setting up your preferred actions. A handle is just a logic entity for
154 the upcoming transfer or series of transfers.
155 You set properties and options for this handle using curl_easy_se‐
157 topt(3). They control how the subsequent transfer or transfers will be
158 made. Options remain set in the handle until set again to something
159 different. They are sticky. Multiple requests using the same handle
160 will use the same options.
161 If you at any point would like to blank all previously set options for
163 a single easy handle, you can call curl_easy_reset(3) and you can also
164 make a clone of an easy handle (with all its set options) using
165 curl_easy_duphandle(3).
166 Many of the options you set in libcurl are "strings", pointers to data
168 terminated with a zero byte. When you set strings with curl_easy_se‐
169 topt(3), libcurl makes its own copy so that they do not need to be kept
170 around in your application after being set[4].
171 One of the most basic properties to set in the handle is the URL. You
173 set your preferred URL to transfer with CURLOPT_URL(3) in a manner sim‐
174 ilar to:
175 curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/");
177 Let's assume for a while that you want to receive data as the URL iden‐
179 tifies a remote resource you want to get here. Since you write a sort
180 of application that needs this transfer, I assume that you would like
181 to get the data passed to you directly instead of simply getting it
182 passed to stdout. So, you write your own function that matches this
183 prototype:
184 size_t write_data(void *buffer, size_t size, size_t nmemb, void *userp);
185 You tell libcurl to pass all data to this function by issuing a func‐
186 tion similar to this:
187 curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, write_data);
188 You can control what data your callback function gets in the fourth ar‐
189 gument by setting another property:
190 curl_easy_setopt(handle, CURLOPT_WRITEDATA, &internal_struct);
191 Using that property, you can easily pass local data between your appli‐
192 cation and the function that gets invoked by libcurl. libcurl itself
193 will not touch the data you pass with CURLOPT_WRITEDATA(3).
194 libcurl offers its own default internal callback that will take care of
196 the data if you do not set the callback with CURLOPT_WRITEFUNCTION(3).
197 It will then simply output the received data to stdout. You can have
198 the default callback write the data to a different file handle by pass‐
199 ing a 'FILE *' to a file opened for writing with the CURLOPT_WRITE‐
200 DATA(3) option.
201 Now, we need to take a step back and have a deep breath. Here's one of
203 those rare platform-dependent nitpicks. Did you spot it? On some plat‐
204 forms[2], libcurl will not be able to operate on files opened by the
205 program. Thus, if you use the default callback and pass in an open file
206 with CURLOPT_WRITEDATA(3), it will crash. You should therefore avoid
207 this to make your program run fine virtually everywhere.
208 (CURLOPT_WRITEDATA(3) was formerly known as CURLOPT_FILE. Both names
210 still work and do the same thing).
211 If you are using libcurl as a win32 DLL, you MUST use the CUR‐
213 LOPT_WRITEFUNCTION(3) if you set CURLOPT_WRITEDATA(3) - or you will ex‐
214 perience crashes.
215 There are of course many more options you can set, and we will get back
217 to a few of them later. Let's instead continue to the actual transfer:
218 success = curl_easy_perform(handle);
219 curl_easy_perform(3) will connect to the remote site, do the necessary
220 commands and receive the transfer. Whenever it receives data, it calls
221 the callback function we previously set. The function may get one byte
222 at a time, or it may get many kilobytes at once. libcurl delivers as
223 much as possible as often as possible. Your callback function should
224 return the number of bytes it "took care of". If that is not the same
225 amount of bytes that was passed to it, libcurl will abort the operation
226 and return with an error code.
227 When the transfer is complete, the function returns a return code that
229 informs you if it succeeded in its mission or not. If a return code is
230 not enough for you, you can use the CURLOPT_ERRORBUFFER(3) to point
231 libcurl to a buffer of yours where it will store a human readable error
232 message as well.
233 If you then want to transfer another file, the handle is ready to be
235 used again. Mind you, it is even preferred that you re-use an existing
236 handle if you intend to make another transfer. libcurl will then at‐
237 tempt to re-use the previous connection.
238 For some protocols, downloading a file can involve a complicated
240 process of logging in, setting the transfer mode, changing the current
241 directory and finally transferring the file data. libcurl takes care of
242 all that complication for you. Given simply the URL to a file, libcurl
243 will take care of all the details needed to get the file moved from one
244 machine to another.
245
248 libcurl is thread safe but there are a few exceptions. Refer to
249 libcurl-thread(3) for more information.
250
253 There will always be times when the transfer fails for some reason. You
254 might have set the wrong libcurl option or misunderstood what the
255 libcurl option actually does, or the remote server might return non-
256 standard replies that confuse the library which then confuses your pro‐
257 gram.
258 There's one golden rule when these things occur: set the CURLOPT_VER‐
260 BOSE(3) option to 1. it will cause the library to spew out the entire
261 protocol details it sends, some internal info and some received proto‐
262 col data as well (especially when using FTP). If you are using HTTP,
263 adding the headers in the received output to study is also a clever way
264 to get a better understanding why the server behaves the way it does.
265 Include headers in the normal body output with CURLOPT_HEADER(3) set 1.
266 Of course, there are bugs left. We need to know about them to be able
268 to fix them, so we are quite dependent on your bug reports. When you do
269 report suspected bugs in libcurl, please include as many details as you
270 possibly can: a protocol dump that CURLOPT_VERBOSE(3) produces, library
271 version, as much as possible of your code that uses libcurl, operating
272 system name and version, compiler name and version etc.
273 If CURLOPT_VERBOSE(3) is not enough, you increase the level of debug
275 data your application receive by using the CURLOPT_DEBUGFUNCTION(3).
276 Getting some in-depth knowledge about the protocols involved is never
278 wrong, and if you are trying to do funny things, you might understand
279 libcurl and how to use it better if you study the appropriate RFC docu‐
280 ments at least briefly.
281
284 libcurl tries to keep a protocol independent approach to most trans‐
285 fers, thus uploading to a remote FTP site is similar to uploading data
286 to an HTTP server with a PUT request.
287 Of course, first you either create an easy handle or you re-use one ex‐
289 isting one. Then you set the URL to operate on just like before. This
290 is the remote URL, that we now will upload.
291 Since we write an application, we most likely want libcurl to get the
293 upload data by asking us for it. To make it do that, we set the read
294 callback and the custom pointer libcurl will pass to our read callback.
295 The read callback should have a prototype similar to:
296 size_t function(char *bufptr, size_t size, size_t nitems, void *userp);
297 Where bufptr is the pointer to a buffer we fill in with data to upload
298 and size*nitems is the size of the buffer and therefore also the maxi‐
299 mum amount of data we can return to libcurl in this call. The userp
300 pointer is the custom pointer we set to point to a struct of ours to
301 pass private data between the application and the callback.
302 curl_easy_setopt(handle, CURLOPT_READFUNCTION, read_function);
303 curl_easy_setopt(handle, CURLOPT_READDATA, &filedata);
305 Tell libcurl that we want to upload:
306 curl_easy_setopt(handle, CURLOPT_UPLOAD, 1L);
307 A few protocols will not behave properly when uploads are done without
308 any prior knowledge of the expected file size. So, set the upload file
309 size using the CURLOPT_INFILESIZE_LARGE(3) for all known file sizes
310 like this[1]:
311 /* in this example, file_size must be an curl_off_t variable */
313 curl_easy_setopt(handle, CURLOPT_INFILESIZE_LARGE, file_size);
314 When you call curl_easy_perform(3) this time, it will perform all the
316 necessary operations and when it has invoked the upload it will call
317 your supplied callback to get the data to upload. The program should
318 return as much data as possible in every invoke, as that is likely to
319 make the upload perform as fast as possible. The callback should return
320 the number of bytes it wrote in the buffer. Returning 0 will signal the
321 end of the upload.
322
325 Many protocols use or even require that user name and password are pro‐
326 vided to be able to download or upload the data of your choice. libcurl
327 offers several ways to specify them.
328 Most protocols support that you specify the name and password in the
330 URL itself. libcurl will detect this and use them accordingly. This is
331 written like this:
332 protocol://user:password@example.com/path/
333 If you need any odd letters in your user name or password, you should
334 enter them URL encoded, as %XX where XX is a two-digit hexadecimal num‐
335 ber.
336 libcurl also provides options to set various passwords. The user name
338 and password as shown embedded in the URL can instead get set with the
339 CURLOPT_USERPWD(3) option. The argument passed to libcurl should be a
340 char * to a string in the format "user:password". In a manner like
341 this:
342 curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret");
343 Another case where name and password might be needed at times, is for
344 those users who need to authenticate themselves to a proxy they use.
345 libcurl offers another option for this, the CURLOPT_PROXYUSERPWD(3). It
346 is used quite similar to the CURLOPT_USERPWD(3) option like this:
347 curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
348 There's a long time Unix "standard" way of storing FTP user names and
349 passwords, namely in the $HOME/.netrc file (on Windows, libcurl also
350 checks the %USERPROFILE% environment variable if %HOME% is unset, and
351 tries "_netrc" as name). The file should be made private so that only
352 the user may read it (see also the "Security Considerations" chapter),
353 as it might contain the password in plain text. libcurl has the ability
354 to use this file to figure out what set of user name and password to
355 use for a particular host. As an extension to the normal functionality,
356 libcurl also supports this file for non-FTP protocols such as HTTP. To
357 make curl use this file, use the CURLOPT_NETRC(3) option:
358 curl_easy_setopt(handle, CURLOPT_NETRC, 1L);
359 And a basic example of how such a .netrc file may look like:
360 machine myhost.mydomain.com
362 login userlogin
363 password secretword
364 All these examples have been cases where the password has been op‐
366 tional, or at least you could leave it out and have libcurl attempt to
367 do its job without it. There are times when the password is not op‐
368 tional, like when you are using an SSL private key for secure trans‐
369 fers.
370 To pass the known private key password to libcurl:
372 curl_easy_setopt(handle, CURLOPT_KEYPASSWD, "keypassword");
373
375 The previous chapter showed how to set user name and password for get‐
376 ting URLs that require authentication. When using the HTTP protocol,
377 there are many different ways a client can provide those credentials to
378 the server and you can control which way libcurl will (attempt to) use
379 them. The default HTTP authentication method is called 'Basic', which
380 is sending the name and password in clear-text in the HTTP request,
381 base64-encoded. This is insecure.
382 At the time of this writing, libcurl can be built to use: Basic, Di‐
384 gest, NTLM, Negotiate (SPNEGO). You can tell libcurl which one to use
385 with CURLOPT_HTTPAUTH(3) as in:
386 curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
387 And when you send authentication to a proxy, you can also set authenti‐
388 cation type the same way but instead with CURLOPT_PROXYAUTH(3):
389 curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
390 Both these options allow you to set multiple types (by ORing them to‐
391 gether), to make libcurl pick the most secure one out of the types the
392 server/proxy claims to support. This method does however add a round-
393 trip since libcurl must first ask the server what it supports:
394 curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC);
395 For convenience, you can use the CURLAUTH_ANY define (instead of a list
396 with specific types) which allows libcurl to use whatever method it
397 wants.
398 When asking for multiple types, libcurl will pick the available one it
400 considers "best" in its own internal order of preference.
401
404 We get many questions regarding how to issue HTTP POSTs with libcurl
405 the proper way. This chapter will thus include examples using both dif‐
406 ferent versions of HTTP POST that libcurl supports.
407 The first version is the simple POST, the most common version, that
409 most HTML pages using the <form> tag uses. We provide a pointer to the
410 data and tell libcurl to post it all to the remote site:
411 char *data="name=daniel&project=curl";
413 curl_easy_setopt(handle, CURLOPT_POSTFIELDS, data);
414 curl_easy_setopt(handle, CURLOPT_URL, "http://posthere.com/");
415 curl_easy_perform(handle); /* post away! */
417 Simple enough, huh? Since you set the POST options with the CUR‐
419 LOPT_POSTFIELDS(3), this automatically switches the handle to use POST
420 in the upcoming request.
421 What if you want to post binary data that also requires you to set the
423 Content-Type: header of the post? Well, binary posts prevent libcurl
424 from being able to do strlen() on the data to figure out the size, so
425 therefore we must tell libcurl the size of the post data. Setting head‐
426 ers in libcurl requests are done in a generic way, by building a list
427 of our own headers and then passing that list to libcurl.
428 struct curl_slist *headers=NULL;
430 headers = curl_slist_append(headers, "Content-Type: text/xml");
431 /* post binary data */
433 curl_easy_setopt(handle, CURLOPT_POSTFIELDS, binaryptr);
434 /* set the size of the postfields data */
436 curl_easy_setopt(handle, CURLOPT_POSTFIELDSIZE, 23L);
437 /* pass our list of custom made headers */
439 curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
440 curl_easy_perform(handle); /* post away! */
442 curl_slist_free_all(headers); /* free the header list */
444 While the simple examples above cover the majority of all cases where
446 HTTP POST operations are required, they do not do multi-part formposts.
447 Multi-part formposts were introduced as a better way to post (possibly
448 large) binary data and were first documented in the RFC 1867 (updated
449 in RFC 2388). they are called multi-part because they are built by a
450 chain of parts, each part being a single unit of data. Each part has
451 its own name and contents. You can in fact create and post a multi-part
452 formpost with the regular libcurl POST support described above, but
453 that would require that you build a formpost yourself and provide to
454 libcurl. To make that easier, libcurl provides a MIME API consisting in
455 several functions: using those, you can create and fill a multi-part
456 form. Function curl_mime_init(3) creates a multi-part body; you can
457 then append new parts to a multi-part body using curl_mime_addpart(3).
458 There are three possible data sources for a part: memory using
459 curl_mime_data(3), file using curl_mime_filedata(3) and user-defined
460 data read callback using curl_mime_data_cb(3). curl_mime_name(3) sets
461 a part's (i.e.: form field) name, while curl_mime_filename(3) fills in
462 the remote file name. With curl_mime_type(3), you can tell the MIME
463 type of a part, curl_mime_headers(3) allows defining the part's head‐
464 ers. When a multi-part body is no longer needed, you can destroy it us‐
465 ing curl_mime_free(3).
466 The following example sets two simple text parts with plain textual
468 contents, and then a file with binary contents and uploads the whole
469 thing.
470 curl_mime *multipart = curl_mime_init(handle);
472 curl_mimepart *part = curl_mime_addpart(multipart);
473 curl_mime_name(part, "name");
474 curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
475 part = curl_mime_addpart(multipart);
476 curl_mime_name(part, "project");
477 curl_mime_data(part, "curl", CURL_ZERO_TERMINATED);
478 part = curl_mime_addpart(multipart);
479 curl_mime_name(part, "logotype-image");
480 curl_mime_filedata(part, "curl.png");
481 /* Set the form info */
483 curl_easy_setopt(handle, CURLOPT_MIMEPOST, multipart);
484 curl_easy_perform(handle); /* post away! */
486 /* free the post data again */
488 curl_mime_free(multipart);
489 To post multiple files for a single form field, you must supply each
491 file in a separate part, all with the same field name. Although func‐
492 tion curl_mime_subparts(3) implements nested multi-parts, this way of
493 multiple files posting is deprecated by RFC 7578, chapter 4.3.
494 To set the data source from an already opened FILE pointer, use:
496 curl_mime_data_cb(part, filesize, (curl_read_callback) fread,
498 (curl_seek_callback) fseek, NULL, filepointer);
499 A deprecated curl_formadd(3) function is still supported in libcurl.
501 It should however not be used anymore for new designs and programs us‐
502 ing it ought to be converted to the MIME API. It is however described
503 here as an aid to conversion.
504 Using curl_formadd, you add parts to the form. When you are done adding
506 parts, you post the whole form.
507 The MIME API example above is expressed as follows using this function:
509 struct curl_httppost *post=NULL;
511 struct curl_httppost *last=NULL;
512 curl_formadd(&post, &last,
513 CURLFORM_COPYNAME, "name",
514 CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
515 curl_formadd(&post, &last,
516 CURLFORM_COPYNAME, "project",
517 CURLFORM_COPYCONTENTS, "curl", CURLFORM_END);
518 curl_formadd(&post, &last,
519 CURLFORM_COPYNAME, "logotype-image",
520 CURLFORM_FILECONTENT, "curl.png", CURLFORM_END);
521 /* Set the form info */
523 curl_easy_setopt(handle, CURLOPT_HTTPPOST, post);
524 curl_easy_perform(handle); /* post away! */
526 /* free the post data again */
528 curl_formfree(post);
529 Multipart formposts are chains of parts using MIME-style separators and
531 headers. It means that each one of these separate parts get a few head‐
532 ers set that describe the individual content-type, size etc. To enable
533 your application to handicraft this formpost even more, libcurl allows
534 you to supply your own set of custom headers to such an individual form
535 part. You can of course supply headers to as many parts as you like,
536 but this little example will show how you set headers to one specific
537 part when you add that to the post handle:
538 struct curl_slist *headers=NULL;
540 headers = curl_slist_append(headers, "Content-Type: text/xml");
541 curl_formadd(&post, &last,
543 CURLFORM_COPYNAME, "logotype-image",
544 CURLFORM_FILECONTENT, "curl.xml",
545 CURLFORM_CONTENTHEADER, headers,
546 CURLFORM_END);
547 curl_easy_perform(handle); /* post away! */
549 curl_formfree(post); /* free post */
551 curl_slist_free_all(headers); /* free custom header list */
552 Since all options on an easy handle are "sticky", they remain the same
554 until changed even if you do call curl_easy_perform(3), you may need to
555 tell curl to go back to a plain GET request if you intend to do one as
556 your next request. You force an easy handle to go back to GET by using
557 the CURLOPT_HTTPGET(3) option:
558 curl_easy_setopt(handle, CURLOPT_HTTPGET, 1L);
559 Just setting CURLOPT_POSTFIELDS(3) to "" or NULL will *not* stop
560 libcurl from doing a POST. It will just make it POST without any data
561 to send!
562
565 Four rules have to be respected in building the multi-part:
566 - The easy handle must be created before building the multi-part.
567 - The multi-part is always created by a call to curl_mime_init(handle).
568 - Each part is created by a call to curl_mime_addpart(multipart).
569 - When complete, the multi-part must be bound to the easy handle using
570 CURLOPT_MIMEPOST(3) instead of CURLOPT_HTTPPOST(3).
571 Here are some example of curl_formadd calls to MIME API sequences:
573 curl_formadd(&post, &last,
575 CURLFORM_COPYNAME, "id",
576 CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
577 CURLFORM_CONTENTHEADER, headers,
578 CURLFORM_END);
579 becomes:
580 part = curl_mime_addpart(multipart);
581 curl_mime_name(part, "id");
582 curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
583 curl_mime_headers(part, headers, FALSE);
584 Setting the last curl_mime_headers argument to TRUE would have caused
586 the headers to be automatically released upon destroyed the multi-part,
587 thus saving a clean-up call to curl_slist_free_all(3).
588 curl_formadd(&post, &last,
590 CURLFORM_PTRNAME, "logotype-image",
591 CURLFORM_FILECONTENT, "-",
592 CURLFORM_END);
593 becomes:
594 part = curl_mime_addpart(multipart);
595 curl_mime_name(part, "logotype-image");
596 curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin);
597 curl_mime_name always copies the field name. The special file name "-"
599 is not supported by curl_mime_file: to read an open file, use a call‐
600 back source using fread(). The transfer will be chunked since the data
601 size is unknown.
602 curl_formadd(&post, &last,
604 CURLFORM_COPYNAME, "datafile[]",
605 CURLFORM_FILE, "file1",
606 CURLFORM_FILE, "file2",
607 CURLFORM_END);
608 becomes:
609 part = curl_mime_addpart(multipart);
610 curl_mime_name(part, "datafile[]");
611 curl_mime_filedata(part, "file1");
612 part = curl_mime_addpart(multipart);
613 curl_mime_name(part, "datafile[]");
614 curl_mime_filedata(part, "file2");
615 The deprecated multipart/mixed implementation of multiple files field
617 is translated to two distinct parts with the same name.
618 curl_easy_setopt(handle, CURLOPT_READFUNCTION, myreadfunc);
620 curl_formadd(&post, &last,
621 CURLFORM_COPYNAME, "stream",
622 CURLFORM_STREAM, arg,
623 CURLFORM_CONTENTLEN, (curl_off_t) datasize,
624 CURLFORM_FILENAME, "archive.zip",
625 CURLFORM_CONTENTTYPE, "application/zip",
626 CURLFORM_END);
627 becomes:
628 part = curl_mime_addpart(multipart);
629 curl_mime_name(part, "stream");
630 curl_mime_data_cb(part, (curl_off_t) datasize,
631 myreadfunc, NULL, NULL, arg);
632 curl_mime_filename(part, "archive.zip");
633 curl_mime_type(part, "application/zip");
634 CURLOPT_READFUNCTION callback is not used: it is replace by directly
636 setting the part source data from the callback read function.
637 curl_formadd(&post, &last,
639 CURLFORM_COPYNAME, "memfile",
640 CURLFORM_BUFFER, "memfile.bin",
641 CURLFORM_BUFFERPTR, databuffer,
642 CURLFORM_BUFFERLENGTH, (long) sizeof databuffer,
643 CURLFORM_END);
644 becomes:
645 part = curl_mime_addpart(multipart);
646 curl_mime_name(part, "memfile");
647 curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer);
648 curl_mime_filename(part, "memfile.bin");
649 curl_mime_data always copies the initial data: data buffer is thus free
651 for immediate reuse.
652 curl_formadd(&post, &last,
654 CURLFORM_COPYNAME, "message",
655 CURLFORM_FILECONTENT, "msg.txt",
656 CURLFORM_END);
657 becomes:
658 part = curl_mime_addpart(multipart);
659 curl_mime_name(part, "message");
660 curl_mime_filedata(part, "msg.txt");
661 curl_mime_filename(part, NULL);
662 Use of curl_mime_filedata sets the remote file name as a side effect:
664 it is therefore necessary to clear it for CURLFORM_FILECONTENT emula‐
665 tion.
666
669 For historical and traditional reasons, libcurl has a built-in progress
670 meter that can be switched on and then makes it present a progress me‐
671 ter in your terminal.
672 Switch on the progress meter by, oddly enough, setting CURLOPT_NO‐
674 PROGRESS(3) to zero. This option is set to 1 by default.
675 For most applications however, the built-in progress meter is useless
677 and what instead is interesting is the ability to specify a progress
678 callback. The function pointer you pass to libcurl will then be called
679 on irregular intervals with information about the current transfer.
680 Set the progress callback by using CURLOPT_PROGRESSFUNCTION(3). And
682 pass a pointer to a function that matches this prototype:
683 int progress_callback(void *clientp,
685 double dltotal,
686 double dlnow,
687 double ultotal,
688 double ulnow);
689 If any of the input arguments is unknown, a 0 will be passed. The first
691 argument, the 'clientp' is the pointer you pass to libcurl with CUR‐
692 LOPT_PROGRESSDATA(3). libcurl will not touch it.
693
696 There's basically only one thing to keep in mind when using C++ instead
697 of C when interfacing libcurl:
698 The callbacks CANNOT be non-static class member functions
700 Example C++ code:
702 class AClass {
704 static size_t write_data(void *ptr, size_t size, size_t nmemb,
705 void *ourpointer)
706 {
707 /* do what you want with the data */
708 }
709 }
710
713 What "proxy" means according to Merriam-Webster: "a person authorized
714 to act for another" but also "the agency, function, or office of a
715 deputy who acts as a substitute for another".
716 Proxies are exceedingly common these days. Companies often only offer
718 Internet access to employees through their proxies. Network clients or
719 user-agents ask the proxy for documents, the proxy does the actual re‐
720 quest and then it returns them.
721 libcurl supports SOCKS and HTTP proxies. When a given URL is wanted,
723 libcurl will ask the proxy for it instead of trying to connect to the
724 actual host identified in the URL.
725 If you are using a SOCKS proxy, you may find that libcurl does not
727 quite support all operations through it.
728 For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain
730 restrictions on what can actually happen. A requested URL that might
731 not be a HTTP URL will be still be passed to the HTTP proxy to deliver
732 back to libcurl. This happens transparently, and an application may not
733 need to know. I say "may", because at times it is important to under‐
734 stand that all operations over an HTTP proxy use the HTTP protocol. For
735 example, you cannot invoke your own custom FTP commands or even proper
736 FTP directory listings.
737 Proxy Options
740 To tell libcurl to use a proxy at a given port number:
742 curl_easy_setopt(handle, CURLOPT_PROXY, "proxy-host.com:8080");
743 Some proxies require user authentication before allowing a re‐
744 quest, and you pass that information similar to this:
745 curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "user:password");
746 If you want to, you can specify the host name only in the CUR‐
747 LOPT_PROXY(3) option, and set the port number separately with
748 CURLOPT_PROXYPORT(3).
749 Tell libcurl what kind of proxy it is with CURLOPT_PROXYTYPE(3)
751 (if not, it will default to assume an HTTP proxy):
752 curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4);
753 Environment Variables
755 libcurl automatically checks and uses a set of environment vari‐
757 ables to know what proxies to use for certain protocols. The
758 names of the variables are following an old tradition and are
759 built up as "[protocol]_proxy" (note the lower casing). Which
760 makes the variable 'http_proxy' checked for a name of a proxy to
761 use when the input URL is HTTP. Following the same rule, the
762 variable named 'ftp_proxy' is checked for FTP URLs. Again, the
763 proxies are always HTTP proxies, the different names of the
764 variables simply allows different HTTP proxies to be used.
765 The proxy environment variable contents should be in the format
767 "[protocol://][user:password@]machine[:port]". Where the proto‐
768 col:// part specifies which type of proxy it is, and the op‐
769 tional port number specifies on which port the proxy operates.
770 If not specified, the internal default port number will be used
771 and that is most likely not the one you would like it to be.
772 There are two special environment variables. 'all_proxy' is what
774 sets proxy for any URL in case the protocol specific variable
775 was not set, and 'no_proxy' defines a list of hosts that should
776 not use a proxy even though a variable may say so. If 'no_proxy'
777 is a plain asterisk ("*") it matches all hosts.
778 To explicitly disable libcurl's checking for and using the proxy
780 environment variables, set the proxy name to "" - an empty
781 string - with CURLOPT_PROXY(3).
782 SSL and Proxies
784 SSL is for secure point-to-point connections. This involves
786 strong encryption and similar things, which effectively makes it
787 impossible for a proxy to operate as a "man in between" which
788 the proxy's task is, as previously discussed. Instead, the only
789 way to have SSL work over an HTTP proxy is to ask the proxy to
790 tunnel everything through without being able to check or fiddle
791 with the traffic.
792 Opening an SSL connection over an HTTP proxy is therefore a mat‐
794 ter of asking the proxy for a straight connection to the target
795 host on a specified port. This is made with the HTTP request
796 CONNECT. ("please dear proxy, connect me to that remote host").
797 Because of the nature of this operation, where the proxy has no
799 idea what kind of data that is passed in and out through this
800 tunnel, this breaks some of the few advantages that come from
801 using a proxy, such as caching. Many organizations prevent this
802 kind of tunneling to other destination port numbers than 443
803 (which is the default HTTPS port number).
804 Tunneling Through Proxy
807 As explained above, tunneling is required for SSL to work and
808 often even restricted to the operation intended for SSL; HTTPS.
809 This is however not the only time proxy-tunneling might offer
811 benefits to you or your application.
812 As tunneling opens a direct connection from your application to
814 the remote machine, it suddenly also re-introduces the ability
815 to do non-HTTP operations over an HTTP proxy. You can in fact
816 use things such as FTP upload or FTP custom commands this way.
817 Again, this is often prevented by the administrators of proxies
819 and is rarely allowed.
820 Tell libcurl to use proxy tunneling like this:
822 curl_easy_setopt(handle, CURLOPT_HTTPPROXYTUNNEL, 1L);
823 In fact, there might even be times when you want to do plain
824 HTTP operations using a tunnel like this, as it then enables you
825 to operate on the remote server instead of asking the proxy to
826 do so. libcurl will not stand in the way for such innovative ac‐
827 tions either!
828 Proxy Auto-Config
831 Netscape first came up with this. It is basically a web page
833 (usually using a .pac extension) with a JavaScript that when ex‐
834 ecuted by the browser with the requested URL as input, returns
835 information to the browser on how to connect to the URL. The re‐
836 turned information might be "DIRECT" (which means no proxy
837 should be used), "PROXY host:port" (to tell the browser where
838 the proxy for this particular URL is) or "SOCKS host:port" (to
839 direct the browser to a SOCKS proxy).
840 libcurl has no means to interpret or evaluate JavaScript and
842 thus it does not support this. If you get yourself in a position
843 where you face this nasty invention, the following advice have
844 been mentioned and used in the past:
845 - Depending on the JavaScript complexity, write up a script that
847 translates it to another language and execute that.
848 - Read the JavaScript code and rewrite the same logic in another
850 language.
851 - Implement a JavaScript interpreter; people have successfully
853 used the Mozilla JavaScript engine in the past.
854 - Ask your admins to stop this, for a static proxy setup or sim‐
856 ilar.
857
860 Re-cycling the same easy handle several times when doing multiple re‐
861 quests is the way to go.
862 After each single curl_easy_perform(3) operation, libcurl will keep the
864 connection alive and open. A subsequent request using the same easy
865 handle to the same host might just be able to use the already open con‐
866 nection! This reduces network impact a lot.
867 Even if the connection is dropped, all connections involving SSL to the
869 same host again, will benefit from libcurl's session ID cache that
870 drastically reduces re-connection time.
871 FTP connections that are kept alive save a lot of time, as the command-
873 response round-trips are skipped, and also you do not risk getting
874 blocked without permission to login again like on many FTP servers only
875 allowing N persons to be logged in at the same time.
876 libcurl caches DNS name resolving results, to make lookups of a previ‐
878 ously looked up name a lot faster.
879 Other interesting details that improve performance for subsequent re‐
881 quests may also be added in the future.
882 Each easy handle will attempt to keep the last few connections alive
884 for a while in case they are to be used again. You can set the size of
885 this "cache" with the CURLOPT_MAXCONNECTS(3) option. Default is 5.
886 There is rarely any point in changing this value, and if you think of
887 changing this it is often just a matter of thinking again.
888 To force your upcoming request to not use an already existing connec‐
890 tion (it will even close one first if there happens to be one alive to
891 the same host you are about to operate on), you can do that by setting
892 CURLOPT_FRESH_CONNECT(3) to 1. In a similar spirit, you can also forbid
893 the upcoming request to be "lying" around and possibly get re-used af‐
894 ter the request by setting CURLOPT_FORBID_REUSE(3) to 1.
895
898 When you use libcurl to do HTTP requests, it will pass along a series
899 of headers automatically. It might be good for you to know and under‐
900 stand these. You can replace or remove them by using the CURLOPT_HTTP‐
901 HEADER(3) option.
902 Host This header is required by HTTP 1.1 and even many 1.0 servers
905 and should be the name of the server we want to talk to. This
906 includes the port number if anything but default.
907 Accept "*/*".
910 Expect When doing POST requests, libcurl sets this header to "100-con‐
913 tinue" to ask the server for an "OK" message before it proceeds
914 with sending the data part of the post. If the posted data
915 amount is deemed "small", libcurl will not use this header.
916
919 There is an ongoing development today where more and more protocols are
920 built upon HTTP for transport. This has obvious benefits as HTTP is a
921 tested and reliable protocol that is widely deployed and has excellent
922 proxy-support.
923 When you use one of these protocols, and even when doing other kinds of
925 programming you may need to change the traditional HTTP (or FTP or...)
926 manners. You may need to change words, headers or various data.
927 libcurl is your friend here too.
929 CUSTOMREQUEST
932 If just changing the actual HTTP request keyword is what you
933 want, like when GET, HEAD or POST is not good enough for you,
934 CURLOPT_CUSTOMREQUEST(3) is there for you. It is simple to use:
935 curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST");
936 When using the custom request, you change the request keyword of
937 the actual request you are performing. Thus, by default you make
938 a GET request but you can also make a POST operation (as de‐
939 scribed before) and then replace the POST keyword if you want
940 to. you are the boss.
941 Modify Headers
944 HTTP-like protocols pass a series of headers to the server when
945 doing the request, and you are free to pass any amount of extra
946 headers that you think fit. Adding headers is this easy:
947 struct curl_slist *headers=NULL; /* init to NULL is important */
949 headers = curl_slist_append(headers, "Hey-server-hey: how are you?");
951 headers = curl_slist_append(headers, "X-silly-content: yes");
952 /* pass our list of custom made headers */
954 curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
955 curl_easy_perform(handle); /* transfer http */
957 curl_slist_free_all(headers); /* free the header list */
959 ... and if you think some of the internally generated headers,
961 such as Accept: or Host: do not contain the data you want them
962 to contain, you can replace them by simply setting them too:
963 headers = curl_slist_append(headers, "Accept: Agent-007");
965 headers = curl_slist_append(headers, "Host: munged.host.line");
966 Delete Headers
969 If you replace an existing header with one with no contents, you
970 will prevent the header from being sent. For instance, if you
971 want to completely prevent the "Accept:" header from being sent,
972 you can disable it with code similar to this:
973 headers = curl_slist_append(headers, "Accept:");
975 Both replacing and canceling internal headers should be done
977 with careful consideration and you should be aware that you may
978 violate the HTTP protocol when doing so.
979 Enforcing chunked transfer-encoding
982 By making sure a request uses the custom header "Transfer-Encod‐
984 ing: chunked" when doing a non-GET HTTP operation, libcurl will
985 switch over to "chunked" upload, even though the size of the
986 data to upload might be known. By default, libcurl usually
987 switches over to chunked upload automatically if the upload data
988 size is unknown.
989 HTTP Version
992 All HTTP requests includes the version number to tell the server
994 which version we support. libcurl speaks HTTP 1.1 by default.
995 Some old servers do not like getting 1.1-requests and when deal‐
996 ing with stubborn old things like that, you can tell libcurl to
997 use 1.0 instead by doing something like this:
998 curl_easy_setopt(handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VER‐
1000 SION_1_0);
1001 FTP Custom Commands
1004 Not all protocols are HTTP-like, and thus the above may not help
1006 you when you want to make, for example, your FTP transfers to
1007 behave differently.
1008 Sending custom commands to an FTP server means that you need to
1010 send the commands exactly as the FTP server expects them (RFC
1011 959 is a good guide here), and you can only use commands that
1012 work on the control-connection alone. All kinds of commands that
1013 require data interchange and thus need a data-connection must be
1014 left to libcurl's own judgment. Also be aware that libcurl will
1015 do its best to change directory to the target directory before
1016 doing any transfer, so if you change directory (with CWD or sim‐
1017 ilar) you might confuse libcurl and then it might not attempt to
1018 transfer the file in the correct remote directory.
1019 A little example that deletes a given file before an operation:
1021 headers = curl_slist_append(headers, "DELE file-to-remove");
1023 /* pass the list of custom commands to the handle */
1025 curl_easy_setopt(handle, CURLOPT_QUOTE, headers);
1026 curl_easy_perform(handle); /* transfer ftp data! */
1028 curl_slist_free_all(headers); /* free the header list */
1030 If you would instead want this operation (or chain of opera‐
1032 tions) to happen _after_ the data transfer took place the option
1033 to curl_easy_setopt(3) would instead be called CUR‐
1034 LOPT_POSTQUOTE(3) and used the exact same way.
1035 The custom FTP command will be issued to the server in the same
1037 order they are added to the list, and if a command gets an error
1038 code returned back from the server, no more commands will be is‐
1039 sued and libcurl will bail out with an error code
1040 (CURLE_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE(3) to
1041 send commands before a transfer, no transfer will actually take
1042 place when a quote command has failed.
1043 If you set the CURLOPT_HEADER(3) to 1, you will tell libcurl to
1045 get information about the target file and output "headers" about
1046 it. The headers will be in "HTTP-style", looking like they do in
1047 HTTP.
1048 The option to enable headers or to run custom FTP commands may
1050 be useful to combine with CURLOPT_NOBODY(3). If this option is
1051 set, no actual file content transfer will be performed.
1052 FTP Custom CUSTOMREQUEST
1055 If you do want to list the contents of an FTP directory using
1056 your own defined FTP command, CURLOPT_CUSTOMREQUEST(3) will do
1057 just that. "NLST" is the default one for listing directories but
1058 you are free to pass in your idea of a good alternative.
1059
1062 In the HTTP sense, a cookie is a name with an associated value. A
1063 server sends the name and value to the client, and expects it to get
1064 sent back on every subsequent request to the server that matches the
1065 particular conditions set. The conditions include that the domain name
1066 and path match and that the cookie has not become too old.
1067 In real-world cases, servers send new cookies to replace existing ones
1069 to update them. Server use cookies to "track" users and to keep "ses‐
1070 sions".
1071 Cookies are sent from server to clients with the header Set-Cookie: and
1073 they are sent from clients to servers with the Cookie: header.
1074 To just send whatever cookie you want to a server, you can use CUR‐
1076 LOPT_COOKIE(3) to set a cookie string like this:
1077 curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;");
1078 In many cases, that is not enough. You might want to dynamically save
1079 whatever cookies the remote server passes to you, and make sure those
1080 cookies are then used accordingly on later requests.
1081 One way to do this, is to save all headers you receive in a plain file
1083 and when you make a request, you tell libcurl to read the previous
1084 headers to figure out which cookies to use. Set the header file to read
1085 cookies from with CURLOPT_COOKIEFILE(3).
1086 The CURLOPT_COOKIEFILE(3) option also automatically enables the cookie
1088 parser in libcurl. Until the cookie parser is enabled, libcurl will not
1089 parse or understand incoming cookies and they will just be ignored.
1090 However, when the parser is enabled the cookies will be understood and
1091 the cookies will be kept in memory and used properly in subsequent re‐
1092 quests when the same handle is used. Many times this is enough, and you
1093 may not have to save the cookies to disk at all. Note that the file you
1094 specify to CURLOPT_COOKIEFILE(3) does not have to exist to enable the
1095 parser, so a common way to just enable the parser and not read any
1096 cookies is to use the name of a file you know does not exist.
1097 If you would rather use existing cookies that you have previously re‐
1099 ceived with your Netscape or Mozilla browsers, you can make libcurl use
1100 that cookie file as input. The CURLOPT_COOKIEFILE(3) is used for that
1101 too, as libcurl will automatically find out what kind of file it is and
1102 act accordingly.
1103 Perhaps the most advanced cookie operation libcurl offers, is saving
1105 the entire internal cookie state back into a Netscape/Mozilla formatted
1106 cookie file. We call that the cookie-jar. When you set a file name with
1107 CURLOPT_COOKIEJAR(3), that file name will be created and all received
1108 cookies will be stored in it when curl_easy_cleanup(3) is called. This
1109 enables cookies to get passed on properly between multiple handles
1110 without any information getting lost.
1111
1114 FTP transfers use a second TCP/IP connection for the data transfer.
1115 This is usually a fact you can forget and ignore but at times this fact
1116 will come back to haunt you. libcurl offers several different ways to
1117 customize how the second connection is being made.
1118 libcurl can either connect to the server a second time or tell the
1120 server to connect back to it. The first option is the default and it is
1121 also what works best for all the people behind firewalls, NATs or IP-
1122 masquerading setups. libcurl then tells the server to open up a new
1123 port and wait for a second connection. This is by default attempted
1124 with EPSV first, and if that does not work it tries PASV instead. (EPSV
1125 is an extension to the original FTP spec and does not exist nor work on
1126 all FTP servers.)
1127 You can prevent libcurl from first trying the EPSV command by setting
1129 CURLOPT_FTP_USE_EPSV(3) to zero.
1130 In some cases, you will prefer to have the server connect back to you
1132 for the second connection. This might be when the server is perhaps be‐
1133 hind a firewall or something and only allows connections on a single
1134 port. libcurl then informs the remote server which IP address and port
1135 number to connect to. This is made with the CURLOPT_FTPPORT(3) option.
1136 If you set it to "-", libcurl will use your system's "default IP ad‐
1137 dress". If you want to use a particular IP, you can set the full IP ad‐
1138 dress, a host name to resolve to an IP address or even a local network
1139 interface name that libcurl will get the IP address from.
1140 When doing the "PORT" approach, libcurl will attempt to use the EPRT
1142 and the LPRT before trying PORT, as they work with more protocols. You
1143 can disable this behavior by setting CURLOPT_FTP_USE_EPRT(3) to zero.
1144
1147 In addition to support HTTP multi-part form fields, the MIME API can be
1148 used to build structured email messages and send them via SMTP or ap‐
1149 pend such messages to IMAP directories.
1150 A structured email message may contain several parts: some are dis‐
1152 played inline by the MUA, some are attachments. Parts can also be
1153 structured as multi-part, for example to include another email message
1154 or to offer several text formats alternatives. This can be nested to
1155 any level.
1156 To build such a message, you prepare the nth-level multi-part and then
1158 include it as a source to the parent multi-part using function
1159 curl_mime_subparts(3). Once it has been bound to its parent multi-part,
1160 a nth-level multi-part belongs to it and should not be freed explic‐
1161 itly.
1162 Email messages data is not supposed to be non-ascii and line length is
1164 limited: fortunately, some transfer encodings are defined by the stan‐
1165 dards to support the transmission of such incompatible data. Function
1166 curl_mime_encoder(3) tells a part that its source data must be encoded
1167 before being sent. It also generates the corresponding header for that
1168 part. If the part data you want to send is already encoded in such a
1169 scheme, do not use this function (this would over-encode it), but ex‐
1170 plicitly set the corresponding part header.
1171 Upon sending such a message, libcurl prepends it with the header list
1173 set with CURLOPT_HTTPHEADER(3), as zero level mime part headers.
1174 Here is an example building an email message with an inline plain/html
1176 text alternative and a file attachment encoded in base64:
1177 curl_mime *message = curl_mime_init(handle);
1179 /* The inline part is an alternative proposing the html and the text
1181 versions of the email. */
1182 curl_mime *alt = curl_mime_init(handle);
1183 /* HTML message. */
1185 curl_mimepart *part = curl_mime_addpart(alt);
1186 curl_mime_data(part, "<html><body><p>This is HTML</p></body></html>",
1187 CURL_ZERO_TERMINATED);
1188 curl_mime_type(part, "text/html");
1189 /* Text message. */
1191 part = curl_mime_addpart(alt);
1192 curl_mime_data(part, "This is plain text message",
1193 CURL_ZERO_TERMINATED);
1194 /* Create the inline part. */
1196 part = curl_mime_addpart(message);
1197 curl_mime_subparts(part, alt);
1198 curl_mime_type(part, "multipart/alternative");
1199 struct curl_slist *headers = curl_slist_append(NULL,
1200 "Content-Disposition: inline");
1201 curl_mime_headers(part, headers, TRUE);
1202 /* Add the attachment. */
1204 part = curl_mime_addpart(message);
1205 curl_mime_filedata(part, "manual.pdf");
1206 curl_mime_encoder(part, "base64");
1207 /* Build the mail headers. */
1209 headers = curl_slist_append(NULL, "From: me@example.com");
1210 headers = curl_slist_append(headers, "To: you@example.com");
1211 /* Set these into the easy handle. */
1213 curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
1214 curl_easy_setopt(handle, CURLOPT_MIMEPOST, mime);
1215 It should be noted that appending a message to an IMAP directory re‐
1217 quires the message size to be known prior upload. It is therefore not
1218 possible to include parts with unknown data size in this context.
1219
1222 Some protocols provide "headers", meta-data separated from the normal
1223 data. These headers are by default not included in the normal data
1224 stream, but you can make them appear in the data stream by setting CUR‐
1225 LOPT_HEADER(3) to 1.
1226 What might be even more useful, is libcurl's ability to separate the
1228 headers from the data and thus make the callbacks differ. You can for
1229 example set a different pointer to pass to the ordinary write callback
1230 by setting CURLOPT_HEADERDATA(3).
1231 Or, you can set an entirely separate function to receive the headers,
1233 by using CURLOPT_HEADERFUNCTION(3).
1234 The headers are passed to the callback function one by one, and you can
1236 depend on that fact. It makes it easier for you to add custom header
1237 parsers etc.
1238 "Headers" for FTP transfers equal all the FTP server responses. They
1240 are not actually true headers, but in this case we pretend they are!
1241 ;-)
1242
1245 See curl_easy_getinfo(3).
1246
1248 The easy interface as described in detail in this document is a syn‐
1249 chronous interface that transfers one file at a time and does not re‐
1250 turn until it is done.
1251 The multi interface, on the other hand, allows your program to transfer
1253 multiple files in both directions at the same time, without forcing you
1254 to use multiple threads. The name might make it seem that the multi in‐
1255 terface is for multi-threaded programs, but the truth is almost the re‐
1256 verse. The multi interface allows a single-threaded application to per‐
1257 form the same kinds of multiple, simultaneous transfers that multi-
1258 threaded programs can perform. It allows many of the benefits of multi-
1259 threaded transfers without the complexity of managing and synchronizing
1260 many threads.
1261 To complicate matters somewhat more, there are even two versions of the
1263 multi interface. The event based one, also called multi_socket and the
1264 "normal one" designed for using with select(). See the libcurl-multi.3
1265 man page for details on the multi_socket event based API, this descrip‐
1266 tion here is for the select() oriented one.
1267 To use this interface, you are better off if you first understand the
1269 basics of how to use the easy interface. The multi interface is simply
1270 a way to make multiple transfers at the same time by adding up multiple
1271 easy handles into a "multi stack".
1272 You create the easy handles you want, one for each concurrent transfer,
1274 and you set all the options just like you learned above, and then you
1275 create a multi handle with curl_multi_init(3) and add all those easy
1276 handles to that multi handle with curl_multi_add_handle(3).
1277 When you have added the handles you have for the moment (you can still
1279 add new ones at any time), you start the transfers by calling
1280 curl_multi_perform(3).
1281 curl_multi_perform(3) is asynchronous. It will only perform what can be
1283 done now and then return control to your program. It is designed to
1284 never block. You need to keep calling the function until all transfers
1285 are completed.
1286 The best usage of this interface is when you do a select() on all pos‐
1288 sible file descriptors or sockets to know when to call libcurl again.
1289 This also makes it easy for you to wait and respond to actions on your
1290 own application's sockets/handles. You figure out what to select() for
1291 by using curl_multi_fdset(3), that fills in a set of fd_set variables
1292 for you with the particular file descriptors libcurl uses for the mo‐
1293 ment.
1294 When you then call select(), it will return when one of the file han‐
1296 dles signal action and you then call curl_multi_perform(3) to allow
1297 libcurl to do what it wants to do. Take note that libcurl does also
1298 feature some time-out code so we advise you to never use long timeouts
1299 on select() before you call curl_multi_perform(3) again.
1300 curl_multi_timeout(3) is provided to help you get a suitable timeout
1301 period.
1302 Another precaution you should use: always call curl_multi_fdset(3) im‐
1304 mediately before the select() call since the current set of file de‐
1305 scriptors may change in any curl function invoke.
1306 If you want to stop the transfer of one of the easy handles in the
1308 stack, you can use curl_multi_remove_handle(3) to remove individual
1309 easy handles. Remember that easy handles should be
1310 curl_easy_cleanup(3)ed.
1311 When a transfer within the multi stack has finished, the counter of
1313 running transfers (as filled in by curl_multi_perform(3)) will de‐
1314 crease. When the number reaches zero, all transfers are done.
1315 curl_multi_info_read(3) can be used to get information about completed
1317 transfers. It then returns the CURLcode for each easy transfer, to al‐
1318 low you to figure out success on each individual transfer.
1319
1322 [ seeding, passwords, keys, certificates, ENGINE, ca certs ]
1323
1326 You can share some data between easy handles when the easy interface is
1327 used, and some data is share automatically when you use the multi in‐
1328 terface.
1329 When you add easy handles to a multi handle, these easy handles will
1331 automatically share a lot of the data that otherwise would be kept on a
1332 per-easy handle basis when the easy interface is used.
1333 The DNS cache is shared between handles within a multi handle, making
1335 subsequent name resolving faster, and the connection pool that is kept
1336 to better allow persistent connections and connection re-use is also
1337 shared. If you are using the easy interface, you can still share these
1338 between specific easy handles by using the share interface, see
1339 libcurl-share(3).
1340 Some things are never shared automatically, not within multi handles,
1342 like for example cookies so the only way to share that is with the
1343 share interface.
1344
1346 [1] libcurl 7.10.3 and later have the ability to switch over to
1347 chunked Transfer-Encoding in cases where HTTP uploads are done
1348 with data of an unknown size.
1349 [2] This happens on Windows machines when libcurl is built and used
1351 as a DLL. However, you can still do this on Windows if you link
1352 with a static library.
1353 [3] The curl-config tool is generated at build-time (on Unix-like
1355 systems) and should be installed with the 'make install' or sim‐
1356 ilar instruction that installs the library, header files, man
1357 pages etc.
1358 [4] This behavior was different in versions before 7.17.0, where
1360 strings had to remain valid past the end of the curl_easy_se‐
1361 topt(3) call.
1362
1364 libcurl-errors(3), libcurl-multi(3), libcurl-easy(3)
1365libcurl 8.2.1 June 25, 2023 libcurl-tutorial(3)