This chapter contains descriptions of functions in the Tcl library that are fundamental to writing C implementations of Tcl commands and to executing Tcl from C.

Unless otherwise indicated, a library function returns either TCL_OK or TCL_ERROR. These are symbolic names for two of the integer codes returned returned by the -code option of Tcl's return statement. When TCL_ERROR is returned by the C function, the interpreter's return string has been set to an error message. Unless you are trying to "catch" the error with your C code, the way to execute one of these functions is

if( Tcl_LibraryFunction( ... ) != TCL_OK ) { 
  clean up anything that has become useless because of the error
  return TCL_ERROR; 
}

Unless otherwise indicated, the Tcl_Interp * Intrp parameter refers to the currently executing Tcl interpreter.

Library functions that contain "Obj" in their names are object-based. All others are string-based. Object-based functions are only available in Tcl version 8.0 or later. The string-based functions mentioned in this book are available in Tcl version 8.0 as well as in earlier versions.

• Allocating Memory
• Manipulating Objects of Type Tcl_Obj
• More about Command Execution
• Accessing Tcl Variables
• List Processing
• Solutions to Exercises