GIT
===
+
All changes to the sources are committed to the git repository as soon as
- they're somewhat verified to work. Changes shall be commited as independently
+ they're somewhat verified to work. Changes shall be committed as independently
as possible so that individual changes can be easier spotted and tracked
afterwards.
want it to remain functional and buildable with these and later versions
(older versions may still work but is not what we work hard to maintain):
- OpenSSL 0.9.6
+ OpenSSL 0.9.7
GnuTLS 1.2
zlib 1.1.4
libssh2 0.16
c-ares 1.6.0
libidn 0.4.1
- *yassl 1.4.0 (http://curl.haxx.se/mail/lib-2008-02/0093.html)
+ cyassl 2.0.0
openldap 2.0
- MIT krb5 lib 1.2.4
- qsossl V5R2M0
- NSS 3.11.x
+ MIT Kerberos 1.2.4
+ GSKit V5R3M0
+ NSS 3.14.x
+ axTLS 1.2.7
+ PolarSSL 1.3.0
Heimdal ?
-
- * = only partly functional, but that's due to bugs in the third party lib, not
- because of libcurl code
+ nghttp2 0.6.0
On systems where configure runs, we aim at working on them all - if they have
a suitable C compiler. On systems that don't run configure, we strive to keep
curl running fine on:
Windows 98
- AS/400 V5R2M0
+ AS/400 V5R3M0
Symbian 9.1
Windows CE ?
TPF ?
GNU Autoconf 2.57
GNU Automake 1.7 (we currently avoid 1.10 due to Solaris-related bugs)
GNU M4 1.4
- perl 4
+ perl 5.004
roffit 0.5
groff ? (any version that supports "groff -Tps -man [in] [out]")
ps2pdf (gs) ?
do it etc there might be reasons for applications to alter that behaviour.
3. The file descriptors for network communication and file operations are
- not easily interchangable as in unix.
+ not easily interchangeable as in unix.
We avoid this by not trying any funny tricks on file descriptors.
Inside the source code, We make an effort to avoid '#ifdef [Your OS]'. All
conditionals that deal with features *should* instead be in the format
'#ifdef HAVE_THAT_WEIRD_FUNCTION'. Since Windows can't run configure scripts,
- we maintain two curl_config-win32.h files (one in lib/ and one in src/) that
- are supposed to look exactly as a curl_config.h file would have looked like on
- a Windows machine!
+ we maintain a curl_config-win32.h file in lib directory that is supposed to
+ look exactly as a curl_config.h file would have looked like on a Windows
+ machine!
Generally speaking: always remember that this will be compiled on dozens of
operating systems. Don't walk on the edge.
Library
=======
+ (See LIBCURL-STRUCTS for a separate document describing all major internal
+ structs and their purposes.)
+
There are plenty of entry points to the library, namely each publicly defined
function that libcurl offers to applications. All of those functions are
rather small and easy-to-follow. All the ones prefixed with 'curl_easy' are
options is documented in the man page. This function mainly sets things in
the 'SessionHandle' struct.
- curl_easy_perform() does a whole lot of things:
+ curl_easy_perform() is just a wrapper function that makes use of the multi
+ API. It basically curl_multi_init(), curl_multi_add_handle(),
+ curl_multi_wait(), and curl_multi_perform() until the transfer is done and
+ then returns.
- It starts off in the lib/easy.c file by calling Curl_perform() and the main
- work then continues in lib/url.c. The flow continues with a call to
- Curl_connect() to connect to the remote site.
+ Some of the most important key functions in url.c are called from multi.c
+ when certain key steps are to be made in the transfer operation.
o Curl_connect()
- ... analyzes the URL, it separates the different components and connects to
- the remote host. This may involve using a proxy and/or using SSL. The
+ Analyzes the URL, it separates the different components and connects to the
+ remote host. This may involve using a proxy and/or using SSL. The
Curl_resolv() function in lib/hostip.c is used for looking up host names
(it does then use the proper underlying method, which may vary between
platforms and builds).
o Curl_do()
Curl_do() makes sure the proper protocol-specific function is called. The
- functions are named after the protocols they handle. Curl_ftp(),
- Curl_http(), Curl_dict(), etc. They all reside in their respective files
- (ftp.c, http.c and dict.c). HTTPS is handled by Curl_http() and FTPS by
- Curl_ftp().
+ functions are named after the protocols they handle.
The protocol-specific functions of course deal with protocol-specific
negotiations and setup. They have access to the Curl_sendf() (from
Some time during the DO function, the Curl_setup_transfer() function must
be called with some basic info about the upcoming transfer: what socket(s)
- to read/write and the expected file tranfer sizes (if known).
+ to read/write and the expected file transfer sizes (if known).
- o Transfer()
+ o Curl_readwrite()
- Curl_perform() then calls Transfer() in lib/transfer.c that performs the
- entire file transfer.
+ Called during the transfer of the actual protocol payload.
During transfer, the progress functions in lib/progress.c are called at a
frequent interval (or at the user's choice, a specified callback might get
used. This function is only used when we are certain that no more transfers
is going to be made on the connection. It can be also closed by force, or
it can be called to make sure that libcurl doesn't keep too many
- connections alive at the same time (there's a default amount of 5 but that
- can be changed with the CURLOPT_MAXCONNECTS option).
+ connections alive at the same time.
This function cleans up all resources that are associated with a single
connection.
- Curl_perform() is the function that does the main "connect - do - transfer -
- done" loop. It loops if there's a Location: to follow.
-
- When completed, the curl_easy_cleanup() should be called to free up used
- resources. It runs Curl_disconnect() on all open connectons.
-
- A quick roundup on internal function sequences (many of these call
- protocol-specific function-pointers):
-
- curl_connect - connects to a remote site and does initial connect fluff
- This also checks for an existing connection to the requested site and uses
- that one if it is possible.
-
- curl_do - starts a transfer
- curl_transfer() - transfers data
- curl_done - ends a transfer
-
- curl_disconnect - disconnects from a remote site. This is called when the
- disconnect is really requested, which doesn't necessarily have to be
- exactly after curl_done in case we want to keep the connection open for
- a while.
HTTP(S)
HTTPS uses in almost every means the same procedure as HTTP, with only two
exceptions: the connect procedure is different and the function used to read
or write from the socket is different, although the latter fact is hidden in
- the source by the use of curl_read() for reading and curl_write() for writing
+ the source by the use of Curl_read() for reading and Curl_write() for writing
data to the remote server.
http_chunks.c contains functions that understands HTTP 1.1 chunked transfer
encoding.
- An interesting detail with the HTTP(S) request, is the add_buffer() series of
- functions we use. They append data to one single buffer, and when the
- building is done the entire request is sent off in one single write. This is
- done this way to overcome problems with flawed firewalls and lame servers.
+ An interesting detail with the HTTP(S) request, is the Curl_add_buffer()
+ series of functions we use. They append data to one single buffer, and when
+ the building is done the entire request is sent off in one single write. This
+ is done this way to overcome problems with flawed firewalls and lame servers.
FTP
Kerberos
- The kerberos support is mainly in lib/krb4.c and lib/security.c.
+ Kerberos support is mainly in lib/krb5.c and lib/security.c but also
+ curl_sasl_sspi.c and curl_sasl_gssapi.c for the email protocols and
+ socks_gssapi.c & socks_sspi.c for SOCKS5 proxy specifics.
TELNET
The file:// protocol is dealt with in lib/file.c.
+ SMB
+
+ The smb:// protocol is dealt with in lib/smb.c.
+
LDAP
- Everything LDAP is in lib/ldap.c.
+ Everything LDAP is in lib/ldap.c and lib/openldap.c
+
+ E-mail
+
+ The e-mail related source code is in lib/imap.c, lib/pop3.c and lib/smtp.c.
GENERAL
URL encoding and decoding, called escaping and unescaping in the source code,
is found in lib/escape.c.
- While transfering data in Transfer() a few functions might get used.
+ While transferring data in Transfer() a few functions might get used.
curl_getdate() in lib/parsedate.c is for HTTP date comparisons (and more).
lib/getenv.c offers curl_getenv() which is for reading environment variables
lib/netrc.c holds the .netrc parser
lib/timeval.c features replacement functions for systems that don't have
- gettimeofday() and a few support functions for timeval convertions.
+ gettimeofday() and a few support functions for timeval conversions.
A function named curl_version() that returns the full curl version string is
found in lib/version.c.
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.
o The 'SessionHandle' struct holds the "connection cache" (an array of
- pointers to 'connectdata' structs). There's one connectdata struct
- allocated for each connection that libcurl knows about. Note that when you
- use the multi interface, the multi handle will hold the connection cache
- and not the particular easy handle. This of course to allow all easy handles
- in a multi stack to be able to share and re-use connections.
+ pointers to 'connectdata' structs).
o This enables the 'curl handle' to be reused on subsequent transfers.
- o When we are about to perform a transfer with curl_easy_perform(), we first
- check for an already existing connection in the cache that we can use,
- otherwise we create a new one and add to the cache. If the cache is full
- already when we add a new connection, we close one of the present ones. We
- select which one to close dependent on the close policy that may have been
- previously set.
- o When the transfer operation is complete, we try to leave the connection
- open. Particular options may tell us not to, and protocols may signal
- closure on connections and then we don't keep it open of course.
+ o When libcurl is told to perform a transfer, it first checks for an already
+ existing connection in the cache that we can use. Otherwise it creates a
+ new one and adds that the cache. If the cache is full already when a new
+ connection is added added, it will first close the oldest unused one.
+ o When the transfer operation is complete, the connection is left
+ open. Particular options may tell libcurl not to, and protocols may signal
+ closure on connections and then they won't be kept open of course.
o When curl_easy_cleanup() is called, we close all still opened connections,
unless of course the multi interface "owns" the connections.
- You do realize that the curl handle must be re-used in order for the
- persistent connections to work.
+ The curl handle must be re-used in order for the persistent connections to
+ work.
multi interface/non-blocking
============================
- We make an effort to provide a non-blocking interface to the library, the
- multi interface. To make that interface work as good as possible, no
- low-level functions within libcurl must be written to work in a blocking
- manner.
+ The multi interface is a non-blocking interface to the library. To make that
+ interface work as good as possible, no low-level functions within libcurl
+ must be written to work in a blocking manner. (There are still a few spots
+ violating this rule.)
One of the primary reasons we introduced c-ares support was to allow the name
resolve phase to be perfectly non-blocking as well.
- The ultimate goal is to provide the easy interface simply by wrapping the
- multi interface functions and thus treat everything internally as the multi
- interface is the single interface we have.
-
- The FTP and the SFTP/SCP protocols are thus perfect examples of how we adapt
- and adjust the code to allow non-blocking operations even on multi-stage
- protocols. The DICT, LDAP and TELNET are crappy examples and they are subject
- for rewrite in the future to better fit the libcurl protocol family.
+ The FTP and the SFTP/SCP protocols are examples of how we adapt and adjust
+ the code to allow non-blocking operations even on multi-stage command-
+ response protocols. They are built around state machines that return when
+ they would otherwise block waiting for data. The DICT, LDAP and TELNET
+ protocols are crappy examples and they are subject for rewrite in the future
+ to better fit the libcurl protocol family.
SSL libraries
=============
in future libcurl versions.
To deal with this internally in the best way possible, we have a generic SSL
- function API as provided by the sslgen.[ch] system, and they are the only SSL
- functions we must use from within libcurl. sslgen is then crafted to use the
+ function API as provided by the vtls.[ch] system, and they are the only SSL
+ functions we must use from within libcurl. vtls is then crafted to use the
appropriate lower-level function calls to whatever SSL library that is in
- use.
+ use. For example vtls/openssl.[ch] for the OpenSSL library.
Library Symbols
===============
All symbols used internally in libcurl must use a 'Curl_' prefix if they're
used in more than a single file. Single-file symbols must be made static.
Public ("exported") symbols must use a 'curl_' prefix. (There are exceptions,
- but they are to be changed to follow this pattern in future versions.)
+ but they are to be changed to follow this pattern in future versions.) Public
+ API functions are marked with CURL_EXTERN in the public header files so that
+ all others can be hidden on platforms where this is possible.
Return Codes and Informationals
===============================
Client
======
- main() resides in src/main.c together with most of the client code.
+ main() resides in src/tool_main.c.
- src/hugehelp.c is automatically generated by the mkhelp.pl perl script to
- display the complete "manual" and the src/urlglob.c file holds the functions
- used for the URL-"globbing" support. Globbing in the sense that the {} and []
- expansion stuff is there.
+ 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
+ functions used for the URL-"globbing" support. Globbing in the sense that the
+ {} and [] expansion stuff is there.
The client mostly messes around to setup its 'config' struct properly, then
it calls the curl_easy_*() functions of the library and when it gets back
curl_easy_getinfo() function to extract useful information from the curl
session.
- Recent versions may loop and do all this several times if many URLs were
- specified on the command line or config file.
+ It may loop and do all this several times if many URLs were specified on the
+ command line or config file.
Memory Debugging
================
Test Suite
==========
- Since November 2000, a test suite has evolved. It is placed in its own
- subdirectory directly off the root in the curl archive tree, and it contains
- a bunch of scripts and a lot of test case data.
+ The test suite is placed in its own subdirectory directly off the root in the
+ curl archive tree, and it contains a bunch of scripts and a lot of test case
+ data.
- The main test script is runtests.pl that will invoke the two servers
+ The main test script is runtests.pl that will invoke test servers like
httpserver.pl and ftpserver.pl before all the test cases are performed. The
test suite currently only runs on unix-like platforms.
- You'll find a complete description of the test case data files in the
- tests/README file.
+ You'll find a description of the test suite in the tests/README file, and the
+ test case data files in the tests/FILEFORMAT file.
The test suite automatically detects if curl was built with the memory
- debugging enabled, and if it was it will detect memory leaks too.
+ debugging enabled, and if it was it will detect memory leaks, too.
Building Releases
=================
There's no magic to this. When you consider everything stable enough to be
- released, run the 'maketgz' script (using 'make distcheck' will give you a
- pretty good view on the status of the current sources). maketgz prompts for
- version number of the client and the library before it creates a release
- archive. maketgz uses 'make dist' for the actual archive building, why you
- need to fill in the Makefile.am files properly for which files that should
- be included in the release archives.
-
- NOTE: you need to have curl checked out from git to be able to do a proper
+ released, do this:
+
+ 1. Tag the source code accordingly.
+
+ 2. run the 'maketgz' script (using 'make distcheck' will give you a pretty
+ good view on the status of the current sources). maketgz requires a
+ version number and creates the release archive. maketgz uses 'make dist'
+ for the actual archive building, why you need to fill in the Makefile.am
+ files properly for which files that should be included in the release
+ archives.
+
+ 3. When that's complete, sign the output files.
+
+ 4. Upload
+
+ 5. Update web site and changelog on site
+
+ 6. Send announcement to the mailing lists
+
+ NOTE: you must have curl checked out from git to be able to do a proper
release build. The release tarballs do not have everything setup in order to
do releases properly.
projects / external / curl.git / blobdiff