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

Portable Code in a Portable World

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

Global Preparation

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

Features libcurl Provides

125       It is considered best-practice to determine libcurl features at runtime
126       rather than at build-time (if possible of course). By calling curl_ver‐
127       sion_info(3)  and checking out the details of the returned struct, your
128       program can figure out exactly what the currently running libcurl  sup‐
129       ports.
130
131

Two Interfaces

133       libcurl  first  introduced the so called easy interface. All operations
134       in the easy interface are prefixed with 'curl_easy'. The easy interface
135       lets  you  do single transfers with a synchronous and blocking function
136       call.
137
138       libcurl also offers another interface that allows multiple simultaneous
139       transfers in a single thread, the so called multi interface. More about
140       that interface is detailed in a  separate  chapter  further  down.  You
141       still  need  to understand the easy interface first, so please continue
142       reading for better understanding.
143

Handle the Easy libcurl

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

Multi-threading Issues

248       libcurl  is  thread  safe  but  there  are  a  few exceptions. Refer to
249       libcurl-thread(3) for more information.
250
251

When It does not Work

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

Upload Data to a Remote Site

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

Passwords

325       Many protocols use or even require that user name and password are pro‐
326       vided to be able to download or upload the data of your choice. libcurl
327       offers several ways to specify them.
328
329       Most  protocols  support  that you specify the name and password in the
330       URL itself. libcurl will detect this and use them accordingly. This  is
331       written like this:
332        protocol://user:password@example.com/path/
333       If  you  need any odd letters in your user name or password, you should
334       enter them URL encoded, as %XX where XX is a two-digit hexadecimal num‐
335       ber.
336
337       libcurl  also  provides options to set various passwords. The user name
338       and password as shown embedded in the URL can instead get set with  the
339       CURLOPT_USERPWD(3)  option.  The argument passed to libcurl should be a
340       char * to a string in the format  "user:password".  In  a  manner  like
341       this:
342        curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret");
343       Another  case  where name and password might be needed at times, is for
344       those users who need to authenticate themselves to a  proxy  they  use.
345       libcurl offers another option for this, the CURLOPT_PROXYUSERPWD(3). It
346       is used quite similar to the CURLOPT_USERPWD(3) option like this:
347        curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
348       There's a long time Unix "standard" way of storing FTP user  names  and
349       passwords,  namely  in  the $HOME/.netrc file (on Windows, libcurl also
350       checks the %USERPROFILE% environment variable if %HOME% is  unset,  and
351       tries  "_netrc"  as name). The file should be made private so that only
352       the user may read it (see also the "Security Considerations"  chapter),
353       as it might contain the password in plain text. libcurl has the ability
354       to use this file to figure out what set of user name  and  password  to
355       use for a particular host. As an extension to the normal functionality,
356       libcurl also supports this file for non-FTP protocols such as HTTP.  To
357       make curl use this file, use the CURLOPT_NETRC(3) option:
358        curl_easy_setopt(handle, CURLOPT_NETRC, 1L);
359       And a basic example of how such a .netrc file may look like:
360
361        machine myhost.mydomain.com
362        login userlogin
363        password secretword
364
365       All  these  examples  have  been  cases where the password has been op‐
366       tional, or at least you could leave it out and have libcurl attempt  to
367       do  its  job  without  it. There are times when the password is not op‐
368       tional, like when you are using an SSL private key  for  secure  trans‐
369       fers.
370
371       To pass the known private key password to libcurl:
372        curl_easy_setopt(handle, CURLOPT_KEYPASSWD, "keypassword");
373

HTTP Authentication

375       The  previous chapter showed how to set user name and password for get‐
376       ting URLs that require authentication. When using  the  HTTP  protocol,
377       there are many different ways a client can provide those credentials to
378       the server and you can control which way libcurl will (attempt to)  use
379       them.  The  default HTTP authentication method is called 'Basic', which
380       is sending the name and password in clear-text  in  the  HTTP  request,
381       base64-encoded. This is insecure.
382
383       At  the  time  of this writing, libcurl can be built to use: Basic, Di‐
384       gest, NTLM, Negotiate (SPNEGO). You can tell libcurl which one  to  use
385       with CURLOPT_HTTPAUTH(3) as in:
386        curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
387       And when you send authentication to a proxy, you can also set authenti‐
388       cation type the same way but instead with CURLOPT_PROXYAUTH(3):
389        curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
390       Both these options allow you to set multiple types (by ORing  them  to‐
391       gether),  to make libcurl pick the most secure one out of the types the
392       server/proxy claims to support. This method does however add  a  round-
393       trip since libcurl must first ask the server what it supports:
394        curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC);
395       For convenience, you can use the CURLAUTH_ANY define (instead of a list
396       with specific types) which allows libcurl to  use  whatever  method  it
397       wants.
398
399       When  asking for multiple types, libcurl will pick the available one it
400       considers "best" in its own internal order of preference.
401
402

HTTP POSTing

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

Converting from deprecated form API to MIME API

565       Four rules have to be respected in building the multi-part:
566       - The easy handle must be created before building the multi-part.
567       - The multi-part is always created by a call to curl_mime_init(handle).
568       - Each part is created by a call to curl_mime_addpart(multipart).
569       -  When complete, the multi-part must be bound to the easy handle using
570       CURLOPT_MIMEPOST(3) instead of CURLOPT_HTTPPOST(3).
571
572       Here are some example of curl_formadd calls to MIME API sequences:
573
574        curl_formadd(&post, &last,
575                     CURLFORM_COPYNAME, "id",
576                     CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
577                     CURLFORM_CONTENTHEADER, headers,
578                     CURLFORM_END);
579       becomes:
580        part = curl_mime_addpart(multipart);
581        curl_mime_name(part, "id");
582        curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
583        curl_mime_headers(part, headers, FALSE);
584
585       Setting the last curl_mime_headers argument to TRUE would  have  caused
586       the headers to be automatically released upon destroyed the multi-part,
587       thus saving a clean-up call to curl_slist_free_all(3).
588
589        curl_formadd(&post, &last,
590                     CURLFORM_PTRNAME, "logotype-image",
591                     CURLFORM_FILECONTENT, "-",
592                     CURLFORM_END);
593       becomes:
594        part = curl_mime_addpart(multipart);
595        curl_mime_name(part, "logotype-image");
596        curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin);
597
598       curl_mime_name always copies the field name. The special file name  "-"
599       is  not  supported by curl_mime_file: to read an open file, use a call‐
600       back source using fread(). The transfer will be chunked since the  data
601       size is unknown.
602
603        curl_formadd(&post, &last,
604                     CURLFORM_COPYNAME, "datafile[]",
605                     CURLFORM_FILE, "file1",
606                     CURLFORM_FILE, "file2",
607                     CURLFORM_END);
608       becomes:
609        part = curl_mime_addpart(multipart);
610        curl_mime_name(part, "datafile[]");
611        curl_mime_filedata(part, "file1");
612        part = curl_mime_addpart(multipart);
613        curl_mime_name(part, "datafile[]");
614        curl_mime_filedata(part, "file2");
615
616       The  deprecated  multipart/mixed implementation of multiple files field
617       is translated to two distinct parts with the same name.
618
619        curl_easy_setopt(handle, CURLOPT_READFUNCTION, myreadfunc);
620        curl_formadd(&post, &last,
621                     CURLFORM_COPYNAME, "stream",
622                     CURLFORM_STREAM, arg,
623                     CURLFORM_CONTENTLEN, (curl_off_t) datasize,
624                     CURLFORM_FILENAME, "archive.zip",
625                     CURLFORM_CONTENTTYPE, "application/zip",
626                     CURLFORM_END);
627       becomes:
628        part = curl_mime_addpart(multipart);
629        curl_mime_name(part, "stream");
630        curl_mime_data_cb(part, (curl_off_t) datasize,
631                          myreadfunc, NULL, NULL, arg);
632        curl_mime_filename(part, "archive.zip");
633        curl_mime_type(part, "application/zip");
634
635       CURLOPT_READFUNCTION callback is not used: it is  replace  by  directly
636       setting the part source data from the callback read function.
637
638        curl_formadd(&post, &last,
639                     CURLFORM_COPYNAME, "memfile",
640                     CURLFORM_BUFFER, "memfile.bin",
641                     CURLFORM_BUFFERPTR, databuffer,
642                     CURLFORM_BUFFERLENGTH, (long) sizeof databuffer,
643                     CURLFORM_END);
644       becomes:
645        part = curl_mime_addpart(multipart);
646        curl_mime_name(part, "memfile");
647        curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer);
648        curl_mime_filename(part, "memfile.bin");
649
650       curl_mime_data always copies the initial data: data buffer is thus free
651       for immediate reuse.
652
653        curl_formadd(&post, &last,
654                     CURLFORM_COPYNAME, "message",
655                     CURLFORM_FILECONTENT, "msg.txt",
656                     CURLFORM_END);
657       becomes:
658        part = curl_mime_addpart(multipart);
659        curl_mime_name(part, "message");
660        curl_mime_filedata(part, "msg.txt");
661        curl_mime_filename(part, NULL);
662
663       Use of curl_mime_filedata sets the remote file name as a  side  effect:
664       it  is  therefore necessary to clear it for CURLFORM_FILECONTENT emula‐
665       tion.
666
667

Showing Progress

669       For historical and traditional reasons, libcurl has a built-in progress
670       meter  that can be switched on and then makes it present a progress me‐
671       ter in your terminal.
672
673       Switch on the progress meter  by,  oddly  enough,  setting  CURLOPT_NO‐
674       PROGRESS(3) to zero. This option is set to 1 by default.
675
676       For  most  applications however, the built-in progress meter is useless
677       and what instead is interesting is the ability to  specify  a  progress
678       callback.  The function pointer you pass to libcurl will then be called
679       on irregular intervals with information about the current transfer.
680
681       Set the progress callback  by  using  CURLOPT_PROGRESSFUNCTION(3).  And
682       pass a pointer to a function that matches this prototype:
683
684        int progress_callback(void *clientp,
685                              double dltotal,
686                              double dlnow,
687                              double ultotal,
688                              double ulnow);
689
690       If any of the input arguments is unknown, a 0 will be passed. The first
691       argument, the 'clientp' is the pointer you pass to  libcurl  with  CUR‐
692       LOPT_PROGRESSDATA(3). libcurl will not touch it.
693
694

libcurl with C++

696       There's basically only one thing to keep in mind when using C++ instead
697       of C when interfacing libcurl:
698
699       The callbacks CANNOT be non-static class member functions
700
701       Example C++ code:
702
703       class AClass {
704           static size_t write_data(void *ptr, size_t size, size_t nmemb,
705                                    void *ourpointer)
706           {
707             /* do what you want with the data */
708           }
709        }
710
711

Proxies

713       What "proxy" means according to Merriam-Webster: "a  person  authorized
714       to  act  for  another"  but  also "the agency, function, or office of a
715       deputy who acts as a substitute for another".
716
717       Proxies are exceedingly common these days. Companies often  only  offer
718       Internet  access to employees through their proxies. Network clients or
719       user-agents ask the proxy for documents, the proxy does the actual  re‐
720       quest and then it returns them.
721
722       libcurl  supports  SOCKS  and HTTP proxies. When a given URL is wanted,
723       libcurl will ask the proxy for it instead of trying to connect  to  the
724       actual host identified in the URL.
725
726       If  you  are  using  a  SOCKS proxy, you may find that libcurl does not
727       quite support all operations through it.
728
729       For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain
730       restrictions  on  what  can actually happen. A requested URL that might
731       not be a HTTP URL will be still be passed to the HTTP proxy to  deliver
732       back to libcurl. This happens transparently, and an application may not
733       need to know. I say "may", because at times it is important  to  under‐
734       stand that all operations over an HTTP proxy use the HTTP protocol. For
735       example, you cannot invoke your own custom FTP commands or even  proper
736       FTP directory listings.
737
738
739       Proxy Options
740
741              To tell libcurl to use a proxy at a given port number:
742               curl_easy_setopt(handle, CURLOPT_PROXY, "proxy-host.com:8080");
743              Some  proxies  require user authentication before allowing a re‐
744              quest, and you pass that information similar to this:
745               curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "user:password");
746              If you want to, you can specify the host name only in  the  CUR‐
747              LOPT_PROXY(3)  option,  and  set the port number separately with
748              CURLOPT_PROXYPORT(3).
749
750              Tell libcurl what kind of proxy it is with  CURLOPT_PROXYTYPE(3)
751              (if not, it will default to assume an HTTP proxy):
752               curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4);
753
754       Environment Variables
755
756              libcurl automatically checks and uses a set of environment vari‐
757              ables to know what proxies to use  for  certain  protocols.  The
758              names  of  the  variables are following an old tradition and are
759              built up as "[protocol]_proxy" (note the  lower  casing).  Which
760              makes the variable 'http_proxy' checked for a name of a proxy to
761              use when the input URL is HTTP. Following  the  same  rule,  the
762              variable  named  'ftp_proxy' is checked for FTP URLs. Again, the
763              proxies are always HTTP proxies,  the  different  names  of  the
764              variables simply allows different HTTP proxies to be used.
765
766              The  proxy environment variable contents should be in the format
767              "[protocol://][user:password@]machine[:port]". Where the  proto‐
768              col://  part  specifies  which  type of proxy it is, and the op‐
769              tional port number specifies on which port the  proxy  operates.
770              If  not specified, the internal default port number will be used
771              and that is most likely not the one you would like it to be.
772
773              There are two special environment variables. 'all_proxy' is what
774              sets  proxy  for  any URL in case the protocol specific variable
775              was not set, and 'no_proxy' defines a list of hosts that  should
776              not use a proxy even though a variable may say so. If 'no_proxy'
777              is a plain asterisk ("*") it matches all hosts.
778
779              To explicitly disable libcurl's checking for and using the proxy
780              environment  variables,  set  the  proxy  name  to "" - an empty
781              string - with CURLOPT_PROXY(3).
782
783       SSL and Proxies
784
785              SSL is for  secure  point-to-point  connections.  This  involves
786              strong encryption and similar things, which effectively makes it
787              impossible for a proxy to operate as a "man  in  between"  which
788              the  proxy's task is, as previously discussed. Instead, the only
789              way to have SSL work over an HTTP proxy is to ask the  proxy  to
790              tunnel  everything through without being able to check or fiddle
791              with the traffic.
792
793              Opening an SSL connection over an HTTP proxy is therefore a mat‐
794              ter  of asking the proxy for a straight connection to the target
795              host on a specified port. This is made  with  the  HTTP  request
796              CONNECT. ("please dear proxy, connect me to that remote host").
797
798              Because  of the nature of this operation, where the proxy has no
799              idea what kind of data that is passed in and  out  through  this
800              tunnel,  this  breaks  some of the few advantages that come from
801              using a proxy, such as caching. Many organizations prevent  this
802              kind  of  tunneling  to  other destination port numbers than 443
803              (which is the default HTTPS port number).
804
805
806       Tunneling Through Proxy
807              As explained above, tunneling is required for SSL  to  work  and
808              often even restricted to the operation intended for SSL; HTTPS.
809
810              This  is  however  not the only time proxy-tunneling might offer
811              benefits to you or your application.
812
813              As tunneling opens a direct connection from your application  to
814              the  remote  machine, it suddenly also re-introduces the ability
815              to do non-HTTP operations over an HTTP proxy. You  can  in  fact
816              use things such as FTP upload or FTP custom commands this way.
817
818              Again,  this is often prevented by the administrators of proxies
819              and is rarely allowed.
820
821              Tell libcurl to use proxy tunneling like this:
822               curl_easy_setopt(handle, CURLOPT_HTTPPROXYTUNNEL, 1L);
823              In fact, there might even be times when you  want  to  do  plain
824              HTTP operations using a tunnel like this, as it then enables you
825              to operate on the remote server instead of asking the  proxy  to
826              do so. libcurl will not stand in the way for such innovative ac‐
827              tions either!
828
829
830       Proxy Auto-Config
831
832              Netscape first came up with this. It is  basically  a  web  page
833              (usually using a .pac extension) with a JavaScript that when ex‐
834              ecuted by the browser with the requested URL as  input,  returns
835              information to the browser on how to connect to the URL. The re‐
836              turned information might  be  "DIRECT"  (which  means  no  proxy
837              should  be  used),  "PROXY host:port" (to tell the browser where
838              the proxy for this particular URL is) or "SOCKS  host:port"  (to
839              direct the browser to a SOCKS proxy).
840
841              libcurl  has  no  means  to interpret or evaluate JavaScript and
842              thus it does not support this. If you get yourself in a position
843              where  you  face this nasty invention, the following advice have
844              been mentioned and used in the past:
845
846              - Depending on the JavaScript complexity, write up a script that
847              translates it to another language and execute that.
848
849              - Read the JavaScript code and rewrite the same logic in another
850              language.
851
852              - Implement a JavaScript interpreter; people  have  successfully
853              used the Mozilla JavaScript engine in the past.
854
855              - Ask your admins to stop this, for a static proxy setup or sim‐
856              ilar.
857
858

Persistence Is The Way to Happiness

860       Re-cycling the same easy handle several times when doing  multiple  re‐
861       quests is the way to go.
862
863       After each single curl_easy_perform(3) operation, libcurl will keep the
864       connection alive and open. A subsequent request  using  the  same  easy
865       handle to the same host might just be able to use the already open con‐
866       nection! This reduces network impact a lot.
867
868       Even if the connection is dropped, all connections involving SSL to the
869       same  host  again,  will  benefit  from libcurl's session ID cache that
870       drastically reduces re-connection time.
871
872       FTP connections that are kept alive save a lot of time, as the command-
873       response  round-trips  are  skipped,  and  also you do not risk getting
874       blocked without permission to login again like on many FTP servers only
875       allowing N persons to be logged in at the same time.
876
877       libcurl  caches DNS name resolving results, to make lookups of a previ‐
878       ously looked up name a lot faster.
879
880       Other interesting details that improve performance for  subsequent  re‐
881       quests may also be added in the future.
882
883       Each  easy  handle  will attempt to keep the last few connections alive
884       for a while in case they are to be used again. You can set the size  of
885       this  "cache"  with  the  CURLOPT_MAXCONNECTS(3)  option. Default is 5.
886       There is rarely any point in changing this value, and if you  think  of
887       changing this it is often just a matter of thinking again.
888
889       To  force  your upcoming request to not use an already existing connec‐
890       tion (it will even close one first if there happens to be one alive  to
891       the  same host you are about to operate on), you can do that by setting
892       CURLOPT_FRESH_CONNECT(3) to 1. In a similar spirit, you can also forbid
893       the  upcoming request to be "lying" around and possibly get re-used af‐
894       ter the request by setting CURLOPT_FORBID_REUSE(3) to 1.
895
896

HTTP Headers Used by libcurl

898       When you use libcurl to do HTTP requests, it will pass along  a  series
899       of  headers  automatically. It might be good for you to know and under‐
900       stand these. You can replace or remove them by using the  CURLOPT_HTTP‐
901       HEADER(3) option.
902
903
904       Host   This  header  is  required by HTTP 1.1 and even many 1.0 servers
905              and should be the name of the server we want to  talk  to.  This
906              includes the port number if anything but default.
907
908
909       Accept "*/*".
910
911
912       Expect When  doing POST requests, libcurl sets this header to "100-con‐
913              tinue" to ask the server for an "OK" message before it  proceeds
914              with  sending  the  data  part  of  the post. If the posted data
915              amount is deemed "small", libcurl will not use this header.
916
917

Customizing Operations

919       There is an ongoing development today where more and more protocols are
920       built  upon  HTTP for transport. This has obvious benefits as HTTP is a
921       tested and reliable protocol that is widely deployed and has  excellent
922       proxy-support.
923
924       When you use one of these protocols, and even when doing other kinds of
925       programming you may need to change the traditional HTTP (or FTP  or...)
926       manners. You may need to change words, headers or various data.
927
928       libcurl is your friend here too.
929
930
931       CUSTOMREQUEST
932              If  just  changing  the  actual HTTP request keyword is what you
933              want, like when GET, HEAD or POST is not good  enough  for  you,
934              CURLOPT_CUSTOMREQUEST(3) is there for you. It is simple to use:
935               curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST");
936              When using the custom request, you change the request keyword of
937              the actual request you are performing. Thus, by default you make
938              a  GET  request  but  you can also make a POST operation (as de‐
939              scribed before) and then replace the POST keyword  if  you  want
940              to. you are the boss.
941
942
943       Modify Headers
944              HTTP-like  protocols pass a series of headers to the server when
945              doing the request, and you are free to pass any amount of  extra
946              headers that you think fit. Adding headers is this easy:
947
948               struct curl_slist *headers=NULL; /* init to NULL is important */
949
950               headers = curl_slist_append(headers, "Hey-server-hey: how are you?");
951               headers = curl_slist_append(headers, "X-silly-content: yes");
952
953               /* pass our list of custom made headers */
954               curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
955
956               curl_easy_perform(handle); /* transfer http */
957
958               curl_slist_free_all(headers); /* free the header list */
959
960              ...  and  if you think some of the internally generated headers,
961              such as Accept: or Host: do not contain the data you  want  them
962              to contain, you can replace them by simply setting them too:
963
964               headers = curl_slist_append(headers, "Accept: Agent-007");
965               headers = curl_slist_append(headers, "Host: munged.host.line");
966
967
968       Delete Headers
969              If you replace an existing header with one with no contents, you
970              will prevent the header from being sent. For  instance,  if  you
971              want to completely prevent the "Accept:" header from being sent,
972              you can disable it with code similar to this:
973
974               headers = curl_slist_append(headers, "Accept:");
975
976              Both replacing and canceling internal  headers  should  be  done
977              with  careful consideration and you should be aware that you may
978              violate the HTTP protocol when doing so.
979
980
981       Enforcing chunked transfer-encoding
982
983              By making sure a request uses the custom header "Transfer-Encod‐
984              ing:  chunked" when doing a non-GET HTTP operation, libcurl will
985              switch over to "chunked" upload, even though  the  size  of  the
986              data  to  upload  might  be  known.  By default, libcurl usually
987              switches over to chunked upload automatically if the upload data
988              size is unknown.
989
990
991       HTTP Version
992
993              All HTTP requests includes the version number to tell the server
994              which version we support. libcurl speaks HTTP  1.1  by  default.
995              Some old servers do not like getting 1.1-requests and when deal‐
996              ing with stubborn old things like that, you can tell libcurl  to
997              use 1.0 instead by doing something like this:
998
999               curl_easy_setopt(handle,  CURLOPT_HTTP_VERSION,  CURL_HTTP_VER‐
1000              SION_1_0);
1001
1002
1003       FTP Custom Commands
1004
1005              Not all protocols are HTTP-like, and thus the above may not help
1006              you  when  you  want to make, for example, your FTP transfers to
1007              behave differently.
1008
1009              Sending custom commands to an FTP server means that you need  to
1010              send the commands exactly as the FTP server expects them (RFC959
1011              is a good guide here), and you can only use commands  that  work
1012              on  the control-connection alone. All kinds of commands that re‐
1013              quire data interchange and thus need a data-connection  must  be
1014              left  to libcurl's own judgment. Also be aware that libcurl will
1015              do its best to change directory to the target  directory  before
1016              doing any transfer, so if you change directory (with CWD or sim‐
1017              ilar) you might confuse libcurl and then it might not attempt to
1018              transfer the file in the correct remote directory.
1019
1020              A little example that deletes a given file before an operation:
1021
1022               headers = curl_slist_append(headers, "DELE file-to-remove");
1023
1024               /* pass the list of custom commands to the handle */
1025               curl_easy_setopt(handle, CURLOPT_QUOTE, headers);
1026
1027               curl_easy_perform(handle); /* transfer ftp data! */
1028
1029               curl_slist_free_all(headers); /* free the header list */
1030
1031              If  you  would  instead  want this operation (or chain of opera‐
1032              tions) to happen _after_ the data transfer took place the option
1033              to    curl_easy_setopt(3)   would   instead   be   called   CUR‐
1034              LOPT_POSTQUOTE(3) and used the exact same way.
1035
1036              The custom FTP command will be issued to the server in the  same
1037              order they are added to the list, and if a command gets an error
1038              code returned back from the server, no more commands will be is‐
1039              sued   and   libcurl   will   bail   out   with  an  error  code
1040              (CURLE_QUOTE_ERROR). Note that if you  use  CURLOPT_QUOTE(3)  to
1041              send  commands before a transfer, no transfer will actually take
1042              place when a quote command has failed.
1043
1044              If you set the CURLOPT_HEADER(3) to 1, you will tell libcurl  to
1045              get information about the target file and output "headers" about
1046              it. The headers will be in "HTTP-style", looking like they do in
1047              HTTP.
1048
1049              The  option  to enable headers or to run custom FTP commands may
1050              be useful to combine with CURLOPT_NOBODY(3). If this  option  is
1051              set, no actual file content transfer will be performed.
1052
1053
1054       FTP Custom CUSTOMREQUEST
1055              If  you  do  want to list the contents of an FTP directory using
1056              your own defined FTP command, CURLOPT_CUSTOMREQUEST(3)  will  do
1057              just that. "NLST" is the default one for listing directories but
1058              you are free to pass in your idea of a good alternative.
1059
1060

Cookies Without Chocolate Chips

1062       In the HTTP sense, a cookie is a  name  with  an  associated  value.  A
1063       server  sends  the  name and value to the client, and expects it to get
1064       sent back on every subsequent request to the server  that  matches  the
1065       particular  conditions set. The conditions include that the domain name
1066       and path match and that the cookie has not become too old.
1067
1068       In real-world cases, servers send new cookies to replace existing  ones
1069       to  update  them. Server use cookies to "track" users and to keep "ses‐
1070       sions".
1071
1072       Cookies are sent from server to clients with the header Set-Cookie: and
1073       they are sent from clients to servers with the Cookie: header.
1074
1075       To  just  send  whatever  cookie you want to a server, you can use CUR‐
1076       LOPT_COOKIE(3) to set a cookie string like this:
1077        curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;");
1078       In many cases, that is not enough. You might want to  dynamically  save
1079       whatever  cookies  the remote server passes to you, and make sure those
1080       cookies are then used accordingly on later requests.
1081
1082       One way to do this, is to save all headers you receive in a plain  file
1083       and  when  you  make  a  request, you tell libcurl to read the previous
1084       headers to figure out which cookies to use. Set the header file to read
1085       cookies from with CURLOPT_COOKIEFILE(3).
1086
1087       The  CURLOPT_COOKIEFILE(3) option also automatically enables the cookie
1088       parser in libcurl. Until the cookie parser is enabled, libcurl will not
1089       parse  or  understand  incoming  cookies and they will just be ignored.
1090       However, when the parser is enabled the cookies will be understood  and
1091       the  cookies will be kept in memory and used properly in subsequent re‐
1092       quests when the same handle is used. Many times this is enough, and you
1093       may not have to save the cookies to disk at all. Note that the file you
1094       specify to CURLOPT_COOKIEFILE(3) does not have to exist to  enable  the
1095       parser,  so  a  common  way  to just enable the parser and not read any
1096       cookies is to use the name of a file you know does not exist.
1097
1098       If you would rather use existing cookies that you have  previously  re‐
1099       ceived with your Netscape or Mozilla browsers, you can make libcurl use
1100       that cookie file as input. The CURLOPT_COOKIEFILE(3) is used  for  that
1101       too, as libcurl will automatically find out what kind of file it is and
1102       act accordingly.
1103
1104       Perhaps the most advanced cookie operation libcurl  offers,  is  saving
1105       the entire internal cookie state back into a Netscape/Mozilla formatted
1106       cookie file. We call that the cookie-jar. When you set a file name with
1107       CURLOPT_COOKIEJAR(3),  that  file name will be created and all received
1108       cookies will be stored in it when curl_easy_cleanup(3) is called.  This
1109       enables  cookies  to  get  passed  on properly between multiple handles
1110       without any information getting lost.
1111
1112

FTP Peculiarities We Need

1114       FTP transfers use a second TCP/IP connection  for  the  data  transfer.
1115       This is usually a fact you can forget and ignore but at times this fact
1116       will come back to haunt you. libcurl offers several different  ways  to
1117       customize how the second connection is being made.
1118
1119       libcurl  can  either  connect  to  the server a second time or tell the
1120       server to connect back to it. The first option is the default and it is
1121       also  what  works best for all the people behind firewalls, NATs or IP-
1122       masquerading setups.  libcurl then tells the server to open  up  a  new
1123       port  and  wait  for  a second connection. This is by default attempted
1124       with EPSV first, and if that does not work it tries PASV instead. (EPSV
1125       is an extension to the original FTP spec and does not exist nor work on
1126       all FTP servers.)
1127
1128       You can prevent libcurl from first trying the EPSV command  by  setting
1129       CURLOPT_FTP_USE_EPSV(3) to zero.
1130
1131       In  some  cases, you will prefer to have the server connect back to you
1132       for the second connection. This might be when the server is perhaps be‐
1133       hind  a  firewall  or something and only allows connections on a single
1134       port. libcurl then informs the remote server which IP address and  port
1135       number to connect to.  This is made with the CURLOPT_FTPPORT(3) option.
1136       If you set it to "-", libcurl will use your system's  "default  IP  ad‐
1137       dress". If you want to use a particular IP, you can set the full IP ad‐
1138       dress, a host name to resolve to an IP address or even a local  network
1139       interface name that libcurl will get the IP address from.
1140
1141       When  doing  the  "PORT" approach, libcurl will attempt to use the EPRT
1142       and the LPRT before trying PORT, as they work with more protocols.  You
1143       can disable this behavior by setting CURLOPT_FTP_USE_EPRT(3) to zero.
1144
1145

MIME API revisited for SMTP and IMAP

1147       In addition to support HTTP multi-part form fields, the MIME API can be
1148       used to build structured email messages and send them via SMTP  or  ap‐
1149       pend such messages to IMAP directories.
1150
1151       A  structured  email  message  may contain several parts: some are dis‐
1152       played inline by the MUA, some  are  attachments.  Parts  can  also  be
1153       structured  as multi-part, for example to include another email message
1154       or to offer several text formats alternatives. This can  be  nested  to
1155       any level.
1156
1157       To  build such a message, you prepare the nth-level multi-part and then
1158       include it  as  a  source  to  the  parent  multi-part  using  function
1159       curl_mime_subparts(3). Once it has been bound to its parent multi-part,
1160       a nth-level multi-part belongs to it and should not  be  freed  explic‐
1161       itly.
1162
1163       Email  messages data is not supposed to be non-ascii and line length is
1164       limited: fortunately, some transfer encodings are defined by the  stan‐
1165       dards  to  support the transmission of such incompatible data. Function
1166       curl_mime_encoder(3) tells a part that its source data must be  encoded
1167       before  being sent. It also generates the corresponding header for that
1168       part.  If the part data you want to send is already encoded in  such  a
1169       scheme,  do  not use this function (this would over-encode it), but ex‐
1170       plicitly set the corresponding part header.
1171
1172       Upon sending such a message, libcurl prepends it with the  header  list
1173       set with CURLOPT_HTTPHEADER(3), as zero level mime part headers.
1174
1175       Here  is an example building an email message with an inline plain/html
1176       text alternative and a file attachment encoded in base64:
1177
1178        curl_mime *message = curl_mime_init(handle);
1179
1180        /* The inline part is an alternative proposing the html and the text
1181           versions of the email. */
1182        curl_mime *alt = curl_mime_init(handle);
1183
1184        /* HTML message. */
1185        curl_mimepart *part = curl_mime_addpart(alt);
1186        curl_mime_data(part, "<html><body><p>This is HTML</p></body></html>",
1187                             CURL_ZERO_TERMINATED);
1188        curl_mime_type(part, "text/html");
1189
1190        /* Text message. */
1191        part = curl_mime_addpart(alt);
1192        curl_mime_data(part, "This is plain text message",
1193                             CURL_ZERO_TERMINATED);
1194
1195        /* Create the inline part. */
1196        part = curl_mime_addpart(message);
1197        curl_mime_subparts(part, alt);
1198        curl_mime_type(part, "multipart/alternative");
1199        struct curl_slist *headers = curl_slist_append(NULL,
1200                          "Content-Disposition: inline");
1201        curl_mime_headers(part, headers, TRUE);
1202
1203        /* Add the attachment. */
1204        part = curl_mime_addpart(message);
1205        curl_mime_filedata(part, "manual.pdf");
1206        curl_mime_encoder(part, "base64");
1207
1208        /* Build the mail headers. */
1209        headers = curl_slist_append(NULL, "From: me@example.com");
1210        headers = curl_slist_append(headers, "To: you@example.com");
1211
1212        /* Set these into the easy handle. */
1213        curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
1214        curl_easy_setopt(handle, CURLOPT_MIMEPOST, mime);
1215
1216       It should be noted that appending a message to an  IMAP  directory  re‐
1217       quires  the  message size to be known prior upload. It is therefore not
1218       possible to include parts with unknown data size in this context.
1219
1220

Headers Equal Fun

1222       Some protocols provide "headers", meta-data separated from  the  normal
1223       data.  These  headers  are  by  default not included in the normal data
1224       stream, but you can make them appear in the data stream by setting CUR‐
1225       LOPT_HEADER(3) to 1.
1226
1227       What  might  be  even more useful, is libcurl's ability to separate the
1228       headers from the data and thus make the callbacks differ. You  can  for
1229       example  set a different pointer to pass to the ordinary write callback
1230       by setting CURLOPT_HEADERDATA(3).
1231
1232       Or, you can set an entirely separate function to receive  the  headers,
1233       by using CURLOPT_HEADERFUNCTION(3).
1234
1235       The headers are passed to the callback function one by one, and you can
1236       depend on that fact. It makes it easier for you to  add  custom  header
1237       parsers etc.
1238
1239       "Headers"  for  FTP  transfers equal all the FTP server responses. They
1240       are not actually true headers, but in this case we  pretend  they  are!
1241       ;-)
1242
1243

Post Transfer Information

1245       See curl_easy_getinfo(3).
1246

The multi Interface

1248       The  easy  interface  as described in detail in this document is a syn‐
1249       chronous interface that transfers one file at a time and does  not  re‐
1250       turn until it is done.
1251
1252       The multi interface, on the other hand, allows your program to transfer
1253       multiple files in both directions at the same time, without forcing you
1254       to use multiple threads. The name might make it seem that the multi in‐
1255       terface is for multi-threaded programs, but the truth is almost the re‐
1256       verse. The multi interface allows a single-threaded application to per‐
1257       form the same kinds of multiple,  simultaneous  transfers  that  multi-
1258       threaded programs can perform. It allows many of the benefits of multi-
1259       threaded transfers without the complexity of managing and synchronizing
1260       many threads.
1261
1262       To complicate matters somewhat more, there are even two versions of the
1263       multi interface. The event based one, also called multi_socket and  the
1264       "normal  one" designed for using with select(). See the libcurl-multi.3
1265       man page for details on the multi_socket event based API, this descrip‐
1266       tion here is for the select() oriented one.
1267
1268       To  use  this interface, you are better off if you first understand the
1269       basics of how to use the easy interface. The multi interface is  simply
1270       a way to make multiple transfers at the same time by adding up multiple
1271       easy handles into a "multi stack".
1272
1273       You create the easy handles you want, one for each concurrent transfer,
1274       and  you  set all the options just like you learned above, and then you
1275       create a multi handle with curl_multi_init(3) and add  all  those  easy
1276       handles to that multi handle with curl_multi_add_handle(3).
1277
1278       When  you have added the handles you have for the moment (you can still
1279       add new  ones  at  any  time),  you  start  the  transfers  by  calling
1280       curl_multi_perform(3).
1281
1282       curl_multi_perform(3) is asynchronous. It will only perform what can be
1283       done now and then return control to your program.  It  is  designed  to
1284       never  block. You need to keep calling the function until all transfers
1285       are completed.
1286
1287       The best usage of this interface is when you do a select() on all  pos‐
1288       sible  file  descriptors or sockets to know when to call libcurl again.
1289       This also makes it easy for you to wait and respond to actions on  your
1290       own  application's sockets/handles. You figure out what to select() for
1291       by using curl_multi_fdset(3), that fills in a set of  fd_set  variables
1292       for  you  with the particular file descriptors libcurl uses for the mo‐
1293       ment.
1294
1295       When you then call select(), it will return when one of the  file  han‐
1296       dles  signal  action  and  you then call curl_multi_perform(3) to allow
1297       libcurl to do what it wants to do. Take note  that  libcurl  does  also
1298       feature  some time-out code so we advise you to never use long timeouts
1299       on   select()   before   you    call    curl_multi_perform(3)    again.
1300       curl_multi_timeout(3)  is  provided  to help you get a suitable timeout
1301       period.
1302
1303       Another precaution you should use: always call curl_multi_fdset(3)  im‐
1304       mediately  before  the  select() call since the current set of file de‐
1305       scriptors may change in any curl function invoke.
1306
1307       If you want to stop the transfer of one of  the  easy  handles  in  the
1308       stack,  you  can  use  curl_multi_remove_handle(3) to remove individual
1309       easy    handles.    Remember    that    easy    handles    should    be
1310       curl_easy_cleanup(3)ed.
1311
1312       When  a  transfer  within  the multi stack has finished, the counter of
1313       running transfers (as filled  in  by  curl_multi_perform(3))  will  de‐
1314       crease. When the number reaches zero, all transfers are done.
1315
1316       curl_multi_info_read(3)  can be used to get information about completed
1317       transfers. It then returns the CURLcode for each easy transfer, to  al‐
1318       low you to figure out success on each individual transfer.
1319
1320

SSL, Certificates and Other Tricks

1322        [ seeding, passwords, keys, certificates, ENGINE, ca certs ]
1323
1324

Sharing Data Between Easy Handles

1326       You can share some data between easy handles when the easy interface is
1327       used, and some data is share automatically when you use the  multi  in‐
1328       terface.
1329
1330       When  you  add  easy handles to a multi handle, these easy handles will
1331       automatically share a lot of the data that otherwise would be kept on a
1332       per-easy handle basis when the easy interface is used.
1333
1334       The  DNS  cache is shared between handles within a multi handle, making
1335       subsequent name resolving faster, and the connection pool that is  kept
1336       to  better  allow  persistent connections and connection re-use is also
1337       shared. If you are using the easy interface, you can still share  these
1338       between  specific  easy  handles  by  using  the  share  interface, see
1339       libcurl-share(3).
1340
1341       Some things are never shared automatically, not within  multi  handles,
1342       like  for  example  cookies  so  the only way to share that is with the
1343       share interface.
1344

Footnotes

1346       [1]    libcurl 7.10.3 and later have the  ability  to  switch  over  to
1347              chunked  Transfer-Encoding  in cases where HTTP uploads are done
1348              with data of an unknown size.
1349
1350       [2]    This happens on Windows machines when libcurl is built and  used
1351              as  a DLL. However, you can still do this on Windows if you link
1352              with a static library.
1353
1354       [3]    The curl-config tool is generated at  build-time  (on  Unix-like
1355              systems) and should be installed with the 'make install' or sim‐
1356              ilar instruction that installs the library,  header  files,  man
1357              pages etc.
1358
1359       [4]    This  behavior  was  different  in versions before 7.17.0, where
1360              strings had to remain valid past the end  of  the  curl_easy_se‐
1361              topt(3) call.
1362

SEE ALSO

1364       libcurl-errors(3), libcurl-multi(3), libcurl-easy(3)
1365
1366
1367
1368libcurl 8.0.1                  January 02, 2023            libcurl-tutorial(3)
Impressum