5 \___|\___/|_| \_\_____|
9 The project is split in two. The library and the client. The client part uses
10 the library, but the library is designed to allow other applications to use
13 The largest amount of code and complexity is in the library part.
18 All changes to the sources are committed to the git repository as soon as
19 they're somewhat verified to work. Changes shall be committed as independently
20 as possible so that individual changes can be easier spotted and tracked
23 Tagging shall be used extensively, and by the time we release new archives we
24 should tag the sources with a name similar to the released version number.
29 We write curl and libcurl to compile with C89 compilers. On 32bit and up
30 machines. Most of libcurl assumes more or less POSIX compliance but that's
33 We write libcurl to build and work with lots of third party tools, and we
34 want it to remain functional and buildable with these and later versions
35 (older versions may still work but is not what we work hard to maintain):
53 On systems where configure runs, we aim at working on them all - if they have
54 a suitable C compiler. On systems that don't run configure, we strive to keep
63 When writing code (mostly for generating stuff included in release tarballs)
64 we use a few "build tools" and we make sure that we remain functional with
69 GNU Automake 1.7 (we currently avoid 1.10 due to Solaris-related bugs)
73 groff ? (any version that supports "groff -Tps -man [in] [out]")
79 There are a few differences in how to program curl the unix way compared to
80 the Windows way. The four perhaps most notable details are:
82 1. Different function names for socket operations.
84 In curl, this is solved with defines and macros, so that the source looks
85 the same at all places except for the header file that defines them. The
86 macros in use are sclose(), sread() and swrite().
88 2. Windows requires a couple of init calls for the socket stuff.
90 That's taken care of by the curl_global_init() call, but if other libs also
91 do it etc there might be reasons for applications to alter that behaviour.
93 3. The file descriptors for network communication and file operations are
94 not easily interchangeable as in unix.
96 We avoid this by not trying any funny tricks on file descriptors.
98 4. When writing data to stdout, Windows makes end-of-lines the DOS way, thus
99 destroying binary data, although you do want that conversion if it is
100 text coming through... (sigh)
102 We set stdout to binary under windows
104 Inside the source code, We make an effort to avoid '#ifdef [Your OS]'. All
105 conditionals that deal with features *should* instead be in the format
106 '#ifdef HAVE_THAT_WEIRD_FUNCTION'. Since Windows can't run configure scripts,
107 we maintain a curl_config-win32.h file in lib directory that is supposed to
108 look exactly as a curl_config.h file would have looked like on a Windows
111 Generally speaking: always remember that this will be compiled on dozens of
112 operating systems. Don't walk on the edge.
117 (See LIBCURL-STRUCTS for a separate document describing all major internal
118 structs and their purposes.)
120 There are plenty of entry points to the library, namely each publicly defined
121 function that libcurl offers to applications. All of those functions are
122 rather small and easy-to-follow. All the ones prefixed with 'curl_easy' are
123 put in the lib/easy.c file.
125 curl_global_init_() and curl_global_cleanup() should be called by the
126 application to initialize and clean up global stuff in the library. As of
127 today, it can handle the global SSL initing if SSL is enabled and it can init
128 the socket layer on windows machines. libcurl itself has no "global" scope.
130 All printf()-style functions use the supplied clones in lib/mprintf.c. This
131 makes sure we stay absolutely platform independent.
133 curl_easy_init() allocates an internal struct and makes some initializations.
134 The returned handle does not reveal internals. This is the 'SessionHandle'
135 struct which works as an "anchor" struct for all curl_easy functions. All
136 connections performed will get connect-specific data allocated that should be
137 used for things related to particular connections/requests.
139 curl_easy_setopt() takes three arguments, where the option stuff must be
140 passed in pairs: the parameter-ID and the parameter-value. The list of
141 options is documented in the man page. This function mainly sets things in
142 the 'SessionHandle' struct.
144 curl_easy_perform() is just a wrapper function that makes use of the multi
145 API. It basically curl_multi_init(), curl_multi_add_handle(),
146 curl_multi_wait(), and curl_multi_perform() until the transfer is done and
149 Some of the most important key functions in url.c are called from multi.c
150 when certain key steps are to be made in the transfer operation.
154 Analyzes the URL, it separates the different components and connects to the
155 remote host. This may involve using a proxy and/or using SSL. The
156 Curl_resolv() function in lib/hostip.c is used for looking up host names
157 (it does then use the proper underlying method, which may vary between
158 platforms and builds).
160 When Curl_connect is done, we are connected to the remote site. Then it is
161 time to tell the server to get a document/file. Curl_do() arranges this.
163 This function makes sure there's an allocated and initiated 'connectdata'
164 struct that is used for this particular connection only (although there may
165 be several requests performed on the same connect). A bunch of things are
166 inited/inherited from the SessionHandle struct.
170 Curl_do() makes sure the proper protocol-specific function is called. The
171 functions are named after the protocols they handle.
173 The protocol-specific functions of course deal with protocol-specific
174 negotiations and setup. They have access to the Curl_sendf() (from
175 lib/sendf.c) function to send printf-style formatted data to the remote
176 host and when they're ready to make the actual file transfer they call the
177 Curl_Transfer() function (in lib/transfer.c) to setup the transfer and
180 If this DO function fails and the connection is being re-used, libcurl will
181 then close this connection, setup a new connection and re-issue the DO
182 request on that. This is because there is no way to be perfectly sure that
183 we have discovered a dead connection before the DO function and thus we
184 might wrongly be re-using a connection that was closed by the remote peer.
186 Some time during the DO function, the Curl_setup_transfer() function must
187 be called with some basic info about the upcoming transfer: what socket(s)
188 to read/write and the expected file transfer sizes (if known).
192 Called during the transfer of the actual protocol payload.
194 During transfer, the progress functions in lib/progress.c are called at a
195 frequent interval (or at the user's choice, a specified callback might get
196 called). The speedcheck functions in lib/speedcheck.c are also used to
197 verify that the transfer is as fast as required.
201 Called after a transfer is done. This function takes care of everything
202 that has to be done after a transfer. This function attempts to leave
203 matters in a state so that Curl_do() should be possible to call again on
204 the same connection (in a persistent connection case). It might also soon
205 be closed with Curl_disconnect().
209 When doing normal connections and transfers, no one ever tries to close any
210 connections so this is not normally called when curl_easy_perform() is
211 used. This function is only used when we are certain that no more transfers
212 is going to be made on the connection. It can be also closed by force, or
213 it can be called to make sure that libcurl doesn't keep too many
214 connections alive at the same time.
216 This function cleans up all resources that are associated with a single
222 HTTP offers a lot and is the protocol in curl that uses the most lines of
223 code. There is a special file (lib/formdata.c) that offers all the multipart
226 base64-functions for user+password stuff (and more) is in (lib/base64.c) and
227 all functions for parsing and sending cookies are found in (lib/cookie.c).
229 HTTPS uses in almost every means the same procedure as HTTP, with only two
230 exceptions: the connect procedure is different and the function used to read
231 or write from the socket is different, although the latter fact is hidden in
232 the source by the use of Curl_read() for reading and Curl_write() for writing
233 data to the remote server.
235 http_chunks.c contains functions that understands HTTP 1.1 chunked transfer
238 An interesting detail with the HTTP(S) request, is the Curl_add_buffer()
239 series of functions we use. They append data to one single buffer, and when
240 the building is done the entire request is sent off in one single write. This
241 is done this way to overcome problems with flawed firewalls and lame servers.
245 The Curl_if2ip() function can be used for getting the IP number of a
246 specified network interface, and it resides in lib/if2ip.c.
248 Curl_ftpsendf() is used for sending FTP commands to the remote server. It was
249 made a separate function to prevent us programmers from forgetting that they
250 must be CRLF terminated. They must also be sent in one single write() to make
251 firewalls and similar happy.
255 Kerberos support is mainly in lib/krb5.c and lib/security.c but also
256 curl_sasl_sspi.c and curl_sasl_gssapi.c for the email protocols and
257 socks_gssapi.c & socks_sspi.c for SOCKS5 proxy specifics.
261 Telnet is implemented in lib/telnet.c.
265 The file:// protocol is dealt with in lib/file.c.
269 The smb:// protocol is dealt with in lib/smb.c.
273 Everything LDAP is in lib/ldap.c and lib/openldap.c
277 The e-mail related source code is in lib/imap.c, lib/pop3.c and lib/smtp.c.
281 URL encoding and decoding, called escaping and unescaping in the source code,
282 is found in lib/escape.c.
284 While transferring data in Transfer() a few functions might get used.
285 curl_getdate() in lib/parsedate.c is for HTTP date comparisons (and more).
287 lib/getenv.c offers curl_getenv() which is for reading environment variables
288 in a neat platform independent way. That's used in the client, but also in
289 lib/url.c when checking the proxy environment variables. Note that contrary
290 to the normal unix getenv(), this returns an allocated buffer that must be
293 lib/netrc.c holds the .netrc parser
295 lib/timeval.c features replacement functions for systems that don't have
296 gettimeofday() and a few support functions for timeval conversions.
298 A function named curl_version() that returns the full curl version string is
299 found in lib/version.c.
301 Persistent Connections
302 ======================
304 The persistent connection support in libcurl requires some considerations on
305 how to do things inside of the library.
307 o The 'SessionHandle' struct returned in the curl_easy_init() call must never
308 hold connection-oriented data. It is meant to hold the root data as well as
309 all the options etc that the library-user may choose.
310 o The 'SessionHandle' struct holds the "connection cache" (an array of
311 pointers to 'connectdata' structs).
312 o This enables the 'curl handle' to be reused on subsequent transfers.
313 o When libcurl is told to perform a transfer, it first checks for an already
314 existing connection in the cache that we can use. Otherwise it creates a
315 new one and adds that the cache. If the cache is full already when a new
316 connection is added added, it will first close the oldest unused one.
317 o When the transfer operation is complete, the connection is left
318 open. Particular options may tell libcurl not to, and protocols may signal
319 closure on connections and then they won't be kept open of course.
320 o When curl_easy_cleanup() is called, we close all still opened connections,
321 unless of course the multi interface "owns" the connections.
323 The curl handle must be re-used in order for the persistent connections to
326 multi interface/non-blocking
327 ============================
329 The multi interface is a non-blocking interface to the library. To make that
330 interface work as good as possible, no low-level functions within libcurl
331 must be written to work in a blocking manner. (There are still a few spots
332 violating this rule.)
334 One of the primary reasons we introduced c-ares support was to allow the name
335 resolve phase to be perfectly non-blocking as well.
337 The FTP and the SFTP/SCP protocols are examples of how we adapt and adjust
338 the code to allow non-blocking operations even on multi-stage command-
339 response protocols. They are built around state machines that return when
340 they would otherwise block waiting for data. The DICT, LDAP and TELNET
341 protocols are crappy examples and they are subject for rewrite in the future
342 to better fit the libcurl protocol family.
347 Originally libcurl supported SSLeay for SSL/TLS transports, but that was then
348 extended to its successor OpenSSL but has since also been extended to several
349 other SSL/TLS libraries and we expect and hope to further extend the support
350 in future libcurl versions.
352 To deal with this internally in the best way possible, we have a generic SSL
353 function API as provided by the vtls.[ch] system, and they are the only SSL
354 functions we must use from within libcurl. vtls is then crafted to use the
355 appropriate lower-level function calls to whatever SSL library that is in
356 use. For example vtls/openssl.[ch] for the OpenSSL library.
361 All symbols used internally in libcurl must use a 'Curl_' prefix if they're
362 used in more than a single file. Single-file symbols must be made static.
363 Public ("exported") symbols must use a 'curl_' prefix. (There are exceptions,
364 but they are to be changed to follow this pattern in future versions.) Public
365 API functions are marked with CURL_EXTERN in the public header files so that
366 all others can be hidden on platforms where this is possible.
368 Return Codes and Informationals
369 ===============================
371 I've made things simple. Almost every function in libcurl returns a CURLcode,
372 that must be CURLE_OK if everything is OK or otherwise a suitable error code
373 as the curl/curl.h include file defines. The very spot that detects an error
374 must use the Curl_failf() function to set the human-readable error
377 In aiding the user to understand what's happening and to debug curl usage, we
378 must supply a fair amount of informational messages by using the Curl_infof()
379 function. Those messages are only displayed when the user explicitly asks for
380 them. They are best used when revealing information that isn't otherwise
386 We make an effort to not export or show internals or how internals work, as
387 that makes it easier to keep a solid API/ABI over time. See docs/libcurl/ABI
388 for our promise to users.
393 main() resides in src/tool_main.c.
395 src/tool_hugehelp.c is automatically generated by the mkhelp.pl perl script
396 to display the complete "manual" and the src/tool_urlglob.c file holds the
397 functions used for the URL-"globbing" support. Globbing in the sense that the
398 {} and [] expansion stuff is there.
400 The client mostly messes around to setup its 'config' struct properly, then
401 it calls the curl_easy_*() functions of the library and when it gets back
402 control after the curl_easy_perform() it cleans up the library, checks status
405 When the operation is done, the ourWriteOut() function in src/writeout.c may
406 be called to report about the operation. That function is using the
407 curl_easy_getinfo() function to extract useful information from the curl
410 It may loop and do all this several times if many URLs were specified on the
411 command line or config file.
416 The file lib/memdebug.c contains debug-versions of a few functions. Functions
417 such as malloc, free, fopen, fclose, etc that somehow deal with resources
418 that might give us problems if we "leak" them. The functions in the memdebug
419 system do nothing fancy, they do their normal function and then log
420 information about what they just did. The logged data can then be analyzed
421 after a complete session,
423 memanalyze.pl is the perl script present in tests/ that analyzes a log file
424 generated by the memory tracking system. It detects if resources are
425 allocated but never freed and other kinds of errors related to resource
428 Internally, definition of preprocessor symbol DEBUGBUILD restricts code which
429 is only compiled for debug enabled builds. And symbol CURLDEBUG is used to
430 differentiate code which is _only_ used for memory tracking/debugging.
432 Use -DCURLDEBUG when compiling to enable memory debugging, this is also
433 switched on by running configure with --enable-curldebug. Use -DDEBUGBUILD
434 when compiling to enable a debug build or run configure with --enable-debug.
436 curl --version will list 'Debug' feature for debug enabled builds, and
437 will list 'TrackMemory' feature for curl debug memory tracking capable
438 builds. These features are independent and can be controlled when running
439 the configure script. When --enable-debug is given both features will be
440 enabled, unless some restriction prevents memory tracking from being used.
445 The test suite is placed in its own subdirectory directly off the root in the
446 curl archive tree, and it contains a bunch of scripts and a lot of test case
449 The main test script is runtests.pl that will invoke test servers like
450 httpserver.pl and ftpserver.pl before all the test cases are performed. The
451 test suite currently only runs on unix-like platforms.
453 You'll find a description of the test suite in the tests/README file, and the
454 test case data files in the tests/FILEFORMAT file.
456 The test suite automatically detects if curl was built with the memory
457 debugging enabled, and if it was it will detect memory leaks, too.
462 There's no magic to this. When you consider everything stable enough to be
465 1. Tag the source code accordingly.
467 2. run the 'maketgz' script (using 'make distcheck' will give you a pretty
468 good view on the status of the current sources). maketgz requires a
469 version number and creates the release archive. maketgz uses 'make dist'
470 for the actual archive building, why you need to fill in the Makefile.am
471 files properly for which files that should be included in the release
474 3. When that's complete, sign the output files.
478 5. Update web site and changelog on site
480 6. Send announcement to the mailing lists
482 NOTE: you must have curl checked out from git to be able to do a proper
483 release build. The release tarballs do not have everything setup in order to
484 do releases properly.
projects / platform / upstream / curl.git / blob