Somewhat updated, changes include: I tried to be more agnostic about the

.\" *                            | (__| |_| |  _ <| |___

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" *

.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" *

.\" *

.\" * This software is licensed as described in the file COPYING, which

.\" * This software is licensed as described in the file COPYING, which

.\" * you should have received as part of this distribution. The terms

.\" * you should have received as part of this distribution. The terms

.\" * $Id$

.\" * $Id$

.\" **************************************************************************

.\" **************************************************************************

.\"

.\"

.TH libcurl-tutorial 3 "9 May 2005" "libcurl" "libcurl programming"

.TH libcurl-tutorial 3 "27 Feb 2007" "libcurl" "libcurl programming"

.SH NAME

.SH NAME

libcurl-tutorial \- libcurl programming tutorial

libcurl-tutorial \- libcurl programming tutorial

.SH "Objective"

.SH "Objective"

.IP "SSL or Not"

.IP "SSL or Not"

libcurl can be built and customized in many ways. One of the things that

libcurl can be built and customized in many ways. One of the things that

varies from different libraries and builds is the support for SSL-based

varies from different libraries and builds is the support for SSL-based

transfers, like HTTPS and FTPS. If OpenSSL was detected properly at

transfers, like HTTPS and FTPS. If a supported SSL library was detected

build-time, libcurl will be built with SSL support. To figure out if an

properly at build-time, libcurl will be built with SSL support. To figure out

installed libcurl has been built with SSL support enabled, use 'curl-config'

if an installed libcurl has been built with SSL support enabled, use

like this:

\&'curl-config' like this:

$ curl-config --feature

$ curl-config --feature

your program already does this or of another library in use does it, you

your program already does this or of another library in use does it, you

should not tell libcurl to do this as well.

should not tell libcurl to do this as well.

.IP CURL_GLOBAL_SSL

.IP CURL_GLOBAL_SSL

which only does anything on libcurls compiled and built

which only does anything on libcurls compiled and built SSL-enabled. On these

SSL-enabled. On these systems, this will make libcurl initialize OpenSSL

systems, this will make libcurl initialize the SSL library properly for this

properly for this application. This is only needed to do once for each

application. This is only needed to do once for each application so if your

application so if your program or another library already does this, this

program or another library already does this, this bit should not be needed.

bit should not be needed.

.RE

.RE

libcurl has a default protection mechanism that detects if

libcurl has a default protection mechanism that detects if

built without c-ares support and not on Windows..

built without c-ares support and not on Windows..

If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are

If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are

then of course using OpenSSL/GnuTLS multi-threaded and those libs have their

then of course using the underlying SSL library multi-threaded and those libs

own requirements on this issue. Basically, you need to provide one or two

might have their own requirements on this issue. Basically, you need to

functions to allow it to function properly. For all details, see this:

provide one or two functions to allow it to function properly. For all

details, see this:

OpenSSL

OpenSSL

 http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html

 http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html

NSS

 is claimed to be thread-safe already without anything required

yassl

 Required actions unknown

When using multiple threads you should set the CURLOPT_NOSIGNAL option to TRUE

When using multiple threads you should set the CURLOPT_NOSIGNAL option to TRUE

for all handles. Everything will or might work fine except that timeouts are

for all handles. Everything will or might work fine except that timeouts are

not honored during the DNS lookup - which you can work around by building

not honored during the DNS lookup - which you can work around by building

for another" but also "the agency, function, or office of a deputy who acts as

for another" but also "the agency, function, or office of a deputy who acts as

a substitute for another".

a substitute for another".

Proxies are exceedingly common these days. Companies often only offer

Proxies are exceedingly common these days. Companies often only offer Internet

Internet access to employees through their HTTP proxies. Network clients or

access to employees through their proxies. Network clients or user-agents ask

user-agents ask the proxy for documents, the proxy does the actual request

the proxy for documents, the proxy does the actual request and then it returns

and then it returns them.

them.

libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl

will ask the proxy for it instead of trying to connect to the actual host

identified in the URL.

libcurl has full support for HTTP proxies, so when a given URL is wanted,

If you're using a SOCKS proxy, you may find that libcurl doesn't quite support

libcurl will ask the proxy for it instead of trying to connect to the actual

all operations through it.

host identified in the URL.

The fact that the proxy is a HTTP proxy puts certain restrictions on what can

For HTTP proxies: the fact that the proxy is a HTTP proxy puts certain

actually happen. A requested URL that might not be a HTTP URL will be still

restrictions on what can actually happen. A requested URL that might not be a

be passed to the HTTP proxy to deliver back to libcurl. This happens

HTTP URL will be still be passed to the HTTP proxy to deliver back to

transparently, and an application may not need to know. I say "may", because

libcurl. This happens transparently, and an application may not need to

at times it is very important to understand that all operations over a HTTP

know. I say "may", because at times it is very important to understand that

proxy is using the HTTP protocol. For example, you can't invoke your own

all operations over a HTTP proxy is using the HTTP protocol. For example, you

custom FTP commands or even proper FTP directory listings.

can't invoke your own custom FTP commands or even proper FTP directory

listings.

.IP "Proxy Options"

.IP "Proxy Options"

If you want to, you can specify the host name only in the CURLOPT_PROXY

If you want to, you can specify the host name only in the CURLOPT_PROXY

option, and set the port number separately with CURLOPT_PROXYPORT.

option, and set the port number separately with CURLOPT_PROXYPORT.

Tell libcurl what kind of proxy it is with CURLOPT_PROXYTYPE (if not, it will

default to assume a HTTP proxy):

 curl_easy_setopt(easyhandle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4);

.IP "Environment Variables"

.IP "Environment Variables"

libcurl automatically checks and uses a set of environment variables to

libcurl automatically checks and uses a set of environment variables to

variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all

variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all

hosts.

hosts.

To explicitly disable libcurl's checking for and using the proxy environment

variables, set the proxy name to "" - an empty string - with CURLOPT_PROXY.

.IP "SSL and Proxies"

.IP "SSL and Proxies"

SSL is for secure point-to-point connections. This involves strong encryption

SSL is for secure point-to-point connections. This involves strong encryption

point in changing this value, and if you think of changing this it is often

point in changing this value, and if you think of changing this it is often

just a matter of thinking again.

just a matter of thinking again.

When the connection cache gets filled, libcurl must close an existing

connection in order to get room for the new one. To know which connection to

close, libcurl uses a "close policy" that you can affect with the

CURLOPT_CLOSEPOLICY option. There's only two polices implemented as of this

writing (libcurl 7.9.4) and they are:

.RS

.IP CURLCLOSEPOLICY_LEAST_RECENTLY_USED

simply close the one that hasn't been used for the longest time. This is the

default behavior.

.IP CURLCLOSEPOLICY_OLDEST

closes the oldest connection, the one that was created the longest time ago.

.RE

There are, or at least were, plans to support a close policy that would call

a user-specified callback to let the user be able to decide which connection

to dump when this is necessary and therefor is the CURLOPT_CLOSEFUNCTION an

existing option still today. Nothing ever uses this though and this will not

be used within the foreseeable future either.

To force your upcoming request to not use an already existing connection (it

To force your upcoming request to not use an already existing connection (it

will even close one first if there happens to be one alive to the same host

will even close one first if there happens to be one alive to the same host

you're about to operate on), you can do that by setting CURLOPT_FRESH_CONNECT

you're about to operate on), you can do that by setting CURLOPT_FRESH_CONNECT

.SH "HTTP Headers Used by libcurl"

.SH "HTTP Headers Used by libcurl"

When you use libcurl to do HTTP requests, it'll pass along a series of headers

When you use libcurl to do HTTP requests, it'll pass along a series of headers

automatically. It might be good for you to know and understand these ones.

automatically. It might be good for you to know and understand these ones. You

can replace or remove them by using the CURLOPT_HTTPHEADER option.

.IP "Host"

.IP "Host"

This header is required by HTTP 1.1 and even many 1.0 servers and should be

This header is required by HTTP 1.1 and even many 1.0 servers and should be

.IP "Accept"

.IP "Accept"

\&"*/*".

\&"*/*".

.IP "Expect:"

.IP "Expect"

When doing multi-part formposts, libcurl will set this header to

When doing POST requests, libcurl sets this header to \&"100-continue" to ask

\&"100-continue" to ask the server for an "OK" message before it proceeds with

the server for an "OK" message before it proceeds with sending the data part

sending the data part of the post.

of the post. If the POSTed data amount is deemed "small", libcurl will not use

this header.

.SH "Customizing Operations"

.SH "Customizing Operations"

There is an ongoing development today where more and more protocols are built

There is an ongoing development today where more and more protocols are built

.IP "HTTP Version"

.IP "HTTP Version"

There's only one aspect left in the HTTP requests that we haven't yet

All HTTP requests includes the version number to tell the server which version

mentioned how to modify: the version field. All HTTP requests includes the

we support. libcurl speak HTTP 1.1 by default. Some very old servers don't

version number to tell the server which version we support. libcurl speak HTTP

like getting 1.1-requests and when dealing with stubborn old things like that,

1.1 by default. Some very old servers don't like getting 1.1-requests and when

you can tell libcurl to use 1.0 instead by doing something like this:

dealing with stubborn old things like that, you can tell libcurl to use 1.0

instead by doing something like this:

 curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);

 curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);

depend on that fact. It makes it easier for you to add custom header parsers

depend on that fact. It makes it easier for you to add custom header parsers

etc.

etc.

"Headers" for FTP transfers equal all the FTP server responses. They aren't

\&"Headers" for FTP transfers equal all the FTP server responses. They aren't

actually true headers, but in this case we pretend they are! ;-)

actually true headers, but in this case we pretend they are! ;-)

.SH "Post Transfer Information"

.SH "Post Transfer Information"