98
98
... analyzes the URL, it separates the different components and connects to
99
99
the remote host. This may involve using a proxy and/or using SSL. The
100
Curl_gethost() function in lib/hostip.c is used for looking up host names.
100
Curl_resolv() function in lib/hostip.c is used for looking up host names
101
(it does then use the proper underlying method, which may vary between
102
platforms and builds).
102
104
When Curl_connect is done, we are connected to the remote site. Then it is
103
105
time to tell the server to get a document/file. Curl_do() arranges this.
122
124
Curl_Transfer() function (in lib/transfer.c) to setup the transfer and
125
Starting in 7.9.1, if this DO function fails and the connection is being
126
re-used, libcurl will then close this connection, setup a new connection
127
and re-issue the DO request on that. This is because there is no way to be
128
perfectly sure that we have discovered a dead connection before the DO
129
function and thus we might wrongly be re-using a connection that was closed
127
If this DO function fails and the connection is being re-used, libcurl will
128
then close this connection, setup a new connection and re-issue the DO
129
request on that. This is because there is no way to be perfectly sure that
130
we have discovered a dead connection before the DO function and thus we
131
might wrongly be re-using a connection that was closed by the remote peer.
133
Some time during the DO function, the Curl_setup_transfer() function must
134
be called with some basic info about the upcoming transfer: what socket(s)
135
to read/write and the expected file tranfer sizes (if known).
134
Curl_perform() then calls Transfer() in lib/transfer.c that performs
135
the entire file transfer.
139
Curl_perform() then calls Transfer() in lib/transfer.c that performs the
140
entire file transfer.
137
142
During transfer, the progress functions in lib/progress.c are called at a
138
143
frequent interval (or at the user's choice, a specified callback might get
236
241
URL encoding and decoding, called escaping and unescaping in the source code,
237
242
is found in lib/escape.c.
239
While transfering data in Transfer() a few functions might get
240
used. curl_getdate() in lib/getdate.c is for HTTP date comparisons (and
244
While transfering data in Transfer() a few functions might get used.
245
curl_getdate() in lib/parsedate.c is for HTTP date comparisons (and more).
243
247
lib/getenv.c offers curl_getenv() which is for reading environment variables
244
248
in a neat platform independent way. That's used in the client, but also in
254
258
A function named curl_version() that returns the full curl version string is
255
259
found in lib/version.c.
257
If authentication is requested but no password is given, a getpass_r() clone
258
exists in lib/getpass.c. libcurl offers a custom callback that can be used
259
instead of this, but it doesn't change much to us.
261
261
Persistent Connections
262
262
======================
269
269
all the options etc that the library-user may choose.
270
270
o The 'SessionHandle' struct holds the "connection cache" (an array of
271
271
pointers to 'connectdata' structs). There's one connectdata struct
272
allocated for each connection that libcurl knows about.
273
o This also enables the 'curl handle' to be reused on subsequent transfers,
274
something that was illegal before libcurl 7.7.
272
allocated for each connection that libcurl knows about. Note that when you
273
use the multi interface, the multi handle will hold the connection cache
274
and not the particular easy handle. This of course to allow all easy handles
275
in a multi stack to be able to share and re-use connections.
276
o This enables the 'curl handle' to be reused on subsequent transfers.
275
277
o When we are about to perform a transfer with curl_easy_perform(), we first
276
278
check for an already existing connection in the cache that we can use,
277
279
otherwise we create a new one and add to the cache. If the cache is full
281
283
o When the transfer operation is complete, we try to leave the connection
282
284
open. Particular options may tell us not to, and protocols may signal
283
285
closure on connections and then we don't keep it open of course.
284
o When curl_easy_cleanup() is called, we close all still opened connections.
286
o When curl_easy_cleanup() is called, we close all still opened connections,
287
unless of course the multi interface "owns" the connections.
286
289
You do realize that the curl handle must be re-used in order for the
287
290
persistent connections to work.
292
multi interface/non-blocking
293
============================
295
We make an effort to provide a non-blocking interface to the library, the
296
multi interface. To make that interface work as good as possible, no
297
low-level functions within libcurl must be written to work in a blocking
300
One of the primary reasons we introduced c-ares support was to allow the name
301
resolve phase to be perfectly non-blocking as well.
303
The ultimate goal is to provide the easy interface simply by wrapping the
304
multi interface functions and thus treat everything internally as the multi
305
interface is the single interface we have.
307
The FTP and the SFTP/SCP protocols are thus perfect examples of how we adapt
308
and adjust the code to allow non-blocking operations even on multi-stage
309
protocols. The DICT, TELNET and TFTP are crappy examples and they are subject
310
for rewrite in the future to better fit the libcurl protocol family.
315
Originally libcurl supported SSLeay for SSL/TLS transports, but that was then
316
extended to its successor OpenSSL but has since also been extended to several
317
other SSL/TLS libraries and we expect and hope to further extend the support
318
in future libcurl versions.
320
To deal with this internally in the best way possible, we have a generic SSL
321
function API as provided by the sslgen.[ch] system, and they are the only SSL
322
functions we must use from within libcurl. sslgen is then crafted to use the
323
appropriate lower-level function calls to whatever SSL library that is in
309
346
them. They are best used when revealing information that isn't otherwise
352
We make an effort to not export or show internals or how internals work, as
353
that makes it easier to keep a solid API/ABI over time. See docs/libcurl/ABI
354
for our promise to users.
added
removed
docs/INTERNALS
