Tcl C API

The Tcl C API (also called' Tcl library' or' Tcl C interface') is a set of public functions which can be used to create binary extensions to the Tcl language. The Tcl C API provides a portable framework in the spirit of the Apache Portable Runtime and Glib .

Documentation

latest

Version 8.4

Version 8.5

Version 8.6

Description

Tcl can be regarded as a powerful configuration language sitting on top of a bunch of C functions. Tcl's original purpose (according to Tcl's inventor John Ousterhout (see How do I use the Tcl C API?)), was to create a standard language that could be embedded in applications. Today, the typical use is via the tclsh or wish interpreters at the scripting level. In some sense, even this usage is a form of embedding Tcl into a larger application that does nothing more than provide a repl for the embedded interpreter.

The new functions that were added in Tcl 8.5 are listed in: Tcl/Tk 8.5: New public C routines

Many of the API functions make use of the Tcl_Obj structure that was introduced in Tcl 8.0.

General usage notes

The file tcl.h should be considered a public declaration of the Tcl C functions, defines/macros, and structures which a developer can safely depend on. (Some extensions also use things from tclInt.h, but the price for that is that they require more maintenance in order to keep working. Stick with tcl.h as long as possible.) Most of the actual function declarations are found in the tclDecls.h file; this has to do with the Stubs mechanism.

LV: When I look in tcl.h, I see only 3 functions listed, along with 2 tcl related #include lines - tclDecls.h and tclPlatDecls.h. Is it correct to assume that the nearly 600 functions declared as EXTERN in the two additional files (in Tcl 8.5) are all considered a part of the public API for Tcl?

Prior to Tcl version 8, the C interface for Tcl commands was string-oriented. This resulted in a lot of conversions between a string representation and other representations such as integers, doubles, lists, so in Tcl 8 included a new interface based on the Tcl_Obj C type, which in addition to a string representation can also store an internal representation, and which performs the necessary conversions between types as needed. This helped to speed up Tcl and made scripts run more efficiently.

Some functions in the API that accept Tcl_Obj argument instead of string arguments include "Obj" in their name. For example, the name1 and name2 arguments to Tcl_GetVar2() are of type const char *, whereas the part1ptr and part2Ptr argumetns to Tcl_ObjGetVar2() are of type Tcl_Obj *. Some functions that do not include "Obj" in their name nevertheless take Tcl_Obj arguments. One example is Tcl_GetString(). Its counterpart, Tcl_GetStringFromObj() additionally provides to the caller the length of the resulting string.

C function list

The following list may not be comprehensive, but the Tcl C API functions include:

Tcl_Main
Tcl_SetVar
TclFreeObj
TclTomMathInitializeStubs
Tcl_Access
Tcl_AddErrorInfo
Tcl_AddObjErrorInfo
Tcl_AlertNotifier
Tcl_Alloc
Tcl_AllocStatBuf
Tcl_AllowExceptions
Tcl_AppendAllObjTypes
Tcl_AppendElement
Tcl_AppendExportList
Tcl_AppendFormatToObj
Tcl_AppendLimitedToObj
Tcl_AppendObjToErrorInfo
Tcl_AppendObjToObj
Tcl_AppendPrintfToObj
Tcl_AppendResult
Tcl_AppendResultVA
Tcl_AppendStringsToObj
Tcl_AppendStringsToObjVA
Tcl_AppendToObj
Tcl_AppendUnicodeToObj
Tcl_AppInit
Tcl_AsyncCreate
Tcl_AsyncDelete
Tcl_AsyncInvoke
Tcl_AsyncMark
Tcl_AsyncReady
Tcl_AttemptAlloc
Tcl_AttemptDbCkalloc
Tcl_AttemptDbCkrealloc
Tcl_AttemptRealloc
Tcl_AttemptSetObjLength
Tcl_BackgroundError
Tcl_Backslash
Tcl_BadChannelOption
Tcl_CallWhenDeleted
Tcl_CancelIdleCall
Tcl_Chdir
Tcl_ClearChannelHandlers
Tcl_Close
Tcl_CommandComplete
Tcl_CommandTraceInfo
Tcl_Concat
Tcl_ConcatObj
Tcl_ConditionFinalize
Tcl_ConditionNotify
Tcl_ConditionWait
Tcl_ConvertCountedElement
Tcl_ConvertElement
Tcl_ConvertToType
Tcl_CreateAlias
Tcl_CreateAliasObj
Tcl_CreateChannel
Tcl_CreateChannelHandler
Tcl_CreateCloseHandler
Tcl_CreateCommand
Tcl_CreateEncoding
Tcl_CreateEnsemble
Tcl_CreateEventSource
Tcl_CreateExitHandler
Tcl_CreateFileHandler
Tcl_CreateHashEntry
Tcl_CreateInterp
Tcl_CreateMathFunc
Tcl_CreateNamespace
Tcl_CreateObjCommand
Tcl_CreateObjTrace
Tcl_CreateSlave
Tcl_CreateThread
Tcl_CreateThreadExitHandler
Tcl_CreateTimerHandler
Tcl_CreateTrace
Tcl_CutChannel
Tcl_DeleteAssocData
Tcl_DeleteChannelHandler
Tcl_DeleteCloseHandler
Tcl_DeleteCommand
Tcl_DeleteCommandFromToken
Tcl_DeleteEvents
Tcl_DeleteEventSource
Tcl_DeleteExitHandler
Tcl_DeleteFileHandler
Tcl_DeleteFileHandler
Tcl_DeleteHashEntry
Tcl_DeleteHashTable
Tcl_DeleteInterp
Tcl_DeleteNamespace
Tcl_DeleteThreadExitHandler
Tcl_DeleteTimerHandler
Tcl_DeleteTrace
Tcl_DetachChannel
Tcl_DetachPids
Tcl_DetachPids
Tcl_DetachPids
Tcl_DictObjDone
Tcl_DictObjFirst
Tcl_DictObjGet
Tcl_DictObjNext
Tcl_DictObjPut
Tcl_DictObjPutKeyList
Tcl_DictObjRemove
Tcl_DictObjRemoveKeyList
Tcl_DictObjSize
Tcl_DiscardInterpState
Tcl_DiscardResult
Tcl_DontCallWhenDeleted
Tcl_DoOneEvent
Tcl_DoWhenIdle
Tcl_DStringAppend
Tcl_DStringAppendElement
Tcl_DStringEndSublist
Tcl_DStringFree
Tcl_DStringGetResult
Tcl_DStringInit
Tcl_DStringResult
Tcl_DStringSetLength
Tcl_DStringStartSublist
Tcl_DumpActiveMemory
Tcl_DuplicateObj
Tcl_Eof
Tcl_ErrnoId
Tcl_ErrnoMsg
Tcl_Eval
Tcl_EvalEx
Tcl_EvalFile
Tcl_EvalObj
Tcl_EvalObjEx
Tcl_EvalObjv
Tcl_EvalTokens
Tcl_EvalTokensStandard
Tcl_EventuallyFree
Tcl_Exit
Tcl_ExitThread
Tcl_Export
Tcl_ExposeCommand
Tcl_ExprBoolean
Tcl_ExprBooleanObj
Tcl_ExprDouble
Tcl_ExprDoubleObj
Tcl_ExprLong
Tcl_ExprLongObj
Tcl_ExprObj
Tcl_ExprString
Tcl_ExternalToUtf
Tcl_ExternalToUtfDString
Tcl_Finalize
Tcl_FinalizeNotifier
Tcl_FinalizeThread
Tcl_FindCommand
Tcl_FindEnsemble
Tcl_FindExecutable
Tcl_FindHashEntry
Tcl_FindNamespace
Tcl_FirstHashEntry
Tcl_Flush
Tcl_ForgetImport
Tcl_Format
Tcl_Free
Tcl_FreeEncoding
Tcl_FreeParse
Tcl_FreeResult
Tcl_FSAccess
Tcl_FSChdir
Tcl_FSConvertToPathType
Tcl_FSCopyDirectory
Tcl_FSCopyFile
Tcl_FSCreateDirectory
Tcl_FSData
Tcl_FSDeleteFile
Tcl_FSEqualPaths
Tcl_FSEvalFile
Tcl_FSEvalFileEx
Tcl_FSFileAttrsGet
Tcl_FSFileAttrsSet
Tcl_FSFileAttrStrings
Tcl_FSFileSystemInfo
Tcl_FSGetCwd
Tcl_FSGetFileSystemForPath
Tcl_FSGetInternalRep
Tcl_FSGetNativePath
Tcl_FSGetNormalizedPath
Tcl_FSGetPathType
Tcl_FSGetTranslatedPath
Tcl_FSGetTranslatedStringPath
Tcl_FSJoinPath
Tcl_FSJoinToPath
Tcl_FSLink
Tcl_FSListVolumes
Tcl_FSLoadFile
Tcl_FSLstat
Tcl_FSMatchInDirectory
Tcl_FSMountsChanged
Tcl_FSNewNativePath
Tcl_FSOpenFileChannel
Tcl_FSPathSeparator
Tcl_FSRegister
Tcl_FSRemoveDirectory
Tcl_FSRenameFile
Tcl_FSSplitPath
Tcl_FSStat
Tcl_FSUnregister
Tcl_FSUtime
Tcl_GetAlias
Tcl_GetAliasObj
Tcl_GetAllocMutex
Tcl_GetAssocData
Tcl_GetBignumFromObj
Tcl_GetBoolean
Tcl_GetBooleanFromObj
Tcl_GetByteArrayFromObj
Tcl_GetChannel
Tcl_GetChannelBufferSize
Tcl_GetChannelError
Tcl_GetChannelErrorInterp
Tcl_GetChannelHandle -> see also Tcl_GetChannelHandle() forward compatibility
Tcl_GetChannelInstanceData
Tcl_GetChannelMode
Tcl_GetChannelName
Tcl_GetChannelNames
Tcl_GetChannelNamesEx
Tcl_GetChannelOption
Tcl_GetChannelThread
Tcl_GetChannelType
Tcl_GetCharLength
Tcl_GetCommandFromObj
Tcl_GetCommandFullName
Tcl_GetCommandInfo
Tcl_GetCommandInfoFromToken
Tcl_GetCommandName
Tcl_GetCurrentNamespace
Tcl_GetCurrentThread
Tcl_GetCwd
Tcl_GetDefaultEncodingDir
Tcl_GetDouble
Tcl_GetDoubleFromObj
Tcl_GetEncoding
Tcl_GetEncodingFromObj
Tcl_GetEncodingName
Tcl_GetEncodingNameFromEnvironment
Tcl_GetEncodingNames
Tcl_GetEncodingSearchPath
Tcl_GetEnsembleFlags
Tcl_GetEnsembleMappingDict
Tcl_GetEnsembleNamespace
Tcl_GetEnsembleSubcommandList
Tcl_GetEnsembleUnknownHandler
Tcl_GetErrno
Tcl_GetGlobalNamespace
Tcl_GetHostName
Tcl_GetIndexFromObjStruct
Tcl_GetInt
Tcl_GetInterpPath
Tcl_GetIntFromObj
Tcl_GetIndexFromObj
Tcl_GetLongFromObj
Tcl_GetMaster
Tcl_GetMathFuncInfo
Tcl_GetMemoryInfo
Tcl_GetNameOfExecutable
Tcl_GetNamespaceUnknownHandler
Tcl_GetObjResult
Tcl_GetObjType
Tcl_GetOpenFile
Tcl_GetOpenFile
Tcl_GetPathType
Tcl_GetRange
Tcl_GetRegExpFromObj
Tcl_GetReturnOptions
Tcl_Gets
Tcl_GetServiceMode
Tcl_GetSlave
Tcl_GetsObj
Tcl_GetStackedChannel
Tcl_GetStdChannel
Tcl_GetString
Tcl_GetStringFromObj
Tcl_GetStringResult -> see also Tcl_GetStringResult() forward compatibility
Tcl_GetThreadData
Tcl_GetTime
Tcl_GetTopChannel
Tcl_GetUniChar
Tcl_GetUnicode
Tcl_GetUnicodeFromObj
Tcl_GetVar
Tcl_GetVar2
Tcl_GetVar2Ex
Tcl_GetVersion
Tcl_GetWideIntFromObj
Tcl_GlobalEval
Tcl_GlobalEvalObj
Tcl_HashStats
Tcl_HideCommand
Tcl_Import
Tcl_Init
Tcl_InitBignumFromDouble
Tcl_InitCustomHashTable
Tcl_InitHashTable
Tcl_InitMemory
Tcl_InitNotifier
Tcl_InitObjHashTable
Tcl_InitStubs
Tcl_InputBlocked
Tcl_InputBuffered
Tcl_InterpDeleted
Tcl_InvalidateStringRep
Tcl_IsChannelExisting
Tcl_IsChannelRegistered
Tcl_IsChannelShared
Tcl_IsEnsemble
Tcl_IsSafe
Tcl_IsStandardChannel
Tcl_JoinPath
Tcl_JoinThread
Tcl_LimitAddHandler
Tcl_LimitCheck
Tcl_LimitExceeded
Tcl_LimitGetCommands
Tcl_LimitGetGranularity
Tcl_LimitGetTime
Tcl_LimitReady
Tcl_LimitRemoveHandler
Tcl_LimitSetCommands
Tcl_LimitSetGranularity
Tcl_LimitSetTime
Tcl_LimitTypeEnabled
Tcl_LimitTypeExceeded
Tcl_LimitTypeReset
Tcl_LimitTypeSet
Tcl_LinkVar
Tcl_ListMathFuncs
Tcl_ListObjAppendElement
Tcl_ListObjAppendList
Tcl_ListObjGetElements
Tcl_ListObjIndex
Tcl_ListObjLength
Tcl_ListObjReplace
Tcl_LogCommandInfo
Tcl_MacOSXOpenBundleResources
Tcl_MacOSXOpenVersionedBundleResources
Tcl_MakeFileChannel
Tcl_MakeSafe
Tcl_MakeTcpClientChannel
Tcl_Merge
Tcl_MutexFinalize
Tcl_MutexLock
Tcl_MutexUnlock
Tcl_NewBignumObj
Tcl_NewBooleanObj
Tcl_NewByteArrayObj
Tcl_NewDictObj
Tcl_NewDoubleObj
Tcl_NewIntObj
Tcl_NewListObj
Tcl_NewLongObj
Tcl_NewObj
Tcl_NewStringObj
Tcl_NewUnicodeObj
Tcl_NewWideIntObj
Tcl_NextHashEntry
Tcl_NotifyChannel
Tcl_NumUtfChars
Tcl_ObjGetVar2
Tcl_ObjPrintf
Tcl_ObjSetVar2
Tcl_OpenCommandChannel
Tcl_OpenCommandChannel
Tcl_OpenCommandChannel
Tcl_OpenFileChannel
Tcl_OpenTcpClient
Tcl_OpenTcpServer
Tcl_OutputBuffered
Tcl_Panic
Tcl_PanicVA
Tcl_ParseBraces
Tcl_ParseCommand
Tcl_ParseExpr
Tcl_ParseQuotedString
Tcl_ParseVar
Tcl_ParseVarName
Tcl_PkgInitStubsCheck
Tcl_PkgPresent -> see also Tcl_PkgPresent() forward compatibility
Tcl_PkgPresentEx
Tcl_PkgProvide
Tcl_PkgProvideEx
Tcl_PkgRequire
Tcl_PkgRequireEx
Tcl_PkgRequireProc
Tcl_PosixError
Tcl_Preserve
Tcl_PrintDouble
Tcl_ProcObjCmd
Tcl_PutEnv
Tcl_QueryTimeProc
Tcl_QueueEvent
Tcl_Read
Tcl_ReadChars
Tcl_ReadRaw
Tcl_Realloc
Tcl_ReapDetachedProcs
Tcl_ReapDetachedProcs
Tcl_ReapDetachedProcs
Tcl_RecordAndEval
Tcl_RecordAndEvalObj
Tcl_RegExpCompile
Tcl_RegExpExec
Tcl_RegExpExecObj
Tcl_RegExpGetInfo
Tcl_RegExpMatch
Tcl_RegExpMatchObj
Tcl_RegExpRange
Tcl_RegisterChannel
Tcl_RegisterConfig
Tcl_RegisterObjType
Tcl_Release
Tcl_ResetResult
Tcl_RestoreInterpState
Tcl_RestoreResult
Tcl_SaveInterpState
Tcl_SaveResult -> see also Tcl_SaveResult() forward compatibility
Tcl_ScanCountedElement
Tcl_ScanElement
Tcl_Seek
Tcl_SeekOld
Tcl_ServiceAll
Tcl_ServiceEvent
Tcl_ServiceModeHook
Tcl_SetAssocData
Tcl_SetBignumObj
Tcl_SetBooleanObj
Tcl_SetByteArrayLength
Tcl_SetByteArrayObj
Tcl_SetChannelBufferSize
Tcl_SetChannelError
Tcl_SetChannelErrorInterp
Tcl_SetChannelOption
Tcl_SetCommandInfo
Tcl_SetCommandInfoFromToken
Tcl_SetDefaultEncodingDir
Tcl_SetDoubleObj
Tcl_SetEncodingSearchPath
Tcl_SetEnsembleFlags
Tcl_SetEnsembleMappingDict
Tcl_SetEnsembleSubcommandList
Tcl_SetEnsembleUnknownHandler
Tcl_SetErrno
Tcl_SetErrorCode
Tcl_SetErrorCodeVA
Tcl_SetExitProc
Tcl_SetIntObj
Tcl_SetListObj
Tcl_SetLongObj
Tcl_SetMainLoop
Tcl_SetMaxBlockTime
Tcl_SetNamespaceUnknownHandler
Tcl_SetNotifier
Tcl_SetObjErrorCode
Tcl_SetObjLength
Tcl_SetObjResult
Tcl_SetPanicProc
Tcl_SetRecursionLimit
Tcl_SetResult
Tcl_SetReturnOptions
Tcl_SetServiceMode
Tcl_SetStdChannel
Tcl_SetStringObj
Tcl_SetSystemEncoding
Tcl_SetTimeProc
Tcl_SetTimer
Tcl_SetUnicodeObj
Tcl_SetVar2
Tcl_SetVar2Ex
Tcl_SetWideIntObj
Tcl_SignalId
Tcl_SignalMsg
Tcl_Sleep
Tcl_SourceRCFile
Tcl_SpliceChannel
Tcl_SplitList
Tcl_SplitPath
Tcl_StackChannel
Tcl_Stat
Tcl_StaticPackage
Tcl_StringCaseMatch
Tcl_StringMatch
Tcl_SubstObj
Tcl_TakeBignumFromObj
Tcl_Tell
Tcl_TellOld
Tcl_ThreadAlert
Tcl_ThreadQueueEvent
Tcl_TraceCommand
Tcl_TraceVar
Tcl_TraceVar2
Tcl_TranslateFileName
Tcl_TruncateChannel
Tcl_Ungets
Tcl_UnlinkVar
Tcl_UnregisterChannel
Tcl_UnsetVar
Tcl_UnsetVar2
Tcl_UnstackChannel
Tcl_UntraceCommand
Tcl_UntraceVar
Tcl_UntraceVar2
Tcl_UpdateLinkedVar
Tcl_UpVar
Tcl_UpVar2
Tcl_ValidateAllMemory
Tcl_VarEval
Tcl_VarEvalVA
Tcl_VarTraceInfo
Tcl_VarTraceInfo2
Tcl_WaitForEvent
Tcl_WaitPid
Tcl_WinTCharToUtf
Tcl_WinUtfToTChar
Tcl_Write
Tcl_WriteChars
Tcl_WriteObj
Tcl_WriteRaw
Tcl_WrongNumArgs

Db

Tcl_DbCkalloc
Tcl_DbCkfree
Tcl_DbCkrealloc
Tcl_DbDecrRefCount
Tcl_DbIncrRefCount
Tcl_DbIsShared
Tcl_DbNewBignumObj
Tcl_DbNewBooleanObj
Tcl_DbNewByteArrayObj
Tcl_DbNewDictObj
Tcl_DbNewDoubleObj
Tcl_DbNewListObj
Tcl_DbNewLongObj
Tcl_DbNewObj
Tcl_DbNewStringObj
Tcl_DbNewWideIntObj

Unicode

Tcl_UniCharAtIndex
Tcl_UniCharCaseMatch
Tcl_UniCharIsAlnum
Tcl_UniCharIsAlpha
Tcl_UniCharIsControl
Tcl_UniCharIsDigit
Tcl_UniCharIsGraph
Tcl_UniCharIsLower
Tcl_UniCharIsPrint
Tcl_UniCharIsPunct
Tcl_UniCharIsSpace
Tcl_UniCharIsUpper
Tcl_UniCharIsWordChar
Tcl_UniCharLen
Tcl_UniCharNcasecmp
Tcl_UniCharNcmp
Tcl_UniCharToLower
Tcl_UniCharToTitle
Tcl_UniCharToUpper
Tcl_UniCharToUtf
Tcl_UniCharToUtfDString

UTF-8

Tcl_UtfAtIndex
Tcl_UtfBackslash
Tcl_UtfCharComplete
Tcl_UtfFindFirst
Tcl_UtfFindLast
Tcl_UtfNcasecmp
Tcl_UtfNcmp
Tcl_UtfNext
Tcl_UtfPrev
Tcl_UtfToExternal
Tcl_UtfToExternalDString
Tcl_UtfToLower
Tcl_UtfToTitle
Tcl_UtfToUniChar
Tcl_UtfToUniCharDString
Tcl_UtfToUpper

ZLib

Tcl_ZlibAdler32
Tcl_ZlibCRC32
Tcl_ZlibDeflate
Tcl_ZlibInflate
Tcl_ZlibStreamChecksum
Tcl_ZlibStreamClose
Tcl_ZlibStreamEof
Tcl_ZlibStreamGet
Tcl_ZlibStreamGetCommandName
Tcl_ZlibStreamInit
Tcl_ZlibStreamPut

Tcl C structures

Other notes

[A list by topic (where related functions are collected together) should be more useful, as the HTML docs already provide this kind of alphabetic list.] [Feel free to organize data on the wiki in the way that helps you most - or seems to be most helpful.] [Yeap, that is kind of challenging...]

Category Tcl Library