5
5
.\" * | (__| |_| | _ <| |___
6
6
.\" * \___|\___/|_| \_\_____|
8
.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, <daniel@haxx.se>, et al.
8
.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, <daniel@haxx.se>, et al.
10
10
.\" * This software is licensed as described in the file COPYING, which
11
11
.\" * you should have received as part of this distribution. The terms
18
18
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19
19
.\" * KIND, either express or implied.
21
.\" * $Id: libcurl-tutorial.3,v 1.12 2006-06-21 17:34:29 bagder Exp $
21
.\" * $Id: libcurl-tutorial.3,v 1.13 2007-02-27 12:44:14 bagder Exp $
22
22
.\" **************************************************************************
24
.TH libcurl-tutorial 3 "9 May 2005" "libcurl" "libcurl programming"
24
.TH libcurl-tutorial 3 "27 Feb 2007" "libcurl" "libcurl programming"
26
26
libcurl-tutorial \- libcurl programming tutorial
65
65
libcurl can be built and customized in many ways. One of the things that
66
66
varies from different libraries and builds is the support for SSL-based
67
transfers, like HTTPS and FTPS. If OpenSSL was detected properly at
68
build-time, libcurl will be built with SSL support. To figure out if an
69
installed libcurl has been built with SSL support enabled, use 'curl-config'
67
transfers, like HTTPS and FTPS. If a supported SSL library was detected
68
properly at build-time, libcurl will be built with SSL support. To figure out
69
if an installed libcurl has been built with SSL support enabled, use
70
\&'curl-config' like this:
72
72
$ curl-config --feature
111
111
your program already does this or of another library in use does it, you
112
112
should not tell libcurl to do this as well.
113
113
.IP CURL_GLOBAL_SSL
114
which only does anything on libcurls compiled and built
115
SSL-enabled. On these systems, this will make libcurl initialize OpenSSL
116
properly for this application. This is only needed to do once for each
117
application so if your program or another library already does this, this
118
bit should not be needed.
114
which only does anything on libcurls compiled and built SSL-enabled. On these
115
systems, this will make libcurl initialize the SSL library properly for this
116
application. This is only needed to do once for each application so if your
117
program or another library already does this, this bit should not be needed.
121
120
libcurl has a default protection mechanism that detects if
256
255
built without c-ares support and not on Windows..
258
257
If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
259
then of course using OpenSSL/GnuTLS multi-threaded and those libs have their
260
own requirements on this issue. Basically, you need to provide one or two
261
functions to allow it to function properly. For all details, see this:
258
then of course using the underlying SSL library multi-threaded and those libs
259
might have their own requirements on this issue. Basically, you need to
260
provide one or two functions to allow it to function properly. For all
265
http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION
265
http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION
269
269
http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html
273
is claimed to be thread-safe already without anything required
277
Required actions unknown
271
279
When using multiple threads you should set the CURLOPT_NOSIGNAL option to TRUE
272
280
for all handles. Everything will or might work fine except that timeouts are
273
281
not honored during the DNS lookup - which you can work around by building
614
622
for another" but also "the agency, function, or office of a deputy who acts as
615
623
a substitute for another".
617
Proxies are exceedingly common these days. Companies often only offer
618
Internet access to employees through their HTTP proxies. Network clients or
619
user-agents ask the proxy for documents, the proxy does the actual request
620
and then it returns them.
622
libcurl has full support for HTTP proxies, so when a given URL is wanted,
623
libcurl will ask the proxy for it instead of trying to connect to the actual
624
host identified in the URL.
626
The fact that the proxy is a HTTP proxy puts certain restrictions on what can
627
actually happen. A requested URL that might not be a HTTP URL will be still
628
be passed to the HTTP proxy to deliver back to libcurl. This happens
629
transparently, and an application may not need to know. I say "may", because
630
at times it is very important to understand that all operations over a HTTP
631
proxy is using the HTTP protocol. For example, you can't invoke your own
632
custom FTP commands or even proper FTP directory listings.
625
Proxies are exceedingly common these days. Companies often only offer Internet
626
access to employees through their proxies. Network clients or user-agents ask
627
the proxy for documents, the proxy does the actual request and then it returns
630
libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl
631
will ask the proxy for it instead of trying to connect to the actual host
632
identified in the URL.
634
If you're using a SOCKS proxy, you may find that libcurl doesn't quite support
635
all operations through it.
637
For HTTP proxies: the fact that the proxy is a HTTP proxy puts certain
638
restrictions on what can actually happen. A requested URL that might not be a
639
HTTP URL will be still be passed to the HTTP proxy to deliver back to
640
libcurl. This happens transparently, and an application may not need to
641
know. I say "may", because at times it is very important to understand that
642
all operations over a HTTP proxy is using the HTTP protocol. For example, you
643
can't invoke your own custom FTP commands or even proper FTP directory
634
646
.IP "Proxy Options"
645
657
If you want to, you can specify the host name only in the CURLOPT_PROXY
646
658
option, and set the port number separately with CURLOPT_PROXYPORT.
660
Tell libcurl what kind of proxy it is with CURLOPT_PROXYTYPE (if not, it will
661
default to assume a HTTP proxy):
663
curl_easy_setopt(easyhandle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4);
648
665
.IP "Environment Variables"
650
667
libcurl automatically checks and uses a set of environment variables to
669
686
variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all
689
To explicitly disable libcurl's checking for and using the proxy environment
690
variables, set the proxy name to "" - an empty string - with CURLOPT_PROXY.
672
691
.IP "SSL and Proxies"
674
693
SSL is for secure point-to-point connections. This involves strong encryption
768
787
point in changing this value, and if you think of changing this it is often
769
788
just a matter of thinking again.
771
When the connection cache gets filled, libcurl must close an existing
772
connection in order to get room for the new one. To know which connection to
773
close, libcurl uses a "close policy" that you can affect with the
774
CURLOPT_CLOSEPOLICY option. There's only two polices implemented as of this
775
writing (libcurl 7.9.4) and they are:
778
.IP CURLCLOSEPOLICY_LEAST_RECENTLY_USED
779
simply close the one that hasn't been used for the longest time. This is the
781
.IP CURLCLOSEPOLICY_OLDEST
782
closes the oldest connection, the one that was created the longest time ago.
785
There are, or at least were, plans to support a close policy that would call
786
a user-specified callback to let the user be able to decide which connection
787
to dump when this is necessary and therefor is the CURLOPT_CLOSEFUNCTION an
788
existing option still today. Nothing ever uses this though and this will not
789
be used within the foreseeable future either.
791
790
To force your upcoming request to not use an already existing connection (it
792
791
will even close one first if there happens to be one alive to the same host
793
792
you're about to operate on), you can do that by setting CURLOPT_FRESH_CONNECT
798
797
.SH "HTTP Headers Used by libcurl"
799
798
When you use libcurl to do HTTP requests, it'll pass along a series of headers
800
automatically. It might be good for you to know and understand these ones.
799
automatically. It might be good for you to know and understand these ones. You
800
can replace or remove them by using the CURLOPT_HTTPHEADER option.
803
803
This header is required by HTTP 1.1 and even many 1.0 servers and should be
815
When doing multi-part formposts, libcurl will set this header to
816
\&"100-continue" to ask the server for an "OK" message before it proceeds with
817
sending the data part of the post.
815
When doing POST requests, libcurl sets this header to \&"100-continue" to ask
816
the server for an "OK" message before it proceeds with sending the data part
817
of the post. If the POSTed data amount is deemed "small", libcurl will not use
819
820
.SH "Customizing Operations"
820
821
There is an ongoing development today where more and more protocols are built
889
890
.IP "HTTP Version"
891
There's only one aspect left in the HTTP requests that we haven't yet
892
mentioned how to modify: the version field. All HTTP requests includes the
893
version number to tell the server which version we support. libcurl speak HTTP
894
1.1 by default. Some very old servers don't like getting 1.1-requests and when
895
dealing with stubborn old things like that, you can tell libcurl to use 1.0
896
instead by doing something like this:
892
All HTTP requests includes the version number to tell the server which version
893
we support. libcurl speak HTTP 1.1 by default. Some very old servers don't
894
like getting 1.1-requests and when dealing with stubborn old things like that,
895
you can tell libcurl to use 1.0 instead by doing something like this:
898
897
curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
1051
1050
depend on that fact. It makes it easier for you to add custom header parsers
1054
"Headers" for FTP transfers equal all the FTP server responses. They aren't
1053
\&"Headers" for FTP transfers equal all the FTP server responses. They aren't
1055
1054
actually true headers, but in this case we pretend they are! ;-)
1057
1056
.SH "Post Transfer Information"
added
removed
docs/libcurl/libcurl-tutorial.3
