varies from different libraries and builds is the support for SSL-based
transfers, like HTTPS and FTPS. If a supported SSL library was detected
properly at build-time, libcurl is built with SSL support. To figure out if an
-installed libcurl has been built with SSL support enabled, use &'curl-config'
+installed libcurl has been built with SSL support enabled, use *curl-config*
like this:
+
~~~c
$ curl-config --feature
~~~
-And if SSL is supported, the keyword *SSL* is written to stdout, possibly
-together with a other features that could be either on or off on for different
+
+If SSL is supported, the keyword *SSL* is written to stdout, possibly together
+with a other features that could be either on or off on for different
libcurls.
See also the "Features libcurl Provides" further down.
handle with CURLOPT_WRITEDATA(3), libcurl crashes. You should avoid this
to make your program run fine virtually everywhere.
-(CURLOPT_WRITEDATA(3) was formerly known as *CURLOPT_FILE*. Both
-names still work and do the same thing).
+(CURLOPT_WRITEDATA(3) was formerly known as *CURLOPT_FILE*. Both names still
+work and do the same thing).
If you are using libcurl as a win32 DLL, you MUST use the
-CURLOPT_WRITEFUNCTION(3) if you set CURLOPT_WRITEDATA(3) - or
-experience crashes.
+CURLOPT_WRITEFUNCTION(3) if you set CURLOPT_WRITEDATA(3) - or experience
+crashes.
There are of course many more options you can set, and we get back to a few of
them later. Let's instead continue to the actual transfer:
+
~~~c
success = curl_easy_perform(handle);
~~~
-curl_easy_perform(3) connects to the remote site, does the necessary
-commands and performs the transfer. Whenever it receives data, it calls the
-callback function we previously set. The function may get one byte at a time,
-or it may get many kilobytes at once. libcurl delivers as much as possible as
-often as possible. Your callback function should return the number of bytes it
-&"took care of". If that is not the same amount of bytes that was passed to
-it, libcurl aborts the operation and returns with an error code.
+
+curl_easy_perform(3) connects to the remote site, does the necessary commands
+and performs the transfer. Whenever it receives data, it calls the callback
+function we previously set. The function may get one byte at a time, or it may
+get many kilobytes at once. libcurl delivers as much as possible as often as
+possible. Your callback function should return the number of bytes it "took
+care of". If that is not the same amount of bytes that was passed to it,
+libcurl aborts the operation and returns with an error code.
When the transfer is complete, the function returns a return code that informs
you if it succeeded in its mission or not. If a return code is not enough for
-you, you can use the CURLOPT_ERRORBUFFER(3) to point libcurl to a buffer
-of yours where it stores a human readable error message as well.
+you, you can use the CURLOPT_ERRORBUFFER(3) to point libcurl to a buffer of
+yours where it stores a human readable error message as well.
If you then want to transfer another file, the handle is ready to be used
again. It is even preferred and encouraged that you reuse an existing handle
password as shown embedded in the URL can instead get set with the
CURLOPT_USERPWD(3) option. The argument passed to libcurl should be a
char * to a string in the format "user:password". In a manner like this:
+
~~~c
curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret");
~~~
+
Another case where name and password might be needed at times, is for those
users who need to authenticate themselves to a proxy they use. libcurl offers
-another option for this, the CURLOPT_PROXYUSERPWD(3). It is used quite
-similar to the CURLOPT_USERPWD(3) option like this:
+another option for this, the CURLOPT_PROXYUSERPWD(3). It is used quite similar
+to the CURLOPT_USERPWD(3) option like this:
+
~~~c
curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
~~~
+
There is a long time Unix "standard" way of storing FTP user names and
passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks
-the *%USERPROFILE% environment* variable if *%HOME%* is unset, and
-tries "_netrc" as name). The file should be made private so that only the user
-may read it (see also the "Security Considerations" chapter), as it might
-contain the password in plain text. libcurl has the ability to use this file
-to figure out what set of user name and password to use for a particular
-host. As an extension to the normal functionality, libcurl also supports this
-file for non-FTP protocols such as HTTP. To make curl use this file, use the
+the *%USERPROFILE% environment* variable if *%HOME%* is unset, and tries
+"_netrc" as name). The file should be made private so that only the user may
+read it (see also the "Security Considerations" chapter), as it might contain
+the password in plain text. libcurl has the ability to use this file to figure
+out what set of user name and password to use for a particular host. As an
+extension to the normal functionality, libcurl also supports this file for
+non-FTP protocols such as HTTP. To make curl use this file, use the
CURLOPT_NETRC(3) option:
+
~~~c
curl_easy_setopt(handle, CURLOPT_NETRC, 1L);
~~~
-And a basic example of how such a .netrc file may look like:
+
+A basic example of how such a .netrc file may look like:
~~~c
machine myhost.mydomain.com
in the HTTP request, base64-encoded. This is insecure.
At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM,
-Negotiate (SPNEGO). You can tell libcurl which one to use
-with CURLOPT_HTTPAUTH(3) as in:
+Negotiate (SPNEGO). You can tell libcurl which one to use with
+CURLOPT_HTTPAUTH(3) as in:
+
~~~c
curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
+
~~~
-And when you send authentication to a proxy, you can also set authentication
-type the same way but instead with CURLOPT_PROXYAUTH(3):
+
+When you send authentication to a proxy, you can also set authentication type
+the same way but instead with CURLOPT_PROXYAUTH(3):
+
~~~c
curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
~~~
+
Both these options allow you to set multiple types (by ORing them together),
to make libcurl pick the most secure one out of the types the server/proxy
claims to support. This method does however add a round-trip since libcurl
must first ask the server what it supports:
+
~~~c
curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC);
~~~
-For convenience, you can use the *CURLAUTH_ANY* define (instead of a list
-with specific types) which allows libcurl to use whatever method it wants.
+
+For convenience, you can use the *CURLAUTH_ANY* define (instead of a list with
+specific types) which allows libcurl to use whatever method it wants.
When asking for multiple types, libcurl picks the available one it considers
"best" in its own internal order of preference.
libcurl automatically checks and uses a set of environment variables to know
what proxies to use for certain protocols. The names of the variables are
following an old tradition and are built up as "[protocol]_proxy" (note the
-lower casing). Which makes the variable &'http_proxy' checked for a name of a
+lower casing). Which makes the variable 'http_proxy' checked for a name of a
proxy to use when the input URL is HTTP. Following the same rule, the variable
named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are always HTTP
proxies, the different names of the variables simply allows different HTTP
number is used and that is most likely not the one you would like it to be.
There are two special environment variables. 'all_proxy' is what sets proxy
-for any URL in case the protocol specific variable was not set, and
-&'no_proxy' defines a list of hosts that should not use a proxy even though a
-variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all
-hosts.
+for any URL in case the protocol specific variable was not set, and 'no_proxy'
+defines a list of hosts that should not use a proxy even though a variable may
+say so. If 'no_proxy' is a plain asterisk ("*") it matches all hosts.
To explicitly disable libcurl's checking for and using the proxy environment
variables, set the proxy name to "" - an empty string - with
## Accept
-&"*/*".
+"*/*"
## Expect
-When doing POST requests, libcurl sets this header to &"100-continue" to ask
+When doing POST requests, libcurl sets this header to "100-continue" to ask
the server for an "OK" message before it proceeds with sending the data part
of the post. If the posted data amount is deemed "small", libcurl does not use
this header.
curl_slist_free_all(headers); /* free the header list */
~~~
-&... and if you think some of the internally generated headers, such as
-Accept: or Host: do not contain the data you want them to contain, you can
-replace them by simply setting them too:
+... and if you think some of the internally generated headers, such as Accept:
+or Host: do not contain the data you want them to contain, you can replace
+them by simply setting them too:
~~~c
headers = curl_slist_append(headers, "Accept: Agent-007");
If you replace an existing header with one with no contents, you prevent the
header from being sent. For instance, if you want to completely prevent the
-&"Accept:" header from being sent, you can disable it with code similar to
+"Accept:" header from being sent, you can disable it with code similar to
this:
headers = curl_slist_append(headers, "Accept:");
depend on that fact. It makes it easier for you to add custom header parsers
etc.
-&"Headers" for FTP transfers equal all the FTP server responses. They are not
+"Headers" for FTP transfers equal all the FTP server responses. They are not
actually true headers, but in this case we pretend they are! ;-)
# Post Transfer Information
projects / thirdparty / curl.git / commitdiff
