mirror of
https://github.com/moparisthebest/curl
synced 2024-12-22 08:08:50 -05:00
INTERNALS: better markdown (follow-up)
- Wrap more words with underscores in backticks.
Follow-up to 13f4913
.
This commit is contained in:
parent
13f4913303
commit
164ee10b0b
@ -174,7 +174,7 @@ Library
|
|||||||
rather small and easy-to-follow. All the ones prefixed with `curl_easy` are
|
rather small and easy-to-follow. All the ones prefixed with `curl_easy` are
|
||||||
put in the lib/easy.c file.
|
put in the lib/easy.c file.
|
||||||
|
|
||||||
`curl_global_init_()` and `curl_global_cleanup()` should be called by the
|
`curl_global_init()` and `curl_global_cleanup()` should be called by the
|
||||||
application to initialize and clean up global stuff in the library. As of
|
application to initialize and clean up global stuff in the library. As of
|
||||||
today, it can handle the global SSL initing if SSL is enabled and it can init
|
today, it can handle the global SSL initing if SSL is enabled and it can init
|
||||||
the socket layer on windows machines. libcurl itself has no "global" scope.
|
the socket layer on windows machines. libcurl itself has no "global" scope.
|
||||||
@ -184,14 +184,14 @@ Library
|
|||||||
|
|
||||||
[ `curl_easy_init()`][2] allocates an internal struct and makes some
|
[ `curl_easy_init()`][2] allocates an internal struct and makes some
|
||||||
initializations. The returned handle does not reveal internals. This is the
|
initializations. The returned handle does not reveal internals. This is the
|
||||||
'Curl_easy' struct which works as an "anchor" struct for all `curl_easy`
|
`Curl_easy` struct which works as an "anchor" struct for all `curl_easy`
|
||||||
functions. All connections performed will get connect-specific data allocated
|
functions. All connections performed will get connect-specific data allocated
|
||||||
that should be used for things related to particular connections/requests.
|
that should be used for things related to particular connections/requests.
|
||||||
|
|
||||||
[`curl_easy_setopt()`][1] takes three arguments, where the option stuff must
|
[`curl_easy_setopt()`][1] takes three arguments, where the option stuff must
|
||||||
be passed in pairs: the parameter-ID and the parameter-value. The list of
|
be passed in pairs: the parameter-ID and the parameter-value. The list of
|
||||||
options is documented in the man page. This function mainly sets things in
|
options is documented in the man page. This function mainly sets things in
|
||||||
the 'Curl_easy' struct.
|
the `Curl_easy` struct.
|
||||||
|
|
||||||
`curl_easy_perform()` is just a wrapper function that makes use of the multi
|
`curl_easy_perform()` is just a wrapper function that makes use of the multi
|
||||||
API. It basically calls `curl_multi_init()`, `curl_multi_add_handle()`,
|
API. It basically calls `curl_multi_init()`, `curl_multi_add_handle()`,
|
||||||
@ -218,7 +218,7 @@ Curl_connect()
|
|||||||
This function makes sure there's an allocated and initiated 'connectdata'
|
This function makes sure there's an allocated and initiated 'connectdata'
|
||||||
struct that is used for this particular connection only (although there may
|
struct that is used for this particular connection only (although there may
|
||||||
be several requests performed on the same connect). A bunch of things are
|
be several requests performed on the same connect). A bunch of things are
|
||||||
inited/inherited from the Curl_easy struct.
|
inited/inherited from the `Curl_easy` struct.
|
||||||
|
|
||||||
<a name="Curl_do"></a>
|
<a name="Curl_do"></a>
|
||||||
Curl_do()
|
Curl_do()
|
||||||
@ -385,11 +385,11 @@ Persistent Connections
|
|||||||
The persistent connection support in libcurl requires some considerations on
|
The persistent connection support in libcurl requires some considerations on
|
||||||
how to do things inside of the library.
|
how to do things inside of the library.
|
||||||
|
|
||||||
- The 'Curl_easy' struct returned in the [`curl_easy_init()`][2] call
|
- The `Curl_easy` struct returned in the [`curl_easy_init()`][2] call
|
||||||
must never hold connection-oriented data. It is meant to hold the root data
|
must never hold connection-oriented data. It is meant to hold the root data
|
||||||
as well as all the options etc that the library-user may choose.
|
as well as all the options etc that the library-user may choose.
|
||||||
|
|
||||||
- The 'Curl_easy' struct holds the "connection cache" (an array of
|
- The `Curl_easy` struct holds the "connection cache" (an array of
|
||||||
pointers to 'connectdata' structs).
|
pointers to 'connectdata' structs).
|
||||||
|
|
||||||
- This enables the 'curl handle' to be reused on subsequent transfers.
|
- This enables the 'curl handle' to be reused on subsequent transfers.
|
||||||
@ -485,7 +485,7 @@ Client
|
|||||||
main() resides in `src/tool_main.c`.
|
main() resides in `src/tool_main.c`.
|
||||||
|
|
||||||
`src/tool_hugehelp.c` is automatically generated by the mkhelp.pl perl script
|
`src/tool_hugehelp.c` is automatically generated by the mkhelp.pl perl script
|
||||||
to display the complete "manual" and the src/tool_urlglob.c file holds the
|
to display the complete "manual" and the `src/tool_urlglob.c` file holds the
|
||||||
functions used for the URL-"globbing" support. Globbing in the sense that the
|
functions used for the URL-"globbing" support. Globbing in the sense that the
|
||||||
{} and [] expansion stuff is there.
|
{} and [] expansion stuff is there.
|
||||||
|
|
||||||
@ -589,7 +589,7 @@ Asynchronous name resolves
|
|||||||
`curl_off_t`
|
`curl_off_t`
|
||||||
==========
|
==========
|
||||||
|
|
||||||
curl_off_t is a data type provided by the external libcurl include
|
`curl_off_t` is a data type provided by the external libcurl include
|
||||||
headers. It is the type meant to be used for the [`curl_easy_setopt()`][1]
|
headers. It is the type meant to be used for the [`curl_easy_setopt()`][1]
|
||||||
options that end with LARGE. The type is 64bit large on most modern
|
options that end with LARGE. The type is 64bit large on most modern
|
||||||
platforms.
|
platforms.
|
||||||
@ -607,10 +607,10 @@ curlx
|
|||||||
|
|
||||||
`curlx_strtoofft()`
|
`curlx_strtoofft()`
|
||||||
-------------------
|
-------------------
|
||||||
A macro that converts a string containing a number to a curl_off_t number.
|
A macro that converts a string containing a number to a `curl_off_t` number.
|
||||||
This might use the curlx_strtoll() function which is provided as source
|
This might use the `curlx_strtoll()` function which is provided as source
|
||||||
code in strtoofft.c. Note that the function is only provided if no
|
code in strtoofft.c. Note that the function is only provided if no
|
||||||
strtoll() (or equivalent) function exist on your platform. If curl_off_t
|
strtoll() (or equivalent) function exist on your platform. If `curl_off_t`
|
||||||
is only a 32 bit number on your platform, this macro uses strtol().
|
is only a 32 bit number on your platform, this macro uses strtol().
|
||||||
|
|
||||||
`curlx_tvnow()`
|
`curlx_tvnow()`
|
||||||
@ -624,17 +624,17 @@ curlx
|
|||||||
|
|
||||||
`curlx_tvdiff_secs()`
|
`curlx_tvdiff_secs()`
|
||||||
---------------------
|
---------------------
|
||||||
returns the same as curlx_tvdiff but with full usec resolution (as a
|
returns the same as `curlx_tvdiff` but with full usec resolution (as a
|
||||||
double)
|
double)
|
||||||
|
|
||||||
Future
|
Future
|
||||||
------
|
------
|
||||||
|
|
||||||
Several functions will be removed from the public curl_ name space in a
|
Several functions will be removed from the public `curl_` name space in a
|
||||||
future libcurl release. They will then only become available as curlx_
|
future libcurl release. They will then only become available as `curlx_`
|
||||||
functions instead. To make the transition easier, we already today provide
|
functions instead. To make the transition easier, we already today provide
|
||||||
these functions with the curlx_ prefix to allow sources to get built properly
|
these functions with the `curlx_` prefix to allow sources to get built
|
||||||
with the new function names. The functions this concerns are:
|
properly with the new function names. The functions this concerns are:
|
||||||
|
|
||||||
- `curlx_getenv`
|
- `curlx_getenv`
|
||||||
- `curlx_strequal`
|
- `curlx_strequal`
|
||||||
@ -719,7 +719,7 @@ hostip.c explained
|
|||||||
|
|
||||||
this host has getaddrinfo() and family, and thus we use that. The host may
|
this host has getaddrinfo() and family, and thus we use that. The host may
|
||||||
not be able to resolve IPv6, but we don't really have to take that into
|
not be able to resolve IPv6, but we don't really have to take that into
|
||||||
account. Hosts that aren't IPv6-enabled have CURLRES_IPV4 defined.
|
account. Hosts that aren't IPv6-enabled have `CURLRES_IPV4` defined.
|
||||||
|
|
||||||
## `CURLRES_ARES`
|
## `CURLRES_ARES`
|
||||||
|
|
||||||
@ -750,7 +750,7 @@ hostip.c explained
|
|||||||
- hostip6.c - IPv6 specific functions
|
- hostip6.c - IPv6 specific functions
|
||||||
|
|
||||||
The hostip.h is the single united header file for all this. It defines the
|
The hostip.h is the single united header file for all this. It defines the
|
||||||
`CURLRES_*` defines based on the config*.h and curl_setup.h defines.
|
`CURLRES_*` defines based on the config*.h and `curl_setup.h` defines.
|
||||||
|
|
||||||
<a name="memoryleak"></a>
|
<a name="memoryleak"></a>
|
||||||
Track Down Memory Leaks
|
Track Down Memory Leaks
|
||||||
@ -874,9 +874,9 @@ for older and later versions as things don't change drastically that often.
|
|||||||
When the `Curl_easy` struct is added to a multi handle, as it must be in
|
When the `Curl_easy` struct is added to a multi handle, as it must be in
|
||||||
order to do any transfer, the ->multi member will point to the `Curl_multi`
|
order to do any transfer, the ->multi member will point to the `Curl_multi`
|
||||||
struct it belongs to. The ->prev and ->next members will then be used by the
|
struct it belongs to. The ->prev and ->next members will then be used by the
|
||||||
multi code to keep a linked list of `Curl_easy` structs that are added to that
|
multi code to keep a linked list of `Curl_easy` structs that are added to
|
||||||
same multi handle. libcurl always uses multi so ->multi *will* point to a
|
that same multi handle. libcurl always uses multi so ->multi *will* point to
|
||||||
`Curl_multi` when a transfer is in progress.
|
a `Curl_multi` when a transfer is in progress.
|
||||||
|
|
||||||
->mstate is the multi state of this particular `Curl_easy`. When
|
->mstate is the multi state of this particular `Curl_easy`. When
|
||||||
`multi_runsingle()` is called, it will act on this handle according to which
|
`multi_runsingle()` is called, it will act on this handle according to which
|
||||||
@ -915,7 +915,7 @@ for older and later versions as things don't change drastically that often.
|
|||||||
doing so. Since connections are kept in the connection cache after use, the
|
doing so. Since connections are kept in the connection cache after use, the
|
||||||
original `Curl_easy` may no longer be around when the time comes to shut down
|
original `Curl_easy` may no longer be around when the time comes to shut down
|
||||||
a particular connection. For this purpose, libcurl holds a special dummy
|
a particular connection. For this purpose, libcurl holds a special dummy
|
||||||
`closure_handle` Curl_easy in the `Curl_multi` struct to use when needed.
|
`closure_handle` `Curl_easy` in the `Curl_multi` struct to use when needed.
|
||||||
|
|
||||||
FTP uses two TCP connections for a typical transfer but it keeps both in
|
FTP uses two TCP connections for a typical transfer but it keeps both in
|
||||||
this single struct and thus can be considered a single connection for most
|
this single struct and thus can be considered a single connection for most
|
||||||
@ -929,7 +929,8 @@ for older and later versions as things don't change drastically that often.
|
|||||||
Internally, the easy interface is implemented as a wrapper around multi
|
Internally, the easy interface is implemented as a wrapper around multi
|
||||||
interface functions. This makes everything multi interface.
|
interface functions. This makes everything multi interface.
|
||||||
|
|
||||||
`Curl_multi` is the multi handle struct exposed as "CURLM *" in external APIs.
|
`Curl_multi` is the multi handle struct exposed as "CURLM *" in external
|
||||||
|
APIs.
|
||||||
|
|
||||||
This struct holds a list of `Curl_easy` structs that have been added to this
|
This struct holds a list of `Curl_easy` structs that have been added to this
|
||||||
handle with [`curl_multi_add_handle()`][13]. The start of the list is
|
handle with [`curl_multi_add_handle()`][13]. The start of the list is
|
||||||
@ -939,10 +940,10 @@ for older and later versions as things don't change drastically that often.
|
|||||||
[`curl_multi_info_read()`][14] is called. Basically a node is added to that
|
[`curl_multi_info_read()`][14] is called. Basically a node is added to that
|
||||||
list when an individual `Curl_easy`'s transfer has completed.
|
list when an individual `Curl_easy`'s transfer has completed.
|
||||||
|
|
||||||
`->hostcache` points to the name cache. It is a hash table for looking up name
|
`->hostcache` points to the name cache. It is a hash table for looking up
|
||||||
to IP. The nodes have a limited life time in there and this cache is meant
|
name to IP. The nodes have a limited life time in there and this cache is
|
||||||
to reduce the time for when the same name is wanted within a short period of
|
meant to reduce the time for when the same name is wanted within a short
|
||||||
time.
|
period of time.
|
||||||
|
|
||||||
`->timetree` points to a tree of `Curl_easy`s, sorted by the remaining time
|
`->timetree` points to a tree of `Curl_easy`s, sorted by the remaining time
|
||||||
until it should be checked - normally some sort of timeout. Each `Curl_easy`
|
until it should be checked - normally some sort of timeout. Each `Curl_easy`
|
||||||
@ -975,12 +976,12 @@ for older and later versions as things don't change drastically that often.
|
|||||||
"HTTP" or "FTP" etc. SSL versions of the protcol need its own `Curl_handler`
|
"HTTP" or "FTP" etc. SSL versions of the protcol need its own `Curl_handler`
|
||||||
setup so HTTPS separate from HTTP.
|
setup so HTTPS separate from HTTP.
|
||||||
|
|
||||||
`->setup_connection` is called to allow the protocol code to allocate protocol
|
`->setup_connection` is called to allow the protocol code to allocate
|
||||||
specific data that then gets associated with that Curl_easy for the rest of
|
protocol specific data that then gets associated with that `Curl_easy` for
|
||||||
this transfer. It gets freed again at the end of the transfer. It will be
|
the rest of this transfer. It gets freed again at the end of the transfer.
|
||||||
called before the 'connectdata' for the transfer has been selected/created.
|
It will be called before the 'connectdata' for the transfer has been
|
||||||
Most protocols will allocate its private 'struct [PROTOCOL]' here and assign
|
selected/created. Most protocols will allocate its private
|
||||||
Curl_easy->req.protop to point to it.
|
'struct [PROTOCOL]' here and assign `Curl_easy->req.protop` to point to it.
|
||||||
|
|
||||||
`->connect_it` allows a protocol to do some specific actions after the TCP
|
`->connect_it` allows a protocol to do some specific actions after the TCP
|
||||||
connect is done, that can still be considered part of the connection phase.
|
connect is done, that can still be considered part of the connection phase.
|
||||||
@ -1004,8 +1005,8 @@ for older and later versions as things don't change drastically that often.
|
|||||||
`->done` gets called when the transfer is complete and DONE. That's after the
|
`->done` gets called when the transfer is complete and DONE. That's after the
|
||||||
main data has been transferred.
|
main data has been transferred.
|
||||||
|
|
||||||
`->do_more` gets called during the `DO_MORE` state. The FTP protocol uses this
|
`->do_more` gets called during the `DO_MORE` state. The FTP protocol uses
|
||||||
state when setting up the second connection.
|
this state when setting up the second connection.
|
||||||
|
|
||||||
->`proto_getsock`
|
->`proto_getsock`
|
||||||
->`doing_getsock`
|
->`doing_getsock`
|
||||||
|
Loading…
Reference in New Issue
Block a user