Daniel Stenberg goes through some basic libcurl fundamentals and API design and explain how easily you can get your first transfers going in your own application. libcurl is the defacto standard library for Internet transfers and runs on virtually all platforms. The language focus will be on C/C++ but the concepts are generally applicable even if you use libcurl bindings for other languages.

1. Getting started
with libcurl
With Daniel Stenberg

2. Daniel Stenberg
@bagder
https://daniel.haxx.se

3. libcurl basics
libcurl basics
Synchronous transfers
Synchronous transfers
Getting information
Getting information
Non-blocking concurrent transfers
Non-blocking concurrent transfers
Q&A
Q&A
@bagder
@bagder

4. @bagder
@bagder
The Basics

5. @bagder
@bagder
cURL = curl && libcurl
The Open Source project itself is often called cURL or just curl
The command line tool is called curl
The internet transfer library is called libcurl
Today we focus on libcurl
libcurl is MIT licensed with commercial support available
@bagder
@bagder

6. @bagder
@bagder
Get libcurl
Install it from your linux distribution provider
Install it from home brew on macOS
…
Build it yourself from source (not detailed today)
@bagder
@bagder

7. @bagder
@bagder
Build your code to use libcurl
Tell the compiler where to find the includes
Tell the linker to use libcurl
@bagder
@bagder
$ gcc -lcurl example.c -o example

8. @bagder
@bagder
Different libcurl builds
Different versions
Different platforms
Different features enabled at build-time
Different backends enabled at build-time
Different third party library versions
@bagder
@bagder

9. @bagder
@bagder
Documentation!
Every function has a man page
Every option has a man page
>100 stand-alone examples
https://curl.se/ has them all (updated)
https://everything.curl.dev/ provides more resources
Tip: just google the function/option name
@bagder
@bagder

10. @bagder
@bagder
API and ABI
Libcurl doesn’t break API or ABI
Once introduced, features and behaviors remain
The SONAME was last bumped in 2006
The API works the same on all platforms
Build-time disabled protocols/features aside
@bagder
@bagder

11. @bagder
@bagder
Different API sets
Libcurl offers a few difererent API “sets” grouped by prefix
curl_easy_*
curl_multi_*
curl_share_*
curl_url_*
etc
@bagder
@bagder

12. @bagder
@bagder
API principles
@bagder
@bagder

13. @bagder
@bagder
Transfer oriented
With libcurl, you setup and perform transfers
Transfers operate with URLs
Get data from a URL or send data to a URL
The other end is always a URL
The default transfer is as simple as possible
The API is generally protocol agnostic
Change behavior by setting options
@bagder
@bagder

14. @bagder
@bagder
Easy handles
“CURL *handle” are often referred to as easy handles
Once created, it identifies a single transfer
Can and should be reused!
Options are sticky, they remain set until told otherwise
Options set copy data (with one notable exception)
CURLOPT_URL is the only mandatory option for a transfer

15. @bagder
@bagder
The easy interface

16. @bagder
@bagder
The easy interface
Synchronous transfers
Performed to the end, returns first once successful or failure
Done as fast as possible
Might take a long time; seconds, minutes, hours, weeks
You can limit how long time it may take

17. @bagder
@bagder
Create easy handle
CURL *easy = curl_easy_init();
Creates an easy handle and initiates it with default values.
This is just an opaque handle, there are no public struct fields.
Similar in spirit to FILE *

18. @bagder
@bagder
Create easy handle and set options
CURL *easy = curl_easy_init();
CURLcode rc = curl_easy_setopt(easy, CURLOPT_URL,
“https://curl.se”);
Options accept different argument types depending on the
option
Read the documentation for each option for details!

19. @bagder
@bagder
Some curl_easy_setopt options
CURLOPT_URL
CURLOPT_VERBOSE
CURLOPT_BUFFERSIZE
CURLOPT_ERRORBUFFER
CURLOPT_WRITEFUNCTION
CURLOPT_READFUNCTION
CURLOPT_TIMEOUT_MS
CURLOPT_CONNECTTIMEOUT_MS
Almost 300
options
Available!

20. @bagder
@bagder
Let’s talk source code

21. @bagder
@bagder
There’s only one include file to know!
#include <curl/curl.h>

22. @bagder
@bagder
A minimal easy example
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
res = curl_easy_perform(curl);
if(res != CURLE_OK)
printf("transfer fail: %sn", curl_easy_strerror(res));
curl_easy_cleanup(curl);
}

23. @bagder
@bagder
Getting and sending data

24. @bagder
@bagder
Get data
Provide a write callback: CURLOPT_WRITEFUNCTION
size_t writecb (void *contents, size_t size, size_t nmemb, void *userp)
{
size_t realsize = size * nmemb;
// the data is in ‘contents’
// ‘userp’ is what CURLOPT_WRITEDATA set
return realsize;
}

25. @bagder
@bagder
Send data
The three primary ways to provide data to libcurl for sending:
CURLOPT_READFUNCTION
CURLOPT_POSTFIELDS
CURLOPT_MIMEPOST

26. @bagder
@bagder
A minimal easy POST example
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, “hello”);
res = curl_easy_perform(curl);
if(res != CURLE_OK)
printf("transfer fail: %sn", curl_easy_strerror(res));
curl_easy_cleanup(curl);
}

27. @bagder
@bagder
Getting transfer information

28. @bagder
@bagder
curl_easy_getinfo()
Pull data from an easy handle after a transfer.
CURLINFO_EFFECTIVE_URL
CURLINFO_RESPONSE_CODE
CURLINFO_TOTAL_TIME_T
CURLINFO_SPEED_DOWNLOAD_T
CURLINFO_CONTENT_TYPE
… and many more

29. @bagder
@bagder
curl_easy_getinfo()
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
char *ct;
res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct);
if((CURLE_OK == res) && ct)
printf("We received Content-Type: %sn", ct);
}

30. @bagder
@bagder
When things go wrong

31. @bagder
@bagder
Debug your libcurl program!
Check return codes!
CURLOPT_VERBOSE
CURLOPT_ERRORBUFFER
CURLOPT_DEBUGFUNCTION
valgrind
curl-library mailing list
Commercial support

32. @bagder
@bagder
Parallel non-blocking transfers

33. @bagder
@bagder
The multi interface
Multiple concurrent non-blocking transfers – in a single thread
Create and setup easy handles just as before
Create a multi handle
Add easy handles to the multi handle
Drive all transfers in parallel
Leaves the event loop to the application!

34. @bagder
@bagder
A multi example
easy_handle = curl_easy_init();
easy_handle2 = curl_easy_init();
curl_easy_setopt(easy_handle, CURLOPT_URL, "https://www.example.com/");
curl_easy_setopt(easy_handle2, CURLOPT_URL, "http://localhost/");
multi_handle = curl_multi_init();
curl_multi_add_handle(multi_handle, easy_handle);
curl_multi_add_handle(multi_handle, easy_handle2);
while(still_running) {
CURLMcode mc = curl_multi_perform(multi_handle, &still_running);
if(still_running) {
mc = curl_multi_poll(multi_handle, NULL, 0, 1000, NULL);
if(mc)
Break;
}
do {
msg = curl_multi_info_read(multi_handle, &queued);
if(msg) {
if(msg->msg == CURLMSG_DONE) {
fprintf(stderr, "Transfer completedn");
}
}
} while(msg);
}
curl_multi_remove_handle(multi_handle, easy_handle);
curl_multi_remove_handle(multi_handle, easy_handle2);
curl_multi_cleanup(multi_handle);
curl_easy_cleanup(easy_handle);
curl_easy_cleanup(easy_handle2);

35. @bagder
@bagder
Going further
You can add and remove transfers at any point
Mix in and also wait for your own file descriptors
curl_multi_setopt()
curl_multi_socket_action() for event-based logic
For hundreds or thousands of concurrent transfers

36. @bagder
@bagder
and much much more

37. https://everything.curl.dev/
@bagder
@bagder

38. 38
You can help!
You can help!
@bagder
@bagder

39. Daniel Stenberg
@bagder
https://daniel.haxx.se/
Thank you!
Thank you!
Questions?
Questions?
@bagder
@bagder

40. @bagder
@bagder
License
This presentation and its contents are
licensed under the Creative Commons
Attribution 4.0 license:
http://creativecommons.org/licenses/by/4.0/
@bagder
@bagder