mirror of
https://github.com/moparisthebest/curl
synced 2024-12-21 23:58:49 -05:00
INTERNALS: better markdown (follow-up)
- Wrap more words with underscores in backticks.
Follow-up to 13f4913.
This commit is contained in:
Jay Satiro
parent
13f4913303
commit
164ee10b0b
@ -174,7 +174,7 @@ Library
|
||||
rather small and easy-to-follow. All the ones prefixed with `curl_easy` are
|
||||
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
|
||||
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.
|
||||
@ -184,14 +184,14 @@ Library
|
||||
|
||||
[ `curl_easy_init()`][2] allocates an internal struct and makes some
|
||||
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
|
||||
that should be used for things related to particular connections/requests.
|
||||
|
||||
[`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
|
||||
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
|
||||
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'
|
||||
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
|
||||
inited/inherited from the Curl_easy struct.
|
||||
inited/inherited from the `Curl_easy` struct.
|
||||
|
||||
<a name="Curl_do"></a>
|
||||
Curl_do()
|
||||
@ -385,11 +385,11 @@ Persistent Connections
|
||||
The persistent connection support in libcurl requires some considerations on
|
||||
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
|
||||
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).
|
||||
|
||||
- This enables the 'curl handle' to be reused on subsequent transfers.
|
||||
@ -485,7 +485,7 @@ Client
|
||||
main() resides in `src/tool_main.c`.
|
||||
|
||||
`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
|
||||
{} and [] expansion stuff is there.
|
||||
|
||||
@ -589,7 +589,7 @@ Asynchronous name resolves
|
||||
`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]
|
||||
options that end with LARGE. The type is 64bit large on most modern
|
||||
platforms.
|
||||
@ -607,10 +607,10 @@ curlx
|
||||
|
||||
`curlx_strtoofft()`
|
||||
-------------------
|
||||
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
|
||||
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
|
||||
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().
|
||||
|
||||
`curlx_tvnow()`
|
||||
@ -624,17 +624,17 @@ curlx
|
||||
|
||||
`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)
|
||||
|
||||
Future
|
||||
------
|
||||
|
||||
Several functions will be removed from the public curl_ name space in a
|
||||
future libcurl release. They will then only become available as curlx_
|
||||
Several functions will be removed from the public `curl_` name space in a
|
||||
future libcurl release. They will then only become available as `curlx_`
|
||||
functions instead. To make the transition easier, we already today provide
|
||||
these functions with the curlx_ prefix to allow sources to get built properly
|
||||
with the new function names. The functions this concerns are:
|
||||
these functions with the `curlx_` prefix to allow sources to get built
|
||||
properly with the new function names. The functions this concerns are:
|
||||
|
||||
- `curlx_getenv`
|
||||
- `curlx_strequal`
|
||||
@ -719,7 +719,7 @@ hostip.c explained
|
||||
|
||||
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
|
||||
account. Hosts that aren't IPv6-enabled have CURLRES_IPV4 defined.
|
||||
account. Hosts that aren't IPv6-enabled have `CURLRES_IPV4` defined.
|
||||
|
||||
## `CURLRES_ARES`
|
||||
|
||||
@ -750,7 +750,7 @@ hostip.c explained
|
||||
- hostip6.c - IPv6 specific functions
|
||||
|
||||
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>
|
||||
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
|
||||
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
|
||||
multi code to keep a linked list of `Curl_easy` structs that are added to that
|
||||
same multi handle. libcurl always uses multi so ->multi *will* point to a
|
||||
`Curl_multi` when a transfer is in progress.
|
||||
multi code to keep a linked list of `Curl_easy` structs that are added to
|
||||
that same multi handle. libcurl always uses multi so ->multi *will* point to
|
||||
a `Curl_multi` when a transfer is in progress.
|
||||
|
||||
->mstate is the multi state of this particular `Curl_easy`. When
|
||||
`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
|
||||
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
|
||||
`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
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
to IP. The nodes have a limited life time in there and this cache is meant
|
||||
to reduce the time for when the same name is wanted within a short period of
|
||||
time.
|
||||
`->hostcache` points to the name cache. It is a hash table for looking up
|
||||
name to IP. The nodes have a limited life time in there and this cache is
|
||||
meant to reduce the time for when the same name is wanted within a short
|
||||
period of 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`
|
||||
@ -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`
|
||||
setup so HTTPS separate from HTTP.
|
||||
|
||||
`->setup_connection` is called to allow the protocol code to allocate protocol
|
||||
specific data that then gets associated with that Curl_easy for the rest of
|
||||
this transfer. It gets freed again at the end of the transfer. It will be
|
||||
called before the 'connectdata' for the transfer has been selected/created.
|
||||
Most protocols will allocate its private 'struct [PROTOCOL]' here and assign
|
||||
Curl_easy->req.protop to point to it.
|
||||
`->setup_connection` is called to allow the protocol code to allocate
|
||||
protocol specific data that then gets associated with that `Curl_easy` for
|
||||
the rest of this transfer. It gets freed again at the end of the transfer.
|
||||
It will be called before the 'connectdata' for the transfer has been
|
||||
selected/created. Most protocols will allocate its private
|
||||
'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 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
|
||||
main data has been transferred.
|
||||
|
||||
`->do_more` gets called during the `DO_MORE` state. The FTP protocol uses this
|
||||
state when setting up the second connection.
|
||||
`->do_more` gets called during the `DO_MORE` state. The FTP protocol uses
|
||||
this state when setting up the second connection.
|
||||
|
||||
->`proto_getsock`
|
||||
->`doing_getsock`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user