diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/INTERNALS.md | 71 |
1 files changed, 36 insertions, 35 deletions
diff --git a/docs/INTERNALS.md b/docs/INTERNALS.md index 2f53ed2b9..9da5ef637 100644 --- a/docs/INTERNALS.md +++ b/docs/INTERNALS.md @@ -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` |