codekingpro/portable-devtools
114k
1/*2 * tcl.h --3 *4 * This header file describes the externally-visible facilities of the5 * Tcl interpreter.6 *7 * Copyright (c) 1987-1994 The Regents of the University of California.8 * Copyright (c) 1993-1996 Lucent Technologies.9 * Copyright (c) 1994-1998 Sun Microsystems, Inc.10 * Copyright (c) 1998-2000 by Scriptics Corporation.11 * Copyright (c) 2002 by Kevin B. Kenny. All rights reserved.12 *13 * See the file "license.terms" for information on usage and redistribution of14 * this file, and for a DISCLAIMER OF ALL WARRANTIES.15 */16 17#ifndef _TCL18#define _TCL19 20/*21 * For C++ compilers, use extern "C"22 */23 24#ifdef __cplusplus25extern "C" {26#endif27 28/*29 * The following defines are used to indicate the various release levels.30 */31 32#define TCL_ALPHA_RELEASE 033#define TCL_BETA_RELEASE 134#define TCL_FINAL_RELEASE 235 36/*37 * When version numbers change here, must also go into the following files and38 * update the version numbers:39 *40 * library/init.tcl (1 LOC patch)41 * unix/configure.in (2 LOC Major, 2 LOC minor, 1 LOC patch)42 * win/configure.in (as above)43 * win/tcl.m4 (not patchlevel)44 * README (sections 0 and 2, with and without separator)45 * macosx/Tcl-Common.xcconfig (not patchlevel) 1 LOC46 * win/README (not patchlevel) (sections 0 and 2)47 * unix/tcl.spec (1 LOC patch)48 * tools/tcl.hpj.in (not patchlevel, for windows installer)49 */50 51#define TCL_MAJOR_VERSION 852#define TCL_MINOR_VERSION 653#define TCL_RELEASE_LEVEL TCL_FINAL_RELEASE54#define TCL_RELEASE_SERIAL 1355 56#define TCL_VERSION "8.6"57#define TCL_PATCH_LEVEL "8.6.13"58 59/*60 *----------------------------------------------------------------------------61 * The following definitions set up the proper options for Windows compilers.62 * We use this method because there is no autoconf equivalent.63 */64 65#ifdef _WIN3266# ifndef __WIN32__67# define __WIN32__68# endif69# ifndef WIN3270# define WIN3271# endif72#endif73 74/*75 * Utility macros: STRINGIFY takes an argument and wraps it in "" (double76 * quotation marks), JOIN joins two arguments.77 */78 79#ifndef STRINGIFY80# define STRINGIFY(x) STRINGIFY1(x)81# define STRINGIFY1(x) #x82#endif83#ifndef JOIN84# define JOIN(a,b) JOIN1(a,b)85# define JOIN1(a,b) a##b86#endif87 88/*89 * A special definition used to allow this header file to be included from90 * windows resource files so that they can obtain version information.91 * RC_INVOKED is defined by default by the windows RC tool.92 *93 * Resource compilers don't like all the C stuff, like typedefs and function94 * declarations, that occur below, so block them out.95 */96 97#ifndef RC_INVOKED98 99/*100 * Special macro to define mutexes, that doesn't do anything if we are not101 * using threads.102 */103 104#ifdef TCL_THREADS105#define TCL_DECLARE_MUTEX(name) static Tcl_Mutex name;106#else107#define TCL_DECLARE_MUTEX(name)108#endif109 110/*111 * Tcl's public routine Tcl_FSSeek() uses the values SEEK_SET, SEEK_CUR, and112 * SEEK_END, all #define'd by stdio.h .113 *114 * Also, many extensions need stdio.h, and they've grown accustomed to tcl.h115 * providing it for them rather than #include-ing it themselves as they116 * should, so also for their sake, we keep the #include to be consistent with117 * prior Tcl releases.118 */119 120#include <stdio.h>121 122/*123 *----------------------------------------------------------------------------124 * Support for functions with a variable number of arguments.125 *126 * The following TCL_VARARGS* macros are to support old extensions127 * written for older versions of Tcl where the macros permitted128 * support for the varargs.h system as well as stdarg.h .129 *130 * New code should just directly be written to use stdarg.h conventions.131 */132 133#include <stdarg.h>134#if !defined(TCL_NO_DEPRECATED) && TCL_MAJOR_VERSION < 9135# define TCL_VARARGS(type, name) (type name, ...)136# define TCL_VARARGS_DEF(type, name) (type name, ...)137# define TCL_VARARGS_START(type, name, list) (va_start(list, name), name)138#endif /* !TCL_NO_DEPRECATED */139#if defined(__GNUC__) && (__GNUC__ > 2)140# if defined(_WIN32) && defined(__USE_MINGW_ANSI_STDIO) && __USE_MINGW_ANSI_STDIO141# define TCL_FORMAT_PRINTF(a,b) __attribute__ ((__format__ (__MINGW_PRINTF_FORMAT, a, b)))142# else143# define TCL_FORMAT_PRINTF(a,b) __attribute__ ((__format__ (__printf__, a, b)))144# endif145# define TCL_NORETURN __attribute__ ((noreturn))146# if defined(BUILD_tcl) || defined(BUILD_tk)147# define TCL_NORETURN1 __attribute__ ((noreturn))148# else149# define TCL_NORETURN1 /* nothing */150# endif151#else152# define TCL_FORMAT_PRINTF(a,b)153# if defined(_MSC_VER) && (_MSC_VER >= 1310)154# define TCL_NORETURN _declspec(noreturn)155# else156# define TCL_NORETURN /* nothing */157# endif158# define TCL_NORETURN1 /* nothing */159#endif160 161/*162 * Allow a part of Tcl's API to be explicitly marked as deprecated.163 *164 * Used to make TIP 330/336 generate moans even if people use the165 * compatibility macros. Change your code, guys! We won't support you forever.166 */167 168#if defined(__GNUC__) && ((__GNUC__ >= 4) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 1)))169# if (__GNUC__ > 4) || ((__GNUC__ == 4) && (__GNUC_MINOR__ >= 5))170# define TCL_DEPRECATED_API(msg) __attribute__ ((__deprecated__ (msg)))171# else172# define TCL_DEPRECATED_API(msg) __attribute__ ((__deprecated__))173# endif174#else175# define TCL_DEPRECATED_API(msg) /* nothing portable */176#endif177 178/*179 *----------------------------------------------------------------------------180 * Macros used to declare a function to be exported by a DLL. Used by Windows,181 * maps to no-op declarations on non-Windows systems. The default build on182 * windows is for a DLL, which causes the DLLIMPORT and DLLEXPORT macros to be183 * nonempty. To build a static library, the macro STATIC_BUILD should be184 * defined.185 *186 * Note: when building static but linking dynamically to MSVCRT we must still187 * correctly decorate the C library imported function. Use CRTIMPORT188 * for this purpose. _DLL is defined by the compiler when linking to189 * MSVCRT.190 */191 192#if (defined(_WIN32) && (defined(_MSC_VER) || (defined(__BORLANDC__) && (__BORLANDC__ >= 0x0550)) || defined(__LCC__) || defined(__WATCOMC__) || (defined(__GNUC__) && defined(__declspec))))193# define HAVE_DECLSPEC 1194# ifdef STATIC_BUILD195# define DLLIMPORT196# define DLLEXPORT197# ifdef _DLL198# define CRTIMPORT __declspec(dllimport)199# else200# define CRTIMPORT201# endif202# else203# define DLLIMPORT __declspec(dllimport)204# define DLLEXPORT __declspec(dllexport)205# define CRTIMPORT __declspec(dllimport)206# endif207#else208# define DLLIMPORT209# if defined(__GNUC__) && __GNUC__ > 3210# define DLLEXPORT __attribute__ ((visibility("default")))211# else212# define DLLEXPORT213# endif214# define CRTIMPORT215#endif216 217/*218 * These macros are used to control whether functions are being declared for219 * import or export. If a function is being declared while it is being built220 * to be included in a shared library, then it should have the DLLEXPORT221 * storage class. If is being declared for use by a module that is going to222 * link against the shared library, then it should have the DLLIMPORT storage223 * class. If the symbol is being declared for a static build or for use from a224 * stub library, then the storage class should be empty.225 *226 * The convention is that a macro called BUILD_xxxx, where xxxx is the name of227 * a library we are building, is set on the compile line for sources that are228 * to be placed in the library. When this macro is set, the storage class will229 * be set to DLLEXPORT. At the end of the header file, the storage class will230 * be reset to DLLIMPORT.231 */232 233#undef TCL_STORAGE_CLASS234#ifdef BUILD_tcl235# define TCL_STORAGE_CLASS DLLEXPORT236#else237# ifdef USE_TCL_STUBS238# define TCL_STORAGE_CLASS239# else240# define TCL_STORAGE_CLASS DLLIMPORT241# endif242#endif243 244/*245 * The following _ANSI_ARGS_ macro is to support old extensions246 * written for older versions of Tcl where it permitted support247 * for compilers written in the pre-prototype era of C.248 *249 * New code should use prototypes.250 */251 252#ifndef TCL_NO_DEPRECATED253# undef _ANSI_ARGS_254# define _ANSI_ARGS_(x) x255#endif256 257/*258 * Definitions that allow this header file to be used either with or without259 * ANSI C features.260 */261 262#ifndef INLINE263# define INLINE264#endif265 266#ifdef NO_CONST267# ifndef const268# define const269# endif270#endif271#ifndef CONST272# define CONST const273#endif274 275#ifdef USE_NON_CONST276# ifdef USE_COMPAT_CONST277# error define at most one of USE_NON_CONST and USE_COMPAT_CONST278# endif279# define CONST84280# define CONST84_RETURN281#else282# ifdef USE_COMPAT_CONST283# define CONST84284# define CONST84_RETURN const285# else286# define CONST84 const287# define CONST84_RETURN const288# endif289#endif290 291#ifndef CONST86292# define CONST86 CONST84293#endif294 295/*296 * Make sure EXTERN isn't defined elsewhere.297 */298 299#ifdef EXTERN300# undef EXTERN301#endif /* EXTERN */302 303#ifdef __cplusplus304# define EXTERN extern "C" TCL_STORAGE_CLASS305#else306# define EXTERN extern TCL_STORAGE_CLASS307#endif308 309/*310 *----------------------------------------------------------------------------311 * The following code is copied from winnt.h. If we don't replicate it here,312 * then <windows.h> can't be included after tcl.h, since tcl.h also defines313 * VOID. This block is skipped under Cygwin and Mingw.314 */315 316#if defined(_WIN32) && !defined(HAVE_WINNT_IGNORE_VOID)317#ifndef VOID318#define VOID void319typedef char CHAR;320typedef short SHORT;321typedef long LONG;322#endif323#endif /* _WIN32 && !HAVE_WINNT_IGNORE_VOID */324 325/*326 * Macro to use instead of "void" for arguments that must have type "void *"327 * in ANSI C; maps them to type "char *" in non-ANSI systems.328 */329 330#ifndef __VXWORKS__331# ifndef NO_VOID332# define VOID void333# else334# define VOID char335# endif336#endif337 338/*339 * Miscellaneous declarations.340 */341 342#ifndef _CLIENTDATA343# ifndef NO_VOID344 typedef void *ClientData;345# else346 typedef int *ClientData;347# endif348# define _CLIENTDATA349#endif350 351/*352 * Darwin specific configure overrides (to support fat compiles, where353 * configure runs only once for multiple architectures):354 */355 356#ifdef __APPLE__357# ifdef __LP64__358# undef TCL_WIDE_INT_TYPE359# define TCL_WIDE_INT_IS_LONG 1360# define TCL_CFG_DO64BIT 1361# else /* !__LP64__ */362# define TCL_WIDE_INT_TYPE long long363# undef TCL_WIDE_INT_IS_LONG364# undef TCL_CFG_DO64BIT365# endif /* __LP64__ */366# undef HAVE_STRUCT_STAT64367#endif /* __APPLE__ */368 369/* Cross-compiling 32-bit on a 64-bit platform? Then our370 * configure script does the wrong thing. Correct that here.371 */372#if defined(__GNUC__) && !defined(_WIN32) && !defined(__LP64__)373# undef TCL_WIDE_INT_IS_LONG374# undef TCL_WIDE_INT_TYPE375# define TCL_WIDE_INT_TYPE long long376#endif377 378/*379 * Define Tcl_WideInt to be a type that is (at least) 64-bits wide, and define380 * Tcl_WideUInt to be the unsigned variant of that type (assuming that where381 * we have one, we can have the other.)382 *383 * Also defines the following macros:384 * TCL_WIDE_INT_IS_LONG - if wide ints are really longs (i.e. we're on a385 * LP64 system such as modern Solaris or Linux ... not including Win64)386 * Tcl_WideAsLong - forgetful converter from wideInt to long.387 * Tcl_LongAsWide - sign-extending converter from long to wideInt.388 * Tcl_WideAsDouble - converter from wideInt to double.389 * Tcl_DoubleAsWide - converter from double to wideInt.390 *391 * The following invariant should hold for any long value 'longVal':392 * longVal == Tcl_WideAsLong(Tcl_LongAsWide(longVal))393 *394 * Note on converting between Tcl_WideInt and strings. This implementation (in395 * tclObj.c) depends on the function396 * sprintf(...,"%" TCL_LL_MODIFIER "d",...).397 */398 399#if !defined(TCL_WIDE_INT_TYPE)&&!defined(TCL_WIDE_INT_IS_LONG)400# ifdef _WIN32401# define TCL_WIDE_INT_TYPE __int64402# ifdef __BORLANDC__403# define TCL_LL_MODIFIER "L"404# elif defined(_WIN32) && (!defined(__USE_MINGW_ANSI_STDIO) || !__USE_MINGW_ANSI_STDIO)405# define TCL_LL_MODIFIER "I64"406# else407# define TCL_LL_MODIFIER "ll"408# endif409# elif defined(__GNUC__)410# define TCL_WIDE_INT_TYPE long long411# define TCL_LL_MODIFIER "ll"412# else /* ! _WIN32 && ! __GNUC__ */413/*414 * Don't know what platform it is and configure hasn't discovered what is415 * going on for us. Try to guess...416 */417# include <limits.h>418# if (INT_MAX < LONG_MAX)419# define TCL_WIDE_INT_IS_LONG 1420# else421# define TCL_WIDE_INT_TYPE long long422# endif423# endif /* _WIN32 */424#endif /* !TCL_WIDE_INT_TYPE & !TCL_WIDE_INT_IS_LONG */425#ifdef TCL_WIDE_INT_IS_LONG426# undef TCL_WIDE_INT_TYPE427# define TCL_WIDE_INT_TYPE long428#endif /* TCL_WIDE_INT_IS_LONG */429 430typedef TCL_WIDE_INT_TYPE Tcl_WideInt;431typedef unsigned TCL_WIDE_INT_TYPE Tcl_WideUInt;432 433#ifdef TCL_WIDE_INT_IS_LONG434# define Tcl_WideAsLong(val) ((long)(val))435# define Tcl_LongAsWide(val) ((long)(val))436# define Tcl_WideAsDouble(val) ((double)((long)(val)))437# define Tcl_DoubleAsWide(val) ((long)((double)(val)))438# ifndef TCL_LL_MODIFIER439# define TCL_LL_MODIFIER "l"440# endif /* !TCL_LL_MODIFIER */441#else /* TCL_WIDE_INT_IS_LONG */442/*443 * The next short section of defines are only done when not running on Windows444 * or some other strange platform.445 */446# ifndef TCL_LL_MODIFIER447# define TCL_LL_MODIFIER "ll"448# endif /* !TCL_LL_MODIFIER */449# define Tcl_WideAsLong(val) ((long)((Tcl_WideInt)(val)))450# define Tcl_LongAsWide(val) ((Tcl_WideInt)((long)(val)))451# define Tcl_WideAsDouble(val) ((double)((Tcl_WideInt)(val)))452# define Tcl_DoubleAsWide(val) ((Tcl_WideInt)((double)(val)))453#endif /* TCL_WIDE_INT_IS_LONG */454 455#ifdef _WIN32456# ifdef __BORLANDC__457 typedef struct stati64 Tcl_StatBuf;458# elif defined(_WIN64) || defined(_USE_64BIT_TIME_T)459 typedef struct __stat64 Tcl_StatBuf;460# elif (defined(_MSC_VER) && (_MSC_VER < 1400)) || defined(_USE_32BIT_TIME_T)461 typedef struct _stati64 Tcl_StatBuf;462# else463 typedef struct _stat32i64 Tcl_StatBuf;464# endif /* _MSC_VER < 1400 */465#elif defined(__CYGWIN__)466 typedef struct {467 dev_t st_dev;468 unsigned short st_ino;469 unsigned short st_mode;470 short st_nlink;471 short st_uid;472 short st_gid;473 /* Here is a 2-byte gap */474 dev_t st_rdev;475 /* Here is a 4-byte gap */476 long long st_size;477 struct {long tv_sec;} st_atim;478 struct {long tv_sec;} st_mtim;479 struct {long tv_sec;} st_ctim;480 /* Here is a 4-byte gap */481 } Tcl_StatBuf;482#elif defined(HAVE_STRUCT_STAT64) && !defined(__APPLE__)483 typedef struct stat64 Tcl_StatBuf;484#else485 typedef struct stat Tcl_StatBuf;486#endif487 488/*489 *----------------------------------------------------------------------------490 * Data structures defined opaquely in this module. The definitions below just491 * provide dummy types. A few fields are made visible in Tcl_Interp492 * structures, namely those used for returning a string result from commands.493 * Direct access to the result field is discouraged in Tcl 8.0. The494 * interpreter result is either an object or a string, and the two values are495 * kept consistent unless some C code sets interp->result directly.496 * Programmers should use either the function Tcl_GetObjResult() or497 * Tcl_GetStringResult() to read the interpreter's result. See the SetResult498 * man page for details.499 *500 * Note: any change to the Tcl_Interp definition below must be mirrored in the501 * "real" definition in tclInt.h.502 *503 * Note: Tcl_ObjCmdProc functions do not directly set result and freeProc.504 * Instead, they set a Tcl_Obj member in the "real" structure that can be505 * accessed with Tcl_GetObjResult() and Tcl_SetObjResult().506 */507 508typedef struct Tcl_Interp509#if !defined(TCL_NO_DEPRECATED) && TCL_MAJOR_VERSION < 9510{511 /* TIP #330: Strongly discourage extensions from using the string512 * result. */513#ifdef USE_INTERP_RESULT514 char *result TCL_DEPRECATED_API("use Tcl_GetStringResult/Tcl_SetResult");515 /* If the last command returned a string516 * result, this points to it. */517 void (*freeProc) (char *blockPtr)518 TCL_DEPRECATED_API("use Tcl_GetStringResult/Tcl_SetResult");519 /* Zero means the string result is statically520 * allocated. TCL_DYNAMIC means it was521 * allocated with ckalloc and should be freed522 * with ckfree. Other values give the address523 * of function to invoke to free the result.524 * Tcl_Eval must free it before executing next525 * command. */526#else527 char *resultDontUse; /* Don't use in extensions! */528 void (*freeProcDontUse) (char *); /* Don't use in extensions! */529#endif530#ifdef USE_INTERP_ERRORLINE531 int errorLine TCL_DEPRECATED_API("use Tcl_GetErrorLine/Tcl_SetErrorLine");532 /* When TCL_ERROR is returned, this gives the533 * line number within the command where the534 * error occurred (1 if first line). */535#else536 int errorLineDontUse; /* Don't use in extensions! */537#endif538}539#endif /* !TCL_NO_DEPRECATED */540Tcl_Interp;541 542typedef struct Tcl_AsyncHandler_ *Tcl_AsyncHandler;543typedef struct Tcl_Channel_ *Tcl_Channel;544typedef struct Tcl_ChannelTypeVersion_ *Tcl_ChannelTypeVersion;545typedef struct Tcl_Command_ *Tcl_Command;546typedef struct Tcl_Condition_ *Tcl_Condition;547typedef struct Tcl_Dict_ *Tcl_Dict;548typedef struct Tcl_EncodingState_ *Tcl_EncodingState;549typedef struct Tcl_Encoding_ *Tcl_Encoding;550typedef struct Tcl_Event Tcl_Event;551typedef struct Tcl_InterpState_ *Tcl_InterpState;552typedef struct Tcl_LoadHandle_ *Tcl_LoadHandle;553typedef struct Tcl_Mutex_ *Tcl_Mutex;554typedef struct Tcl_Pid_ *Tcl_Pid;555typedef struct Tcl_RegExp_ *Tcl_RegExp;556typedef struct Tcl_ThreadDataKey_ *Tcl_ThreadDataKey;557typedef struct Tcl_ThreadId_ *Tcl_ThreadId;558typedef struct Tcl_TimerToken_ *Tcl_TimerToken;559typedef struct Tcl_Trace_ *Tcl_Trace;560typedef struct Tcl_Var_ *Tcl_Var;561typedef struct Tcl_ZLibStream_ *Tcl_ZlibStream;562 563/*564 *----------------------------------------------------------------------------565 * Definition of the interface to functions implementing threads. A function566 * following this definition is given to each call of 'Tcl_CreateThread' and567 * will be called as the main fuction of the new thread created by that call.568 */569 570#if defined _WIN32571typedef unsigned (__stdcall Tcl_ThreadCreateProc) (ClientData clientData);572#else573typedef void (Tcl_ThreadCreateProc) (ClientData clientData);574#endif575 576/*577 * Threading function return types used for abstracting away platform578 * differences when writing a Tcl_ThreadCreateProc. See the NewThread function579 * in generic/tclThreadTest.c for it's usage.580 */581 582#if defined _WIN32583# define Tcl_ThreadCreateType unsigned __stdcall584# define TCL_THREAD_CREATE_RETURN return 0585#else586# define Tcl_ThreadCreateType void587# define TCL_THREAD_CREATE_RETURN588#endif589 590/*591 * Definition of values for default stacksize and the possible flags to be592 * given to Tcl_CreateThread.593 */594 595#define TCL_THREAD_STACK_DEFAULT (0) /* Use default size for stack. */596#define TCL_THREAD_NOFLAGS (0000) /* Standard flags, default597 * behaviour. */598#define TCL_THREAD_JOINABLE (0001) /* Mark the thread as joinable. */599 600/*601 * Flag values passed to Tcl_StringCaseMatch.602 */603 604#define TCL_MATCH_NOCASE (1<<0)605 606/*607 * Flag values passed to Tcl_GetRegExpFromObj.608 */609 610#define TCL_REG_BASIC 000000 /* BREs (convenience). */611#define TCL_REG_EXTENDED 000001 /* EREs. */612#define TCL_REG_ADVF 000002 /* Advanced features in EREs. */613#define TCL_REG_ADVANCED 000003 /* AREs (which are also EREs). */614#define TCL_REG_QUOTE 000004 /* No special characters, none. */615#define TCL_REG_NOCASE 000010 /* Ignore case. */616#define TCL_REG_NOSUB 000020 /* Don't care about subexpressions. */617#define TCL_REG_EXPANDED 000040 /* Expanded format, white space &618 * comments. */619#define TCL_REG_NLSTOP 000100 /* \n doesn't match . or [^ ] */620#define TCL_REG_NLANCH 000200 /* ^ matches after \n, $ before. */621#define TCL_REG_NEWLINE 000300 /* Newlines are line terminators. */622#define TCL_REG_CANMATCH 001000 /* Report details on partial/limited623 * matches. */624 625/*626 * Flags values passed to Tcl_RegExpExecObj.627 */628 629#define TCL_REG_NOTBOL 0001 /* Beginning of string does not match ^. */630#define TCL_REG_NOTEOL 0002 /* End of string does not match $. */631 632/*633 * Structures filled in by Tcl_RegExpInfo. Note that all offset values are634 * relative to the start of the match string, not the beginning of the entire635 * string.636 */637 638typedef struct Tcl_RegExpIndices {639 long start; /* Character offset of first character in640 * match. */641 long end; /* Character offset of first character after642 * the match. */643} Tcl_RegExpIndices;644 645typedef struct Tcl_RegExpInfo {646 int nsubs; /* Number of subexpressions in the compiled647 * expression. */648 Tcl_RegExpIndices *matches; /* Array of nsubs match offset pairs. */649 long extendStart; /* The offset at which a subsequent match650 * might begin. */651 long reserved; /* Reserved for later use. */652} Tcl_RegExpInfo;653 654/*655 * Picky compilers complain if this typdef doesn't appear before the struct's656 * reference in tclDecls.h.657 */658 659typedef Tcl_StatBuf *Tcl_Stat_;660typedef struct stat *Tcl_OldStat_;661 662/*663 *----------------------------------------------------------------------------664 * When a TCL command returns, the interpreter contains a result from the665 * command. Programmers are strongly encouraged to use one of the functions666 * Tcl_GetObjResult() or Tcl_GetStringResult() to read the interpreter's667 * result. See the SetResult man page for details. Besides this result, the668 * command function returns an integer code, which is one of the following:669 *670 * TCL_OK Command completed normally; the interpreter's result671 * contains the command's result.672 * TCL_ERROR The command couldn't be completed successfully; the673 * interpreter's result describes what went wrong.674 * TCL_RETURN The command requests that the current function return;675 * the interpreter's result contains the function's676 * return value.677 * TCL_BREAK The command requests that the innermost loop be678 * exited; the interpreter's result is meaningless.679 * TCL_CONTINUE Go on to the next iteration of the current loop; the680 * interpreter's result is meaningless.681 */682 683#define TCL_OK 0684#define TCL_ERROR 1685#define TCL_RETURN 2686#define TCL_BREAK 3687#define TCL_CONTINUE 4688 689#define TCL_RESULT_SIZE 200690 691/*692 *----------------------------------------------------------------------------693 * Flags to control what substitutions are performed by Tcl_SubstObj():694 */695 696#define TCL_SUBST_COMMANDS 001697#define TCL_SUBST_VARIABLES 002698#define TCL_SUBST_BACKSLASHES 004699#define TCL_SUBST_ALL 007700 701/*702 * Argument descriptors for math function callbacks in expressions:703 */704 705typedef enum {706 TCL_INT, TCL_DOUBLE, TCL_EITHER, TCL_WIDE_INT707} Tcl_ValueType;708 709typedef struct Tcl_Value {710 Tcl_ValueType type; /* Indicates intValue or doubleValue is valid,711 * or both. */712 long intValue; /* Integer value. */713 double doubleValue; /* Double-precision floating value. */714 Tcl_WideInt wideValue; /* Wide (min. 64-bit) integer value. */715} Tcl_Value;716 717/*718 * Forward declaration of Tcl_Obj to prevent an error when the forward719 * reference to Tcl_Obj is encountered in the function types declared below.720 */721 722struct Tcl_Obj;723 724/*725 *----------------------------------------------------------------------------726 * Function types defined by Tcl:727 */728 729typedef int (Tcl_AppInitProc) (Tcl_Interp *interp);730typedef int (Tcl_AsyncProc) (ClientData clientData, Tcl_Interp *interp,731 int code);732typedef void (Tcl_ChannelProc) (ClientData clientData, int mask);733typedef void (Tcl_CloseProc) (ClientData data);734typedef void (Tcl_CmdDeleteProc) (ClientData clientData);735typedef int (Tcl_CmdProc) (ClientData clientData, Tcl_Interp *interp,736 int argc, CONST84 char *argv[]);737typedef void (Tcl_CmdTraceProc) (ClientData clientData, Tcl_Interp *interp,738 int level, char *command, Tcl_CmdProc *proc,739 ClientData cmdClientData, int argc, CONST84 char *argv[]);740typedef int (Tcl_CmdObjTraceProc) (ClientData clientData, Tcl_Interp *interp,741 int level, const char *command, Tcl_Command commandInfo, int objc,742 struct Tcl_Obj *const *objv);743typedef void (Tcl_CmdObjTraceDeleteProc) (ClientData clientData);744typedef void (Tcl_DupInternalRepProc) (struct Tcl_Obj *srcPtr,745 struct Tcl_Obj *dupPtr);746typedef int (Tcl_EncodingConvertProc) (ClientData clientData, const char *src,747 int srcLen, int flags, Tcl_EncodingState *statePtr, char *dst,748 int dstLen, int *srcReadPtr, int *dstWrotePtr, int *dstCharsPtr);749typedef void (Tcl_EncodingFreeProc) (ClientData clientData);750typedef int (Tcl_EventProc) (Tcl_Event *evPtr, int flags);751typedef void (Tcl_EventCheckProc) (ClientData clientData, int flags);752typedef int (Tcl_EventDeleteProc) (Tcl_Event *evPtr, ClientData clientData);753typedef void (Tcl_EventSetupProc) (ClientData clientData, int flags);754typedef void (Tcl_ExitProc) (ClientData clientData);755typedef void (Tcl_FileProc) (ClientData clientData, int mask);756typedef void (Tcl_FileFreeProc) (ClientData clientData);757typedef void (Tcl_FreeInternalRepProc) (struct Tcl_Obj *objPtr);758typedef void (Tcl_FreeProc) (char *blockPtr);759typedef void (Tcl_IdleProc) (ClientData clientData);760typedef void (Tcl_InterpDeleteProc) (ClientData clientData,761 Tcl_Interp *interp);762typedef int (Tcl_MathProc) (ClientData clientData, Tcl_Interp *interp,763 Tcl_Value *args, Tcl_Value *resultPtr);764typedef void (Tcl_NamespaceDeleteProc) (ClientData clientData);765typedef int (Tcl_ObjCmdProc) (ClientData clientData, Tcl_Interp *interp,766 int objc, struct Tcl_Obj *const *objv);767typedef int (Tcl_PackageInitProc) (Tcl_Interp *interp);768typedef int (Tcl_PackageUnloadProc) (Tcl_Interp *interp, int flags);769typedef void (Tcl_PanicProc) (const char *format, ...);770typedef void (Tcl_TcpAcceptProc) (ClientData callbackData, Tcl_Channel chan,771 char *address, int port);772typedef void (Tcl_TimerProc) (ClientData clientData);773typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *interp, struct Tcl_Obj *objPtr);774typedef void (Tcl_UpdateStringProc) (struct Tcl_Obj *objPtr);775typedef char * (Tcl_VarTraceProc) (ClientData clientData, Tcl_Interp *interp,776 CONST84 char *part1, CONST84 char *part2, int flags);777typedef void (Tcl_CommandTraceProc) (ClientData clientData, Tcl_Interp *interp,778 const char *oldName, const char *newName, int flags);779typedef void (Tcl_CreateFileHandlerProc) (int fd, int mask, Tcl_FileProc *proc,780 ClientData clientData);781typedef void (Tcl_DeleteFileHandlerProc) (int fd);782typedef void (Tcl_AlertNotifierProc) (ClientData clientData);783typedef void (Tcl_ServiceModeHookProc) (int mode);784typedef ClientData (Tcl_InitNotifierProc) (void);785typedef void (Tcl_FinalizeNotifierProc) (ClientData clientData);786typedef void (Tcl_MainLoopProc) (void);787 788/*789 *----------------------------------------------------------------------------790 * The following structure represents a type of object, which is a particular791 * internal representation for an object plus a set of functions that provide792 * standard operations on objects of that type.793 */794 795typedef struct Tcl_ObjType {796 const char *name; /* Name of the type, e.g. "int". */797 Tcl_FreeInternalRepProc *freeIntRepProc;798 /* Called to free any storage for the type's799 * internal rep. NULL if the internal rep does800 * not need freeing. */801 Tcl_DupInternalRepProc *dupIntRepProc;802 /* Called to create a new object as a copy of803 * an existing object. */804 Tcl_UpdateStringProc *updateStringProc;805 /* Called to update the string rep from the806 * type's internal representation. */807 Tcl_SetFromAnyProc *setFromAnyProc;808 /* Called to convert the object's internal rep809 * to this type. Frees the internal rep of the810 * old type. Returns TCL_ERROR on failure. */811} Tcl_ObjType;812 813/*814 * One of the following structures exists for each object in the Tcl system.815 * An object stores a value as either a string, some internal representation,816 * or both.817 */818 819typedef struct Tcl_Obj {820 int refCount; /* When 0 the object will be freed. */821 char *bytes; /* This points to the first byte of the822 * object's string representation. The array823 * must be followed by a null byte (i.e., at824 * offset length) but may also contain825 * embedded null characters. The array's826 * storage is allocated by ckalloc. NULL means827 * the string rep is invalid and must be828 * regenerated from the internal rep. Clients829 * should use Tcl_GetStringFromObj or830 * Tcl_GetString to get a pointer to the byte831 * array as a readonly value. */832 int length; /* The number of bytes at *bytes, not833 * including the terminating null. */834 const Tcl_ObjType *typePtr; /* Denotes the object's type. Always835 * corresponds to the type of the object's836 * internal rep. NULL indicates the object has837 * no internal rep (has no type). */838 union { /* The internal representation: */839 long longValue; /* - an long integer value. */840 double doubleValue; /* - a double-precision floating value. */841 void *otherValuePtr; /* - another, type-specific value,842 not used internally any more. */843 Tcl_WideInt wideValue; /* - a long long value. */844 struct { /* - internal rep as two pointers.845 * the main use of which is a bignum's846 * tightly packed fields, where the alloc,847 * used and signum flags are packed into848 * ptr2 with everything else hung off ptr1. */849 void *ptr1;850 void *ptr2;851 } twoPtrValue;852 struct { /* - internal rep as a pointer and a long,853 not used internally any more. */854 void *ptr;855 unsigned long value;856 } ptrAndLongRep;857 } internalRep;858} Tcl_Obj;859 860/*861 * Macros to increment and decrement a Tcl_Obj's reference count, and to test862 * whether an object is shared (i.e. has reference count > 1). Note: clients863 * should use Tcl_DecrRefCount() when they are finished using an object, and864 * should never call TclFreeObj() directly. TclFreeObj() is only defined and865 * made public in tcl.h to support Tcl_DecrRefCount's macro definition.866 */867 868void Tcl_IncrRefCount(Tcl_Obj *objPtr);869void Tcl_DecrRefCount(Tcl_Obj *objPtr);870int Tcl_IsShared(Tcl_Obj *objPtr);871 872/*873 *----------------------------------------------------------------------------874 * The following structure contains the state needed by Tcl_SaveResult. No-one875 * outside of Tcl should access any of these fields. This structure is876 * typically allocated on the stack.877 */878 879typedef struct Tcl_SavedResult {880 char *result;881 Tcl_FreeProc *freeProc;882 Tcl_Obj *objResultPtr;883 char *appendResult;884 int appendAvl;885 int appendUsed;886 char resultSpace[TCL_RESULT_SIZE+1];887} Tcl_SavedResult;888 889/*890 *----------------------------------------------------------------------------891 * The following definitions support Tcl's namespace facility. Note: the first892 * five fields must match exactly the fields in a Namespace structure (see893 * tclInt.h).894 */895 896typedef struct Tcl_Namespace {897 char *name; /* The namespace's name within its parent898 * namespace. This contains no ::'s. The name899 * of the global namespace is "" although "::"900 * is an synonym. */901 char *fullName; /* The namespace's fully qualified name. This902 * starts with ::. */903 ClientData clientData; /* Arbitrary value associated with this904 * namespace. */905 Tcl_NamespaceDeleteProc *deleteProc;906 /* Function invoked when deleting the907 * namespace to, e.g., free clientData. */908 struct Tcl_Namespace *parentPtr;909 /* Points to the namespace that contains this910 * one. NULL if this is the global911 * namespace. */912} Tcl_Namespace;913 914/*915 *----------------------------------------------------------------------------916 * The following structure represents a call frame, or activation record. A917 * call frame defines a naming context for a procedure call: its local scope918 * (for local variables) and its namespace scope (used for non-local919 * variables; often the global :: namespace). A call frame can also define the920 * naming context for a namespace eval or namespace inscope command: the921 * namespace in which the command's code should execute. The Tcl_CallFrame922 * structures exist only while procedures or namespace eval/inscope's are923 * being executed, and provide a Tcl call stack.924 *925 * A call frame is initialized and pushed using Tcl_PushCallFrame and popped926 * using Tcl_PopCallFrame. Storage for a Tcl_CallFrame must be provided by the927 * Tcl_PushCallFrame caller, and callers typically allocate them on the C call928 * stack for efficiency. For this reason, Tcl_CallFrame is defined as a929 * structure and not as an opaque token. However, most Tcl_CallFrame fields930 * are hidden since applications should not access them directly; others are931 * declared as "dummyX".932 *933 * WARNING!! The structure definition must be kept consistent with the934 * CallFrame structure in tclInt.h. If you change one, change the other.935 */936 937typedef struct Tcl_CallFrame {938 Tcl_Namespace *nsPtr;939 int dummy1;940 int dummy2;941 void *dummy3;942 void *dummy4;943 void *dummy5;944 int dummy6;945 void *dummy7;946 void *dummy8;947 int dummy9;948 void *dummy10;949 void *dummy11;950 void *dummy12;951 void *dummy13;952} Tcl_CallFrame;953 954/*955 *----------------------------------------------------------------------------956 * Information about commands that is returned by Tcl_GetCommandInfo and957 * passed to Tcl_SetCommandInfo. objProc is an objc/objv object-based command958 * function while proc is a traditional Tcl argc/argv string-based function.959 * Tcl_CreateObjCommand and Tcl_CreateCommand ensure that both objProc and960 * proc are non-NULL and can be called to execute the command. However, it may961 * be faster to call one instead of the other. The member isNativeObjectProc962 * is set to 1 if an object-based function was registered by963 * Tcl_CreateObjCommand, and to 0 if a string-based function was registered by964 * Tcl_CreateCommand. The other function is typically set to a compatibility965 * wrapper that does string-to-object or object-to-string argument conversions966 * then calls the other function.967 */968 969typedef struct Tcl_CmdInfo {970 int isNativeObjectProc; /* 1 if objProc was registered by a call to971 * Tcl_CreateObjCommand; 0 otherwise.972 * Tcl_SetCmdInfo does not modify this973 * field. */974 Tcl_ObjCmdProc *objProc; /* Command's object-based function. */975 ClientData objClientData; /* ClientData for object proc. */976 Tcl_CmdProc *proc; /* Command's string-based function. */977 ClientData clientData; /* ClientData for string proc. */978 Tcl_CmdDeleteProc *deleteProc;979 /* Function to call when command is980 * deleted. */981 ClientData deleteData; /* Value to pass to deleteProc (usually the982 * same as clientData). */983 Tcl_Namespace *namespacePtr;/* Points to the namespace that contains this984 * command. Note that Tcl_SetCmdInfo will not985 * change a command's namespace; use986 * TclRenameCommand or Tcl_Eval (of 'rename')987 * to do that. */988} Tcl_CmdInfo;989 990/*991 *----------------------------------------------------------------------------992 * The structure defined below is used to hold dynamic strings. The only993 * fields that clients should use are string and length, accessible via the994 * macros Tcl_DStringValue and Tcl_DStringLength.995 */996 997#define TCL_DSTRING_STATIC_SIZE 200998typedef struct Tcl_DString {999 char *string; /* Points to beginning of string: either1000 * staticSpace below or a malloced array. */1001 int length; /* Number of non-NULL characters in the1002 * string. */1003 int spaceAvl; /* Total number of bytes available for the1004 * string and its terminating NULL char. */1005 char staticSpace[TCL_DSTRING_STATIC_SIZE];1006 /* Space to use in common case where string is1007 * small. */1008} Tcl_DString;1009 1010#define Tcl_DStringLength(dsPtr) ((dsPtr)->length)1011#define Tcl_DStringValue(dsPtr) ((dsPtr)->string)1012#define Tcl_DStringTrunc Tcl_DStringSetLength1013 1014/*1015 * Definitions for the maximum number of digits of precision that may be1016 * specified in the "tcl_precision" variable, and the number of bytes of1017 * buffer space required by Tcl_PrintDouble.1018 */1019 1020#define TCL_MAX_PREC 171021#define TCL_DOUBLE_SPACE (TCL_MAX_PREC+10)1022 1023/*1024 * Definition for a number of bytes of buffer space sufficient to hold the1025 * string representation of an integer in base 10 (assuming the existence of1026 * 64-bit integers).1027 */1028 1029#define TCL_INTEGER_SPACE 241030 1031/*1032 * Flag values passed to Tcl_ConvertElement.1033 * TCL_DONT_USE_BRACES forces it not to enclose the element in braces, but to1034 * use backslash quoting instead.1035 * TCL_DONT_QUOTE_HASH disables the default quoting of the '#' character. It1036 * is safe to leave the hash unquoted when the element is not the first1037 * element of a list, and this flag can be used by the caller to indicate1038 * that condition.1039 */1040 1041#define TCL_DONT_USE_BRACES 11042#define TCL_DONT_QUOTE_HASH 81043 1044/*1045 * Flag that may be passed to Tcl_GetIndexFromObj to force it to disallow1046 * abbreviated strings.1047 */1048 1049#define TCL_EXACT 11050 1051/*1052 *----------------------------------------------------------------------------1053 * Flag values passed to Tcl_RecordAndEval, Tcl_EvalObj, Tcl_EvalObjv.1054 * WARNING: these bit choices must not conflict with the bit choices for1055 * evalFlag bits in tclInt.h!1056 *1057 * Meanings:1058 * TCL_NO_EVAL: Just record this command1059 * TCL_EVAL_GLOBAL: Execute script in global namespace1060 * TCL_EVAL_DIRECT: Do not compile this script1061 * TCL_EVAL_INVOKE: Magical Tcl_EvalObjv mode for aliases/ensembles1062 * o Run in iPtr->lookupNsPtr or global namespace1063 * o Cut out of error traces1064 * o Don't reset the flags controlling ensemble1065 * error message rewriting.1066 * TCL_CANCEL_UNWIND: Magical Tcl_CancelEval mode that causes the1067 * stack for the script in progress to be1068 * completely unwound.1069 * TCL_EVAL_NOERR: Do no exception reporting at all, just return1070 * as the caller will report.1071 */1072 1073#define TCL_NO_EVAL 0x0100001074#define TCL_EVAL_GLOBAL 0x0200001075#define TCL_EVAL_DIRECT 0x0400001076#define TCL_EVAL_INVOKE 0x0800001077#define TCL_CANCEL_UNWIND 0x1000001078#define TCL_EVAL_NOERR 0x2000001079 1080/*1081 * Special freeProc values that may be passed to Tcl_SetResult (see the man1082 * page for details):1083 */1084 1085#define TCL_VOLATILE ((Tcl_FreeProc *) 1)1086#define TCL_STATIC ((Tcl_FreeProc *) 0)1087#define TCL_DYNAMIC ((Tcl_FreeProc *) 3)1088 1089/*1090 * Flag values passed to variable-related functions.1091 * WARNING: these bit choices must not conflict with the bit choice for1092 * TCL_CANCEL_UNWIND, above.1093 */1094 1095#define TCL_GLOBAL_ONLY 11096#define TCL_NAMESPACE_ONLY 21097#define TCL_APPEND_VALUE 41098#define TCL_LIST_ELEMENT 81099#define TCL_TRACE_READS 0x101100#define TCL_TRACE_WRITES 0x201101#define TCL_TRACE_UNSETS 0x401102#define TCL_TRACE_DESTROYED 0x801103#define TCL_INTERP_DESTROYED 0x1001104#define TCL_LEAVE_ERR_MSG 0x2001105#define TCL_TRACE_ARRAY 0x8001106#ifndef TCL_REMOVE_OBSOLETE_TRACES1107/* Required to support old variable/vdelete/vinfo traces. */1108#define TCL_TRACE_OLD_STYLE 0x10001109#endif1110/* Indicate the semantics of the result of a trace. */1111#define TCL_TRACE_RESULT_DYNAMIC 0x80001112#define TCL_TRACE_RESULT_OBJECT 0x100001113 1114/*1115 * Flag values for ensemble commands.1116 */1117 1118#define TCL_ENSEMBLE_PREFIX 0x02/* Flag value to say whether to allow1119 * unambiguous prefixes of commands or to1120 * require exact matches for command names. */1121 1122/*1123 * Flag values passed to command-related functions.1124 */1125 1126#define TCL_TRACE_RENAME 0x20001127#define TCL_TRACE_DELETE 0x40001128 1129#define TCL_ALLOW_INLINE_COMPILATION 0x200001130 1131/*1132 * The TCL_PARSE_PART1 flag is deprecated and has no effect. The part1 is now1133 * always parsed whenever the part2 is NULL. (This is to avoid a common error1134 * when converting code to use the new object based APIs and forgetting to1135 * give the flag)1136 */1137 1138#if !defined(TCL_NO_DEPRECATED) && TCL_MAJOR_VERSION < 91139# define TCL_PARSE_PART1 0x4001140#endif /* !TCL_NO_DEPRECATED */1141 1142/*1143 * Types for linked variables:1144 */1145 1146#define TCL_LINK_INT 11147#define TCL_LINK_DOUBLE 21148#define TCL_LINK_BOOLEAN 31149#define TCL_LINK_STRING 41150#define TCL_LINK_WIDE_INT 51151#define TCL_LINK_CHAR 61152#define TCL_LINK_UCHAR 71153#define TCL_LINK_SHORT 81154#define TCL_LINK_USHORT 91155#define TCL_LINK_UINT 101156#define TCL_LINK_LONG 111157#define TCL_LINK_ULONG 121158#define TCL_LINK_FLOAT 131159#define TCL_LINK_WIDE_UINT 141160#define TCL_LINK_READ_ONLY 0x801161 1162/*1163 *----------------------------------------------------------------------------1164 * Forward declarations of Tcl_HashTable and related types.1165 */1166 1167typedef struct Tcl_HashKeyType Tcl_HashKeyType;1168typedef struct Tcl_HashTable Tcl_HashTable;1169typedef struct Tcl_HashEntry Tcl_HashEntry;1170 1171typedef unsigned (Tcl_HashKeyProc) (Tcl_HashTable *tablePtr, void *keyPtr);1172typedef int (Tcl_CompareHashKeysProc) (void *keyPtr, Tcl_HashEntry *hPtr);1173typedef Tcl_HashEntry * (Tcl_AllocHashEntryProc) (Tcl_HashTable *tablePtr,1174 void *keyPtr);1175typedef void (Tcl_FreeHashEntryProc) (Tcl_HashEntry *hPtr);1176 1177/*1178 * This flag controls whether the hash table stores the hash of a key, or1179 * recalculates it. There should be no reason for turning this flag off as it1180 * is completely binary and source compatible unless you directly access the1181 * bucketPtr member of the Tcl_HashTableEntry structure. This member has been1182 * removed and the space used to store the hash value.1183 */1184 1185#ifndef TCL_HASH_KEY_STORE_HASH1186# define TCL_HASH_KEY_STORE_HASH 11187#endif1188 1189/*1190 * Structure definition for an entry in a hash table. No-one outside Tcl1191 * should access any of these fields directly; use the macros defined below.1192 */1193 1194struct Tcl_HashEntry {1195 Tcl_HashEntry *nextPtr; /* Pointer to next entry in this hash bucket,1196 * or NULL for end of chain. */1197 Tcl_HashTable *tablePtr; /* Pointer to table containing entry. */1198#if TCL_HASH_KEY_STORE_HASH1199 void *hash; /* Hash value, stored as pointer to ensure1200 * that the offsets of the fields in this