1Command Writing(TCL) Command Writing(TCL)
2
6 TclCommandWriting - Writing C language extensions to Tcl.
7
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 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
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 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 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
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 A simple C extension to Tcl is now presented, and described below:
63 #include "tcl.h"
65 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 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 The client data pointer will be described later.
86
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
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 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 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 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 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
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 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 Tcl_Obj *obj;
155 obj = Tcl_GetObjResult (interp);
157 Tcl_SetIntObj (obj, value);
158 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 Another way to do it would be to set up a new object and tell Tcl that
164 this object contains the result...
165 Tcl_Obj *resultObj;
167 /* create a new object for use as a result */
169 resultObj = Tcl_NewObj ();
170 Tcl_SetIntObj (obj, value);
172 Tcl_SetObjResult (interp, resultObj);
173 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
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 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 A simple, but important, check that every C extension should do is ver‐
191 ify that it has the right number of arguments.
192 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 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
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 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 if (objc < 3)
228 return TclX_WrongArgs (interp, objv[0],
229 " num1 num2 [..numN]");
230 for (idx = 1; idx < objc; idx++) {
232 if (Tcl_GetIntFromObj (interp, objv[idx], &value) != TCL_OK)
233 return TCL_ERROR;
234 if (value > maxVal) {
236 maxVal = value;
237 }
238 }
239 Tcl_SetIntObj (Tcl_GetObjResult (interp), value);
240 return TCL_OK;
241 }
242 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 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 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
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 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
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 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 lreverse then operates on the array of pointers, swapping them from
288 lowest to highest, second-lowest to second-highest, and so forth.
289 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 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 /* 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 /* Create an object to handle the new list we're creating */
312 newListObjv = Tcl_NewObj();
313 /* 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 /* 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
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 The client data pointer and the callback routine will be described
339 later.
340 For example, for the max function above (which, incidentally, comes
342 from TclX's tclXmath.c in the TclX7.4/src directory):
343 Tcl_CreateCommand (interp, "max", Tcl_MaxCmd, (ClientData)NULL,
345 (void (*)())NULL);
346 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
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 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 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
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 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 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 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 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
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 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 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 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
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 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
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 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
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
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 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 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 if (Cute_Init (interp) == TCL_ERROR) {
527 return TCL_ERROR;
528 }
529 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 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
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 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 tclAppName = "cute";
554 tclAppLongName = "Call Unix/Tcl Environment";
555 tclAppVersion = "2.1";
556 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
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 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
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 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 For more information please consult the EvalObj(3) and Eval(3) manual
602 pages within the Tcl distribution.
603
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 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 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 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 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 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
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 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 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 For more information, please examine the LinkVar(3) manual page in the
665 core Tcl distribution.
666
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 New math functions can be added to Tcl, or existing math functions can
676 be replaced, by calling Tcl_CreateMathFunc.
677
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 The TclX random command is still available -- it has some useful capa‐
685 bilities not directly provided by the new baseline functions.
686 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
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 For more information please consult the Translate(3) manual page in the
698 core Tcl distribution.
699
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 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
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 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 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 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
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 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
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 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 For more information on hash tables, please consult the Hash(3) manual
763 page in the core Tcl distribution.
764
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 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 For more information on variable traces, consult the TraceVar(3) manual
780 page in the core Tcl distribution.
781
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 Command tracing is used in Extended Tcl to implement the cmdtrace Tcl
788 command, a useful command for debugging Tcl applications.
789 For complete information on execution tracing, please look at the Crt‐
791 Trace(3) manual pages in the core Tcl distribution.
792
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 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 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
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 More information about Tcl_StringMatch is available in the StrMatch(3)
820 manpage in the core Tcl distribution.
821
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 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 For more information on this function, please consult the RegExp(3)
836 manpage in the core Tcl distribution.
837
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 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 For more information on these commands, please consult the ListObj(3)
857 manual page in the core Tcl distribution.
858
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 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 Tcl_Concat is documented in the Concat(3) manpage, and Tcl_ConcatObj in
870 the tringObj manpage, both in the core Tcl distribution.
871
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 For more information examine CmdCmplt(3) in the core Tcl distribution.
881
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 These commands work like Tcl_EvalObj and Tcl_Eval, respectively, except
889 that these versions record the command as well as executing it.
890 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 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
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 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 The precision of the output string is controlled by the Tcl tcl_preci‐
910 sion variable.
911 For complete information on these routines, please examine DoubleObj(3)
913 and PrintDbl(3) in the core Tcl distribution.
914
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
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
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 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 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 For complete information on these routines, please look at Detach‐
948 Pids(3) in the core Tcl distribution.
949
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 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 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
970 Extended Tcl was created by Karl Lehenbauer (karl@neosoft.com) and Mark
971 Diekhans (markd@grizzly.com).
972Tcl Command Writing(TCL)