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 prewritten macro that probably
72              does    everything    you    need    in    this    area.     See
73              docs/libcurl/libcurl.m4  file  -  it includes docs on how to use
74              it.
75
76

Portable Code in a Portable World

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

Global Preparation

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

Features libcurl Provides

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

Two Interfaces

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

Handle the Easy libcurl

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

Multi-threading Issues

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

When It Doesn't Work

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

Upload Data to a Remote Site

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

Passwords

352       Many protocols use or even require that user name and password are pro‐
353       vided to be able to download or upload the data of your choice. libcurl
354       offers several ways to specify them.
355
356       Most protocols support that you specify the name and  password  in  the
357       URL  itself. libcurl will detect this and use them accordingly. This is
358       written like this:
359
360        protocol://user:password@example.com/path/
361
362       If you need any odd letters in your user name or password,  you  should
363       enter them URL encoded, as %XX where XX is a two-digit hexadecimal num‐
364       ber.
365
366       libcurl also provides options to set various passwords. The  user  name
367       and  password as shown embedded in the URL can instead get set with the
368       CURLOPT_USERPWD(3) option. The argument passed to libcurl should  be  a
369       char  *  to  a  string  in the format "user:password". In a manner like
370       this:
371
372        curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret");
373
374       Another case where name and password might be needed at times,  is  for
375       those  users  who  need to authenticate themselves to a proxy they use.
376       libcurl offers another option for this, the CURLOPT_PROXYUSERPWD(3). It
377       is used quite similar to the CURLOPT_USERPWD(3) option like this:
378
379        curl_easy_setopt(easyhandle,    CURLOPT_PROXYUSERPWD,   "myname:these‐
380       cret");
381
382       There's a long time Unix "standard" way of storing FTP user  names  and
383       passwords,  namely  in  the  $HOME/.netrc file. The file should be made
384       private so that only the user may read it (see also the "Security  Con‐
385       siderations"  chapter), as it might contain the password in plain text.
386       libcurl has the ability to use this file to figure out what set of user
387       name  and password to use for a particular host. As an extension to the
388       normal functionality, libcurl also supports this file for non-FTP  pro‐
389       tocols  such  as  HTTP.  To  make  curl  use  this  file,  use the CUR‐
390       LOPT_NETRC(3) option:
391
392        curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L);
393
394       And a very 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  isn't  op‐
403       tional, like when you're using an SSL private key for secure transfers.
404
405       To pass the known private key password to libcurl:
406
407        curl_easy_setopt(easyhandle, CURLOPT_KEYPASSWD, "keypassword");
408
409

HTTP Authentication

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

HTTP POSTing

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

Converting from deprecated form API to MIME API

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

Showing Progress

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

libcurl with C++

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

Proxies

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

Persistence Is The Way to Happiness

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

HTTP Headers Used by libcurl

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

Customizing Operations

978       There is an ongoing development today where more and more protocols are
979       built  upon  HTTP for transport. This has obvious benefits as HTTP is a
980       tested and reliable protocol that is widely deployed and has  excellent
981       proxy-support.
982
983       When you use one of these protocols, and even when doing other kinds of
984       programming you may need to change the traditional HTTP (or FTP  or...)
985       manners. You may need to change words, headers or various data.
986
987       libcurl is your friend here too.
988
989
990       CUSTOMREQUEST
991              If  just  changing  the  actual HTTP request keyword is what you
992              want, like when GET, HEAD or POST is not good  enough  for  you,
993              CURLOPT_CUSTOMREQUEST(3)  is there for you. It is very simple to
994              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're 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're 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: don't contain the data you want them to
1025              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  very  old servers don't like getting 1.1-requests and when
1059              dealing with stubborn old things like that, you can tell libcurl
1060              to 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 very best to change directory to the target directory be‐
1079              fore doing any transfer, so if you change directory (with CWD or
1080              similar) you might confuse libcurl and then it might not attempt
1081              to 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're 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 hasn't 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're 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)  doesn't 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 doesn't exist.
1163
1164       If  you  would  rather  use existing cookies that you've 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 doesn't 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 e-mail messages and send them via SMTP or ap‐
1215       pend such messages to IMAP directories.
1216
1217       A structured e-mail 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 e-mail 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       E-mail 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 e-mail 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 e-mail. */
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       aren't actually true headers, but in this case we pretend they are! ;-)
1307
1308

Post Transfer Information

1310       See curl_easy_getinfo(3).
1311

The multi Interface

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

SSL, Certificates and Other Tricks

1386        [ seeding, passwords, keys, certificates, ENGINE, ca certs ]
1387
1388

Sharing Data Between Easy Handles

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

Footnotes

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

SEE ALSO

1428       libcurl-errors(3), libcurl-multi(3), libcurl-easy(3)
1429
1430
1431
1432libcurl 7.76.1                 November 05, 2020           libcurl-tutorial(3)
Impressum