Tcl can be regarded as a powerful configuration language sitting on top of a bunch of C functions. Tcl's original purpose (according to Tcl's inventor John Ousterhout (see How do I use the Tcl C API?)), was to create a standard language that could be embedded in applications. The intent was that Tcl would be accessed only via its C API. Today, the typical use is via the tclsh or wish interpreters at the scripting level.
If you want to learn more about the C core of Tcl and how it is working, start here: The Tcl Core.
This C API can be use to extend Tcl, giving it new commands and new functionality (see Extending Tcl). The recommended way for this is to use Tcl's Extension Architecture TEA, a set of guidelines and techniques for the distribution, configuration, compilation, and installation of Tcl extensions. TEA comes with a "sample extension" showing how to do things:
Regardless whether you are writing an extension in C or Tcl, here is some more information:
To see how extendind Tcl works in practice, you should have a look at the typical 'Hello world' example:
There are also other examples of small extensions in C:
One thing you might wonder about is the return value of a C function implementing a Tcl command. In Tcl, a procedure will always return the value that you want to use outside the procedure, in the code calling the procedure. In C, a function implementing a Tcl command must return a status code that is typically either Tcl_OK or TCL_ERROR (there are also TCL_BREAK, TCL_CONTINUE and TCL_RETURN for special cases). The Tcl value which is returned on the script level is stored in the Tcl_Obj that was passed as an argument to the C function implementing the Tcl command. This is done using functions such as Tcl_SetResult/Tcl_SetObjResult, Tcl_AppendResult, Tcl_AppendElement together with Tcl_GetObjResult and Tcl_GetStringResult.
The Tcl Extension Architecture is a whole story in itself. TEA is largely defined by the tcl.m4 file in tclconfig, along with the configure.in and Makefile files in the sample extension. A makefile.vc and rules.vc file is also included for Windows builds. TEA describes a directory layout both for the source distribution and for files installed as part of the extension. Files in the source distribution of an extension are laid out such that platform-specific components live in a directory dedicated to that platform. The version of TEA is defined by the TEA_VERSION variable in the tcl.m4 file in tclconfig.
Here are some pages dealing with TEA:
Examples of existing extensions using TEA are: Tktable, TclX, itcl/itk.
Going one step further, you can even extend Tcl with a C function that is written inside the Tcl script where you need it:
Of course, you can also still use Tcl as embedded language in you application. Here are some pages about this, including customization of tclsh itself:
Embedding Tcl typically involves using the C API function Tcl_Init.
All the Tcl C API functions have manual pages (see here ). However, the Wiki has also a bit of information on some of the API functions. Start with the list of function here:
There are some common design principles in the C API which you can read about here: Tcl C API Design Principles.
Some special information on certain aspects of the Tcl C API can be found here:
Prior to Tcl version 8, the C interface for Tcl commands was string oriented (fitting Tcl's philosophy of everything is a string. As this resulted in a lot of conversions when you wanted integers, doubles, lists from this string, Tcl 8 introduced a new interface based on the Tcl_Obj C type. This type can store the various incarnations of a Tcl value at the same time, doing the necessary conversions between types in a lazy fashion. This helped to speed up Tcl and made scripts run more efficiently.
Note: Although Tcl_Obj is termed an "object", it has nothing to do with object-oriented programming (that's what TclOO is for). Think of Tcl_Obj as a Tcl value with different clothes on. Depending on your needs, Tcl will provide you with the Tcl value dressed differently.
Some of the Tcl_Obj functions come in two flavours, e.g. Tcl_GetString and Tcl_GetStringFromObj. Don't get confused, both are dealing with Tcl_Obj and return the string representation of a Tcl_Obj although it looks like the first is dealing with strings only and the other with Tcl_Obj! The difference is just that you may sometimes be interested in not only getting the string itself but also the length of the string. If so, you can use Tcl_GetStringFromObj instead of Tcl_GetString.
Just as Tcl, also Tk has its own C API. Here is a list (probably incomplete) with more information on at least a few of the Tk C functions:
Here is some more information (and examples) on extending Tk: