1
0
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:
Jay Satiro 2016-10-31 00:38:27 -04:00
parent 13f4913303
commit 164ee10b0b

View File

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