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. C programming information can also be found in the
13 *.3 manual pages in the doc directory of the Berkeley distribution, and
14 in the *.3 manpages in the man directory of Extended Tcl.
15
17 All C-based Tcl commands are called with four arguments: a client data
18 pointer, an interpreter pointer, an argument count and a pointer to an
19 array of pointers to character strings containing the Tcl arguments to
20 the command.
21 A simple Tcl extension in C is now presented, and described below:
23 #include "tcl.h"
25 int App_EchoCmd(clientData, interp, argc, argv)
27 void *clientData;
28 Tcl_Interp *interp;
29 int argc;
30 char **argv;
31 {
32 int i;
33 for (i = 1; i < argc; i++) {
35 printf("%s",argv[i]);
36 if (i < argc - 1) printf(" ");
37 }
38 printf("\n");
39 return TCL_OK;
40 }
41 The client data pointer will be described later.
43 The interpreter pointer is the ``key'' to an interpreter. It is
45 returned by Tcl_CreateInterp and is used extensively within Tcl, and
46 will be by your C extensions. The data structure pointed to by the
47 interpreter pointer, and all of the subordinate structures that branch
48 off of it, make up a Tcl interpreter, which includes all of the cur‐
49 rently defined procedures, commands, variables, arrays and the execu‐
50 tion state of that interpreter. (For more information on creating and
51 deleting interpreters, please examine the CrtInterp(3) manpage in the
52 Berkeley Tcl distribution. For information on creating interpreters
53 that include the commands provided by Extended Tcl, check out the
54 TclX_Init(3) manpage of Extended Tcl. For a manual page describing the
55 user-visible fields of a Tcl interpreter, please look at Interp(3) in
56 Berkeley Tcl.)
57 The argument count and pointer to an array of pointers to textual argu‐
59 ments is handled by your C code in the same manner that you would use
60 in writing a C main function -- the argument count and array of point‐
61 ers works the same as in a C main call; pointers to the arguments to
62 the function are contained in the argv array. Similar to a C main, the
63 first argument (argv[0]) is the name the routine was called as (in a
64 main, the name the program was invoked as).
65 In the above example, all of the arguments are output with a space
67 between each one by looping through argv from one to the argument
68 count, argc, and a newline is output to terminate the line -- an
69 ``echo'' command.
70 All arguments from a Tcl call to a Tcl C extension are passed as
72 strings. If your C routine expects certain numeric arguments, your
73 routine must first convert them using the Tcl_GetInt or Tcl_GetDouble
74 function, Extended Tcl's Tcl_GetLong or Tcl_GetUnsigned, or some other
75 method of your own devising. Likewise for converting boolean values,
76 Tcl_GetBoolean should be used. These routines automatically leave an
77 appropriate error message in the Tcl interpreter's result buffer and
78 return TCL_ERROR if a conversion error occurs. (For more information
79 on these routines, please look at the GetInt(3) manpage in the Berkeley
80 Tcl distribution.)
81 Likewise, if you program produces a numeric result, it should return a
83 string equivalent to that numeric value. A common way of doing this is
84 something like...
85 sprintf(interp->result, "%ld", result);
87 Writing results directly into the interpreter's result buffer is only
89 good for relatively short results. Tcl has a function, Tcl_SetResult,
90 which provides the ability for your C extensions to return very large
91 strings to Tcl, with the ability to tell the interpreter whether it
92 ``owns'' the string (meaning that Tcl should delete the string when
93 it's done with it), that the string is likely to be changed or over‐
94 written soon (meaning that Tcl should make a copy of the string right
95 away), or that the string won't change (so Tcl can use the string as is
96 and not worry about it). Understanding how results are passed back to
97 Tcl is essential to the C extension writer. Please study the SetRe‐
98 sult(3) manual page in the Tcl distribution.
99 Sophisticated commands should verify their arguments whenever possible,
101 both by examining the argument count, by verifying that numeric fields
102 are really numeric, that values are in range (when their ranges are
103 known), and so forth.
104 Tcl is designed to be as bullet-proof as possible, in the sense that no
106 Tcl program should be able to cause Tcl to dump core. Please carry
107 this notion forward with your C extensions by validating arguments as
108 above.
109
111 In the command below, two or more arguments are compared and the one
112 with the maximum value is returned, if all goes well. It is an error
113 if there are fewer than three arguments (the pointer to the ``max''
114 command text itself, argv[0], and pointers to at least two arguments to
115 compare the values of).
116 This routine also shows the use of the programmer labor-saving
118 Tcl_AppendResult routine. See the Tcl manual page, SetResult(3), for
119 details. Also examine the calls Tcl_AddErrorInfo, Tcl_SetErrorCode and
120 Tcl_PosixError documented in the Tcl manual page AddErrInfo(3).
121 int
123 Tcl_MaxCmd (clientData, interp, argc, argv)
124 char *clientData;
125 Tcl_Interp *interp;
126 int argc;
127 char **argv;
128 {
129 int maxVal = MININT;
130 int maxIdx = 1;
131 int value, idx;
132 if (argc < 3) {
135 Tcl_AppendResult (interp, "bad # arg: ", argv[0],
136 " num1 num2 [..numN]", (char *)NULL);
137 return TCL_ERROR;
138 }
139 for (idx = 1; idx < argc; idx++) {
141 if (Tcl_GetInt (argv[idx], 10, &Value) != TCL_OK)
142 return TCL_ERROR;
143 if (value > maxVal) {
145 maxVal = value;
146 maxIdx = idx;
147 }
148 }
149 Tcl_SetResult (interp, argv [maxIdx], TCL_VOLATILE);
150 return TCL_OK;
151 }
152 When Tcl-callable functions complete, they should normally return
154 TCL_OK or TCL_ERROR. TCL_OK is returned when the command succeeded and
155 TCL_ERROR is returned when the command has failed in some abnormal way.
156 TCL_ERROR should be returned for all syntax errors, non-numeric values
157 (when numeric ones were expected), and so forth. Less clear in some
158 cases is whether Tcl errors should be returned or whether a function
159 should just return a status value. For example, end-of-file during a
160 gets returns a status, but open returns an error if the open fails.
161 Errors can be caught from Tcl programs using the catch command. (See
162 Tcl's catch(n) and error(n) manual pages.)
163 Less common return values are TCL_RETURN, TCL_BREAK and TCL_CONTINUE.
165 These are used if you are adding new control and/or looping structures
166 to Tcl. To see these values in action, examine the source code to
167 Tcl's while, for and if, and Extended Tcl's loop commands.
168 Note the call to Tcl_SetResult in the above command to set the return
170 value to Tcl. TCL_VOLATILE is used because the memory containing the
171 result will be freed upon the function's return.
172
175 In the command below, one list is passed as an argument, and a list
176 containing all of the elements of the list in reverse order is
177 returned. It is an error if anything other than two arguments are
178 passed (the pointer to the ``lreverse'' command text itself, argv[0],
179 and a pointer to the list to reverse.
180 Once lreverse has determined that it has received the correct number of
182 arguments, Tcl_SplitList is called to break the list into an argc and
183 argv array of pointers.
184 lreverse then operates on the array of pointers, swapping them from
186 lowest to highest, second-lowest to second-highest, and so forth.
187 Finally Tcl_Merge is calleds to create a single new string containing
189 the reversed list and it is set as the result via Tcl_SetResult. Note
190 that TCL_DYNAMIC is used to tell Tcl_SetResult that it now owns the
191 string and it is up to Tcl to free the string when it is done with it.
192 Note that it is safe to play around with the argv list like this, and
194 that a single call to ckfree can be made to free all the data returned
195 by Tcl_SplitList in this manner.
196 int
198 Tcl_LreverseCmd(notUsed, interp, argc, argv)
199 ClientData notUsed; /* Not used. */
200 Tcl_Interp *interp; /* Current interpreter. */
201 int argc; /* Number of arguments. */
202 char **argv; /* Argument strings. */
203 {
204 int listArgc, lowListIndex, hiListIndex;
205 char **listArgv;
206 char *temp, *resultList;
207 if (argc != 2) {
209 Tcl_AppendResult(interp, "wrong # args: should be
210 " list
211 return TCL_ERROR;
212 }
213 if (Tcl_SplitList(interp, argv[1], &listArgc, &listArgv) != TCL_OK) {
215 return TCL_ERROR;
216 }
217 for (lowListIndex = 0, hiListIndex = listArgc;
218 --hiListIndex > lowListIndex; lowListIndex++) {
219 temp = listArgv[lowListIndex];
220 listArgv[lowListIndex] = listArgv[hiListIndex];
221 listArgv[hiListIndex] = temp;
222 }
223 resultList = Tcl_Merge (listArgc, listArgv);
224 ckfree (listArgv);
225 Tcl_SetResult (interp, resultList, TCL_DYNAMIC);
226 return TCL_OK;
227 }
228
230 To install your command into Tcl you must call Tcl_CreateCommand, pass‐
231 ing it the pointer to the interpreter you want to install the command
232 into, the name of the command, a pointer to the C function that imple‐
233 ments the command, a client data pointer, and a pointer to an optional
234 callback routine.
235 The client data pointer and the callback routine will be described
237 later.
238 For example, for the max function above (which, incidentally, comes
240 from TclX's tclXmath.c in the TclX7.4/src directory):
241 Tcl_CreateCommand (interp, "max", Tcl_MaxCmd, (ClientData)NULL,
243 (void (*)())NULL);
244 In the above example, the max function is added to the specified inter‐
246 preter. The client data pointer and callback function pointer are
247 NULL. (For complete information on Tcl_CreateCommand and its companion
248 routine, Tcl_CommandInfo, please examine the CrtCommand(3) command page
249 in the Berkeley Tcl distribution.)
250
252 Dynamic strings are an important abstraction that first became avail‐
253 able with Tcl 7.0. Dynamic strings, or DStrings, provide a way to
254 build up arbitrarily long strings through a repeated process of append‐
255 ing information to them. DStrings reduce the amount of allocating and
256 copying required to add information to a string. Further, they sim‐
257 plify the process of doing so. For complete information on dynamic
258 strings, please examine the DString(3) manual page in the Berkeley Tcl
259 distribution.
260
262 The client data pointer provides a means for Tcl commands to have data
263 associated with them that is not global to the C program nor included
264 in the Tcl core. Client data is essential in a multi-interpreter envi‐
265 ronment (where a single program has created and is making use of multi‐
266 ple Tcl interpreters) for the C routines to maintain any permanent data
267 they need on a per-interpreter basis. Otherwise there would be reen‐
268 trancy problems. Tcl solves this through the client data mechanism.
269 When you are about to call Tcl_CreateCommand to add a new command to an
270 interpreter, if that command needs to keep some read/write data across
271 invocations, you should allocate the space, preferably using ckalloc,
272 then pass the address of that space as the ClientData pointer to
273 Tcl_CreateCommand.
274 When your command is called from Tcl, the ClientData pointer you gave
276 to Tcl_CreateCommand when you added the command to that interpreter is
277 passed to your C routine through the ClientData pointer calling argu‐
278 ment.
279 Commands that need to share this data with one another can do so by
281 using the same ClientData pointer when the commands are added.
282 It is important to note that the Tcl extensions in the tclX7.4/src
284 directory have had all of their data set up in this way. Since release
285 6.2, Extended Tcl has supported multiple interpreters within one invo‐
286 cation of Tcl.
287
289 Sometimes you need to have a data element that isn't readily repre‐
290 sentable as a string within Tcl, for example a pointer to a complex C
291 data structure. It is not a good idea to try to pass pointers around
292 within Tcl as strings by converting them to and from hex or integer
293 representations, for example. It is too easy to mess one up, and the
294 likely outcome of doing that is a core dump.
295 Instead we have developed and made use of the concept of handles. Han‐
297 dles are identifiers a C extension can pass to, and accept from, Tcl to
298 make the transition between what your C code knows something as and
299 what name Tcl knows it by to be as safe and painless as possible. For
300 example, the stdio package included in Tcl uses file handles. When you
301 open a file from Tcl, a handle is returned of the form filen where n is
302 a file number. When you pass the file handle back to puts, gets, seek,
303 flush and so forth, they validate the file handle by checking the the
304 file text is present, then converting the file number to an integer
305 that they use to look into a data structure of pointers to Tcl open
306 file structures, which contain a Unix file descriptor, flags indicating
307 whether or not the file is currently open, whether the file is a file
308 or a pipe and so forth.
309 Handles have proven so useful that, as of release 6.1a, general support
311 has been added for them. If you need a similar capability, it would be
312 best to use the handle routines, documented in Handles(3) in Extended
313 Tcl. We recommend that you use a unique-to-your-package textual handle
314 coupled with a specific identifier and let the handle management rou‐
315 tines validate it when it's passed back. It is much easier to track
316 down a bug with an implicated handle named something like file4 or bit‐
317 map6 than just 6.
318
320 Occasionally you may write code that scribbles past the end of an allo‐
321 cated piece of memory. The memory debugging routines included in Tcl
322 can help find these problems. See Memory(TCL) for details.
323
325 To add your extensions to Extended Tcl, you must compile them and cause
326 them to be linked with TclX. For the routines to be linked into the
327 tcl and wishx executables, they must be referenced (directly or indi‐
328 rectly) from TclX. For these extensions to be visible as Tcl commands,
329 they must be installed into Tcl with Tcl_CreateCommand.
330 Application-specific startup is accomplished by creating or editing the
332 Tcl_AppInit function. In Tcl_AppInit you should add a call to an
333 application-specific init function which you create. This function
334 should take the address of the interpreter it should install its com‐
335 mands into, and it should install those commands with Tcl_CreateCommand
336 and do any other application-specific startup that is necessary.
337 The naming convention for application startup routines is App_Init,
339 where App is the name of your application. For example, to add an
340 application named cute one would create a Cute_Init routine that
341 expected a Tcl_Interp pointer as an argument, and add the following
342 code to Tcl_AppInit:
343 if (Cute_Init (interp) == TCL_ERROR) {
345 return TCL_ERROR;
346 }
347 As you can guess from the above example, if your init routine is unable
349 to initialize, it should use Tcl_AppendResult to provide some kind of
350 useful error message back to TclX, then return TCL_ERROR to indicate
351 that an error occurred. If the routine executed successfully, it
352 should return TCL_OK.
353 When you examine Tcl_AppInit, note that there is one call already there
355 to install an application -- the call to TclX_Init installs Extended
356 Tcl into the Tcl core.
357
360 TclX's infox command can return several pieces of information relevant
361 to Extended Tcl, including the application's name, descriptive name,
362 patch level and version. Your application's startup can set these
363 variables to application-specific values. If it doesn't, they are
364 given default values for Extended Tcl.
365 To set these values, first be sure that you include either tclExtend.h
367 or tclExtdInt.h from the source file that defines your init routine.
368 This will create external declarations for the variables. Then, set
369 the variables in your init route, for example:
370 tclAppName = "cute";
372 tclAppLongName = "Call Unix/Tcl Environment";
373 tclAppVersion = "2.1";
374 Note that the default values are set by TclX_Init, so if you wish to
376 override them, you must call your init routine in Tcl_AppInit after its
377 call to TclX_Init.
378
380 When Extended Tcl exits, Tcl_DeleteInterp may be called to free memory
381 used by Tcl -- normally, this is only called if TCL_MEM_DEBUG was
382 defined, since Unix will return all of the allocated memory back to the
383 system, anyway. If TCL_MEM_DEBUG was defined, it is called so that any
384 memory that was allocated without ever being freed can be detected.
385 This greatly reduces the amount of work to detect and track down memory
386 leaks, a situation where some piece of your code allocates memory
387 repeatedly without ever freeing it, or without always freeing it.
388 It is often necessary for an application to perform special cleanup
390 functions upon the deletion of an interpreter as well. To facilitate
391 this activity, Tcl provides the ability to perform a function callback
392 when an interpreter is deleted. To arrange for a C function to be
393 called when the interpreter is deleted, call Tcl_CallWhenDeleted from
394 your application initialization routine. For details on how to use
395 this function, read the CallDel(3) manual page that ships with Berkeley
396 Tcl.
397
399 Suppose you are in the middle of coding a C extension and you realize
400 that you need some operation performed, one that would be simple from
401 Tcl but possibly excruciating to do directly in C. Tcl provides the
402 Tcl_Eval, Tcl_VarEval, Tcl_EvalFile and Tcl_GlobalEval functions for
403 the purpose of executing Tcl code from within a C extension. The
404 results of the call will be in interp->result. For more information
405 please consult the Eval(3) manual page within the Tcl distribution.
406
408 Tcl variables and arrays can be read from a C extension through the
409 Tcl_GetVar and Tcl_GetVar2 functions, and set from C extensions through
410 the Tcl_SetVar and Tcl_SetVar2 functions. They can also be unset via
411 the Tcl_UnsetVar and Tcl_UnsetVar2 functions. For complete information
412 on these functions, please refer to the SetVar(3) manual page in the
413 doc directory of the Berkeley Tcl distribution.
414
416 Tcl_LinkVar and Tcl_UnlinkVar can be used to automatically keep Tcl
417 variables synchronized with corresponding C variables. Once a Tcl
418 variable has been linked to a C variable with Tcl_LinkVar, anytime the
419 Tcl variable is read the value of the C variable will be returned, and
420 when the Tcl variable is written, the C variable will be updated with
421 the new value.
422 Tcl_LinkVar uses variable traces to keep the Tcl variable named by var‐
424 Name in sync with the C variable at the address given by addr.
425 Whenever the Tcl variable is read the value of the C variable will be
427 returned, and whenever the Tcl variable is written the C variable will
428 be updated to have the same value.
429 Int, double, boolean and char * variables are supported. For more
431 information, please examine the LinkVar(3) manual page in the Berkeley
432 Tcl distribution.
433
435 As of Tcl version 7.0, math functions such as sin, cos, etc, are
436 directly supported within Tcl expressions. These obsolete the Extended
437 Tcl commands that provided explicit calls for these functions for many
438 releases.
439 New math functions can be added to Tcl, or existing math functions can
441 be replaced, by calling Tcl_CreateMathFunc.
442 For more information on adding math functions, please examine the Crt‐
444 MathFnc(3) manual page in the Berkeley Tcl distribution.
445
447 The Tcl_TildeSubst function is available to C extension writers to per‐
448 form tilde substitutions on filenames. If the name starts with a ``~''
449 character, the function returns a new string where the name is replaced
450 with the home directory of the given user. For more information please
451 consult the TildeSubst(3) manual page in the Berkeley Tcl distribution.
452
454 Tcl has a preset recursion limit that limits the maximum allowable
455 nesting depth of calls within an interpreter. This is useful for
456 detecting infinite recursions before other limits such as the process
457 memory limit or, worse, available swap space on the system, are
458 exceeded.
459 The default limit is just a guess, however, and applications that make
461 heavy use of recursion may need to call Tcl_SetRecursionLimit to raise
462 this limit. For more information, please consult the SetRecLmt(3) man‐
463 ual page in the Berkeley Tcl distribution.
464
466 If an event such as a signal occurs while a Tcl script is being exe‐
467 cuted, it isn't safe to do much in the signal handling routine -- the
468 Tcl environment cannot be safely manipulated at this point because it
469 could be in the middle of some operation, such as updating pointers,
470 leaving the interpreter in an unreliable state.
471 The only safe approach is to set a flag indicating that the event
473 occurred, then handle the event later when the interpreter has returned
474 to a safe state, such as after the current Tcl command completes.
475 The Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, and
477 Tcl_AsyncDelete functions provide a safe mechanism for dealing with
478 signals and other asynchronous events. For more information on how to
479 use this capability, please refer to the Async(3) manual page in the
480 Berkeley Tcl distribution.
481
484 The Tcl_Backslash function is called to parse Tcl backslash sequences.
485 These backslash sequences are the usual sort that you see in the C pro‐
486 gramming language, such as \n for newline, \r for return, and so forth.
487 Tcl_Backslash parses a single backslash sequence and returns a single
488 character corresponding to the backslash sequence.
489 For more info on this call, look at the Backslash(3) manual page in the
491 Berkeley Tcl distribution. For information on the valid backslash
492 sequences, consult the summary of Tcl language syntax, Tcl(n) in the
493 same distribution.
494
496 Hash tables provide Tcl with a high-performance facility for looking up
497 and managing key-value pairs located and maintained in memory. Tcl
498 uses hash tables internally to locate procedure definitions, Tcl vari‐
499 ables, array elements, file handles and so forth. Tcl makes the hash
500 table functions accessible to C extension writers as well.
501 Hash tables grow automatically to maintain efficiency, rather than
503 exposing the table size to the programmer at allocation time, which
504 would needlessly add complexity to Tcl and would be prone to ineffi‐
505 ciency due to the need to guess the number of items that will go into
506 the table, and the seemingly inevitable growth in amount of data pro‐
507 cessed per run over the life of the program.
508 For more information on hash tables, please consult the Hash(3) manual
510 page in the Berkeley Tcl distribution.
511
513 The C extension writer can arrange to have a C routine called whenever
514 a Tcl variable is read, written, or unset. Variable traces are the
515 mechanism by which Tk toolkit widgets such as radio and checkbuttons,
516 messages and so forth update without Tcl programmer intervention when
517 their data variables are changed. They are also used by the routine
518 that links Tcl and C variables, Tcl_LinkVar, described above.
519 Tcl_TraceVar is called to establish a variable trace. Entire arrays
521 and individual array elements can be traced as well. If the programmer
522 already has an array name in one string and a variable name in another,
523 Tcl_TraceVar2 can be called. Calls are also available to request
524 information about traces and to delete them.
525 For more information on variable traces, consult the TraceVar(3) manual
527 page in the Berkeley Tcl distribution.
528
530 Tcl has the ability to call C routines for every command it executes,
531 up to a specified depth of nesting levels. The command Tcl_CreateTrace
532 creates an execution trace; Tcl_DeleteTrace deletes it.
533 Command tracing is used in Extended Tcl to implement the cmdtrace Tcl
535 command, a useful command for debugging Tcl applications.
536 For complete information on execution tracing, please look at the Crt‐
538 Trace(3) manual pages in the Berkeley Tcl distribution.
539
541 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBool, and Tcl_ExprString can be
542 called to evaluate Tcl expressions from within a C routine. Depending
543 on the routine called, the result is either a C long, a double, a bool‐
544 ean (int with a value of 0 or 1), or a char * (pointed to by
545 interp->result).
546 For complete information on evaluating Tcl expressions from C, you are
548 invited to examine the ExprLong(3) manpage in the Berkeley Tcl distri‐
549 bution.
550
552 The Tcl_StringMatch function can be called to see if a string matches a
553 specified pattern. Tcl_StringMatch is called by the Tcl string match
554 command, so the format for patterns is identical. The pattern format
555 is similar to the one used by the C-shell; string(n) describes this
556 format.
557 More information about Tcl_StringMatch is available in the StrMatch(3)
559 manpage in the Berkeley Tcl distribution.
560
562 Tcl_RegExpMatch can be called to determine whether a string matches a
563 regular expression. Tcl_RegExpMatch is used internally by the regexp
564 Tcl command.
565 For more information on this function, please consult the RegExp(3)
567 manpage in the Berkeley Tcl distribution.
568
570 The C extension writer often needs to create, manipulate and decompose
571 Tcl lists. Tcl_SplitList parses a list into an argv and argc like to
572 the way command-line arguments are passed to a Tcl extension.
573 Tcl_Merge, likewise, creates a single string (pointer to a char *) from
574 an argv and argc.
575 Two routines, Tcl_ScanElement and Tcl_ConvertElement, do most of the
577 work of Tcl_Merge, and may also be of use to the C programmer.
578 For more information on these commands, please consult the SplitList(3)
580 manual page in the Berkeley Tcl distribution.
581
583 Tcl_Concat concatenates zero or more strings into a single string. The
584 strings are space-separated. Tcl_Concat works like Tcl_Merge, except
585 that Tcl_Concat does not attempt to make the resulting string into a
586 valid Tcl list.
587 Tcl_Concat is documented in the Concat(3) manpage in the Berkeley Tcl
589 distribution.
590
592 C routines that collect data to form a command to be passed to Tcl_Eval
593 often need a way to tell whether they have a complete command already
594 or whether they need more data. (Programs that read typed-in Tcl input
595 such as Tcl shells need this capability.) Tcl_CommandComplete can be
596 used to tell whether or not you have a complete command.
597 For more information examine CmdCmplt(3) in the Berkeley Tcl distribu‐
599 tion.
600
602 Tcl has a history mechanism that is accessed from Tcl through the his‐
603 tory command. To propagate commands into the command history, your
604 extension should call Tcl_RecordAndEval. This command works just like
605 Tcl_Eval, except that it records the command as well as executing it.
606 Tcl_RecordAndEval should only be called with user-entered top-level
608 commands, since the history mechanism exists to allow the user to eas‐
609 ily access, edit and reissue previously issued commands.
610 For complete information on this function, please examine the RecordE‐
612 val.3 manual page in the Berkeley Tcl distribution.
613
615 Tcl_PrintDouble converts a C double into an ASCII string. It ensures
616 that the string output will continue to be interpreted as a floating
617 point number, rather than an integer, by always putting a ``.'' or
618 ``e'' into the string representing the number. The precision of the
619 output string is controlled by the Tcl tcl_precision variable.
620 For complete information on Tcl_PrintDouble, examine PrintDbl(3) in the
622 Berkeley Tcl distribution.
623
625 Tcl_CreatePipeline is a useful procedure for spawning child processes.
626 The child (or pipeline of children) can have its standard input, output
627 and error redirected from files, variables or pipes. To understand the
628 meaning of the redirection symbols understood by this function, look at
629 the exec(n) Tcl command. For complete information on Tcl_Cre‐
630 atePipeline, please examine CrtPipelin(3).
631
633 Files opened from your C code can be made visible to Tcl code via the
634 Tcl_EnterFile function. Likewise, Tcl filehandles passed to your C
635 extension can be translated to a Posix FILE * structure using the
636 Tcl_GetOpenFile function.
637 For complete explanations of these commands, please look at Enter‐
639 File(3) in the Berkeley Tcl distribution.
640
643 When a Posix system does a fork to create a new process, the process ID
644 of the child is returned to the caller. After the child process exits,
645 its process table entry (and some other data associated with the
646 process) cannot be reclaimed by the operating system until a call to
647 waitpid, or one of a couple of other, similar system calls, has been
648 made by the parent process.
649 The C extension writer who has created a subprocess, by whatever mecha‐
651 nism, can turn over responsibility for detecting the processes' termi‐
652 nation and calling waitpid to obtain its exit status by calling
653 Tcl_DetachPids.
654 Tcl_ReapDetachedProcs is the C routine that will detect the termination
656 of any processes turned over to Tcl, permitting the processes to be
657 fully reclaimed by the operating system.
658 For complete information on these routines, please look at Detach‐
660 Pids(3) in the Berkeley Tcl distribution.
661
663 In addition to the documentation referenced above, you can learn a lot
664 by studying the source code of the commands added by Tcl, Tk and
665 Extended Tcl. The comp.lang.tcl Usenet newsgroup is read by tens of
666 thousands of Tcl people, and is a good place to ask questions.
667 Finally, if you have interactive Internet access, you can ftp to
668 ftp.aud.alcatel.com, the site for contributed Tcl sources. This site
669 contains quite a few extensions, applications, and so forth, including
670 several object-oriented extension packages.
671
673 Extended Tcl was created by Karl Lehenbauer (karl@neosoft.com) and Mark
674 Diekhans (markd@grizzly.com).
675Tcl Command Writing(TCL)