1Command Writing(TCL)                                      Command Writing(TCL)
2
3
4

NAME

6       TclCommandWriting - Writing C language extensions to Tcl.
7

OVERVIEW

9       This  document  is intended to help the programmer who wishes to extend
10       Tcl with C language routines.  It should  also  be  useful  to  someone
11       wishing  to add Tcl to an existing editor, communications program, win‐
12       dow manager, etc.  Experienced extension writers may find  this  manual
13       helpful  in rewriting their applications to use the new Tcl object sys‐
14       tem.  We assume you are already fluent in the  C  programming  language
15       and that you have built and installed Tcl on your machine.
16
17       Information  on  the available C interface routines to Tcl can be found
18       in the *.3 manual pages in the doc directory of the baseline  Tcl  dis‐
19       tribution,  and  in  the  *.3 manpages in the doc directory of Extended
20       Tcl.
21

TCL OBJECT SYSTEM

23       With the release of Tcl version 8, Tcl has a new  system  for  managing
24       Tcl values internally.  To the Tcl programmer, the new objects look and
25       act like strings, as before.  But at the C level, these objects can now
26       also  hold  cached  internal  representations of the strings in various
27       native datatypes.  For example, an object containing a string  consist‐
28       ing of an integer, will now maintain a machine-code integer representa‐
29       tion, if an  integer  representation  has  been  needed.   Using  these
30       objects  is much more efficient than using the older-style Tcl strings,
31       although the older style is still (currently) supported.
32
33       Although the object system has almost no effect at all on how  the  Tcl
34       programmer uses Tcl, the object system's C interfaces to strings, inte‐
35       gers, lists, etc., have changed considerably.  While converting a pack‐
36       age  to use the new system can be a lot of work, the combination of the
37       object system, which  saves  Tcl  from  having  to  constantly  convert
38       strings  to  integers  and back, etc., and the on-the-fly bytecode com‐
39       piler (which keeps Tcl from having to continually reparse code it is to
40       execute)  yield  Tcl programs that routinely execute several times more
41       quickly than with previous versions (Tcl 7 and  before),  and  in  some
42       cases run as much as 2500 (!) times faster than before.
43
44       We  have  chosen,  then, to rewrite the Command Writer's manpage, which
45       has been shipping with Extended Tcl for a number of years,  to  produce
46       this  new  version  based  on  the new object system.  The old manpage,
47       based on the older string-oriented routines, will still be included  in
48       TclX  releases for now, as it is still relevant to Tcl releases through
49       version 7, and may be of  use  to  those  modifying/upgrading  packages
50       written  for  the  old  model.  The old manual will be dropped from the
51       release once we deem it unneeded; the old interfaces should now be con‐
52       sidered legacy interfaces, and all new development should be done using
53       the new object interfaces, unless backwards compatibility to  pre-Tcl-8
54       releases is needed.
55
56

A SIMPLE C EXTENSION

58       All  C-based Tcl commands are called with four arguments: a client data
59       pointer, an interpreter pointer, an argument count and a pointer to  an
60       array of Tcl objects containing the arguments to the command.
61
62       A simple C extension to Tcl is now presented, and described below:
63
64           #include "tcl.h"
65
66           int App_DumpArgsObjCmd(clientData, interp, objc, objv)
67               void          *clientData;
68               Tcl_Interp    *interp;
69               int            objc;
70               Tcl_Obj      **objv;
71           {
72                   int   i;
73                int   stringLen;
74                char *stringPtr;
75
76                   for (i = 1; i < objc; i++) {
77                     stringPtr = Tcl_GetStringFromObj (objv [i], &stringLen);
78                           printf("%s", stringPtr);
79                     if (i < objc - 1) printf(" ");
80                   }
81                   printf("\n");
82                   return TCL_OK;
83           }
84
85       The client data pointer will be described later.
86

INTERPRETERS

88       The  interpreter  pointer  is  the  ``key''  to  an interpreter.  It is
89       returned by Tcl_CreateInterp and is used extensively  within  Tcl,  and
90       will  be  used  by your C extensions.  The data structure pointed to by
91       the interpreter pointer, and all of  the  subordinate  structures  that
92       branch  off of it, make up a Tcl interpreter, which includes all of the
93       currently defined procedures, commands, variables, arrays and the  exe‐
94       cution  state  of  that interpreter.  (For more information on creating
95       and deleting interpreters, please examine the CrtInterp(3)  manpage  in
96       the  core  Tcl  distribution.  For information on creating interpreters
97       that include the commands provided  by  Extended  Tcl,  check  out  the
98       TclX_Init(3) manpage of Extended Tcl.  For a manual page describing the
99       user-visible fields of a Tcl interpreter, please look at  Interp(3)  in
100       core Tcl.)
101

OBJECT COUNT AND ARGUMENTS

103       The  argument count, or object count (objc), and pointer to an array of
104       pointers to Tcl objects of the command's arguments (objv) is handled by
105       your  C code, in a manner similar to the one you would use in writing a
106       C main function -- an argument count and array of  pointers  works  the
107       same as in a C main call; pointers to the arguments to the function are
108       contained in the objv array.  Similar to a C main, the  first  argument
109       (objv[0])  is  an  object containing the name the routine was called as
110       (in a C main, the name the program was invoked as).
111
112       In Tcl, however, the array of pointers are not  pointers  to  character
113       strings (although they were in all version of Tcl before 8.0).
114
115       In  the  above  example,  all  of the arguments are output with a space
116       between each one by looping through elements of the objv array from one
117       to  the  argument count, objc, and a newline is output to terminate the
118       line -- a simple ``echo'' command.  This example uses printf  for  sim‐
119       plicity.   Of  course  in production code you would want to use the Tcl
120       filesystem interfaces.  See GetFile(3) and friends  for  more  informa‐
121       tion.
122
123       All  arguments  from  a Tcl call to a Tcl C extension are passed as Tcl
124       Objects.  If your C routine wants to look at one of those arguments  as
125       an integer, you need to make a call to a routine to fetch the represen‐
126       tation of the object that  you  need.   In  the  earlier  example,  for
127       instance,  Tcl_GetStringFromObj is called to obtain a textual represen‐
128       tation of an object.  Additional routines are available  to  fetch  the
129       representation  of a data element as other data types.  Tcl_GetBoolean‐
130       FromObj, Tcl_GetDoubleFromObj,  Tcl_GetIntFromObj,  Tcl_GetLongFromObj,
131       and Tcl_GetIndexFromObj, fetch object representations of Tcl strings as
132       booleans, double-precision floating point, integer, long  integer,  and
133       lists, among others.
134
135       These  routines automatically leave an appropriate error message in the
136       Tcl interpreter's result object and return TCL_ERROR  if  a  conversion
137       error occurs.   (For more information on these routines, please look at
138       the Object(3) manpage in the core Tcl distribution.)
139

RETURNING RESULTS

141       As you might expect, the API for setting results from C extensions  has
142       changed  significantly  under  the object system.  The old technique of
143       writing small results directory into the interpreter's result buffer is
144       no  longer used, for example.  The notion of having to tell Tcl whether
145       a result is static or dynamic is also a thing of the past.   Under  the
146       object  system,  results  are objects that are set up by your code, and
147       objects are freed when their reference counts say they should be.  More
148       on this later.
149
150       If  you  program  produces  a  numeric result, it should set the result
151       object to contain that numeric value.  A common way of  doing  this  is
152       something like...
153
154               Tcl_Obj *obj;
155
156               obj = Tcl_GetObjResult (interp);
157            Tcl_SetIntObj (obj, value);
158
159       The  above  code obtains a pointer to the result object (an object made
160       available to your routine that you're supposed to  store  your  results
161       into) and sets the integer value value into it.
162
163       Another  way to do it would be to set up a new object and tell Tcl that
164       this object contains the result...
165
166               Tcl_Obj *resultObj;
167
168               /* create a new object for use as a result */
169            resultObj = Tcl_NewObj ();
170
171            Tcl_SetIntObj (obj, value);
172            Tcl_SetObjResult (interp, resultObj);
173
174       Understanding how results are passed back to Tcl is essential to the  C
175       extension  writer.  Please study the SetObjResult(3) manual page in the
176       Tcl distribution for more information.
177

VALIDATING ARGUMENTS

179       It is a design goal of Tcl that no Tcl program be able to cause Tcl  to
180       dump  core.   It is important that the extension writers, likewise, use
181       the avaiable methods and tools to make sure that  their  extensions  do
182       not  allow  unchecked input, for example, to cause the code to get some
183       kind of runtime exception.
184
185       The object system has simplified, to some degree, the task of  validat‐
186       ing  arguments,  in  that the object system automatically attempts type
187       conversions as needed, and will return an error when a type  conversion
188       fails.
189
190       A simple, but important, check that every C extension should do is ver‐
191       ify that it has the right number of arguments.
192
193       The act of trying to use, say, a string as an integer, implicitly  per‐
194       forms  the  type conversion of the string and, if it doesn't work as an
195       integer,  returns  TCL_ERROR.   The  developer  should  check  for  the
196       TCL_ERROR  return  from  all  of the GetXxxFromObj commands, and handle
197       them as appropriate.  Usually this will mean propagating the  error  on
198       back to the user, or to an intevening catch, as the case may be.
199
200       You  should  also check that values are in range (when their ranges are
201       known), and so forth.  When C data structures need to be handled in Tcl
202       in  some  form  or  another,  yet  the contents of the data must remain
203       opaque to Tcl, as is  usually  the  case  with  binary  data  (although
204       futures  releases of Tcl are expected to have native abilities to read,
205       write and manipulate binary data instrinsically), handles  need  to  be
206       used.   Handles will be described and examples presented, later in this
207       doc.
208

ANOTHER C EXTENSION - THE MAX COMMAND

210       In the command below, two or more arguments are compared, and  the  one
211       with  the  maximum value is returned, if all goes well.  It is an error
212       if there are fewer than two arguments (the pointer to the ``max''  com‐
213       mand text itself, objv[0], and a pointer to at least one object to com‐
214       pare the values of).
215
216           int
217           Tcl_MaxCmd (clientData, interp, objc, objv)
218               char         *clientData;
219               Tcl_Interp   *interp;
220               int           objc;
221               Tcl_Obj     **objv;
222           {
223               int maxVal = MININT;
224               int value, idx;
225
226
227               if (objc < 3)
228                return TclX_WrongArgs (interp, objv[0],
229                                          " num1 num2 [..numN]");
230
231               for (idx = 1; idx < objc; idx++) {
232                   if (Tcl_GetIntFromObj (interp, objv[idx], &value) != TCL_OK)
233                       return TCL_ERROR;
234
235                   if (value > maxVal) {
236                       maxVal = value;
237                   }
238               }
239            Tcl_SetIntObj (Tcl_GetObjResult (interp), value);
240               return TCL_OK;
241           }
242
243       Here we introduce the  Extended  Tcl  helper  function  TclX_WrongArgs.
244       This  routine makes it easy to create an error message and error return
245       in response to the common mistake of being called with a wrong number.
246
247       Tcl_GetIntFromObj is used to fetch the integer values of the  remaining
248       arguments.   If any fail to be converted, we return a Tcl error.  If an
249       interpreter is specified in the call to Tcl_GetIntFromObj, an appropri‐
250       ate  error  message  about  the  conversion failure will be left in the
251       result, so we do that here.
252
253       After examining all of the arguments to find the largest value, we  set
254       the result object to contain that value, and return TCL_OK.
255

RETURNING RESULTS

257       When  Tcl-callable  functions  complete,  they  should  normally return
258       TCL_OK or TCL_ERROR.  TCL_OK is returned when  the  command  succeeded,
259       and  TCL_ERROR is returned when the command has failed in some abnormal
260       way.  TCL_ERROR should be returned for all syntax  errors,  non-numeric
261       values  when  numeric  ones were expected, and so forth.  Less clear in
262       some cases is whether Tcl errors should be returned or whether a  func‐
263       tion  should just return a status value.  For example, end-of-file dur‐
264       ing a gets returns a status, but open returns an  error  if  it  fails.
265       Errors  can  be caught from Tcl programs using the catch command.  (See
266       Tcl's catch(n) and error(n) manual pages.)
267
268       Less common return values are TCL_RETURN, TCL_BREAK  and  TCL_CONTINUE.
269       These  are used if you are adding new control and/or looping structures
270       to Tcl.  To see these values in action,  examine  the  source  code  to
271       Extended Tcl's loop commands.  Tcl's while, for and if commands used to
272       work in the just same manner, but are now compiled into bytecode by the
273       bytecode for performance.
274

ANOTHER C EXTENSION - THE LREVERSE COMMAND

276       In  the command below, a list is passed as an argument, and a list con‐
277       taining all of the elements of the list in reverse order  is  returned.
278       It  is  an  error  if anything other than two arguments are passed (the
279       pointer to the ``lreverse'' command text itself, objv[0], and a pointer
280       to the list to reverse.
281
282       Once lreverse has determined that it has received the correct number of
283       arguments, Tcl_ListObjGetElements is called to split the list into  its
284       own  objc  count  of  elements and objv array of pointers to the list's
285       elements.
286
287       lreverse then operates on the array of  pointers,  swapping  them  from
288       lowest to highest, second-lowest to second-highest, and so forth.
289
290       Tcl_ListObjAppendElement is called on successive list elements to build
291       up the new list, which is finally returned as result of the command.
292
293       int
294       Tcl_LreverseObjCmd(notUsed, interp, objc, objv)
295           ClientData    notUsed;         /* Not used. */
296           Tcl_Interp   *interp;          /* Current interpreter. */
297           int           objc;            /* Number of arguments. */
298           Tcl_Obj     **obj;             /* Argument strings. */
299       {
300           int listObjc, lowListIndex, hiListIndex;
301           Tcl_Obj **listObjv;
302           char *temp, *resultList;
303           Tcl_Obj **newListObjv;
304
305           /* Verify argument count.  Since we take only one argument, argument
306            * count must be 2 (command plus one argument).
307            */
308           if (objc != 2)
309            return TclX_WrongArgs (interp, objv [0], "list");
310
311           /* Create an object to handle the new list we're creating */
312           newListObjv = Tcl_NewObj();
313
314           /* Crack the list at objv[1] into its own count and array of object
315            * pointers.
316            */
317           if (Tcl_ListObjGetElements (interp, objv[1], &listObjc, &listObjv) != TCL_OK) {
318            return TCL_ERROR;
319           }
320
321           /* For each element in the source list from last to first, append an
322            * element to the new list.
323            */
324           for (listIndex = listObjc - 1; listIndex >= 0; listIndex--) {
325            Tcl_ListObjAppendElement (interp, newListObjv, listObjv[listIndex]);
326           }
327       FIX: NEED TO RETURN THE LIST.
328           return TCL_OK;
329       }
330

INSTALLING YOUR COMMAND

332       To install your command into Tcl you  must  call  Tcl_CreateObjCommand,
333       passing  it the pointer to the interpreter you want to install the com‐
334       mand into, the name of the command, a pointer to the  C  function  that
335       implements  the  command,  a  client  data pointer, and a pointer to an
336       optional callback routine.
337
338       The client data pointer and the  callback  routine  will  be  described
339       later.
340
341       For  example,  for  the  max function above (which, incidentally, comes
342       from TclX's tclXmath.c in the TclX7.4/src directory):
343
344           Tcl_CreateCommand (interp, "max", Tcl_MaxCmd, (ClientData)NULL,
345                             (void (*)())NULL);
346
347       In the above example, the max function is added to the specified inter‐
348       preter.   The  client  data  pointer  and callback function pointer are
349       NULL.  (For complete information on Tcl_CreateCommand and its companion
350       routine, Tcl_CommandInfo, please examine the CrtCommand(3) command page
351       in the core Tcl distribution.)
352

DYNAMIC STRINGS

354       Dynamic strings are an important abstraction that first  became  avail‐
355       able  with  Tcl  7.0.   Dynamic  strings, or DStrings, provide a way to
356       build up arbitrarily long strings through a repeated process of append‐
357       ing  information to them.  DStrings reduce the amount of allocating and
358       copying required to add information to a string.   Further,  they  sim‐
359       plify the process of doing so.
360
361       At  first  glance,  it  may  seem  that  the  object  system supersedes
362       DStrings.  It does not, in that the performance improvements made  pos‐
363       sible  by  the  lazy  conversion of an object's representation from one
364       datatype to another does not come into  play  much  while  constructing
365       strings as the string representation is always available either without
366       any type conversion or where type conversion would be necessary in  any
367       case  as a string representation of the object is required when strings
368       are being constructed by concatenation, etc.
369
370       It should be noted, however, that the C level string manipulation capa‐
371       bilites of objects, such as Tcl_AppendToObj and Tcl_AppendStringsToObj,
372       are often plenty enough for what you need to do.  For complete informa‐
373       tion  on  dynamic strings, please examine the DString(3) manual page in
374       the core Tcl distribution.  For more on  Tcl  object's  string-oriented
375       calls, seek Tcl_StringObj(3) in the same location.
376

CLIENT DATA

378       The  client data pointer provides a means for Tcl commands to have data
379       associated with them that is not global to the C program  nor  included
380       in the Tcl core.  Client data is essential in a multi-interpreter envi‐
381       ronment (where a single program has created and is making use of multi‐
382       ple Tcl interpreters) for the C routines to maintain any permanent data
383       they need on a per-interpreter basis.  If needed static data was simply
384       declared  static  in C, you will probably have reentrancy problems when
385       you work with multiple interpreters.
386
387       Tcl solves this through the client data mechanism.  When you are  about
388       to call Tcl_CreateObjCommand to add a new command to an interpreter, if
389       your command needs to keep some read/write data across invocations, you
390       should  allocate  the space, preferably using Tcl_Alloc instead of mal‐
391       loc, then pass the address of that space as the ClientData  pointer  to
392       Tcl_CreateObjCommand.
393
394       When your command is called from Tcl, the ClientData pointer you passed
395       to Tcl_CreateObjCommand will be passed to your C  routine  through  the
396       ClientData pointer calling argument.
397
398       Commands  that  need  to  share this data with one another can do so by
399       using the same ClientData pointer when the commands are added.
400
401       It is important to note that the Tcl extensions in the tclX8.0.0 direc‐
402       tory have had all of their data set up in this way.  Since release 6.2,
403       Extended Tcl has supported multiple interpreters within one  invocation
404       of Tcl.
405

THEORY OF HANDLES

407       Sometimes  you  need  to  have a data element that isn't readily repre‐
408       sentable as a string within Tcl, for example a pointer to a  complex  C
409       data  structure.   It is not a good idea to try to pass pointers around
410       within Tcl as strings by converting them to and  from  hex  or  integer
411       representations,  for  example.  It is too easy to mess one up, and the
412       likely outcome of doing that is a core dump.
413
414       Instead we have developed and made use of the concept of handles.  Han‐
415       dles are identifiers a C extension can pass to, and accept from, Tcl to
416       make the transition between what your C code  knows  something  as  and
417       what  name Tcl knows it by to be as safe and painless as possible.  For
418       example, the I/O system included in Tcl uses file  handles.   When  you
419       open a file from Tcl, a handle is returned of the form filen where n is
420       a file number.  When you pass the file handle back to puts, gets, seek,
421       flush  and  so forth, they validate the file handle by checking the the
422       file text is present, then converting the file  number  to  an  integer
423       that  they  use  to  look into a data structure of pointers to Tcl open
424       file structures, which contain a Unix file descriptor, flags indicating
425       whether  or  not the file is currently open, whether the file is a file
426       or a pipe and so forth.
427
428       Handles have proven so useful that, since TclX  release  6.1a,  general
429       support has been available to help create and manipulate them.  Many of
430       these capabilities have migrated into baseline Tcl.  If you have a sim‐
431       ilar need, you might like to use the handle routines documented in Han‐
432       dles(3) in Extended Tcl.  We recommend that you use  a  unique-to-your-
433       package  textual  handle coupled with a specific identifier and let the
434       handle management routines validate it when it's passed  back.   It  is
435       much  easier  to track down a bug with an implicated handle named some‐
436       thing like file4 or bitmap6 than just 6.
437
438       Note that Tcl's object offers another way for complex  data  structures
439       to exist in parallel with and underneath Tcl strings.  As of this writ‐
440       ing (May 30, 1997) this is fairly new territory, but things are looking
441       good  for  the prospects of using the Tcl object system in this manner,
442       and for enhancements to the object system that allow even  Tcl  objects
443       to have methods in a very straightforward and simple way.
444

USING COMMANDS TO DO THE SAME THING, AND MORE

446       Another  handle-like  technique,  first  popularized in the Tk toolkit,
447       offers handle-like capabilities as well as some neat  additional  capa‐
448       bilities.   That  is  to  create  a  new Tcl command, from C, that uses
449       ClientData to keep a "handle" on its complex underlying data structure.
450       Then  by having that command look at its second argument for what it is
451       to do (its sub-functions), you get these nice methods, where  you  have
452       several additional sub-commands that don't pollute the global namespace
453       and only work on (and are available with) the  objects  (new  commands)
454       they  are  relevant  to.   For  example,  in Tk, creating a checkbutton
455       (checkbutton .b) creates a new Tcl command (.b), that  has  methods  to
456       configure the button, select, deselect, toggle and flash it.
457
458       A  lot  of  people  think this is really the way to go, and I am pretty
459       much leaning that way myself.  If you use  the  incr  tcl  script-level
460       object  system  for  Tcl, objects that you define in Tcl will be highly
461       compatible in terms of their command interfaces and configuration  man‐
462       agement  with objects you create in C using the the command-and-Client‐
463       Data technique described here.  I believe Tk has some  nice  facilities
464       for making this easy for the Tcl programmer.  Itcl certainly does.
465

TRACKING MEMORY CORRUPTION PROBLEMS

467       Occasionally you may write code that scribbles past the end of an allo‐
468       cated piece of memory.  This will usually result in a core dump or mem‐
469       ory allocation failure sometime later in the program, often implicating
470       code that is not actually responsible for the  problem  (as  you  start
471       looking  from  the  point where the error is detected, which is usually
472       where the later routine has failed).
473
474       The memory debugging routines included in Tcl can help find these prob‐
475       lems.   Developed  by  Mark and Karl, the memory debugging routines are
476       now part of baseline Tcl, and is to our knowledge the largest piece  of
477       TclX to drop into the core without being reengineered first.  (You see,
478       summer back in '91, John was sitting in his office in the  CS  building
479       at  UC  Berkeley trying to find a memory leak somewhere in Tcl, when he
480       was paid a visit  by  two  long-haired-yet-polite  programmers  bearing
481       gifts in the form of the technology grab-bag known as Extended Tcl.  He
482       saw that, using TclX's malloc routines, Tcl could be prompted to  print
483       the filename and line number of every single memory allocation that did
484       not have a corresponding free.  It was just what the doctor ordered ;-)
485       See Memory(TCL) for details.
486

INSTALLING YOUR EXTENSIONS INTO TCL

488       To  add  your  extensions  to  Tcl, you used to have to statically link
489       them, together with any other extensions, into  a  single  binary  exe‐
490       cutable  image.   Today,  although  the statically linked executable is
491       still an option, most operating systems, even Microsoft  Windows,  sup‐
492       port shared libraries, and in most cases, Tcl can now make use of those
493       shared libraries such that you extensions, and most others, can now  be
494       built  a shared libraries that can be loaded in (using package require)
495       by scripts that need them.  Shared libraries can simplify a Tcl instal‐
496       lation,  because  only one copy of Tcl is required, rather than a hode‐
497       podge of combinations of applications that you might have  found  at  a
498       big Tcl site in the previous era.
499

GNU AUTOCONF

501       While  the  build  procedure for shared libraries varies from system to
502       system, most Unix and  Unix  workalike  systems  will  figure  out  the
503       nuances  of  the  compiler  and linker arguments automatically when the
504       configure script is run.  If you are building a package that  you  plan
505       to  make  generally  available,  we strongly recommend that you use GNU
506       autoconf (ftp://prep.ai.mit.edu/pub/gnu) to set up an automatic config‐
507       ure  script for it.  Be forewarned that autoconf uses some pretty heavy
508       duty shell and sed script magic to get the job done, and  the  learning
509       curve  can  be  pretty  steep.   Once done and shaken out, though, it's
510       rewarding to know that your package can build  and  run  on  everything
511       from a notebook to a Cray to a RISC SMP server.
512
513       Application-specific startup is accomplished by creating or editing the
514       Tcl_AppInit function.  In Tcl_AppInit you  should  add  a  call  to  an
515       application-specific  init  function  which  you create.  This function
516       should take the address of the interpreter it should install  its  com‐
517       mands into, and it should install those commands with Tcl_CreateCommand
518       and do any other application-specific startup that is necessary.
519
520       The naming convention for application  startup  routines  is  App_Init,
521       where  App  is  the  name  of your application.  For example, to add an
522       application named cute  one  would  create  a  Cute_Init  routine  that
523       expected  a  Tcl_Interp  pointer  as an argument, and add the following
524       code to Tcl_AppInit:
525
526           if (Cute_Init (interp) == TCL_ERROR) {
527            return TCL_ERROR;
528           }
529
530       As you can guess from the above example, if your init routine is unable
531       to  initialize,  it should use Tcl_AppendResult to provide some kind of
532       useful error message back to TclX, then return  TCL_ERROR  to  indicate
533       that  an  error  occurred.   If  the  routine executed successfully, it
534       should return TCL_OK.
535
536       When you examine Tcl_AppInit, note that there is one call already there
537       to  install  an  application -- the call to TclX_Init installs Extended
538       Tcl into the Tcl core.
539
540

MAKING APPLICATION INFORMATION VISIBLE FROM EXTENDED TCL

542       TclX's infox command can return several pieces of information  relevant
543       to  Extended  Tcl,  including the application's name, descriptive name,
544       patch level and version.  Your  application's  startup  can  set  these
545       variables  to  application-specific  values.   If  it doesn't, they are
546       given default values for Extended Tcl.
547
548       To set these values, first be sure that you include either  tclExtend.h
549       or  tclExtdInt.h  from  the source file that defines your init routine.
550       This will create external declarations for the  variables.   Then,  set
551       the variables in your init route, for example:
552
553           tclAppName = "cute";
554           tclAppLongName = "Call Unix/Tcl Environment";
555           tclAppVersion = "2.1";
556
557       Note  that  the  default values are set by TclX_Init, so if you wish to
558       override them, you must call your init routine in Tcl_AppInit after its
559       call to TclX_Init.
560

EXTENDED TCL EXIT

562       When  Extended Tcl exits, Tcl_DeleteInterp may be called to free memory
563       used by Tcl -- normally, this  is  only  called  if  TCL_MEM_DEBUG  was
564       defined, since Unix will return all of the allocated memory back to the
565       system, anyway.  If TCL_MEM_DEBUG was defined, it is called so that any
566       memory  that  was  allocated  without ever being freed can be detected.
567       This greatly reduces the amount of work to detect and track down memory
568       leaks,  a  situation  where  some  piece  of your code allocates memory
569       repeatedly without ever freeing it, or at least without always  freeing
570       it.
571
572       It  is  often  necessary  for an application to perform special cleanup
573       functions upon the deletion of an interpreter as well.   To  facilitate
574       this  activity, Tcl provides the ability to perform a function callback
575       when an interpreter is deleted.  To arrange for  a  C  function  to  be
576       called  when  the interpreter is deleted, call Tcl_CallWhenDeleted from
577       your application initialization routine.  For details  on  how  to  use
578       this  function,  read  the  CallDel(3) manual page that ships with core
579       Tcl.
580

EXECUTING TCL CODE FROM YOUR C EXTENSION

582       Suppose you are in the middle of coding a C extension and  you  realize
583       that  you  need some operation performed, one that would be simple from
584       Tcl, but possibly excruciating to do directly in  C.   Tcl  provides  a
585       number  of C-level interfaces whereby you can cause Tcl code to be exe‐
586       cuteed.  The old-style calls are  Tcl_Eval,  Tcl_VarEval,  Tcl_EvalFile
587       and  Tcl_GlobalEval.   The results of these calls can be dug out of the
588       interpreter using Tcl_GetStringResult, if you want a string representa‐
589       tion  of  the result, or Tcl_GetObjResult if you want the object.  (The
590       use of interp->result to access the result string has been deprecated.)
591
592       The Tcl object system adds Tcl_EvalObj and Tcl_GlobalEvalObj.  The dif‐
593       ference  here  is  that we are evaluating an object, not just a string,
594       and using these routines in preference to the aforementioned  ones  can
595       result  in  a major performance improvement in your code, when the code
596       is executed repeatedly (even if it only executes once but loops several
597       times  within itself), as these routines make it possible for the byte‐
598       code compiler to compile the code being evaluated and save the compiled
599       code with the data structure, in an implementation-dependent manner.
600
601       For  more  information please consult the EvalObj(3) and Eval(3) manual
602       pages within the Tcl distribution.
603

ACCESSING TCL VARIABLES AND ARRAYS FROM YOUR C EXTENSIONS

605       In addition to the non-object-system ways of reading from  and  storing
606       to  Tcl  variables, using routines such as Tcl_SetVar2 and Tcl_GetVar2,
607       Tcl variables and arrays can be read from a C extension as Tcl  objects
608       by using the Tcl_ObjGetVar2 function, and set from C extensions through
609       the Tcl_ObjSetVar2 function.
610
611       Please note that the object versions do not carry forward analogues  to
612       the  one-variable-name-argument  Tcl_GetVar, Tcl_SetVar, and Tcl_Unset‐
613       Var.  If you know you have a scalar, call the object variable  get  and
614       set functions with a NULL second argument.  If your variable name might
615       contain an array reference via a self-contained  embedded  array  index
616       (i.e.,  I'm  asking  Tcl_ObjGetVar2 for "foo(5)" instead of "foo" "5"),
617       add the TCL_PARSE_PART1 to the flags in your call.
618
619       While the fact that Tcl_ObjGetVar2 retrieves Tcl objects,  rather  than
620       strings,  is  critical  for the object system to be able to provide the
621       performance boosts from "lazy" type  conversion  and  the  binary  data
622       capabilities,  the arguments containing the variable name, or the array
623       name and element name if they've been split out, also must be specified
624       as  Tcl objects rather than strings.  While this is useful on occasion,
625       those writing C extensions for Tcl in the post-object-system  era  usu‐
626       ally  have the names available as plain old char * variables, requiring
627       conversion of the strings to objects before use and account  for  their
628       possible destruction afterwards.
629
630       To  simplify  the  task  in those cases, TclX adds the TclX_ObjGetVar2S
631       subroutine.  It works just like Tcl_ObjGetVar2, except the one  or  two
632       variable name arguments are specified as strings, and the routine takes
633       care of making and disposing of object equivalents.
634
635       Tcl variables can be unset from C via the Tcl_UnsetVar  and  Tcl_Unset‐
636       Var2  functions.   There  are  currently  (as  of 8.0) no object-system
637       equivalents, so in the rare case where you have the name of  the  vari‐
638       able  you  want  unset  as  an object instead of a string, you can call
639       Tcl_GetStringFromObj to obtain the string representation first.
640
641       For complete information  on  these  functions,  please  refer  to  the
642       ObjSetVar(3)  and  SetVar(3)  manual  pages in the doc directory of the
643       core Tcl distribution.
644

LINKING TCL VARIABLES TO C VARIABLES

646       Tcl_LinkVar and Tcl_UnlinkVar can be used  to  automatically  keep  Tcl
647       variables  synchronized  with  corresponding  C  variables.  Once a Tcl
648       variable has been linked to a C variable with Tcl_LinkVar, anytime  the
649       Tcl variable is read, the value of the C variable is converted (if nec‐
650       essary) and returned, and when the Tcl variable is written, the C vari‐
651       able will be updated with the new value.
652
653       Tcl_LinkVar uses variable traces to keep the Tcl variable named by var‐
654       Name in sync with the C variable at the address given by addr.
655
656       Int, double, boolean and char * variables are supported.  You can  make
657       your  linked  variables  read  only from the Tcl side, as well.  Please
658       note that the C variables must continually exist while they are linked,
659       in  other  words, linking "automatic" C variables, those created on the
660       stack while a routine is being executed and destroyed afterwards,  will
661       result  in  a  malfunctioning program at best and a coredump or more at
662       worst.
663
664       For more information, please examine the LinkVar(3) manual page in  the
665       core Tcl distribution.
666

ADDING NEW MATH FUNCTIONS TO TCL

668       As  of  Tcl  version  7.0,  math  functions  such as sin, cos, etc, are
669       directly supported within Tcl expressions.  These obsolete the Extended
670       Tcl  commands  that  provided explicit commands for these functions for
671       many, many releases, although procs equivalencing the old TclX commands
672       to  the new math functions are still provided for backwards compatibil‐
673       ity.
674
675       New math functions can be added to Tcl, or existing math functions  can
676       be replaced, by calling Tcl_CreateMathFunc.
677

ACCESSING AND MANIPULATING THE RANDOM NUMBER GENERATOR

679       Prior to Tcl version 8.0, the Tcl core did not provide access to a ran‐
680       dom number generator, but TclX did, through its random command.  As  of
681       Tcl  version  8.0,  access  to a random number generator is provided by
682       baseline Tcl through the new math functions, rand and srand.
683
684       The TclX random command is still available -- it has some useful  capa‐
685       bilities not directly provided by the new baseline functions.
686
687       For  more  information on adding your own math functions to Tcl, please
688       study the CrtMathFnc(3) manual page in the core Tcl distribution.
689

CONVERTING FILENAMES TO NATIVE FORM AND PERFORMING TILDE SUBSTITUTIONS

691       The Tcl_TranslateFileName function is available to C extension  writers
692       to  translate filenames to a form suitable for use by the local operat‐
693       ing system.  It converts network names to their native form, and if the
694       name  starts  with a ``~'' character, the function returns a new string
695       where the name is replaced with the home directory of the given user.
696
697       For more information please consult the Translate(3) manual page in the
698       core Tcl distribution.
699

SETTING THE RECURSION LIMIT

701       Tcl  has  a  preset  recursion  limit that limits the maximum allowable
702       nesting depth of calls within  an  interpreter.   This  is  useful  for
703       detecting  infinite  recursions before other limits such as the process
704       memory limit or, worse, available swap space on the system, run out.
705
706       The default limit is just a guess, however, and applications that  make
707       heavy  use of recursion may need to call Tcl_SetRecursionLimit to raise
708       this limit.  For more information, please consult the SetRecLmt(3) man‐
709       ual page in the core Tcl distribution.
710

HANDLING SIGNALS FROM TCL EXTENSIONS

712       If  an  event  such as a signal occurs while a Tcl script is being exe‐
713       cuted, it isn't safe to do much in the signal handling routine  --  the
714       Tcl  environment  cannot be safely manipulated at this point because it
715       could be in the middle of some operation, such  as  updating  pointers,
716       leaving the interpreter in an unreliable state.
717
718       The  only  safe  approach  is  to  set a flag indicating that the event
719       occurred, then handle the event later when the interpreter has returned
720       to a safe state, such as after the current Tcl command completes.
721
722       The     Tcl_AsyncCreate,     Tcl_AsyncMark,     Tcl_AsyncInvoke,    and
723       Tcl_AsyncDelete functions provide a safe  mechanism  for  dealing  with
724       signals  and other asynchronous events.  For more information on how to
725       use this capability, please refer to the Async(3) manual  page  in  the
726       core Tcl distribution.
727
728       Note  that  Extended Tcl provides built-in support for managing signals
729       in numerous ways, including generating them with alarm(2) and  kill(2),
730       ignoring them, trapping them, getting, setting, blocking and unblocking
731       them.  You can cause specific code to execute at a safe point  after  a
732       signal occurs, or cause a Tcl error backtrace on one's occurrence.  For
733       more information, please examine the TclX documentation.
734
735

PARSING BACKSLASH SEQUENCES

737       The Tcl_Backslash function is called to parse Tcl backslash  sequences.
738       These backslash sequences are the usual sort that you see in the C pro‐
739       gramming language, such as \n for newline, \r for return, and so forth.
740       Tcl_Backslash  parses  a single backslash sequence and returns a single
741       character corresponding to the backslash sequence.
742
743       For more info on this call, look at the Backslash(3) manual page in the
744       core   Tcl  distribution.   For  information  on  the  valid  backslash
745       sequences, consult the summary of Tcl language syntax,  Tcl(n)  in  the
746       same distribution.
747

HASH TABLES

749       Hash tables provide Tcl with a high-performance facility for looking up
750       and managing key-value pairs located and  maintained  in  memory.   Tcl
751       uses  hash tables internally to locate procedure definitions, Tcl vari‐
752       ables, array elements, file handles and so forth.  Tcl makes  the  hash
753       table functions accessible to C extension writers as well.
754
755       Hash  tables  grow  automatically  to  maintain efficiency, rather than
756       exposing the table size to the programmer  at  allocation  time,  which
757       would  needlessly  add  complexity to Tcl and would be prone to ineffi‐
758       ciency due to the need to guess the number of items that will  go  into
759       the  table,  and the seemingly inevitable growth in amount of data pro‐
760       cessed per run over the useful life of the program.
761
762       For more information on hash tables, please consult the Hash(3)  manual
763       page in the core Tcl distribution.
764

TRACING VARIABLE ACCESSES

766       The  C extension writer can arrange to have a C routine called whenever
767       a Tcl variable is read, written, or unset.   Variable  traces  are  the
768       mechanism  by  which Tk toolkit widgets such as radio and checkbuttons,
769       messages and so forth update without Tcl programmer  intervention  when
770       their  data  variables  are changed.  They are also used by the routine
771       that links Tcl and C variables, Tcl_LinkVar, described above.
772
773       Tcl_TraceVar is called to establish a variable  trace.   Entire  arrays
774       and individual array elements can be traced as well.  If the programmer
775       already has an array name in one string and a variable name in another,
776       Tcl_TraceVar2  can  be  called.   Calls  are  also available to request
777       information about traces and to delete them.
778
779       For more information on variable traces, consult the TraceVar(3) manual
780       page in the core Tcl distribution.
781

TRACING TCL EXECUTION

783       Tcl has the ability to call C routines each time it executes a Tcl com‐
784       mand, up to a specified depth of nesting levels.  The command  Tcl_Cre‐
785       ateTrace creates an execution trace; Tcl_DeleteTrace deletes it.
786
787       Command  tracing  is used in Extended Tcl to implement the cmdtrace Tcl
788       command, a useful command for debugging Tcl applications.
789
790       For complete information on execution tracing, please look at the  Crt‐
791       Trace(3) manual pages in the core Tcl distribution.
792

EVALUATING TCL EXPRESSIONS FROM C

794       Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBool, and Tcl_ExprString all take
795       string arguments and,  when  called,  evaluate  those  strings  as  Tcl
796       expressions.  Depending on the routine called, the result is either a C
797       long, a double, a boolean (int with a value of 0 or 1),  or  a  char  *
798       (obtainable through Tcl_GetResult).
799
800       To  take advantage of the performance gains available through the byte‐
801       code compiler, Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBoolObj, and
802       Tcl_ExprObj all take an object containing an expression to be evaluated
803       (rather than a string.)  The result is that  bytecode-compiled  version
804       of the expression will be kept in the object, alongside the string rep‐
805       resentation.  If the  expression  is  evaluated  again,  without  being
806       changed, it does not have to be recompiled... a major performance win.
807
808       For  complete information on evaluating Tcl expressions from C, you are
809       invited to examine the ExprLong(3) and ExprLongObj(3) manpages  in  the
810       core Tcl distribution.
811

PATTERN MATCHING

813       The Tcl_StringMatch function can be called to see if a string matches a
814       specified pattern.  Tcl_StringMatch is called by the Tcl  string  match
815       command,  so  the format for patterns is identical.  The pattern format
816       is similar to the one used by the  C-shell;  string(n)  describes  this
817       format.
818
819       More  information about Tcl_StringMatch is available in the StrMatch(3)
820       manpage in the core Tcl distribution.
821

REGULAR EXPRESSION PATTERN MATCHING

823       Tcl_RegExpMatch can be called to determine whether a string  matches  a
824       regular  expression.   Tcl_RegExpMatch is used internally by the regexp
825       Tcl command.
826
827       As regular expressions are typically "compiled" before  use,  a  fairly
828       involved process, Tcl also supports routines that separate the compila‐
829       tion of an expression from its use:  Tcl_RegExpCompile, Tcl_RegExpExec,
830       and  Tcl_RegExpRange.   If  an  expression  is going to be matched many
831       times, doing the compile once and caching the compiled regular  expres‐
832       sion  result,  then reusing the cached version by using Tcl_RegExpExec,
833       can be a significant performance win.
834
835       For more information on this function,  please  consult  the  RegExp(3)
836       manpage in the core Tcl distribution.
837

MANIPULATING TCL LISTS FROM C EXTENSIONS

839       The  C extension writer often needs to create, manipulate and decompose
840       Tcl lists.  Tcl_SplitList and Tcl_Merge used to  be  the  only  way  to
841       parse  strings  into  lists  and vice versa.  As of Tcl 8, lists can be
842       parsed and assembled, object-style,  using  Tcl_ListObjGetElements  and
843       Tcl_SetListObj, and friends.  Once again the "win" of using object-sys‐
844       tem-based list manipulation, instead of the previous string based  rou‐
845       tines, is that the parsing of a string in an object to a list is cached
846       in the object structure, the same as with integers and  floating  point
847       numbers,  compiled procedures, etc.  The next time this string needs to
848       be looked at as a list, if the contents of the string have not changed,
849       the string does not have to be parsed.
850
851       In  the author's experience, working with an admittedly degenerate test
852       whereby we iterated rather inefficiently across a 6,000-element list, a
853       speedup  factor  of  more than 2500 was obtained over the previous non-
854       object-based version of Tcl.
855
856       For more information on these commands, please consult  the  ListObj(3)
857       manual page in the core Tcl distribution.
858

CONCATENATING STRINGS

860       Tcl_ConcatObj  concatenates  the  string representation of zero or more
861       objects into a single new object.  The elements of the new  string  are
862       space-separated.   Tcl_Concat  does  the  same  thing  for  strings, as
863       Tcl_ConcatObj does for objects.
864
865       Concatenating strings is  similar  to  constructing  lists  from  them,
866       except  that  Tcl_ConcatObj  and  Tcl_Concat do not attempt to make the
867       resulting string into a valid Tcl list.
868
869       Tcl_Concat is documented in the Concat(3) manpage, and Tcl_ConcatObj in
870       the tringObj manpage, both in the core Tcl distribution.
871

DETECTING WHETHER OR NOT YOU HAVE A COMPLETE COMMAND

873       C routines that collect data to form a command to be passed to Tcl_Eval
874       often need a way to tell whether they have a complete  command  already
875       or whether they need more data.  (Programs that read typed-in Tcl input
876       such as Tcl shells need this capability, for  instance.)   Tcl_Command‐
877       Complete  can  be  used to tell whether or not you have a complete com‐
878       mand.
879
880       For more information examine CmdCmplt(3) in the core Tcl distribution.
881

RECORDING COMMANDS FOR COMMAND HISTORY

883       Tcl has a history mechanism that is accessed from Tcl through the  his‐
884       tory  command.   If  you want your extension to propagate commands into
885       the command history, you should call Tcl_RecordAndEvalObj (object  sys‐
886       tem) or Tcl_RecordAndEval (old system),
887
888       These commands work like Tcl_EvalObj and Tcl_Eval, respectively, except
889       that these versions record the command as well as executing it.
890
891       Tcl_RecordAndEval and Tcl_RecordAndEvlObj should only  be  called  with
892       user-entered  top-level commands, since the history mechanism exists to
893       allow the user to easily access, edit  and  reissue  previously  issued
894       commands.
895
896       For  complete  information  on  these  functions,  please  examine  the
897       RecordEval.3 and RecEvalObj.3 manual pages in the  core  Tcl  distribu‐
898       tion.
899

CONVERTING FLOATING POINT VALUES TO STRINGS

901       The  Tcl  object system's Tcl_GetDoubleFromObj and Tcl_SetDoubleObj use
902       Tcl objects, rather than the strings used by Tcl_PrintDouble, and  con‐
903       vert, when necessary, an ASCII string to a double and back again.
904
905       These routines ensure that the string output will continue to be inter‐
906       pretable as a floating point number, rather than an integer, by  always
907       putting a ``.'' or ``e'' into the string representing the number.
908
909       The  precision of the output string is controlled by the Tcl tcl_preci‐
910       sion variable.
911
912       For complete information on these routines, please examine DoubleObj(3)
913       and PrintDbl(3) in the core Tcl distribution.
914

CREATING CHILD PROCESSES AND PIPELINES FROM C

916       Tcl_OpenCommandChannel  provides  a  C-level  interface to the exec and
917       open commands.  The child (or pipeline of children) can have its  stan‐
918       dard input, output and error redirected from files, variables or pipes.
919       To understand the meaning of the redirection symbols understood by this
920       function, look at the exec(n) Tcl command.  For complete information on
921       Tcl_OpenCommandChannel, please examine OpenFileChnl(3).
922

ACCESSING TCL FILEHANDLES FROM C

924       On Posix/Unix systems, Tcl filehandles passed to your C  extension  can
925       be  translated  to  a  Posix FILE * structure using the Tcl_GetOpenFile
926       function, documented in GetOpnFl.3.
927

MANAGING BACKGROUND PROCESS TERMINATION AND CLEANUP

929       When a Posix system does a fork to create a new process, the process ID
930       of the child is returned to the caller.  After the child process exits,
931       its process table entry  (and  some  other  data  associated  with  the
932       process)  cannot  be  reclaimed by the operating system until a call to
933       waitpid, or one of a couple of other, similar system  calls,  has  been
934       made by the parent process.
935
936       The C extension writer who has created a subprocess, by whatever mecha‐
937       nism, can turn over responsibility for detecting the processes'  termi‐
938       nation  and  calling  waitpid  to  obtain  its  exit status, by calling
939       Tcl_DetachPids on it.
940
941       Tcl_ReapDetachedProcs is the C routine that will detect the termination
942       of  any  processes  turned  over to Tcl, permitting the processes to be
943       fully reclaimed by the operating system.  It is usually  not  necessary
944       to call Tcl_ReapDetachedProcs, as it is called automatically every time
945       exec is performed.
946
947       For complete information on these  routines,  please  look  at  Detach‐
948       Pids(3) in the core Tcl distribution.
949

FOR MORE INFORMATION

951       In  addition to the documentation referenced above, you can learn a lot
952       by studying the source code of  the  commands  added  by  Tcl,  Tk  and
953       Extended  Tcl, etc.  The comp.lang.tcl Usenet newsgroup is read by hun‐
954       dreds of thousands of Tcl people.  A number of Frequently  Asked  Ques‐
955       tions (FAQs) about Tcl are posted there periodically.  The newsgroup is
956       a good place to ask questions  (after  you've  made  sure  they're  not
957       already answered in the FAQ ;-)
958
959       Finally,  if  you  have  interactive  Internet  access,  you can ftp to
960       ftp://ftp.neosoft.com/pub/tcl, the site for  contributed  Tcl  sources.
961       This  site contains quite a few extensions, applications, and so forth,
962       including several object-oriented extension packages.
963
964       If you have access via the world-wide web, check out the Sun  Microsys‐
965       tems  site  (http://sunscript.sun.com), the contributed sources archive
966       website (http://www.neosoft.com/tcl), and the homepage for Extended Tcl
967       (http://www.neosoft.com/tclx).
968

AUTHORS

970       Extended Tcl was created by Karl Lehenbauer (karl@neosoft.com) and Mark
971       Diekhans (markd@grizzly.com).
972
973Tcl                                                       Command Writing(TCL)
Impressum