Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 506 lines (379 sloc) 21.35 kb
a07bc79 @yangtse removed trailing whitespace
yangtse authored
1 _ _ ____ _
2 ___| | | | _ \| |
3 / __| | | | |_) | |
4 | (__| |_| | _ <| |___
7c37c6a @bagder moved here from the root directory
authored
5 \___|\___/|_| \_\_____|
6
7 INTERNALS
8
ff681f7 @bagder 7.7 beta 2 fixes
authored
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
11 it.
7c37c6a @bagder moved here from the root directory
authored
12
ff681f7 @bagder 7.7 beta 2 fixes
authored
13 The largest amount of code and complexity is in the library part.
7c37c6a @bagder moved here from the root directory
authored
14
1609685 @bagder various changes of CVS to git
authored
15 GIT
a5217dd @bagder minor things about the test suite added
authored
16 ===
1609685 @bagder various changes of CVS to git
authored
17 All changes to the sources are committed to the git repository as soon as
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
18 they're somewhat verified to work. Changes shall be committed as independently
a5217dd @bagder minor things about the test suite added
authored
19 as possible so that individual changes can be easier spotted and tracked
20 afterwards.
21
22 Tagging shall be used extensively, and by the time we release new archives we
23 should tag the sources with a name similar to the released version number.
24
9918541 @bagder My first attempt at documenting what we try to support and make curl …
authored
25 Portability
26 ===========
27
28 We write curl and libcurl to compile with C89 compilers. On 32bit and up
29 machines. Most of libcurl assumes more or less POSIX compliance but that's
30 not a requirement.
31
32 We write libcurl to build and work with lots of third party tools, and we
33 want it to remain functional and buildable with these and later versions
34 (older versions may still work but is not what we work hard to maintain):
35
36 OpenSSL 0.9.6
37 GnuTLS 1.2
38 zlib 1.1.4
39 libssh2 0.16
19f45ea @bagder duphandle: use ares_dup()
authored
40 c-ares 1.6.0
9918541 @bagder My first attempt at documenting what we try to support and make curl …
authored
41 libidn 0.4.1
ee7e4fc @toddouska cyassl: update to CyaSSL 2.0.x API
toddouska authored
42 cyassl 2.0.0
9918541 @bagder My first attempt at documenting what we try to support and make curl …
authored
43 openldap 2.0
44 MIT krb5 lib 1.2.4
45 qsossl V5R2M0
42aa796 @kdudka nss: unconditionally require PK11_CreateGenericObject()
kdudka authored
46 NSS 3.12.x
3427bec @dfandrich Mention axTLS in some more documentation
dfandrich authored
47 axTLS 1.2.7
9918541 @bagder My first attempt at documenting what we try to support and make curl …
authored
48 Heimdal ?
49
50 * = only partly functional, but that's due to bugs in the third party lib, not
51 because of libcurl code
52
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
55 curl running fine on:
56
57 Windows 98
58 AS/400 V5R2M0
59 Symbian 9.1
60 Windows CE ?
61 TPF ?
62
af779fa @bagder added the versions of a range of build tools that we want to remain t…
authored
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
65 these versions:
66
67 GNU Libtool 1.4.2
68 GNU Autoconf 2.57
69 GNU Automake 1.7 (we currently avoid 1.10 due to Solaris-related bugs)
70 GNU M4 1.4
84e7ea2 Require a less ancient version of perl
Colin Hogben authored
71 perl 5.004
af779fa @bagder added the versions of a range of build tools that we want to remain t…
authored
72 roffit 0.5
73 groff ? (any version that supports "groff -Tps -man [in] [out]")
74 ps2pdf (gs) ?
75
7c37c6a @bagder moved here from the root directory
authored
76 Windows vs Unix
77 ===============
78
79 There are a few differences in how to program curl the unix way compared to
444024e @bagder brought up-to-date and extended
authored
80 the Windows way. The four perhaps most notable details are:
7c37c6a @bagder moved here from the root directory
authored
81
e8382ba @bagder moved the symbols talk to the library part, updated slightly to match
authored
82 1. Different function names for socket operations.
9c69539 @bagder edited the portable code section
authored
83
84 In curl, this is solved with defines and macros, so that the source looks
e8382ba @bagder moved the symbols talk to the library part, updated slightly to match
authored
85 the same at all places except for the header file that defines them. The
86 macros in use are sclose(), sread() and swrite().
9c69539 @bagder edited the portable code section
authored
87
ff681f7 @bagder 7.7 beta 2 fixes
authored
88 2. Windows requires a couple of init calls for the socket stuff.
9c69539 @bagder edited the portable code section
authored
89
322308e @bagder the winsock stuff is made by curl_global_init
authored
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.
9c69539 @bagder edited the portable code section
authored
92
7c37c6a @bagder moved here from the root directory
authored
93 3. The file descriptors for network communication and file operations are
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
94 not easily interchangeable as in unix.
9c69539 @bagder edited the portable code section
authored
95
96 We avoid this by not trying any funny tricks on file descriptors.
97
7c37c6a @bagder moved here from the root directory
authored
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)
101
9c69539 @bagder edited the portable code section
authored
102 We set stdout to binary under windows
7c37c6a @bagder moved here from the root directory
authored
103
ff681f7 @bagder 7.7 beta 2 fixes
authored
104 Inside the source code, We make an effort to avoid '#ifdef [Your OS]'. All
7c37c6a @bagder moved here from the root directory
authored
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,
919c97f @yangtse curl tool: use configuration files from lib directory
yangtse authored
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
109 machine!
7c37c6a @bagder moved here from the root directory
authored
110
444024e @bagder brought up-to-date and extended
authored
111 Generally speaking: always remember that this will be compiled on dozens of
112 operating systems. Don't walk on the edge.
113
7c37c6a @bagder moved here from the root directory
authored
114 Library
115 =======
116
3b60784 @bagder updated to be more valid for version 7 workings
authored
117 There are plenty of entry points to the library, namely each publicly defined
7c37c6a @bagder moved here from the root directory
authored
118 function that libcurl offers to applications. All of those functions are
3b60784 @bagder updated to be more valid for version 7 workings
authored
119 rather small and easy-to-follow. All the ones prefixed with 'curl_easy' are
120 put in the lib/easy.c file.
7c37c6a @bagder moved here from the root directory
authored
121
36e1363 @bagder minor edit
authored
122 curl_global_init_() and curl_global_cleanup() should be called by the
123 application to initialize and clean up global stuff in the library. As of
124 today, it can handle the global SSL initing if SSL is enabled and it can init
125 the socket layer on windows machines. libcurl itself has no "global" scope.
de16ddd @bagder updated, improved language at a few places
authored
126
444024e @bagder brought up-to-date and extended
authored
127 All printf()-style functions use the supplied clones in lib/mprintf.c. This
128 makes sure we stay absolutely platform independent.
129
a5217dd @bagder minor things about the test suite added
authored
130 curl_easy_init() allocates an internal struct and makes some initializations.
2297a7a @bagder more accurate
authored
131 The returned handle does not reveal internals. This is the 'SessionHandle'
132 struct which works as an "anchor" struct for all curl_easy functions. All
133 connections performed will get connect-specific data allocated that should be
134 used for things related to particular connections/requests.
a5217dd @bagder minor things about the test suite added
authored
135
de16ddd @bagder updated, improved language at a few places
authored
136 curl_easy_setopt() takes three arguments, where the option stuff must be
137 passed in pairs: the parameter-ID and the parameter-value. The list of
138 options is documented in the man page. This function mainly sets things in
2297a7a @bagder more accurate
authored
139 the 'SessionHandle' struct.
7c37c6a @bagder moved here from the root directory
authored
140
a5217dd @bagder minor things about the test suite added
authored
141 curl_easy_perform() does a whole lot of things:
3b60784 @bagder updated to be more valid for version 7 workings
authored
142
26d4c80 @bagder clarified and updated
authored
143 It starts off in the lib/easy.c file by calling Curl_perform() and the main
de16ddd @bagder updated, improved language at a few places
authored
144 work then continues in lib/url.c. The flow continues with a call to
26d4c80 @bagder clarified and updated
authored
145 Curl_connect() to connect to the remote site.
146
147 o Curl_connect()
148
149 ... analyzes the URL, it separates the different components and connects to
150 the remote host. This may involve using a proxy and/or using SSL. The
dc11239 @bagder slightly less outdated
authored
151 Curl_resolv() function in lib/hostip.c is used for looking up host names
152 (it does then use the proper underlying method, which may vary between
153 platforms and builds).
26d4c80 @bagder clarified and updated
authored
154
155 When Curl_connect is done, we are connected to the remote site. Then it is
156 time to tell the server to get a document/file. Curl_do() arranges this.
157
de16ddd @bagder updated, improved language at a few places
authored
158 This function makes sure there's an allocated and initiated 'connectdata'
159 struct that is used for this particular connection only (although there may
160 be several requests performed on the same connect). A bunch of things are
2297a7a @bagder more accurate
authored
161 inited/inherited from the SessionHandle struct.
de16ddd @bagder updated, improved language at a few places
authored
162
26d4c80 @bagder clarified and updated
authored
163 o Curl_do()
164
165 Curl_do() makes sure the proper protocol-specific function is called. The
166 functions are named after the protocols they handle. Curl_ftp(),
167 Curl_http(), Curl_dict(), etc. They all reside in their respective files
de16ddd @bagder updated, improved language at a few places
authored
168 (ftp.c, http.c and dict.c). HTTPS is handled by Curl_http() and FTPS by
169 Curl_ftp().
26d4c80 @bagder clarified and updated
authored
170
171 The protocol-specific functions of course deal with protocol-specific
172 negotiations and setup. They have access to the Curl_sendf() (from
173 lib/sendf.c) function to send printf-style formatted data to the remote
174 host and when they're ready to make the actual file transfer they call the
175 Curl_Transfer() function (in lib/transfer.c) to setup the transfer and
176 returns.
177
dc11239 @bagder slightly less outdated
authored
178 If this DO function fails and the connection is being re-used, libcurl will
179 then close this connection, setup a new connection and re-issue the DO
180 request on that. This is because there is no way to be perfectly sure that
181 we have discovered a dead connection before the DO function and thus we
182 might wrongly be re-using a connection that was closed by the remote peer.
183
184 Some time during the DO function, the Curl_setup_transfer() function must
185 be called with some basic info about the upcoming transfer: what socket(s)
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
186 to read/write and the expected file transfer sizes (if known).
2297a7a @bagder more accurate
authored
187
26d4c80 @bagder clarified and updated
authored
188 o Transfer()
189
dc11239 @bagder slightly less outdated
authored
190 Curl_perform() then calls Transfer() in lib/transfer.c that performs the
191 entire file transfer.
26d4c80 @bagder clarified and updated
authored
192
193 During transfer, the progress functions in lib/progress.c are called at a
194 frequent interval (or at the user's choice, a specified callback might get
195 called). The speedcheck functions in lib/speedcheck.c are also used to
196 verify that the transfer is as fast as required.
197
198 o Curl_done()
199
200 Called after a transfer is done. This function takes care of everything
201 that has to be done after a transfer. This function attempts to leave
202 matters in a state so that Curl_do() should be possible to call again on
de16ddd @bagder updated, improved language at a few places
authored
203 the same connection (in a persistent connection case). It might also soon
204 be closed with Curl_disconnect().
26d4c80 @bagder clarified and updated
authored
205
206 o Curl_disconnect()
207
de16ddd @bagder updated, improved language at a few places
authored
208 When doing normal connections and transfers, no one ever tries to close any
2297a7a @bagder more accurate
authored
209 connections so this is not normally called when curl_easy_perform() is
26d4c80 @bagder clarified and updated
authored
210 used. This function is only used when we are certain that no more transfers
de16ddd @bagder updated, improved language at a few places
authored
211 is going to be made on the connection. It can be also closed by force, or
212 it can be called to make sure that libcurl doesn't keep too many
213 connections alive at the same time (there's a default amount of 5 but that
214 can be changed with the CURLOPT_MAXCONNECTS option).
26d4c80 @bagder clarified and updated
authored
215
216 This function cleans up all resources that are associated with a single
217 connection.
218
219 Curl_perform() is the function that does the main "connect - do - transfer -
220 done" loop. It loops if there's a Location: to follow.
7c37c6a @bagder moved here from the root directory
authored
221
444024e @bagder brought up-to-date and extended
authored
222 When completed, the curl_easy_cleanup() should be called to free up used
cb787b7 @dfandrich Fixed some typos in documentation
dfandrich authored
223 resources. It runs Curl_disconnect() on all open connections.
7c37c6a @bagder moved here from the root directory
authored
224
ff681f7 @bagder 7.7 beta 2 fixes
authored
225 A quick roundup on internal function sequences (many of these call
226 protocol-specific function-pointers):
227
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
228 Curl_connect - connects to a remote site and does initial connect fluff
ff681f7 @bagder 7.7 beta 2 fixes
authored
229 This also checks for an existing connection to the requested site and uses
230 that one if it is possible.
231
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
232 Curl_do - starts a transfer
233 Curl_handler::do_it() - transfers data
234 Curl_done - ends a transfer
ff681f7 @bagder 7.7 beta 2 fixes
authored
235
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
236 Curl_disconnect - disconnects from a remote site. This is called when the
ff681f7 @bagder 7.7 beta 2 fixes
authored
237 disconnect is really requested, which doesn't necessarily have to be
238 exactly after curl_done in case we want to keep the connection open for
239 a while.
240
7c37c6a @bagder moved here from the root directory
authored
241 HTTP(S)
242
243 HTTP offers a lot and is the protocol in curl that uses the most lines of
244 code. There is a special file (lib/formdata.c) that offers all the multipart
245 post functions.
246
444024e @bagder brought up-to-date and extended
authored
247 base64-functions for user+password stuff (and more) is in (lib/base64.c) and
248 all functions for parsing and sending cookies are found in (lib/cookie.c).
7c37c6a @bagder moved here from the root directory
authored
249
250 HTTPS uses in almost every means the same procedure as HTTP, with only two
3b60784 @bagder updated to be more valid for version 7 workings
authored
251 exceptions: the connect procedure is different and the function used to read
252 or write from the socket is different, although the latter fact is hidden in
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
253 the source by the use of Curl_read() for reading and Curl_write() for writing
3b60784 @bagder updated to be more valid for version 7 workings
authored
254 data to the remote server.
7c37c6a @bagder moved here from the root directory
authored
255
ff681f7 @bagder 7.7 beta 2 fixes
authored
256 http_chunks.c contains functions that understands HTTP 1.1 chunked transfer
257 encoding.
258
c91c487 @bagder INTERNALS: clean up
authored
259 An interesting detail with the HTTP(S) request, is the Curl_add_buffer()
260 series of functions we use. They append data to one single buffer, and when
261 the building is done the entire request is sent off in one single write. This
262 is done this way to overcome problems with flawed firewalls and lame servers.
ff681f7 @bagder 7.7 beta 2 fixes
authored
263
7c37c6a @bagder moved here from the root directory
authored
264 FTP
265
444024e @bagder brought up-to-date and extended
authored
266 The Curl_if2ip() function can be used for getting the IP number of a
267 specified network interface, and it resides in lib/if2ip.c.
268
269 Curl_ftpsendf() is used for sending FTP commands to the remote server. It was
270 made a separate function to prevent us programmers from forgetting that they
271 must be CRLF terminated. They must also be sent in one single write() to make
272 firewalls and similar happy.
273
274 Kerberos
275
276 The kerberos support is mainly in lib/krb4.c and lib/security.c.
7c37c6a @bagder moved here from the root directory
authored
277
278 TELNET
279
280 Telnet is implemented in lib/telnet.c.
281
282 FILE
283
284 The file:// protocol is dealt with in lib/file.c.
285
286 LDAP
287
c91c487 @bagder INTERNALS: clean up
authored
288 Everything LDAP is in lib/ldap.c and lib/openldap.c
7c37c6a @bagder moved here from the root directory
authored
289
290 GENERAL
291
292 URL encoding and decoding, called escaping and unescaping in the source code,
293 is found in lib/escape.c.
294
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
295 While transferring data in Transfer() a few functions might get used.
dc11239 @bagder slightly less outdated
authored
296 curl_getdate() in lib/parsedate.c is for HTTP date comparisons (and more).
7c37c6a @bagder moved here from the root directory
authored
297
3b60784 @bagder updated to be more valid for version 7 workings
authored
298 lib/getenv.c offers curl_getenv() which is for reading environment variables
299 in a neat platform independent way. That's used in the client, but also in
444024e @bagder brought up-to-date and extended
authored
300 lib/url.c when checking the proxy environment variables. Note that contrary
301 to the normal unix getenv(), this returns an allocated buffer that must be
302 free()ed after use.
7c37c6a @bagder moved here from the root directory
authored
303
a5217dd @bagder minor things about the test suite added
authored
304 lib/netrc.c holds the .netrc parser
7c37c6a @bagder moved here from the root directory
authored
305
306 lib/timeval.c features replacement functions for systems that don't have
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
307 gettimeofday() and a few support functions for timeval conversions.
a07bc79 @yangtse removed trailing whitespace
yangtse authored
308
7c37c6a @bagder moved here from the root directory
authored
309 A function named curl_version() that returns the full curl version string is
310 found in lib/version.c.
311
e83550f @bagder persistent is spelled with an 'e', not an 'a'
authored
312 Persistent Connections
7d562bb @bagder a whole new section on persitant connections and how they're treated
authored
313 ======================
314
de16ddd @bagder updated, improved language at a few places
authored
315 The persistent connection support in libcurl requires some considerations on
316 how to do things inside of the library.
7d562bb @bagder a whole new section on persitant connections and how they're treated
authored
317
2297a7a @bagder more accurate
authored
318 o The 'SessionHandle' struct returned in the curl_easy_init() call must never
319 hold connection-oriented data. It is meant to hold the root data as well as
320 all the options etc that the library-user may choose.
321 o The 'SessionHandle' struct holds the "connection cache" (an array of
322 pointers to 'connectdata' structs). There's one connectdata struct
dc11239 @bagder slightly less outdated
authored
323 allocated for each connection that libcurl knows about. Note that when you
324 use the multi interface, the multi handle will hold the connection cache
325 and not the particular easy handle. This of course to allow all easy handles
326 in a multi stack to be able to share and re-use connections.
327 o This enables the 'curl handle' to be reused on subsequent transfers.
7d562bb @bagder a whole new section on persitant connections and how they're treated
authored
328 o When we are about to perform a transfer with curl_easy_perform(), we first
329 check for an already existing connection in the cache that we can use,
330 otherwise we create a new one and add to the cache. If the cache is full
331 already when we add a new connection, we close one of the present ones. We
332 select which one to close dependent on the close policy that may have been
333 previously set.
de16ddd @bagder updated, improved language at a few places
authored
334 o When the transfer operation is complete, we try to leave the connection
335 open. Particular options may tell us not to, and protocols may signal
336 closure on connections and then we don't keep it open of course.
dc11239 @bagder slightly less outdated
authored
337 o When curl_easy_cleanup() is called, we close all still opened connections,
338 unless of course the multi interface "owns" the connections.
7d562bb @bagder a whole new section on persitant connections and how they're treated
authored
339
340 You do realize that the curl handle must be re-used in order for the
e83550f @bagder persistent is spelled with an 'e', not an 'a'
authored
341 persistent connections to work.
7d562bb @bagder a whole new section on persitant connections and how they're treated
authored
342
ebce0a1 @bagder more blurb
authored
343 multi interface/non-blocking
344 ============================
345
346 We make an effort to provide a non-blocking interface to the library, the
347 multi interface. To make that interface work as good as possible, no
348 low-level functions within libcurl must be written to work in a blocking
349 manner.
350
351 One of the primary reasons we introduced c-ares support was to allow the name
352 resolve phase to be perfectly non-blocking as well.
353
354 The ultimate goal is to provide the easy interface simply by wrapping the
355 multi interface functions and thus treat everything internally as the multi
356 interface is the single interface we have.
357
358 The FTP and the SFTP/SCP protocols are thus perfect examples of how we adapt
359 and adjust the code to allow non-blocking operations even on multi-stage
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
360 protocols. They are built around state machines that return when they could
361 block waiting for data. The DICT, LDAP and TELNET protocols are crappy
362 examples and they are subject for rewrite in the future to better fit the
363 libcurl protocol family.
ebce0a1 @bagder more blurb
authored
364
365 SSL libraries
366 =============
367
368 Originally libcurl supported SSLeay for SSL/TLS transports, but that was then
369 extended to its successor OpenSSL but has since also been extended to several
370 other SSL/TLS libraries and we expect and hope to further extend the support
371 in future libcurl versions.
372
373 To deal with this internally in the best way possible, we have a generic SSL
374 function API as provided by the sslgen.[ch] system, and they are the only SSL
375 functions we must use from within libcurl. sslgen is then crafted to use the
376 appropriate lower-level function calls to whatever SSL library that is in
377 use.
378
e8382ba @bagder moved the symbols talk to the library part, updated slightly to match
authored
379 Library Symbols
380 ===============
a07bc79 @yangtse removed trailing whitespace
yangtse authored
381
e8382ba @bagder moved the symbols talk to the library part, updated slightly to match
authored
382 All symbols used internally in libcurl must use a 'Curl_' prefix if they're
de16ddd @bagder updated, improved language at a few places
authored
383 used in more than a single file. Single-file symbols must be made static.
384 Public ("exported") symbols must use a 'curl_' prefix. (There are exceptions,
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
385 but they are to be changed to follow this pattern in future versions.) Public
386 API functions are marked with CURL_EXTERN in the public header files so that
387 all others can be hidden on platforms where this is possible.
e8382ba @bagder moved the symbols talk to the library part, updated slightly to match
authored
388
444024e @bagder brought up-to-date and extended
authored
389 Return Codes and Informationals
390 ===============================
391
392 I've made things simple. Almost every function in libcurl returns a CURLcode,
393 that must be CURLE_OK if everything is OK or otherwise a suitable error code
394 as the curl/curl.h include file defines. The very spot that detects an error
395 must use the Curl_failf() function to set the human-readable error
396 description.
397
398 In aiding the user to understand what's happening and to debug curl usage, we
399 must supply a fair amount of informational messages by using the Curl_infof()
400 function. Those messages are only displayed when the user explicitly asks for
401 them. They are best used when revealing information that isn't otherwise
402 obvious.
403
ebce0a1 @bagder more blurb
authored
404 API/ABI
405 =======
406
407 We make an effort to not export or show internals or how internals work, as
408 that makes it easier to keep a solid API/ABI over time. See docs/libcurl/ABI
409 for our promise to users.
410
7c37c6a @bagder moved here from the root directory
authored
411 Client
412 ======
413
a5217dd @bagder minor things about the test suite added
authored
414 main() resides in src/main.c together with most of the client code.
26d4c80 @bagder clarified and updated
authored
415
a5217dd @bagder minor things about the test suite added
authored
416 src/hugehelp.c is automatically generated by the mkhelp.pl perl script to
417 display the complete "manual" and the src/urlglob.c file holds the functions
444024e @bagder brought up-to-date and extended
authored
418 used for the URL-"globbing" support. Globbing in the sense that the {} and []
419 expansion stuff is there.
7c37c6a @bagder moved here from the root directory
authored
420
444024e @bagder brought up-to-date and extended
authored
421 The client mostly messes around to setup its 'config' struct properly, then
422 it calls the curl_easy_*() functions of the library and when it gets back
3b60784 @bagder updated to be more valid for version 7 workings
authored
423 control after the curl_easy_perform() it cleans up the library, checks status
424 and exits.
7c37c6a @bagder moved here from the root directory
authored
425
b2e47df @bagder updated to better reflect reality
authored
426 When the operation is done, the ourWriteOut() function in src/writeout.c may
427 be called to report about the operation. That function is using the
428 curl_easy_getinfo() function to extract useful information from the curl
429 session.
430
26d4c80 @bagder clarified and updated
authored
431 Recent versions may loop and do all this several times if many URLs were
444024e @bagder brought up-to-date and extended
authored
432 specified on the command line or config file.
433
434 Memory Debugging
435 ================
436
26d4c80 @bagder clarified and updated
authored
437 The file lib/memdebug.c contains debug-versions of a few functions. Functions
438 such as malloc, free, fopen, fclose, etc that somehow deal with resources
439 that might give us problems if we "leak" them. The functions in the memdebug
440 system do nothing fancy, they do their normal function and then log
441 information about what they just did. The logged data can then be analyzed
442 after a complete session,
444024e @bagder brought up-to-date and extended
authored
443
1609685 @bagder various changes of CVS to git
authored
444 memanalyze.pl is the perl script present in tests/ that analyzes a log file
445 generated by the memory tracking system. It detects if resources are
446 allocated but never freed and other kinds of errors related to resource
447 management.
444024e @bagder brought up-to-date and extended
authored
448
3f8d3e9 @yangtse Update memory tracking/debugging reference
yangtse authored
449 Internally, definition of preprocessor symbol DEBUGBUILD restricts code which
450 is only compiled for debug enabled builds. And symbol CURLDEBUG is used to
451 differentiate code which is _only_ used for memory tracking/debugging.
452
453 Use -DCURLDEBUG when compiling to enable memory debugging, this is also
454 switched on by running configure with --enable-curldebug. Use -DDEBUGBUILD
455 when compiling to enable a debug build or run configure with --enable-debug.
456
457 curl --version will list 'Debug' feature for debug enabled builds, and
458 will list 'TrackMemory' feature for curl debug memory tracking capable
459 builds. These features are independent and can be controlled when running
460 the configure script. When --enable-debug is given both features will be
461 enabled, unless some restriction prevents memory tracking from being used.
444024e @bagder brought up-to-date and extended
authored
462
a5217dd @bagder minor things about the test suite added
authored
463 Test Suite
464 ==========
465
c91c487 @bagder INTERNALS: clean up
authored
466 The test suite is placed in its own subdirectory directly off the root in the
467 curl archive tree, and it contains a bunch of scripts and a lot of test case
468 data.
a5217dd @bagder minor things about the test suite added
authored
469
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
470 The main test script is runtests.pl that will invoke test servers like
a5217dd @bagder minor things about the test suite added
authored
471 httpserver.pl and ftpserver.pl before all the test cases are performed. The
472 test suite currently only runs on unix-like platforms.
b2e47df @bagder updated to better reflect reality
authored
473
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
474 You'll find a description of the test suite in the tests/README file, and the
475 test case data files in the tests/FILEFORMAT file.
444024e @bagder brought up-to-date and extended
authored
476
477 The test suite automatically detects if curl was built with the memory
7ba5e88 @dfandrich Some minor edits including updates to function names
dfandrich authored
478 debugging enabled, and if it was it will detect memory leaks, too.
444024e @bagder brought up-to-date and extended
authored
479
480 Building Releases
481 =================
482
483 There's no magic to this. When you consider everything stable enough to be
c91c487 @bagder INTERNALS: clean up
authored
484 released, do this:
485
486 1. Tag the source code accordingly.
487
488 2. run the 'maketgz' script (using 'make distcheck' will give you a pretty
489 good view on the status of the current sources). maketgz requires a
490 version number and creates the release archive. maketgz uses 'make dist'
491 for the actual archive building, why you need to fill in the Makefile.am
492 files properly for which files that should be included in the release
493 archives.
494
495 3. When that's complete, sign the output files.
496
497 4. Upload
498
499 5. Update web site and changelog on site
500
501 6. Send announcement to the mailing lists
502
503 NOTE: you must have curl checked out from git to be able to do a proper
e08296f @bagder mention that cvs is needed for releases
authored
504 release build. The release tarballs do not have everything setup in order to
505 do releases properly.
Something went wrong with that request. Please try again.