INTERNALS: better markdown (follow-up)

 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.

 [ `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()`,

   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()

 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.

 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.

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

`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()`

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

 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`

 - 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

  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

  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

  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

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

  "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.

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