docs: remove spurious ampersands from markdown

They were leftovers from the nroff conversion.

Follow-up to eefcc1bda4

Closes #12800
This commit is contained in:
Daniel Stenberg 2024-01-26 09:54:48 +01:00
Родитель 7b2d98dfad
Коммит 92f8a1686d
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 5CC908FDB71E12C2
11 изменённых файлов: 90 добавлений и 73 удалений

Просмотреть файл

@ -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: