1libcurl-tutorial(3)           libcurl programming          libcurl-tutorial(3)
2
3
4

NAME

6       libcurl-tutorial - libcurl programming tutorial
7

Objective

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
14       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
21       To  get  more  details  on  all options and functions described herein,
22       please refer to their respective man pages.
23
24

Building

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
31       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
37              $ curl-config --cflags
38
39
40       Linking the Program with libcurl
41              When having compiled the program, you need to link  your  object
42              files  to  create  a single executable. For that to succeed, you
43              need to link with libcurl and possibly also with other libraries
44              that  libcurl itself depends on. Like the OpenSSL libraries, but
45              even some standard OS libraries may be  needed  on  the  command
46              line.  To  figure  out which flags to use, once again the 'curl-
47              config' tool comes to the rescue:
48
49              $ curl-config --libs
50
51
52       SSL or Not
53              libcurl can be built and customized in many  ways.  One  of  the
54              things  that  varies  from different libraries and builds is the
55              support for SSL-based transfers, like HTTPS and FTPS. If a  sup‐
56              ported  SSL library was detected properly at build-time, libcurl
57              will be built with SSL support. To figure out  if  an  installed
58              libcurl  has been built with SSL support enabled, use 'curl-con‐
59              fig' like this:
60
61              $ curl-config --feature
62
63              And if SSL is supported, the keyword 'SSL' will  be  written  to
64              stdout,  possibly  together with a few other features that could
65              be either on or off on for different libcurls.
66
67              See also the "Features libcurl Provides" further down.
68
69       autoconf macro
70              When you write your configure script to detect libcurl and setup
71              variables  accordingly,  we offer a macro that probably does ev‐
72              erything you need in this area. See docs/libcurl/libcurl.m4 file
73              - it includes docs on how to use it.
74
75

Portable Code in a Portable World

77       The  people  behind  libcurl  have  put  a  considerable effort to make
78       libcurl work on a large amount of different operating systems and envi‐
79       ronments.
80
81       You program libcurl the same way on all platforms that libcurl runs on.
82       There are only a few minor details that differ. If you just  make  sure
83       to  write your code portable enough, you can create a portable program.
84       libcurl should not stop you from that.
85
86

Global Preparation

88       The program must initialize some of the libcurl functionality globally.
89       That means it should be done exactly once, no matter how many times you
90       intend to use the library. Once for your program's  entire  life  time.
91       This is done using
92
93        curl_global_init()
94
95       and  it  takes  one parameter which is a bit pattern that tells libcurl
96       what to initialize. Using CURL_GLOBAL_ALL will make it  initialize  all
97       known  internal  sub  modules,  and might be a good default option. The
98       current two bits that are specified are:
99
100              CURL_GLOBAL_WIN32
101                     which only does anything on Windows machines.  When  used
102                     on a Windows machine, it will make libcurl initialize the
103                     win32 socket stuff. Without having that initialized prop‐
104                     erly,  your  program  cannot  use  sockets  properly. You
105                     should only do this once for each application, so if your
106                     program  already  does  this or of another library in use
107                     does it, you should not tell libcurl to do this as well.
108
109              CURL_GLOBAL_SSL
110                     which only does anything on libcurls compiled  and  built
111                     SSL-enabled.  On  these  systems,  this will make libcurl
112                     initialize the SSL library properly for this application.
113                     This  only  needs to be done once for each application so
114                     if your program or another  library  already  does  this,
115                     this bit should not be needed.
116
117       libcurl   has   a   default   protection   mechanism  that  detects  if
118       curl_global_init(3) has not been  called  by  the  time  curl_easy_per‐
119       form(3)  is  called  and if that is the case, libcurl runs the function
120       itself with a guessed bit pattern. Please note that depending solely on
121       this is not considered nice nor good.
122
123       When   the   program   no   longer   uses   libcurl,   it  should  call
124       curl_global_cleanup(3), which is the opposite of the init call. It will
125       then   do   the  reversed  operations  to  cleanup  the  resources  the
126       curl_global_init(3) call initialized.
127
128       Repeated calls to curl_global_init(3) and curl_global_cleanup(3) should
129       be avoided. They should only be called once each.
130
131

Features libcurl Provides

133       It is considered best-practice to determine libcurl features at runtime
134       rather than at build-time (if possible of course). By calling curl_ver‐
135       sion_info(3)  and checking out the details of the returned struct, your
136       program can figure out exactly what the currently running libcurl  sup‐
137       ports.
138
139

Two Interfaces

141       libcurl  first  introduced the so called easy interface. All operations
142       in the easy interface are prefixed with 'curl_easy'. The easy interface
143       lets  you  do single transfers with a synchronous and blocking function
144       call.
145
146       libcurl also offers another interface that allows multiple simultaneous
147       transfers in a single thread, the so called multi interface. More about
148       that interface is detailed in a  separate  chapter  further  down.  You
149       still  need  to understand the easy interface first, so please continue
150       reading for better understanding.
151

Handle the Easy libcurl

153       To use the easy interface, you must first create yourself an easy  han‐
154       dle. You need one handle for each easy session you want to perform. Ba‐
155       sically, you should use one handle for every thread you plan to use for
156       transferring. You must never share the same handle in multiple threads.
157
158       Get an easy handle with
159
160        easyhandle = curl_easy_init();
161
162       It  returns  an  easy  handle. Using that you proceed to the next step:
163       setting up your preferred actions. A handle is just a logic entity  for
164       the upcoming transfer or series of transfers.
165
166       You  set  properties  and  options  for this handle using curl_easy_se‐
167       topt(3). They control how the subsequent transfer or transfers will  be
168       made.  Options  remain  set  in the handle until set again to something
169       different. They are sticky. Multiple requests  using  the  same  handle
170       will use the same options.
171
172       If  you at any point would like to blank all previously set options for
173       a single easy handle, you can call curl_easy_reset(3) and you can  also
174       make  a  clone  of  an  easy  handle  (with  all its set options) using
175       curl_easy_duphandle(3).
176
177       Many of the options you set in libcurl are "strings", pointers to  data
178       terminated  with  a  zero byte. When you set strings with curl_easy_se‐
179       topt(3), libcurl makes its own copy so that they do not need to be kept
180       around in your application after being set[4].
181
182       One  of  the most basic properties to set in the handle is the URL. You
183       set your preferred URL to transfer with CURLOPT_URL(3) in a manner sim‐
184       ilar to:
185
186        curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/");
187
188       Let's assume for a while that you want to receive data as the URL iden‐
189       tifies a remote resource you want to get here. Since you write  a  sort
190       of  application  that needs this transfer, I assume that you would like
191       to get the data passed to you directly instead  of  simply  getting  it
192       passed  to  stdout.  So,  you write your own function that matches this
193       prototype:
194
195        size_t  write_data(void  *buffer,  size_t  size,  size_t  nmemb,  void
196       *userp);
197
198       You  tell  libcurl to pass all data to this function by issuing a func‐
199       tion similar to this:
200
201        curl_easy_setopt(easyhandle, CURLOPT_WRITEFUNCTION, write_data);
202
203       You can control what data your callback function gets in the fourth ar‐
204       gument by setting another property:
205
206        curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct);
207
208       Using that property, you can easily pass local data between your appli‐
209       cation and the function that gets invoked by  libcurl.  libcurl  itself
210       will not touch the data you pass with CURLOPT_WRITEDATA(3).
211
212       libcurl offers its own default internal callback that will take care of
213       the data if you do not set the callback with  CURLOPT_WRITEFUNCTION(3).
214       It  will  then  simply output the received data to stdout. You can have
215       the default callback write the data to a different file handle by pass‐
216       ing  a  'FILE  *'  to a file opened for writing with the CURLOPT_WRITE‐
217       DATA(3) option.
218
219       Now, we need to take a step back and have a deep breath. Here's one  of
220       those  rare platform-dependent nitpicks. Did you spot it? On some plat‐
221       forms[2], libcurl will not be able to operate on files  opened  by  the
222       program. Thus, if you use the default callback and pass in an open file
223       with CURLOPT_WRITEDATA(3), it will crash. You  should  therefore  avoid
224       this to make your program run fine virtually everywhere.
225
226       (CURLOPT_WRITEDATA(3)  was  formerly  known as CURLOPT_FILE. Both names
227       still work and do the same thing).
228
229       If you are using libcurl  as  a  win32  DLL,  you  MUST  use  the  CUR‐
230       LOPT_WRITEFUNCTION(3) if you set CURLOPT_WRITEDATA(3) - or you will ex‐
231       perience crashes.
232
233       There are of course many more options you can set, and we will get back
234       to a few of them later. Let's instead continue to the actual transfer:
235
236        success = curl_easy_perform(easyhandle);
237
238       curl_easy_perform(3)  will connect to the remote site, do the necessary
239       commands and receive the transfer. Whenever it receives data, it  calls
240       the  callback function we previously set. The function may get one byte
241       at a time, or it may get many kilobytes at once.  libcurl  delivers  as
242       much  as  possible  as often as possible. Your callback function should
243       return the number of bytes it "took care of". If that is not  the  same
244       amount of bytes that was passed to it, libcurl will abort the operation
245       and return with an error code.
246
247       When the transfer is complete, the function returns a return code  that
248       informs  you if it succeeded in its mission or not. If a return code is
249       not enough for you, you can use  the  CURLOPT_ERRORBUFFER(3)  to  point
250       libcurl to a buffer of yours where it will store a human readable error
251       message as well.
252
253       If you then want to transfer another file, the handle is  ready  to  be
254       used  again. Mind you, it is even preferred that you re-use an existing
255       handle if you intend to make another transfer. libcurl  will  then  at‐
256       tempt to re-use the previous connection.
257
258       For  some  protocols,  downloading  a  file  can  involve a complicated
259       process of logging in, setting the transfer mode, changing the  current
260       directory and finally transferring the file data. libcurl takes care of
261       all that complication for you. Given simply the URL to a file,  libcurl
262       will take care of all the details needed to get the file moved from one
263       machine to another.
264
265

Multi-threading Issues

267       libcurl is thread safe  but  there  are  a  few  exceptions.  Refer  to
268       libcurl-thread(3) for more information.
269
270

When It does not Work

272       There will always be times when the transfer fails for some reason. You
273       might have set the wrong  libcurl  option  or  misunderstood  what  the
274       libcurl  option  actually  does, or the remote server might return non-
275       standard replies that confuse the library which then confuses your pro‐
276       gram.
277
278       There's  one  golden rule when these things occur: set the CURLOPT_VER‐
279       BOSE(3) option to 1. it will cause the library to spew out  the  entire
280       protocol  details it sends, some internal info and some received proto‐
281       col data as well (especially when using FTP). If you  are  using  HTTP,
282       adding the headers in the received output to study is also a clever way
283       to get a better understanding why the server behaves the way  it  does.
284       Include headers in the normal body output with CURLOPT_HEADER(3) set 1.
285
286       Of  course,  there are bugs left. We need to know about them to be able
287       to fix them, so we are quite dependent on your bug reports. When you do
288       report suspected bugs in libcurl, please include as many details as you
289       possibly can: a protocol dump that CURLOPT_VERBOSE(3) produces, library
290       version,  as much as possible of your code that uses libcurl, operating
291       system name and version, compiler name and version etc.
292
293       If CURLOPT_VERBOSE(3) is not enough, you increase the  level  of  debug
294       data your application receive by using the CURLOPT_DEBUGFUNCTION(3).
295
296       Getting  some  in-depth knowledge about the protocols involved is never
297       wrong, and if you are trying to do funny things, you  might  understand
298       libcurl and how to use it better if you study the appropriate RFC docu‐
299       ments at least briefly.
300
301

Upload Data to a Remote Site

303       libcurl tries to keep a protocol independent approach  to  most  trans‐
304       fers,  thus uploading to a remote FTP site is similar to uploading data
305       to an HTTP server with a PUT request.
306
307       Of course, first you either create an easy handle or you re-use one ex‐
308       isting  one.  Then you set the URL to operate on just like before. This
309       is the remote URL, that we now will upload.
310
311       Since we write an application, we most likely want libcurl to  get  the
312       upload  data  by  asking us for it. To make it do that, we set the read
313       callback and the custom pointer libcurl will pass to our read callback.
314       The read callback should have a prototype similar to:
315
316        size_t   function(char  *bufptr,  size_t  size,  size_t  nitems,  void
317       *userp);
318
319       Where bufptr is the pointer to a buffer we fill in with data to  upload
320       and  size*nitems is the size of the buffer and therefore also the maxi‐
321       mum amount of data we can return to libcurl in this call.  The  'userp'
322       pointer  is  the  custom pointer we set to point to a struct of ours to
323       pass private data between the application and the callback.
324
325        curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, read_function);
326
327        curl_easy_setopt(easyhandle, CURLOPT_READDATA, &filedata);
328
329       Tell libcurl that we want to upload:
330
331        curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, 1L);
332
333       A few protocols will not behave properly when uploads are done  without
334       any  prior knowledge of the expected file size. So, set the upload file
335       size using the CURLOPT_INFILESIZE_LARGE(3) for  all  known  file  sizes
336       like this[1]:
337
338        /* in this example, file_size must be an curl_off_t variable */
339        curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size);
340
341       When  you  call curl_easy_perform(3) this time, it will perform all the
342       necessary operations and when it has invoked the upload  it  will  call
343       your  supplied  callback  to get the data to upload. The program should
344       return as much data as possible in every invoke, as that is  likely  to
345       make the upload perform as fast as possible. The callback should return
346       the number of bytes it wrote in the buffer. Returning 0 will signal the
347       end of the upload.
348
349

Passwords

351       Many protocols use or even require that user name and password are pro‐
352       vided to be able to download or upload the data of your choice. libcurl
353       offers several ways to specify them.
354
355       Most  protocols  support  that you specify the name and password in the
356       URL itself. libcurl will detect this and use them accordingly. This  is
357       written like this:
358
359        protocol://user:password@example.com/path/
360
361       If  you  need any odd letters in your user name or password, you should
362       enter them URL encoded, as %XX where XX is a two-digit hexadecimal num‐
363       ber.
364
365       libcurl  also  provides options to set various passwords. The user name
366       and password as shown embedded in the URL can instead get set with  the
367       CURLOPT_USERPWD(3)  option.  The argument passed to libcurl should be a
368       char * to a string in the format  "user:password".  In  a  manner  like
369       this:
370
371        curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret");
372
373       Another  case  where name and password might be needed at times, is for
374       those users who need to authenticate themselves to a  proxy  they  use.
375       libcurl offers another option for this, the CURLOPT_PROXYUSERPWD(3). It
376       is used quite similar to the CURLOPT_USERPWD(3) option like this:
377
378        curl_easy_setopt(easyhandle,   CURLOPT_PROXYUSERPWD,    "myname:these‐
379       cret");
380
381       There's  a  long time Unix "standard" way of storing FTP user names and
382       passwords, namely in the $HOME/.netrc file (on  Windows,  libcurl  also
383       checks  the  %USERPROFILE% environment variable if %HOME% is unset, and
384       tries _netrc as name). The file should be made private so that only the
385       user  may  read it (see also the "Security Considerations" chapter), as
386       it might contain the password in plain text. libcurl has the ability to
387       use  this  file to figure out what set of user name and password to use
388       for a particular host. As an extension  to  the  normal  functionality,
389       libcurl  also supports this file for non-FTP protocols such as HTTP. To
390       make curl use this file, use the CURLOPT_NETRC(3) option:
391
392        curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L);
393
394       And a basic example of how such a .netrc file may look like:
395
396        machine myhost.mydomain.com
397        login userlogin
398        password secretword
399
400       All these examples have been cases where  the  password  has  been  op‐
401       tional,  or at least you could leave it out and have libcurl attempt to
402       do its job without it. There are times when the  password  is  not  op‐
403       tional,  like  when  you are using an SSL private key for secure trans‐
404       fers.
405
406       To pass the known private key password to libcurl:
407
408        curl_easy_setopt(easyhandle, CURLOPT_KEYPASSWD, "keypassword");
409
410

HTTP Authentication

412       The previous chapter showed how to set user name and password for  get‐
413       ting  URLs  that  require authentication. When using the HTTP protocol,
414       there are many different ways a client can provide those credentials to
415       the  server and you can control which way libcurl will (attempt to) use
416       them. The default HTTP authentication method is called  'Basic',  which
417       is  sending  the  name  and password in clear-text in the HTTP request,
418       base64-encoded. This is insecure.
419
420       At the time of this writing, libcurl can be built to  use:  Basic,  Di‐
421       gest,  NTLM,  Negotiate (SPNEGO). You can tell libcurl which one to use
422       with CURLOPT_HTTPAUTH(3) as in:
423
424        curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
425
426       And when you send authentication to a proxy, you can also set authenti‐
427       cation type the same way but instead with CURLOPT_PROXYAUTH(3):
428
429        curl_easy_setopt(easyhandle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
430
431       Both  these  options allow you to set multiple types (by ORing them to‐
432       gether), to make libcurl pick the most secure one out of the types  the
433       server/proxy  claims  to support. This method does however add a round-
434       trip since libcurl must first ask the server what it supports:
435
436        curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH,
437        CURLAUTH_DIGEST|CURLAUTH_BASIC);
438
439       For convenience, you can use the 'CURLAUTH_ANY' define  (instead  of  a
440       list  with  specific types) which allows libcurl to use whatever method
441       it wants.
442
443       When asking for multiple types, libcurl will pick the available one  it
444       considers "best" in its own internal order of preference.
445
446

HTTP POSTing

448       We  get  many  questions regarding how to issue HTTP POSTs with libcurl
449       the proper way. This chapter will thus include examples using both dif‐
450       ferent versions of HTTP POST that libcurl supports.
451
452       The  first  version  is  the simple POST, the most common version, that
453       most HTML pages using the <form> tag uses. We provide a pointer to  the
454       data and tell libcurl to post it all to the remote site:
455
456           char *data="name=daniel&project=curl";
457           curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, data);
458           curl_easy_setopt(easyhandle, CURLOPT_URL, "http://posthere.com/");
459
460           curl_easy_perform(easyhandle); /* post away! */
461
462       Simple  enough,  huh?  Since  you  set  the  POST options with the CUR‐
463       LOPT_POSTFIELDS(3), this automatically switches the handle to use  POST
464       in the upcoming request.
465
466       What  if you want to post binary data that also requires you to set the
467       Content-Type: header of the post? Well, binary  posts  prevent  libcurl
468       from  being  able to do strlen() on the data to figure out the size, so
469       therefore we must tell libcurl the size of the post data. Setting head‐
470       ers  in  libcurl requests are done in a generic way, by building a list
471       of our own headers and then passing that list to libcurl.
472
473        struct curl_slist *headers=NULL;
474        headers = curl_slist_append(headers, "Content-Type: text/xml");
475
476        /* post binary data */
477        curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, binaryptr);
478
479        /* set the size of the postfields data */
480        curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23L);
481
482        /* pass our list of custom made headers */
483        curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
484
485        curl_easy_perform(easyhandle); /* post away! */
486
487        curl_slist_free_all(headers); /* free the header list */
488
489       While the simple examples above cover the majority of all  cases  where
490       HTTP POST operations are required, they do not do multi-part formposts.
491       Multi-part formposts were introduced as a better way to post  (possibly
492       large) binary data and were first documented in the RFC1867 (updated in
493       RFC2388). they are called multi-part because they are built by a  chain
494       of  parts, each part being a single unit of data. Each part has its own
495       name and contents. You can in fact create and post a  multi-part  form‐
496       post  with  the  regular libcurl POST support described above, but that
497       would require that  you  build  a  formpost  yourself  and  provide  to
498       libcurl. To make that easier, libcurl provides a MIME API consisting in
499       several functions: using those, you can create and  fill  a  multi-part
500       form.   Function  curl_mime_init(3)  creates a multi-part body; you can
501       then append new parts to a multi-part body using  curl_mime_addpart(3).
502       There  are  three  possible  data  sources  for  a  part:  memory using
503       curl_mime_data(3), file using  curl_mime_filedata(3)  and  user-defined
504       data  read callback using curl_mime_data_cb(3).  curl_mime_name(3) sets
505       a part's (i.e.: form field) name, while curl_mime_filename(3) fills  in
506       the  remote  file  name.  With curl_mime_type(3), you can tell the MIME
507       type of a part, curl_mime_headers(3) allows defining the  part's  head‐
508       ers. When a multi-part body is no longer needed, you can destroy it us‐
509       ing curl_mime_free(3).
510
511       The following example sets two simple text  parts  with  plain  textual
512       contents,  and  then  a file with binary contents and uploads the whole
513       thing.
514
515        curl_mime *multipart = curl_mime_init(easyhandle);
516        curl_mimepart *part = curl_mime_addpart(multipart);
517        curl_mime_name(part, "name");
518        curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
519        part = curl_mime_addpart(multipart);
520        curl_mime_name(part, "project");
521        curl_mime_data(part, "curl", CURL_ZERO_TERMINATED);
522        part = curl_mime_addpart(multipart);
523        curl_mime_name(part, "logotype-image");
524        curl_mime_filedata(part, "curl.png");
525
526        /* Set the form info */
527        curl_easy_setopt(easyhandle, CURLOPT_MIMEPOST, multipart);
528
529        curl_easy_perform(easyhandle); /* post away! */
530
531        /* free the post data again */
532        curl_mime_free(multipart);
533
534       To post multiple files for a single form field, you  must  supply  each
535       file  in  a separate part, all with the same field name. Although func‐
536       tion curl_mime_subparts(3) implements nested multi-parts, this  way  of
537       multiple files posting is deprecated by RFC 7578, chapter 4.3.
538
539       To set the data source from an already opened FILE pointer, use:
540
541        curl_mime_data_cb(part, filesize, (curl_read_callback) fread,
542                          (curl_seek_callback) fseek, NULL, filepointer);
543
544       A  deprecated  curl_formadd(3)  function is still supported in libcurl.
545       It should however not be used anymore for new designs and programs  us‐
546       ing  it  ought to be converted to the MIME API. It is however described
547       here as an aid to conversion.
548
549       Using curl_formadd, you add parts to the form. When you are done adding
550       parts, you post the whole form.
551
552       The MIME API example above is expressed as follows using this function:
553
554        struct curl_httppost *post=NULL;
555        struct curl_httppost *last=NULL;
556        curl_formadd(&post, &last,
557                     CURLFORM_COPYNAME, "name",
558                     CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
559        curl_formadd(&post, &last,
560                     CURLFORM_COPYNAME, "project",
561                     CURLFORM_COPYCONTENTS, "curl", CURLFORM_END);
562        curl_formadd(&post, &last,
563                     CURLFORM_COPYNAME, "logotype-image",
564                     CURLFORM_FILECONTENT, "curl.png", CURLFORM_END);
565
566        /* Set the form info */
567        curl_easy_setopt(easyhandle, CURLOPT_HTTPPOST, post);
568
569        curl_easy_perform(easyhandle); /* post away! */
570
571        /* free the post data again */
572        curl_formfree(post);
573
574       Multipart formposts are chains of parts using MIME-style separators and
575       headers. It means that each one of these separate parts get a few head‐
576       ers  set that describe the individual content-type, size etc. To enable
577       your application to handicraft this formpost even more, libcurl  allows
578       you to supply your own set of custom headers to such an individual form
579       part. You can of course supply headers to as many parts  as  you  like,
580       but  this  little example will show how you set headers to one specific
581       part when you add that to the post handle:
582
583        struct curl_slist *headers=NULL;
584        headers = curl_slist_append(headers, "Content-Type: text/xml");
585
586        curl_formadd(&post, &last,
587                     CURLFORM_COPYNAME, "logotype-image",
588                     CURLFORM_FILECONTENT, "curl.xml",
589                     CURLFORM_CONTENTHEADER, headers,
590                     CURLFORM_END);
591
592        curl_easy_perform(easyhandle); /* post away! */
593
594        curl_formfree(post); /* free post */
595        curl_slist_free_all(headers); /* free custom header list */
596
597       Since all options on an easyhandle are "sticky", they remain  the  same
598       until changed even if you do call curl_easy_perform(3), you may need to
599       tell curl to go back to a plain GET request if you intend to do one  as
600       your  next  request. You force an easyhandle to go back to GET by using
601       the CURLOPT_HTTPGET(3) option:
602
603        curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L);
604
605       Just setting CURLOPT_POSTFIELDS(3)  to  ""  or  NULL  will  *not*  stop
606       libcurl  from  doing a POST. It will just make it POST without any data
607       to send!
608
609

Converting from deprecated form API to MIME API

611       Four rules have to be respected in building the multi-part:
612       - The easy handle must be created before building the multi-part.
613       - The multi-part is always created by a call to curl_mime_init(easyhan‐
614       dle).
615       - Each part is created by a call to curl_mime_addpart(multipart).
616       -  When complete, the multi-part must be bound to the easy handle using
617       CURLOPT_MIMEPOST(3) instead of CURLOPT_HTTPPOST(3).
618
619       Here are some example of curl_formadd calls to MIME API sequences:
620
621        curl_formadd(&post, &last,
622                     CURLFORM_COPYNAME, "id",
623                     CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
624                     CURLFORM_CONTENTHEADER, headers,
625                     CURLFORM_END);
626       becomes:
627        part = curl_mime_addpart(multipart);
628        curl_mime_name(part, "id");
629        curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
630        curl_mime_headers(part, headers, FALSE);
631
632       Setting the last curl_mime_headers argument to TRUE would  have  caused
633       the headers to be automatically released upon destroyed the multi-part,
634       thus saving a clean-up call to curl_slist_free_all(3).
635
636        curl_formadd(&post, &last,
637                     CURLFORM_PTRNAME, "logotype-image",
638                     CURLFORM_FILECONTENT, "-",
639                     CURLFORM_END);
640       becomes:
641        part = curl_mime_addpart(multipart);
642        curl_mime_name(part, "logotype-image");
643        curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin);
644
645       curl_mime_name always copies the field name. The special file name  "-"
646       is  not  supported by curl_mime_file: to read an open file, use a call‐
647       back source using fread(). The transfer will be chunked since the  data
648       size is unknown.
649
650        curl_formadd(&post, &last,
651                     CURLFORM_COPYNAME, "datafile[]",
652                     CURLFORM_FILE, "file1",
653                     CURLFORM_FILE, "file2",
654                     CURLFORM_END);
655       becomes:
656        part = curl_mime_addpart(multipart);
657        curl_mime_name(part, "datafile[]");
658        curl_mime_filedata(part, "file1");
659        part = curl_mime_addpart(multipart);
660        curl_mime_name(part, "datafile[]");
661        curl_mime_filedata(part, "file2");
662
663       The  deprecated  multipart/mixed implementation of multiple files field
664       is translated to two distinct parts with the same name.
665
666        curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, myreadfunc);
667        curl_formadd(&post, &last,
668                     CURLFORM_COPYNAME, "stream",
669                     CURLFORM_STREAM, arg,
670                     CURLFORM_CONTENTLEN, (curl_off_t) datasize,
671                     CURLFORM_FILENAME, "archive.zip",
672                     CURLFORM_CONTENTTYPE, "application/zip",
673                     CURLFORM_END);
674       becomes:
675        part = curl_mime_addpart(multipart);
676        curl_mime_name(part, "stream");
677        curl_mime_data_cb(part, (curl_off_t) datasize,
678                          myreadfunc, NULL, NULL, arg);
679        curl_mime_filename(part, "archive.zip");
680        curl_mime_type(part, "application/zip");
681
682       CURLOPT_READFUNCTION callback is not used: it is  replace  by  directly
683       setting the part source data from the callback read function.
684
685        curl_formadd(&post, &last,
686                     CURLFORM_COPYNAME, "memfile",
687                     CURLFORM_BUFFER, "memfile.bin",
688                     CURLFORM_BUFFERPTR, databuffer,
689                     CURLFORM_BUFFERLENGTH, (long) sizeof databuffer,
690                     CURLFORM_END);
691       becomes:
692        part = curl_mime_addpart(multipart);
693        curl_mime_name(part, "memfile");
694        curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer);
695        curl_mime_filename(part, "memfile.bin");
696
697       curl_mime_data always copies the initial data: data buffer is thus free
698       for immediate reuse.
699
700        curl_formadd(&post, &last,
701                     CURLFORM_COPYNAME, "message",
702                     CURLFORM_FILECONTENT, "msg.txt",
703                     CURLFORM_END);
704       becomes:
705        part = curl_mime_addpart(multipart);
706        curl_mime_name(part, "message");
707        curl_mime_filedata(part, "msg.txt");
708        curl_mime_filename(part, NULL);
709
710       Use of curl_mime_filedata sets the remote file name as a  side  effect:
711       it  is  therefore necessary to clear it for CURLFORM_FILECONTENT emula‐
712       tion.
713
714

Showing Progress

716       For historical and traditional reasons, libcurl has a built-in progress
717       meter  that can be switched on and then makes it present a progress me‐
718       ter in your terminal.
719
720       Switch on the progress meter  by,  oddly  enough,  setting  CURLOPT_NO‐
721       PROGRESS(3) to zero. This option is set to 1 by default.
722
723       For  most  applications however, the built-in progress meter is useless
724       and what instead is interesting is the ability to  specify  a  progress
725       callback.  The function pointer you pass to libcurl will then be called
726       on irregular intervals with information about the current transfer.
727
728       Set the progress callback  by  using  CURLOPT_PROGRESSFUNCTION(3).  And
729       pass a pointer to a function that matches this prototype:
730
731        int progress_callback(void *clientp,
732                              double dltotal,
733                              double dlnow,
734                              double ultotal,
735                              double ulnow);
736
737       If any of the input arguments is unknown, a 0 will be passed. The first
738       argument, the 'clientp' is the pointer you pass to  libcurl  with  CUR‐
739       LOPT_PROGRESSDATA(3). libcurl will not touch it.
740
741

libcurl with C++

743       There's basically only one thing to keep in mind when using C++ instead
744       of C when interfacing libcurl:
745
746       The callbacks CANNOT be non-static class member functions
747
748       Example C++ code:
749
750       class AClass {
751           static size_t write_data(void *ptr, size_t size, size_t nmemb,
752                                    void *ourpointer)
753           {
754             /* do what you want with the data */
755           }
756        }
757
758

Proxies

760       What "proxy" means according to Merriam-Webster: "a  person  authorized
761       to  act  for  another"  but  also "the agency, function, or office of a
762       deputy who acts as a substitute for another".
763
764       Proxies are exceedingly common these days. Companies often  only  offer
765       Internet  access to employees through their proxies. Network clients or
766       user-agents ask the proxy for documents, the proxy does the actual  re‐
767       quest and then it returns them.
768
769       libcurl  supports  SOCKS  and HTTP proxies. When a given URL is wanted,
770       libcurl will ask the proxy for it instead of trying to connect  to  the
771       actual host identified in the URL.
772
773       If  you  are  using  a  SOCKS proxy, you may find that libcurl does not
774       quite support all operations through it.
775
776       For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain
777       restrictions  on  what  can actually happen. A requested URL that might
778       not be a HTTP URL will be still be passed to the HTTP proxy to  deliver
779       back to libcurl. This happens transparently, and an application may not
780       need to know. I say "may", because at times it is important  to  under‐
781       stand that all operations over an HTTP proxy use the HTTP protocol. For
782       example, you cannot invoke your own custom FTP commands or even  proper
783       FTP directory listings.
784
785
786       Proxy Options
787
788              To tell libcurl to use a proxy at a given port number:
789
790               curl_easy_setopt(easyhandle,       CURLOPT_PROXY,       "proxy-
791              host.com:8080");
792
793              Some proxies require user authentication before allowing  a  re‐
794              quest, and you pass that information similar to this:
795
796               curl_easy_setopt(easyhandle,  CURLOPT_PROXYUSERPWD, "user:pass‐
797              word");
798
799              If you want to, you can specify the host name only in  the  CUR‐
800              LOPT_PROXY(3)  option,  and  set the port number separately with
801              CURLOPT_PROXYPORT(3).
802
803              Tell libcurl what kind of proxy it is with  CURLOPT_PROXYTYPE(3)
804              (if not, it will default to assume an HTTP proxy):
805
806               curl_easy_setopt(easyhandle,      CURLOPT_PROXYTYPE,      CURL‐
807              PROXY_SOCKS4);
808
809
810       Environment Variables
811
812              libcurl automatically checks and uses a set of environment vari‐
813              ables  to  know  what  proxies to use for certain protocols. The
814              names of the variables are following an ancient de  facto  stan‐
815              dard and are built up as "[protocol]_proxy" (note the lower cas‐
816              ing). Which makes the variable 'http_proxy' checked for  a  name
817              of a proxy to use when the input URL is HTTP. Following the same
818              rule, the variable named 'ftp_proxy' is checked  for  FTP  URLs.
819              Again,  the proxies are always HTTP proxies, the different names
820              of the variables simply allows  different  HTTP  proxies  to  be
821              used.
822
823              The  proxy environment variable contents should be in the format
824              "[protocol://][user:password@]machine[:port]". Where the  proto‐
825              col://  part  is  simply ignored if present (so http://proxy and
826              bluerk://proxy will do the same) and the  optional  port  number
827              specifies  on  which port the proxy operates on the host. If not
828              specified, the internal default port number  will  be  used  and
829              that is most likely *not* the one you would like it to be.
830
831              There are two special environment variables. 'all_proxy' is what
832              sets proxy for any URL in case the  protocol  specific  variable
833              was  not set, and 'no_proxy' defines a list of hosts that should
834              not use a proxy even though a variable may say so. If 'no_proxy'
835              is a plain asterisk ("*") it matches all hosts.
836
837              To explicitly disable libcurl's checking for and using the proxy
838              environment variables, set the proxy  name  to  ""  -  an  empty
839              string - with CURLOPT_PROXY(3).
840
841       SSL and Proxies
842
843              SSL  is  for  secure  point-to-point  connections. This involves
844              strong encryption and similar things, which effectively makes it
845              impossible  for  a  proxy to operate as a "man in between" which
846              the proxy's task is, as previously discussed. Instead, the  only
847              way  to  have SSL work over an HTTP proxy is to ask the proxy to
848              tunnel everything through without being able to check or  fiddle
849              with the traffic.
850
851              Opening an SSL connection over an HTTP proxy is therefore a mat‐
852              ter of asking the proxy for a straight connection to the  target
853              host  on  a  specified  port. This is made with the HTTP request
854              CONNECT. ("please mr proxy, connect me to that remote host").
855
856              Because of the nature of this operation, where the proxy has  no
857              idea  what  kind  of data that is passed in and out through this
858              tunnel, this breaks some of the few advantages  that  come  from
859              using  a proxy, such as caching. Many organizations prevent this
860              kind of tunneling to other destination  port  numbers  than  443
861              (which is the default HTTPS port number).
862
863
864       Tunneling Through Proxy
865              As  explained  above,  tunneling is required for SSL to work and
866              often even restricted to the operation intended for SSL; HTTPS.
867
868              This is however not the only time  proxy-tunneling  might  offer
869              benefits to you or your application.
870
871              As  tunneling opens a direct connection from your application to
872              the remote machine, it suddenly also re-introduces  the  ability
873              to  do  non-HTTP  operations over an HTTP proxy. You can in fact
874              use things such as FTP upload or FTP custom commands this way.
875
876              Again, this is often prevented by the administrators of  proxies
877              and is rarely allowed.
878
879              Tell libcurl to use proxy tunneling like this:
880
881               curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, 1L);
882
883              In  fact,  there  might  even be times when you want to do plain
884              HTTP operations using a tunnel like this, as it then enables you
885              to  operate  on the remote server instead of asking the proxy to
886              do so. libcurl will not stand in the way for such innovative ac‐
887              tions either!
888
889
890       Proxy Auto-Config
891
892              Netscape  first  came  up  with this. It is basically a web page
893              (usually using a .pac extension) with a JavaScript that when ex‐
894              ecuted  by  the browser with the requested URL as input, returns
895              information to the browser on how to connect to the URL. The re‐
896              turned  information  might  be  "DIRECT"  (which  means no proxy
897              should be used), "PROXY host:port" (to tell  the  browser  where
898              the  proxy  for this particular URL is) or "SOCKS host:port" (to
899              direct the browser to a SOCKS proxy).
900
901              libcurl has no means to interpret  or  evaluate  JavaScript  and
902              thus it does not support this. If you get yourself in a position
903              where you face this nasty invention, the following  advice  have
904              been mentioned and used in the past:
905
906              - Depending on the JavaScript complexity, write up a script that
907              translates it to another language and execute that.
908
909              - Read the JavaScript code and rewrite the same logic in another
910              language.
911
912              -  Implement  a JavaScript interpreter; people have successfully
913              used the Mozilla JavaScript engine in the past.
914
915              - Ask your admins to stop this, for a static proxy setup or sim‐
916              ilar.
917
918

Persistence Is The Way to Happiness

920       Re-cycling  the  same easy handle several times when doing multiple re‐
921       quests is the way to go.
922
923       After each single curl_easy_perform(3) operation, libcurl will keep the
924       connection  alive  and  open.  A subsequent request using the same easy
925       handle to the same host might just be able to use the already open con‐
926       nection! This reduces network impact a lot.
927
928       Even if the connection is dropped, all connections involving SSL to the
929       same host again, will benefit from  libcurl's  session  ID  cache  that
930       drastically reduces re-connection time.
931
932       FTP connections that are kept alive save a lot of time, as the command-
933       response round-trips are skipped, and also  you  do  not  risk  getting
934       blocked without permission to login again like on many FTP servers only
935       allowing N persons to be logged in at the same time.
936
937       libcurl caches DNS name resolving results, to make lookups of a  previ‐
938       ously looked up name a lot faster.
939
940       Other  interesting  details that improve performance for subsequent re‐
941       quests may also be added in the future.
942
943       Each easy handle will attempt to keep the last  few  connections  alive
944       for  a while in case they are to be used again. You can set the size of
945       this "cache" with the  CURLOPT_MAXCONNECTS(3)  option.  Default  is  5.
946       There  is  rarely any point in changing this value, and if you think of
947       changing this it is often just a matter of thinking again.
948
949       To force your upcoming request to not use an already  existing  connec‐
950       tion  (it will even close one first if there happens to be one alive to
951       the same host you are about to operate on), you can do that by  setting
952       CURLOPT_FRESH_CONNECT(3) to 1. In a similar spirit, you can also forbid
953       the upcoming request to be "lying" around and possibly get re-used  af‐
954       ter the request by setting CURLOPT_FORBID_REUSE(3) to 1.
955
956

HTTP Headers Used by libcurl

958       When  you  use libcurl to do HTTP requests, it will pass along a series
959       of headers automatically. It might be good for you to know  and  under‐
960       stand  these. You can replace or remove them by using the CURLOPT_HTTP‐
961       HEADER(3) option.
962
963
964       Host   This header is required by HTTP 1.1 and even  many  1.0  servers
965              and  should  be  the name of the server we want to talk to. This
966              includes the port number if anything but default.
967
968
969       Accept "*/*".
970
971
972       Expect When doing POST requests, libcurl sets this header to  "100-con‐
973              tinue"  to ask the server for an "OK" message before it proceeds
974              with sending the data part of  the  post.  If  the  POSTed  data
975              amount is deemed "small", libcurl will not use this header.
976
977

Customizing Operations

979       There is an ongoing development today where more and more protocols are
980       built upon HTTP for transport. This has obvious benefits as HTTP  is  a
981       tested  and reliable protocol that is widely deployed and has excellent
982       proxy-support.
983
984       When you use one of these protocols, and even when doing other kinds of
985       programming  you may need to change the traditional HTTP (or FTP or...)
986       manners. You may need to change words, headers or various data.
987
988       libcurl is your friend here too.
989
990
991       CUSTOMREQUEST
992              If just changing the actual HTTP request  keyword  is  what  you
993              want,  like  when  GET, HEAD or POST is not good enough for you,
994              CURLOPT_CUSTOMREQUEST(3) is there for you. It is simple to use:
995
996               curl_easy_setopt(easyhandle,  CURLOPT_CUSTOMREQUEST,  "MYOWNRE‐
997              QUEST");
998
999              When using the custom request, you change the request keyword of
1000              the actual request you are performing. Thus, by default you make
1001              a  GET  request  but  you can also make a POST operation (as de‐
1002              scribed before) and then replace the POST keyword  if  you  want
1003              to. you are the boss.
1004
1005
1006       Modify Headers
1007              HTTP-like  protocols pass a series of headers to the server when
1008              doing the request, and you are free to pass any amount of  extra
1009              headers that you think fit. Adding headers is this easy:
1010
1011               struct curl_slist *headers=NULL; /* init to NULL is important */
1012
1013               headers = curl_slist_append(headers, "Hey-server-hey: how are you?");
1014               headers = curl_slist_append(headers, "X-silly-content: yes");
1015
1016               /* pass our list of custom made headers */
1017               curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
1018
1019               curl_easy_perform(easyhandle); /* transfer http */
1020
1021               curl_slist_free_all(headers); /* free the header list */
1022
1023              ...  and  if you think some of the internally generated headers,
1024              such as Accept: or Host: do not contain the data you  want  them
1025              to contain, you can replace them by simply setting them too:
1026
1027               headers = curl_slist_append(headers, "Accept: Agent-007");
1028               headers = curl_slist_append(headers, "Host: munged.host.line");
1029
1030
1031       Delete Headers
1032              If you replace an existing header with one with no contents, you
1033              will prevent the header from being sent. For  instance,  if  you
1034              want to completely prevent the "Accept:" header from being sent,
1035              you can disable it with code similar to this:
1036
1037               headers = curl_slist_append(headers, "Accept:");
1038
1039              Both replacing and canceling internal  headers  should  be  done
1040              with  careful consideration and you should be aware that you may
1041              violate the HTTP protocol when doing so.
1042
1043
1044       Enforcing chunked transfer-encoding
1045
1046              By making sure a request uses the custom header "Transfer-Encod‐
1047              ing:  chunked" when doing a non-GET HTTP operation, libcurl will
1048              switch over to "chunked" upload, even though  the  size  of  the
1049              data  to  upload  might  be  known.  By default, libcurl usually
1050              switches over to chunked upload automatically if the upload data
1051              size is unknown.
1052
1053
1054       HTTP Version
1055
1056              All HTTP requests includes the version number to tell the server
1057              which version we support. libcurl speaks HTTP  1.1  by  default.
1058              Some old servers do not like getting 1.1-requests and when deal‐
1059              ing with stubborn old things like that, you can tell libcurl  to
1060              use 1.0 instead by doing something like this:
1061
1062               curl_easy_setopt(easyhandle,              CURLOPT_HTTP_VERSION,
1063              CURL_HTTP_VERSION_1_0);
1064
1065
1066       FTP Custom Commands
1067
1068              Not all protocols are HTTP-like, and thus the above may not help
1069              you  when  you  want to make, for example, your FTP transfers to
1070              behave differently.
1071
1072              Sending custom commands to an FTP server means that you need  to
1073              send the commands exactly as the FTP server expects them (RFC959
1074              is a good guide here), and you can only use commands  that  work
1075              on  the control-connection alone. All kinds of commands that re‐
1076              quire data interchange and thus need a data-connection  must  be
1077              left to libcurl's own judgement. Also be aware that libcurl will
1078              do its best to change directory to the target  directory  before
1079              doing any transfer, so if you change directory (with CWD or sim‐
1080              ilar) you might confuse libcurl and then it might not attempt to
1081              transfer the file in the correct remote directory.
1082
1083              A little example that deletes a given file before an operation:
1084
1085               headers = curl_slist_append(headers, "DELE file-to-remove");
1086
1087               /* pass the list of custom commands to the handle */
1088               curl_easy_setopt(easyhandle, CURLOPT_QUOTE, headers);
1089
1090               curl_easy_perform(easyhandle); /* transfer ftp data! */
1091
1092               curl_slist_free_all(headers); /* free the header list */
1093
1094              If  you  would  instead  want this operation (or chain of opera‐
1095              tions) to happen _after_ the data transfer took place the option
1096              to    curl_easy_setopt(3)   would   instead   be   called   CUR‐
1097              LOPT_POSTQUOTE(3) and used the exact same way.
1098
1099              The custom FTP command will be issued to the server in the  same
1100              order they are added to the list, and if a command gets an error
1101              code returned back from the server, no more commands will be is‐
1102              sued   and   libcurl   will   bail   out   with  an  error  code
1103              (CURLE_QUOTE_ERROR). Note that if you  use  CURLOPT_QUOTE(3)  to
1104              send  commands before a transfer, no transfer will actually take
1105              place when a quote command has failed.
1106
1107              If you set the CURLOPT_HEADER(3) to 1, you will tell libcurl  to
1108              get information about the target file and output "headers" about
1109              it. The headers will be in "HTTP-style", looking like they do in
1110              HTTP.
1111
1112              The  option  to enable headers or to run custom FTP commands may
1113              be useful to combine with CURLOPT_NOBODY(3). If this  option  is
1114              set, no actual file content transfer will be performed.
1115
1116
1117       FTP Custom CUSTOMREQUEST
1118              If  you  do  want to list the contents of an FTP directory using
1119              your own defined FTP command, CURLOPT_CUSTOMREQUEST(3)  will  do
1120              just that. "NLST" is the default one for listing directories but
1121              you are free to pass in your idea of a good alternative.
1122
1123

Cookies Without Chocolate Chips

1125       In the HTTP sense, a cookie is a  name  with  an  associated  value.  A
1126       server  sends  the  name and value to the client, and expects it to get
1127       sent back on every subsequent request to the server  that  matches  the
1128       particular  conditions set. The conditions include that the domain name
1129       and path match and that the cookie has not become too old.
1130
1131       In real-world cases, servers send new cookies to replace existing  ones
1132       to  update  them. Server use cookies to "track" users and to keep "ses‐
1133       sions".
1134
1135       Cookies are sent from server to clients with the header Set-Cookie: and
1136       they are sent from clients to servers with the Cookie: header.
1137
1138       To  just  send  whatever  cookie you want to a server, you can use CUR‐
1139       LOPT_COOKIE(3) to set a cookie string like this:
1140
1141        curl_easy_setopt(easyhandle,       CURLOPT_COOKIE,        "name1=var1;
1142       name2=var2;");
1143
1144       In  many  cases, that is not enough. You might want to dynamically save
1145       whatever cookies the remote server passes to you, and make  sure  those
1146       cookies are then used accordingly on later requests.
1147
1148       One  way to do this, is to save all headers you receive in a plain file
1149       and when you make a request, you tell  libcurl  to  read  the  previous
1150       headers to figure out which cookies to use. Set the header file to read
1151       cookies from with CURLOPT_COOKIEFILE(3).
1152
1153       The CURLOPT_COOKIEFILE(3) option also automatically enables the  cookie
1154       parser in libcurl. Until the cookie parser is enabled, libcurl will not
1155       parse or understand incoming cookies and they  will  just  be  ignored.
1156       However,  when the parser is enabled the cookies will be understood and
1157       the cookies will be kept in memory and used properly in subsequent  re‐
1158       quests when the same handle is used. Many times this is enough, and you
1159       may not have to save the cookies to disk at all. Note that the file you
1160       specify  to  CURLOPT_COOKIEFILE(3) does not have to exist to enable the
1161       parser, so a common way to just enable the  parser  and  not  read  any
1162       cookies is to use the name of a file you know does not exist.
1163
1164       If  you  would rather use existing cookies that you have previously re‐
1165       ceived with your Netscape or Mozilla browsers, you can make libcurl use
1166       that  cookie  file as input. The CURLOPT_COOKIEFILE(3) is used for that
1167       too, as libcurl will automatically find out what kind of file it is and
1168       act accordingly.
1169
1170       Perhaps  the  most  advanced cookie operation libcurl offers, is saving
1171       the entire internal cookie state back into a Netscape/Mozilla formatted
1172       cookie file. We call that the cookie-jar. When you set a file name with
1173       CURLOPT_COOKIEJAR(3), that file name will be created and  all  received
1174       cookies  will be stored in it when curl_easy_cleanup(3) is called. This
1175       enables cookies to get passed  on  properly  between  multiple  handles
1176       without any information getting lost.
1177
1178

FTP Peculiarities We Need

1180       FTP  transfers  use  a  second TCP/IP connection for the data transfer.
1181       This is usually a fact you can forget and ignore but at times this fact
1182       will  come  back to haunt you. libcurl offers several different ways to
1183       customize how the second connection is being made.
1184
1185       libcurl can either connect to the server a  second  time  or  tell  the
1186       server to connect back to it. The first option is the default and it is
1187       also what works best for all the people behind firewalls, NATs  or  IP-
1188       masquerading  setups.   libcurl  then tells the server to open up a new
1189       port and wait for a second connection. This  is  by  default  attempted
1190       with EPSV first, and if that does not work it tries PASV instead. (EPSV
1191       is an extension to the original FTP spec and does not exist nor work on
1192       all FTP servers.)
1193
1194       You  can  prevent libcurl from first trying the EPSV command by setting
1195       CURLOPT_FTP_USE_EPSV(3) to zero.
1196
1197       In some cases, you will prefer to have the server connect back  to  you
1198       for the second connection. This might be when the server is perhaps be‐
1199       hind a firewall or something and only allows connections  on  a  single
1200       port.  libcurl then informs the remote server which IP address and port
1201       number to connect to.  This is made with the CURLOPT_FTPPORT(3) option.
1202       If  you  set  it to "-", libcurl will use your system's "default IP ad‐
1203       dress". If you want to use a particular IP, you can set the full IP ad‐
1204       dress,  a host name to resolve to an IP address or even a local network
1205       interface name that libcurl will get the IP address from.
1206
1207       When doing the "PORT" approach, libcurl will attempt to  use  the  EPRT
1208       and  the LPRT before trying PORT, as they work with more protocols. You
1209       can disable this behavior by setting CURLOPT_FTP_USE_EPRT(3) to zero.
1210
1211

MIME API revisited for SMTP and IMAP

1213       In addition to support HTTP multi-part form fields, the MIME API can be
1214       used  to  build structured email messages and send them via SMTP or ap‐
1215       pend such messages to IMAP directories.
1216
1217       A structured email message may contain several  parts:  some  are  dis‐
1218       played  inline  by  the  MUA,  some  are attachments. Parts can also be
1219       structured as multi-part, for example to include another email  message
1220       or  to  offer  several text formats alternatives. This can be nested to
1221       any level.
1222
1223       To build such a message, you prepare the nth-level multi-part and  then
1224       include  it  as  a  source  to  the  parent  multi-part  using function
1225       curl_mime_subparts(3). Once it has been bound to its parent multi-part,
1226       a  nth-level  multi-part  belongs to it and should not be freed explic‐
1227       itly.
1228
1229       Email messages data is not supposed to be non-ascii and line length  is
1230       limited:  fortunately, some transfer encodings are defined by the stan‐
1231       dards to support the transmission of such incompatible  data.  Function
1232       curl_mime_encoder(3)  tells a part that its source data must be encoded
1233       before being sent. It also generates the corresponding header for  that
1234       part.   If  the part data you want to send is already encoded in such a
1235       scheme, do not use this function (this would over-encode it),  but  ex‐
1236       plicitly set the corresponding part header.
1237
1238       Upon  sending  such a message, libcurl prepends it with the header list
1239       set with CURLOPT_HTTPHEADER(3), as 0th-level mime part headers.
1240
1241       Here is an example building an email message with an inline  plain/html
1242       text alternative and a file attachment encoded in base64:
1243
1244        curl_mime *message = curl_mime_init(easyhandle);
1245
1246        /* The inline part is an alternative proposing the html and the text
1247           versions of the email. */
1248        curl_mime *alt = curl_mime_init(easyhandle);
1249
1250        /* HTML message. */
1251        curl_mimepart *part = curl_mime_addpart(alt);
1252        curl_mime_data(part, "<html><body><p>This is HTML</p></body></html>",
1253                             CURL_ZERO_TERMINATED);
1254        curl_mime_type(part, "text/html");
1255
1256        /* Text message. */
1257        part = curl_mime_addpart(alt);
1258        curl_mime_data(part, "This is plain text message",
1259                             CURL_ZERO_TERMINATED);
1260
1261        /* Create the inline part. */
1262        part = curl_mime_addpart(message);
1263        curl_mime_subparts(part, alt);
1264        curl_mime_type(part, "multipart/alternative");
1265        struct curl_slist *headers = curl_slist_append(NULL,
1266                          "Content-Disposition: inline");
1267        curl_mime_headers(part, headers, TRUE);
1268
1269        /* Add the attachment. */
1270        part = curl_mime_addpart(message);
1271        curl_mime_filedata(part, "manual.pdf");
1272        curl_mime_encoder(part, "base64");
1273
1274        /* Build the mail headers. */
1275        headers = curl_slist_append(NULL, "From: me@example.com");
1276        headers = curl_slist_append(headers, "To: you@example.com");
1277
1278        /* Set these into the easy handle. */
1279        curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
1280        curl_easy_setopt(easyhandle, CURLOPT_MIMEPOST, mime);
1281
1282       It  should  be  noted that appending a message to an IMAP directory re‐
1283       quires the message size to be known prior upload. It is  therefore  not
1284       possible to include parts with unknown data size in this context.
1285
1286

Headers Equal Fun

1288       Some  protocols  provide "headers", meta-data separated from the normal
1289       data. These headers are by default not  included  in  the  normal  data
1290       stream, but you can make them appear in the data stream by setting CUR‐
1291       LOPT_HEADER(3) to 1.
1292
1293       What might be even more useful, is libcurl's ability  to  separate  the
1294       headers  from  the data and thus make the callbacks differ. You can for
1295       example set a different pointer to pass to the ordinary write  callback
1296       by setting CURLOPT_HEADERDATA(3).
1297
1298       Or,  you  can set an entirely separate function to receive the headers,
1299       by using CURLOPT_HEADERFUNCTION(3).
1300
1301       The headers are passed to the callback function one by one, and you can
1302       depend  on  that  fact. It makes it easier for you to add custom header
1303       parsers etc.
1304
1305       "Headers" for FTP transfers equal all the FTP  server  responses.  They
1306       are  not  actually  true headers, but in this case we pretend they are!
1307       ;-)
1308
1309

Post Transfer Information

1311       See curl_easy_getinfo(3).
1312

The multi Interface

1314       The easy interface as described in detail in this document  is  a  syn‐
1315       chronous  interface  that transfers one file at a time and does not re‐
1316       turn until it is done.
1317
1318       The multi interface, on the other hand, allows your program to transfer
1319       multiple files in both directions at the same time, without forcing you
1320       to use multiple threads. The name might make it seem that the multi in‐
1321       terface is for multi-threaded programs, but the truth is almost the re‐
1322       verse. The multi interface allows a single-threaded application to per‐
1323       form  the  same  kinds  of multiple, simultaneous transfers that multi-
1324       threaded programs can perform. It allows many of the benefits of multi-
1325       threaded transfers without the complexity of managing and synchronizing
1326       many threads.
1327
1328       To complicate matters somewhat more, there are even two versions of the
1329       multi  interface. The event based one, also called multi_socket and the
1330       "normal one" designed for using with select(). See the  libcurl-multi.3
1331       man page for details on the multi_socket event based API, this descrip‐
1332       tion here is for the select() oriented one.
1333
1334       To use this interface, you are better off if you first  understand  the
1335       basics  of how to use the easy interface. The multi interface is simply
1336       a way to make multiple transfers at the same time by adding up multiple
1337       easy handles into a "multi stack".
1338
1339       You create the easy handles you want, one for each concurrent transfer,
1340       and you set all the options just like you learned above, and  then  you
1341       create  a  multi  handle with curl_multi_init(3) and add all those easy
1342       handles to that multi handle with curl_multi_add_handle(3).
1343
1344       When you have added the handles you have for the moment (you can  still
1345       add  new  ones  at  any  time),  you  start  the  transfers  by calling
1346       curl_multi_perform(3).
1347
1348       curl_multi_perform(3) is asynchronous. It will only perform what can be
1349       done  now  and  then  return control to your program. It is designed to
1350       never block. You need to keep calling the function until all  transfers
1351       are completed.
1352
1353       The  best usage of this interface is when you do a select() on all pos‐
1354       sible file descriptors or sockets to know when to call  libcurl  again.
1355       This  also makes it easy for you to wait and respond to actions on your
1356       own application's sockets/handles. You figure out what to select()  for
1357       by  using  curl_multi_fdset(3), that fills in a set of fd_set variables
1358       for you with the particular file descriptors libcurl uses for  the  mo‐
1359       ment.
1360
1361       When  you  then call select(), it will return when one of the file han‐
1362       dles signal action and you then  call  curl_multi_perform(3)  to  allow
1363       libcurl  to  do  what  it wants to do. Take note that libcurl does also
1364       feature some time-out code so we advise you to never use long  timeouts
1365       on    select()    before    you   call   curl_multi_perform(3)   again.
1366       curl_multi_timeout(3) is provided to help you get  a  suitable  timeout
1367       period.
1368
1369       Another  precaution you should use: always call curl_multi_fdset(3) im‐
1370       mediately before the select() call since the current set  of  file  de‐
1371       scriptors may change in any curl function invoke.
1372
1373       If  you  want  to  stop  the transfer of one of the easy handles in the
1374       stack, you can use  curl_multi_remove_handle(3)  to  remove  individual
1375       easy    handles.    Remember    that    easy    handles    should    be
1376       curl_easy_cleanup(3)ed.
1377
1378       When a transfer within the multi stack has  finished,  the  counter  of
1379       running  transfers  (as  filled  in  by curl_multi_perform(3)) will de‐
1380       crease. When the number reaches zero, all transfers are done.
1381
1382       curl_multi_info_read(3) can be used to get information about  completed
1383       transfers.  It then returns the CURLcode for each easy transfer, to al‐
1384       low you to figure out success on each individual transfer.
1385
1386

SSL, Certificates and Other Tricks

1388        [ seeding, passwords, keys, certificates, ENGINE, ca certs ]
1389
1390

Sharing Data Between Easy Handles

1392       You can share some data between easy handles when the easy interface is
1393       used,  and  some data is share automatically when you use the multi in‐
1394       terface.
1395
1396       When you add easy handles to a multi handle, these  easy  handles  will
1397       automatically share a lot of the data that otherwise would be kept on a
1398       per-easy handle basis when the easy interface is used.
1399
1400       The DNS cache is shared between handles within a multi  handle,  making
1401       subsequent  name resolving faster, and the connection pool that is kept
1402       to better allow persistent connections and connection  re-use  is  also
1403       shared.  If you are using the easy interface, you can still share these
1404       between specific  easy  handles  by  using  the  share  interface,  see
1405       libcurl-share(3).
1406
1407       Some  things  are never shared automatically, not within multi handles,
1408       like for example cookies so the only way to  share  that  is  with  the
1409       share interface.
1410

Footnotes

1412       [1]    libcurl  7.10.3  and  later  have  the ability to switch over to
1413              chunked Transfer-Encoding in cases where HTTP uploads  are  done
1414              with data of an unknown size.
1415
1416       [2]    This  happens on Windows machines when libcurl is built and used
1417              as a DLL. However, you can still do this on Windows if you  link
1418              with a static library.
1419
1420       [3]    The  curl-config  tool  is generated at build-time (on Unix-like
1421              systems) and should be installed with the 'make install' or sim‐
1422              ilar  instruction  that  installs the library, header files, man
1423              pages etc.
1424
1425       [4]    This behavior was different in  versions  before  7.17.0,  where
1426              strings  had  to  remain valid past the end of the curl_easy_se‐
1427              topt(3) call.
1428

SEE ALSO

1430       libcurl-errors(3), libcurl-multi(3), libcurl-easy(3)
1431
1432
1433
1434libcurl 7.85.0                   May 17, 2022              libcurl-tutorial(3)
Impressum