/*

 * tcl.h --

 *

 *	This header file describes the externally-visible facilities

 *	of the Tcl interpreter.

 *

 * Copyright (c) 1987-1994 The Regents of the University of California.

 * Copyright (c) 1993-1996 Lucent Technologies.

 * Copyright (c) 1994-1998 Sun Microsystems, Inc.

 * Copyright (c) 1998-2000 by Scriptics Corporation.

 * Copyright (c) 2002 by Kevin B. Kenny.  All rights reserved.

 * Portions Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiaries. All rights reserved.  

 *

 * See the file "license.terms" for information on usage and redistribution

 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.

 *

 * RCS: @(#) $Id: tcl.h,v 1.153.2.30 2006/10/23 17:53:26 dgp Exp $

 */

#ifndef _TCL

#define _TCL

/*

 * For C++ compilers, use extern "C"

 */

#ifdef __cplusplus

extern "C" {

#endif

/*

 * The following defines are used to indicate the various release levels.

 */

#define TCL_ALPHA_RELEASE	0

#define TCL_BETA_RELEASE	1

#define TCL_FINAL_RELEASE	2

/*

 * When version numbers change here, must also go into the following files

 * and update the version numbers:

 *

 * library/init.tcl	(only if Major.minor changes, not patchlevel) 1 LOC

 * unix/configure.in	(2 LOC Major, 2 LOC minor, 1 LOC patch)

 * win/configure.in	(as above)

 * win/tcl.m4		(not patchlevel)

 * win/makefile.vc	(not patchlevel) 2 LOC

 * README		(sections 0 and 2)

 * mac/README		(2 LOC, not patchlevel)

 * macosx/Tcl.pbproj/project.pbxproj (not patchlevel) 1 LOC

 * macosx/Tcl.pbproj/default.pbxuser (not patchlevel) 1 LOC

 * win/README.binary	(sections 0-4)

 * win/README		(not patchlevel) (sections 0 and 2)

 * unix/tcl.spec	(2 LOC Major/Minor, 1 LOC patch)

 * tests/basic.test	(1 LOC M/M, not patchlevel)

 * tools/tcl.hpj.in	(not patchlevel, for windows installer)

 * tools/tcl.wse.in	(for windows installer)

 * tools/tclSplash.bmp	(not patchlevel)

 */

#define TCL_MAJOR_VERSION   8

#define TCL_MINOR_VERSION   4

#define TCL_RELEASE_LEVEL   TCL_FINAL_RELEASE

#define TCL_RELEASE_SERIAL  15

#define TCL_VERSION	    "8.4"

#define TCL_PATCH_LEVEL	    "8.4.15"

/*

 * The following definitions set up the proper options for Windows

 * compilers.  We use this method because there is no autoconf equivalent.

 */

// Only if not compiling for Symbian on a PC with a Windows compiler

#ifndef __SYMBIAN32__  

#ifndef __WIN32__

#   if defined(_WIN32) || defined(WIN32) || defined(__MINGW32__) || defined(__BORLANDC__)

#	define __WIN32__

#	ifndef WIN32

#	    define WIN32

#	endif

#   endif

#endif

#endif

/*

 * STRICT: See MSDN Article Q83456

 */

#ifdef __WIN32__

#   ifndef STRICT

#	define STRICT

#   endif

#endif /* __WIN32__ */

/*

 * The following definitions set up the proper options for Macintosh

 * compilers.  We use this method because there is no autoconf equivalent.

 */

#ifdef MAC_TCL

#include <ConditionalMacros.h>

#   ifndef USE_TCLALLOC

#	define USE_TCLALLOC 1

#   endif

#   ifndef NO_STRERROR

#	define NO_STRERROR 1

#   endif

#   define INLINE 

#endif

/*

 * Utility macros: STRINGIFY takes an argument and wraps it in "" (double

 * quotation marks), JOIN joins two arguments.

 */

#ifndef STRINGIFY

#  define STRINGIFY(x) STRINGIFY1(x)

#  define STRINGIFY1(x) #x

#endif

#ifndef JOIN

#  define JOIN(a,b) JOIN1(a,b)

#  define JOIN1(a,b) a##b

#endif

/* 

 * A special definition used to allow this header file to be included

 * from windows or mac resource files so that they can obtain version

 * information.  RC_INVOKED is defined by default by the windows RC tool

 * and manually set for macintosh.

 *

 * Resource compilers don't like all the C stuff, like typedefs and

 * procedure declarations, that occur below, so block them out.

 */

#ifndef RC_INVOKED

/*

 * Special macro to define mutexes, that doesn't do anything

 * if we are not using threads.

 */

#ifdef TCL_THREADS

#define TCL_DECLARE_MUTEX(name) static Tcl_Mutex name;

#else

#define TCL_DECLARE_MUTEX(name)

#endif

/*

 * Macros that eliminate the overhead of the thread synchronization

 * functions when compiling without thread support.

 */

#ifndef TCL_THREADS

#define Tcl_MutexLock(mutexPtr)

#define Tcl_MutexUnlock(mutexPtr)

#define Tcl_MutexFinalize(mutexPtr)

#define Tcl_ConditionNotify(condPtr)

#define Tcl_ConditionWait(condPtr, mutexPtr, timePtr)

#define Tcl_ConditionFinalize(condPtr)

#endif /* TCL_THREADS */

#ifndef BUFSIZ

#   include <stdio.h>

#endif

/*

 * Definitions that allow Tcl functions with variable numbers of

 * arguments to be used with either varargs.h or stdarg.h.  TCL_VARARGS

 * is used in procedure prototypes.  TCL_VARARGS_DEF is used to declare

 * the arguments in a function definiton: it takes the type and name of

 * the first argument and supplies the appropriate argument declaration

 * string for use in the function definition.  TCL_VARARGS_START

 * initializes the va_list data structure and returns the first argument.

 */

#if !defined(NO_STDARG)

#   include <stdarg.h>

#   define TCL_VARARGS(type, name) (type name, ...)

#   define TCL_VARARGS_DEF(type, name) (type name, ...)

#   define TCL_VARARGS_START(type, name, list) (va_start(list, name), name)

#else

#   include <varargs.h>

#      define TCL_VARARGS(type, name) ()

#      define TCL_VARARGS_DEF(type, name) (va_alist)

#   define TCL_VARARGS_START(type, name, list) \

	(va_start(list), va_arg(list, type))

#endif

/*

 * Macros used to declare a function to be exported by a DLL.

 * Used by Windows, maps to no-op declarations on non-Windows systems.

 * The default build on windows is for a DLL, which causes the DLLIMPORT

 * and DLLEXPORT macros to be nonempty. To build a static library, the

 * macro STATIC_BUILD should be defined.

 */

#ifdef STATIC_BUILD

#   define DLLIMPORT

#   define DLLEXPORT

#else

#   if (defined(__WIN32__) && (defined(_MSC_VER) || (__BORLANDC__ >= 0x0550) || (defined(__GNUC__) && defined(__declspec)))) || (defined(MAC_TCL) && FUNCTION_DECLSPEC)

#	define DLLIMPORT __declspec(dllimport)

#	define DLLEXPORT __declspec(dllexport)

#   else

#	define DLLIMPORT

#	define DLLEXPORT

#   endif

#endif

/*

 * These macros are used to control whether functions are being declared for

 * import or export.  If a function is being declared while it is being built

 * to be included in a shared library, then it should have the DLLEXPORT

 * storage class.  If is being declared for use by a module that is going to

 * link against the shared library, then it should have the DLLIMPORT storage

 * class.  If the symbol is beind declared for a static build or for use from a

 * stub library, then the storage class should be empty.

 *

 * The convention is that a macro called BUILD_xxxx, where xxxx is the

 * name of a library we are building, is set on the compile line for sources

 * that are to be placed in the library.  When this macro is set, the

 * storage class will be set to DLLEXPORT.  At the end of the header file, the

 * storage class will be reset to DLLIMPORT.

 */

#undef TCL_STORAGE_CLASS

#ifdef BUILD_tcl

#   define TCL_STORAGE_CLASS DLLEXPORT

#else

#   ifdef USE_TCL_STUBS

#      define TCL_STORAGE_CLASS

#   else

#      define TCL_STORAGE_CLASS DLLIMPORT

#   endif

#endif

/*

 * Definitions that allow this header file to be used either with or

 * without ANSI C features like function prototypes.

 */

#undef _ANSI_ARGS_

#undef CONST

#ifndef INLINE

#   define INLINE

#endif

#ifndef NO_CONST

#   define CONST const

#else

#   define CONST

#endif

#ifndef NO_PROTOTYPES

#   define _ANSI_ARGS_(x)	x

#else

#   define _ANSI_ARGS_(x)	()

#endif

#ifdef USE_NON_CONST

#   ifdef USE_COMPAT_CONST

#      error define at most one of USE_NON_CONST and USE_COMPAT_CONST

#   endif

#   define CONST84

#   define CONST84_RETURN

#else

#   ifdef USE_COMPAT_CONST

#      define CONST84 

#      define CONST84_RETURN CONST

#   else

#      define CONST84 CONST

#      define CONST84_RETURN CONST

#   endif

#endif

/*

 * Make sure EXTERN isn't defined elsewhere

 */

#ifdef EXTERN

#   undef EXTERN

#endif /* EXTERN */

#ifdef __cplusplus

#   define EXTERN extern "C" TCL_STORAGE_CLASS

#else

#   define EXTERN extern TCL_STORAGE_CLASS

#endif

#ifdef __SYMBIAN32__  

#ifdef EXTERN

#   undef EXTERN

#endif

#ifdef __cplusplus

#   define EXTERN extern "C"

#else

#   define EXTERN extern

#endif

#endif

/*

 * The following code is copied from winnt.h.

 * If we don't replicate it here, then <windows.h> can't be included 

 * after tcl.h, since tcl.h also defines VOID.

 * This block is skipped under Cygwin and Mingw.

 * 

 * 

 */

#if defined(__WIN32__) && !defined(HAVE_WINNT_IGNORE_VOID)

#ifndef VOID

#define VOID void

typedef char CHAR;

typedef short SHORT;

typedef long LONG;

#endif

#endif /* __WIN32__ && !HAVE_WINNT_IGNORE_VOID */

/*

 * Macro to use instead of "void" for arguments that must have

 * type "void *" in ANSI C;  maps them to type "char *" in

 * non-ANSI systems.

 */

#ifndef NO_VOID

#         define VOID void

#else

#         define VOID char

#endif

/*

 * Miscellaneous declarations.

 */

#ifndef _CLIENTDATA

#   ifndef NO_VOID

	typedef void *ClientData;

#   else

	typedef int *ClientData;

#   endif

#   define _CLIENTDATA

#endif

/*

 * Darwin specifc configure overrides (to support fat compiles, where

 * configure runs only once for multiple architectures):

 */

#ifdef __APPLE__

#   ifdef __LP64__

#	undef TCL_WIDE_INT_TYPE

#	define TCL_WIDE_INT_IS_LONG 1

#    else /* !__LP64__ */

#	define TCL_WIDE_INT_TYPE long long

#	undef TCL_WIDE_INT_IS_LONG

#    endif /* __LP64__ */

#    undef HAVE_STRUCT_STAT64

#endif /* __APPLE__ */

/*

 * Define Tcl_WideInt to be a type that is (at least) 64-bits wide,

 * and define Tcl_WideUInt to be the unsigned variant of that type

 * (assuming that where we have one, we can have the other.)

 *

 * Also defines the following macros:

 * TCL_WIDE_INT_IS_LONG - if wide ints are really longs (i.e. we're on

 *	a real 64-bit system.)

 * Tcl_WideAsLong - forgetful converter from wideInt to long.

 * Tcl_LongAsWide - sign-extending converter from long to wideInt.

 * Tcl_WideAsDouble - converter from wideInt to double.

 * Tcl_DoubleAsWide - converter from double to wideInt.

 *

 * The following invariant should hold for any long value 'longVal':

 *	longVal == Tcl_WideAsLong(Tcl_LongAsWide(longVal))

 *

 * Note on converting between Tcl_WideInt and strings.  This

 * implementation (in tclObj.c) depends on the functions strtoull()

 * and sprintf(...,"%" TCL_LL_MODIFIER "d",...).  TCL_LL_MODIFIER_SIZE

 * is the length of the modifier string, which is "ll" on most 32-bit

 * Unix systems.  It has to be split up like this to allow for the more

 * complex formats sometimes needed (e.g. in the format(n) command.)

 */

#if !defined(TCL_WIDE_INT_TYPE)&&!defined(TCL_WIDE_INT_IS_LONG)

#   if defined(__GNUC__)

#      define TCL_WIDE_INT_TYPE long long

#      if defined(__WIN32__) && !defined(__CYGWIN__)

#         define TCL_LL_MODIFIER        "I64"

#         define TCL_LL_MODIFIER_SIZE   3

#      else

#      define TCL_LL_MODIFIER	"L"

#      define TCL_LL_MODIFIER_SIZE	1

#      endif

typedef struct stat	Tcl_StatBuf;

#   elif defined(__WIN32__)

#      define TCL_WIDE_INT_TYPE __int64

#      ifdef __BORLANDC__

typedef struct stati64 Tcl_StatBuf;

#         define TCL_LL_MODIFIER	"L"

#         define TCL_LL_MODIFIER_SIZE	1

#      else /* __BORLANDC__ */

#         if _MSC_VER < 1400 || !defined(_M_IX86)

typedef struct _stati64	Tcl_StatBuf;

#         else

typedef struct _stat64 Tcl_StatBuf;

#         endif /* _MSC_VER < 1400 */

#         define TCL_LL_MODIFIER	"I64"

#         define TCL_LL_MODIFIER_SIZE	3

#      endif /* __BORLANDC__ */

#   else /* __WIN32__ */

/*

 * Don't know what platform it is and configure hasn't discovered what

 * is going on for us.  Try to guess...

 */

#      ifdef NO_LIMITS_H

#	  error please define either TCL_WIDE_INT_TYPE or TCL_WIDE_INT_IS_LONG

#      else /* !NO_LIMITS_H */

#	  include <limits.h>

#	  if (INT_MAX < LONG_MAX)

#	     define TCL_WIDE_INT_IS_LONG	1

#	  else

#	     define TCL_WIDE_INT_TYPE long long

#         endif

#      endif /* NO_LIMITS_H */

#   endif /* __WIN32__ */

#endif /* !TCL_WIDE_INT_TYPE & !TCL_WIDE_INT_IS_LONG */

#ifdef TCL_WIDE_INT_IS_LONG

#   undef TCL_WIDE_INT_TYPE

#   define TCL_WIDE_INT_TYPE	long

#endif /* TCL_WIDE_INT_IS_LONG */

typedef TCL_WIDE_INT_TYPE		Tcl_WideInt;

typedef unsigned TCL_WIDE_INT_TYPE	Tcl_WideUInt;

#ifdef TCL_WIDE_INT_IS_LONG

typedef struct stat	Tcl_StatBuf;

#   define Tcl_WideAsLong(val)		((long)(val))

#   define Tcl_LongAsWide(val)		((long)(val))

#   define Tcl_WideAsDouble(val)	((double)((long)(val)))

#   define Tcl_DoubleAsWide(val)	((long)((double)(val)))

#   ifndef TCL_LL_MODIFIER

#      define TCL_LL_MODIFIER		"l"

#      define TCL_LL_MODIFIER_SIZE	1

#   endif /* !TCL_LL_MODIFIER */

#else /* TCL_WIDE_INT_IS_LONG */

/*

 * The next short section of defines are only done when not running on

 * Windows or some other strange platform.

 */

#   ifndef TCL_LL_MODIFIER

#      ifdef HAVE_STRUCT_STAT64

typedef struct stat64	Tcl_StatBuf;

#      else

typedef struct stat	Tcl_StatBuf;

#      endif /* HAVE_STRUCT_STAT64 */

#      define TCL_LL_MODIFIER		"ll"

#      define TCL_LL_MODIFIER_SIZE	2

#   endif /* !TCL_LL_MODIFIER */

#   define Tcl_WideAsLong(val)		((long)((Tcl_WideInt)(val)))

#   define Tcl_LongAsWide(val)		((Tcl_WideInt)((long)(val)))

#   define Tcl_WideAsDouble(val)	((double)((Tcl_WideInt)(val)))

#   define Tcl_DoubleAsWide(val)	((Tcl_WideInt)((double)(val)))

#endif /* TCL_WIDE_INT_IS_LONG */

/*

 * This flag controls whether binary compatability is maintained with

 * extensions built against a previous version of Tcl. This is true

 * by default.

 */

#ifndef TCL_PRESERVE_BINARY_COMPATABILITY

#   define TCL_PRESERVE_BINARY_COMPATABILITY 1

#endif

/*

 * Data structures defined opaquely in this module. The definitions below

 * just provide dummy types. A few fields are made visible in Tcl_Interp

 * structures, namely those used for returning a string result from

 * commands. Direct access to the result field is discouraged in Tcl 8.0.

 * The interpreter result is either an object or a string, and the two

 * values are kept consistent unless some C code sets interp->result

 * directly. Programmers should use either the procedure Tcl_GetObjResult()

 * or Tcl_GetStringResult() to read the interpreter's result. See the

 * SetResult man page for details.

 * 

 * Note: any change to the Tcl_Interp definition below must be mirrored

 * in the "real" definition in tclInt.h.

 *

 * Note: Tcl_ObjCmdProc procedures do not directly set result and freeProc.

 * Instead, they set a Tcl_Obj member in the "real" structure that can be

 * accessed with Tcl_GetObjResult() and Tcl_SetObjResult().

 */

typedef struct Tcl_Interp {

    char *result;		/* If the last command returned a string

				 * result, this points to it. */

    void (*freeProc) _ANSI_ARGS_((char *blockPtr));

				/* Zero means the string result is

				 * statically allocated. TCL_DYNAMIC means

				 * it was allocated with ckalloc and should

				 * be freed with ckfree. Other values give

				 * the address of procedure to invoke to

				 * free the result. Tcl_Eval must free it

				 * before executing next command. */

    int errorLine;              /* When TCL_ERROR is returned, this gives

                                 * the line number within the command where

                                 * the error occurred (1 if first line). */

} Tcl_Interp;

typedef struct Tcl_AsyncHandler_ *Tcl_AsyncHandler;

typedef struct Tcl_Channel_ *Tcl_Channel;

typedef struct Tcl_Command_ *Tcl_Command;

typedef struct Tcl_Condition_ *Tcl_Condition;

typedef struct Tcl_EncodingState_ *Tcl_EncodingState;

typedef struct Tcl_Encoding_ *Tcl_Encoding;

typedef struct Tcl_Event Tcl_Event;

typedef struct Tcl_Mutex_ *Tcl_Mutex;

typedef struct Tcl_Pid_ *Tcl_Pid;

typedef struct Tcl_RegExp_ *Tcl_RegExp;

typedef struct Tcl_ThreadDataKey_ *Tcl_ThreadDataKey;

typedef struct Tcl_ThreadId_ *Tcl_ThreadId;

typedef struct Tcl_TimerToken_ *Tcl_TimerToken;

typedef struct Tcl_Trace_ *Tcl_Trace;

typedef struct Tcl_Var_ *Tcl_Var;

typedef struct Tcl_ChannelTypeVersion_ *Tcl_ChannelTypeVersion;

typedef struct Tcl_LoadHandle_ *Tcl_LoadHandle;

/*

 * Definition of the interface to procedures implementing threads.