mirror of
https://github.com/moparisthebest/curl
synced 2024-08-13 17:03:50 -04:00
Somewhat updated, changes include: I tried to be more agnostic about the
specific SSL library that might be used, and I cut out the closepolicy stuff that we no longer support
This commit is contained in:
parent
acc4cf87cd
commit
fa31335926
@ -5,7 +5,7 @@
|
|||||||
.\" * | (__| |_| | _ <| |___
|
.\" * | (__| |_| | _ <| |___
|
||||||
.\" * \___|\___/|_| \_\_____|
|
.\" * \___|\___/|_| \_\_____|
|
||||||
.\" *
|
.\" *
|
||||||
.\" * 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
|
||||||
@ -21,7 +21,7 @@
|
|||||||
.\" * $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"
|
||||||
@ -64,10 +64,10 @@ $ curl-config --libs
|
|||||||
.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
|
||||||
|
|
||||||
@ -111,11 +111,10 @@ sockets properly. You should only do this once for each application, so if
|
|||||||
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
|
||||||
@ -256,9 +255,10 @@ handlers. Signals are used timeouting name resolves (during DNS lookup) - when
|
|||||||
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
|
||||||
|
|
||||||
@ -268,6 +268,14 @@ GnuTLS
|
|||||||
|
|
||||||
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
|
||||||
@ -614,22 +622,26 @@ What "proxy" means according to Merriam-Webster: "a person authorized to act
|
|||||||
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 has full support for HTTP proxies, so when a given URL is wanted,
|
libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl
|
||||||
libcurl will ask the proxy for it instead of trying to connect to the actual
|
will ask the proxy for it instead of trying to connect to the actual host
|
||||||
host identified in the URL.
|
identified in the URL.
|
||||||
|
|
||||||
The fact that the proxy is a HTTP proxy puts certain restrictions on what can
|
If you're using a SOCKS proxy, you may find that libcurl doesn't quite support
|
||||||
actually happen. A requested URL that might not be a HTTP URL will be still
|
all operations through it.
|
||||||
be passed to the HTTP proxy to deliver back to libcurl. This happens
|
|
||||||
transparently, and an application may not need to know. I say "may", because
|
For HTTP proxies: the fact that the proxy is a HTTP proxy puts certain
|
||||||
at times it is very important to understand that all operations over a HTTP
|
restrictions on what can actually happen. A requested URL that might not be a
|
||||||
proxy is using the HTTP protocol. For example, you can't invoke your own
|
HTTP URL will be still be passed to the HTTP proxy to deliver back to
|
||||||
custom FTP commands or even proper FTP directory listings.
|
libcurl. This happens transparently, and an application may not need to
|
||||||
|
know. I say "may", because at times it is very important to understand that
|
||||||
|
all operations over a HTTP proxy is using the HTTP protocol. For example, you
|
||||||
|
can't invoke your own custom FTP commands or even proper FTP directory
|
||||||
|
listings.
|
||||||
|
|
||||||
.IP "Proxy Options"
|
.IP "Proxy Options"
|
||||||
|
|
||||||
@ -645,6 +657,11 @@ pass that information similar to this:
|
|||||||
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
|
||||||
@ -669,6 +686,8 @@ for any URL in case the protocol specific variable wasn't set, and
|
|||||||
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
|
||||||
@ -768,26 +787,6 @@ with the CURLOPT_MAXCONNECTS option. Default is 5. It is very seldom any
|
|||||||
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
|
||||||
@ -797,7 +796,8 @@ CURLOPT_FORBID_REUSE to TRUE.
|
|||||||
|
|
||||||
.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
|
||||||
@ -811,10 +811,11 @@ fetch a fresh one.
|
|||||||
.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
|
||||||
@ -888,12 +889,10 @@ data size is unknown.
|
|||||||
|
|
||||||
.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);
|
||||||
|
|
||||||
@ -1051,7 +1050,7 @@ The headers are passed to the callback function one by one, and you can
|
|||||||
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"
|
||||||
|
Loading…
Reference in New Issue
Block a user