Using the libcurl Library (C Programming)

curl is a command line tool that can upload and download files from HTTP and FTP servers. Actually, that’s a gross oversimplification; curl knows how to deal with HTTP, FTP, secure HTTP and FTP servers, gopher servers, telnet servers, local files, and many more protocols.

Downloading a file with curl is easy. For example, to download a file named news.html from the example.com Web site (and save it to a file named mylocalfile), execute the following command:

$curl -o mylocalfile http://example.com/ news.html

curl is very similar to the more familiar wget, except that wget can only download data; curl can move data in both directions.

You can harness the power of curl in your own C programs by making calls to the libcurl API. The libcurl library comes in two flavors that you can mix and match. The easy API defines only six functions (and you can write useful, network-enabled programs using only four of those functions). The multi interface is more complex. When you call a function in the easy API, your program pauses until the function completes. The multi interface, on the other hand, performs transfers in the background, returning control to your program as soon as you initiate a transfer. In other words, the easy API is synchronous, and the multi interface is asynchronous.

You can find the curl (and libcurl) Web site at curl.haxx.se. You’ll find complete (and easy-to-follow) documentation about both the easy and the multi interface.

The Fedora, SuSE, and Mandrake distributions all include the curl command line program in an RPM package named curl. To write libcurl-enabled programs, install the curl package and the curl-devel package.

The multi API is built with functions defined by the easy API. That means that you can mix functions from both interfaces.

Everything that you know about the easy interface is applicable when you build a more sophisticated program based on the multi interface.

Uploading a File with a Simple Program Using libcurl

Every libcurl program starts with a call to an initialization function (typically curl_easy_init()) and ends with a call to a cleanup function (typically curl_easy_cleanup()). In between these calls, you use the curl_easy_setopt() and curl_easy_perform() functions to create and execute transfer jobs. Listing 53-1 shows a simple program (named curlupload) that uses libcurl’s easy API to upload a file.

When you run curlupload (we show you how to compile it in a moment), include two command line parameters:

The name of the file you want to upload

The upload destination, specified in the form of a URL

For example, to upload a file named photo.jpg to an FTP server, use this command:

$curlupload ./photo.jpg ftp://ftp. example.com/pub/upload/

When you use this example in your own code, be sure to add some error checking. Check the command line arguments and be sure the files are valid files. See the libcurl documentation to find out how errors are reported to your program.

The following sections take a closer look at some lines in the curlupload program.

Line 7: Defining functions and data types

The libcurl C functions and data types are defined in the curl/curl.h header file, so libcurl-enabled programs should #include that file (see line 7).

Line 14: Calling the initialization function

Line 14 shows the call to the libcurl initialization function, curl_easy_init(). curl_easy_init(). This call returns a handle.

A handle is a small piece of data that a library uses to keep track of the state of something. In the case of libcurl, the handle holds the state of a transfer job. In libcurl programs, a handle takes the form of a CURL pointer (see line 11).

So what does a CURL pointer point to? Who knows? That’s the whole point of a handle — the API’s author puts anything that he needs into the structure behind the handle, but the author of a client application (that’s you) can’t see the data. The API creates the handle, and the client application just gives it back to the API whenever it’s needed.

Lines 18– 21: Defining the transfer

To create a transfer job, use curl_easy_setopt() to define the characteristics of the transfer. Each time you call curl_easy_setopt(), you pass three parameters:

The CURL handle returned by curl_easy_init()

The symbolic name of the option you want to change

The new value for the option

To upload a file, you must set four transfer options, as shown on Lines 18–21.

Line 18: Routing libcurl error messages

Line 18 sets the CURLOPT_ERRORBUFFER option. This option tells libcurl where to store any error messages in case something whacks out. When you set the CURLOPT_ERRORBUFFER option, the third argument specifies the buffer where libcurl will store the error messages. The documentation tells you that the error message buffer should be at least CURL_ERROR_SIZE bytes long (see line 16).

Speaking of documentation, when you install the curl RPM package, the documentation for libcurl is installed as well. See info curl_easy_setopt (or man curl_easy_ setopt if you prefer) for a complete list of transfer options and values.

Line 19: Telling libcurl you want to upload a file

At line 19, you define the CURLOPT_UPLOAD option to let libcurl know that you want to upload a file (by default, libcurl assumes that you want to download data).

You may have noticed that the data type for the third argument to curl_easy_setopt() varies. In some cases, the third argument is a char *; in others, it’s a numeric value; and a few options expect a Boolean value. Unfortunately, you have to infer the proper data type from the online documentation.

Line 20: Telling libcurl where to send data

specified in the form of a URL, and curlupload simply passes along the second command line argument (argv[2]). CURLOPT_URL is arguably the most important and most powerful transfer option.

libcurl supports full URL syntax, so you can include a host name, user name, password, directory, and file name when you run curlupload. Here are a few examples:

ftp://example.com

A simple URL specifies a protocol (ftp) and a host name (example.com). libcurl can upload data by using http or ftp. You can’t upload to a URL this simple because you have to specify a target filename (but you can download from a simple URL).

ftp://freddie@example.com

If you don’t specify a user name, libcurl assumes that you want to log in to an FTP server as user anonymous. If you want to connect using a different user name, just insert the user name, followed by @ in front of the host name.

ftp://freddie:password@example.com

You can also include a password in a URL by inserting a colon (:) and the password following the user name.

ftp://example.com/pub/

A URL that ends with a / specifies a directory name. You can’t upload to a URL that ends with /, but you can download from such a URL.

ftp://example.com/pub/drinks.txt

Because this URL does not end in a /, libcurl assumes that drinks.txt is the name of the destination file.

Line 21: Telling libcurl where the data resides