docs: remove spurious ampersands from markdown
They were leftovers from the nroff conversion.
Follow-up to eefcc1bda4
Closes #12800
This commit is contained in:
Родитель
7b2d98dfad
Коммит
92f8a1686d
|
@ -129,9 +129,9 @@ associated bits.
|
|||
names of the features that libcurl supports. The array is terminated by a NULL
|
||||
entry. See the list of features names below.
|
||||
|
||||
*ssl_version* is an ASCII string for the TLS library name + version
|
||||
used. If libcurl has no SSL support, this is NULL. For example "Schannel",
|
||||
&"Secure Transport" or "OpenSSL/1.1.0g".
|
||||
*ssl_version* is an ASCII string for the TLS library name + version used. If
|
||||
libcurl has no SSL support, this is NULL. For example "Schannel", "Secure
|
||||
Transport" or "OpenSSL/1.1.0g".
|
||||
|
||||
*ssl_version_num* is always 0.
|
||||
|
||||
|
|
|
@ -44,7 +44,7 @@ this.
|
|||
|
||||
# .netrc
|
||||
|
||||
&.netrc is a pretty handy file/feature that allows you to login quickly and
|
||||
.netrc is a pretty handy file/feature that allows you to login quickly and
|
||||
automatically to frequently visited sites. The file contains passwords in
|
||||
clear text and is a real security risk. In some cases, your .netrc is also
|
||||
stored in a home directory that is NFS mounted or used on another network
|
||||
|
|
|
@ -27,8 +27,7 @@ All functions in the share interface are prefixed with curl_share.
|
|||
|
||||
# OBJECTIVES
|
||||
|
||||
The share interface was added to enable sharing of data between curl
|
||||
&"handles".
|
||||
The share interface was added to enable sharing of data between curl handles.
|
||||
|
||||
# ONE SET OF DATA - MANY TRANSFERS
|
||||
|
||||
|
|
|
@ -64,13 +64,15 @@ 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
|
||||
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.
|
||||
|
@ -227,30 +229,32 @@ program. Therefore, if you use the default callback and pass in an open file
|
|||
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
|
||||
|
@ -363,30 +367,36 @@ libcurl also provides options to set various passwords. The user name and
|
|||
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
|
||||
|
@ -414,25 +424,32 @@ method is called 'Basic', which is sending the name and password in clear-text
|
|||
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.
|
||||
|
@ -842,7 +859,7 @@ it defaults to assuming an HTTP proxy):
|
|||
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
|
||||
|
@ -855,10 +872,9 @@ which port the proxy operates. If not specified, the internal default port
|
|||
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
|
||||
|
@ -984,11 +1000,11 @@ anything but default.
|
|||
|
||||
## 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.
|
||||
|
@ -1038,9 +1054,9 @@ curl_easy_perform(handle); /* transfer http */
|
|||
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");
|
||||
|
@ -1051,7 +1067,7 @@ headers = curl_slist_append(headers, "Host: munged.host.line");
|
|||
|
||||
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:");
|
||||
|
@ -1310,7 +1326,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
|
||||
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
|
||||
|
|
|
@ -142,12 +142,14 @@ The appended string can of course also get URL encoded on add, and if asked to
|
|||
URL encode, the encoding process skips the '=' character. For example, append
|
||||
"candy=N&N" to what we already have, and URL encode it to deal with the
|
||||
ampersand in the data:
|
||||
|
||||
~~~c
|
||||
rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
|
||||
CURLU_APPENDQUERY | CURLU_URLENCODE);
|
||||
~~~
|
||||
|
||||
Now the URL looks like
|
||||
|
||||
~~~c
|
||||
https://example.com/?shoes=2&hat=1&candy=N%26N
|
||||
~~~
|
||||
|
|
|
@ -37,10 +37,10 @@ struct curl_certinfo {
|
|||
~~~
|
||||
|
||||
The *certinfo* struct member is an array of linked lists of certificate
|
||||
information. The *num_of_certs* struct member is the number of
|
||||
certificates which is the number of elements in the array. Each certificate's
|
||||
list has items with textual information in the format "name:content" such as
|
||||
&"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on
|
||||
information. The *num_of_certs* struct member is the number of certificates
|
||||
which is the number of elements in the array. Each certificate's list has
|
||||
items with textual information in the format "name:content" such as
|
||||
"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on
|
||||
the SSL backend and the certificate.
|
||||
|
||||
# PROTOCOLS
|
||||
|
|
|
@ -24,7 +24,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPSSLAUTH, long order);
|
|||
# DESCRIPTION
|
||||
|
||||
Pass a long using one of the values from below, to alter how libcurl issues
|
||||
&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only
|
||||
"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only
|
||||
interesting if CURLOPT_USE_SSL(3) is also set.
|
||||
|
||||
Possible *order* values:
|
||||
|
|
|
@ -48,7 +48,7 @@ an entry valid for all subdomains to the name as well or only for the exact
|
|||
name.
|
||||
|
||||
[stamp] is the time (in UTC) when the entry expires and it uses the format
|
||||
&"YYYYMMDD HH:MM:SS".
|
||||
"YYYYMMDD HH:MM:SS".
|
||||
|
||||
Lines starting with "#" are treated as comments and are ignored. There is
|
||||
currently no length or size limit.
|
||||
|
|
|
@ -30,16 +30,16 @@ stream using this option. If unset, libcurl defaults to operating on generic
|
|||
server options by passing '*' in the place of the RTSP Stream URI. This option
|
||||
is distinct from CURLOPT_URL(3). When working with RTSP, the
|
||||
CURLOPT_RTSP_STREAM_URI(3) indicates what URL to send to the server in the
|
||||
request header while the CURLOPT_URL(3) indicates where to make the
|
||||
connection to. (e.g. the CURLOPT_URL(3) for the above examples might be set
|
||||
to *rtsp://foo/twister*
|
||||
request header while the CURLOPT_URL(3) indicates where to make the connection
|
||||
to. (e.g. the CURLOPT_URL(3) for the above examples might be set to
|
||||
*rtsp://foo/twister*
|
||||
|
||||
The application does not have to keep the string around after setting this
|
||||
option.
|
||||
|
||||
# DEFAULT
|
||||
|
||||
&'*'
|
||||
"*"
|
||||
|
||||
# PROTOCOLS
|
||||
|
||||
|
|
|
@ -28,9 +28,9 @@ Pass a pointer to a null-terminated string as parameter. The string should be
|
|||
the format of your private key. Supported formats are "PEM", "DER" and "ENG".
|
||||
|
||||
The format "ENG" enables you to load the private key from a crypto engine. In
|
||||
this case CURLOPT_SSLKEY(3) is used as an identifier passed to the
|
||||
engine. You have to set the crypto engine with CURLOPT_SSLENGINE(3).
|
||||
&"DER" format key file currently does not work because of a bug in OpenSSL.
|
||||
this case CURLOPT_SSLKEY(3) is used as an identifier passed to the engine. You
|
||||
have to set the crypto engine with CURLOPT_SSLENGINE(3). "DER" format key file
|
||||
currently does not work because of a bug in OpenSSL.
|
||||
|
||||
The application does not have to keep the string around after setting this
|
||||
option.
|
||||
|
|
|
@ -29,25 +29,25 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list);
|
|||
Pass a char pointer, pointing to a null-terminated string holding the list of
|
||||
ciphers to use for the SSL connection. The list must be syntactically correct,
|
||||
it consists of one or more cipher strings separated by colons. Commas or
|
||||
spaces are also acceptable separators but colons are normally used, &!, &- and
|
||||
&+ can be used as operators.
|
||||
spaces are also acceptable separators but colons are normally used, !, - and
|
||||
+ can be used as operators.
|
||||
|
||||
For OpenSSL and GnuTLS valid examples of cipher lists include **RC4-SHA**,
|
||||
**SHA1+DES**, **TLSv1** and **DEFAULT**. The default list is normally
|
||||
set when you compile OpenSSL.
|
||||
**SHA1+DES**, **TLSv1** and **DEFAULT**. The default list is normally set when
|
||||
you compile OpenSSL.
|
||||
|
||||
For WolfSSL, valid examples of cipher lists include **ECDHE-RSA-RC4-SHA**,
|
||||
**AES256-SHA:AES256-SHA256**, etc.
|
||||
|
||||
For BearSSL, valid examples of cipher lists include
|
||||
**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using IANA names
|
||||
**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using
|
||||
IANA names
|
||||
**TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256**,
|
||||
etc.
|
||||
With BearSSL you do not add/remove ciphers. If one uses this option then all
|
||||
known ciphers are disabled and only those passed in are enabled.
|
||||
etc. With BearSSL you do not add/remove ciphers. If one uses this option then
|
||||
all known ciphers are disabled and only those passed in are enabled.
|
||||
|
||||
For Schannel, you can use this option to set algorithms but not specific cipher
|
||||
suites. Refer to the ciphers lists document for algorithms.
|
||||
For Schannel, you can use this option to set algorithms but not specific
|
||||
cipher suites. Refer to the ciphers lists document for algorithms.
|
||||
|
||||
Find more details about cipher lists on this URL:
|
||||
|
||||
|
|
Загрузка…
Ссылка в новой задаче