Tcl Source Code

char *
\fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
.sp
int
\fBTcl_UtfToExternalDStringEx\fR(\fIinterp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr\fR)
.sp
int
\fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)

.sp
int
\fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)

.sp
const char *
\fBTcl_GetEncodingName\fR(\fIencoding\fR)
.sp
Tcl_Size
\fBTcl_GetEncodingNulLength\fR(\fIencoding\fR)
.sp

.BS
.SH NAME
Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfToChar16, Tcl_UtfToWChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_Char16ToUtfDString, Tcl_UtfToWCharDString, Tcl_UtfToChar16DString, Tcl_WCharToUtfDString, Tcl_WCharLen, Tcl_Char16Len, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharNcasecmp, Tcl_UniCharCaseMatch, Tcl_UtfNcmp, Tcl_UtfNcasecmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash \- routines for manipulating UTF-8 strings
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp


Tcl_Size
\fBTcl_UniCharToUtf\fR(\fIch, buf\fR)
.sp
Tcl_Size
\fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR)
.sp
Tcl_Size

---
CommandName: Tcl_AppInit
ManualSection: 3
Version: 7.0
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_Main(3)
Keywords:
 - application
 - argument
 - command
 - initialization
 - interpreter
Copyright:
 - Copyright (c) 1993 The Regents of the University of California.
 - Copyright (c) 1994-1996 Sun Microsystems, Inc.
---

# Name

Tcl_AppInit - perform application-specific initialization

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[int]{.ret} [Tcl_AppInit]{.ccmd}[interp]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter for the application. 

# Description

**Tcl_AppInit** is a "hook" procedure that is invoked by the main programs for Tcl applications such as **tclsh** and **wish**. Its purpose is to allow new Tcl applications to be created without modifying the main programs provided as part of Tcl and Tk. To create a new application you write a new version of **Tcl_AppInit** to replace the default version provided by Tcl, then link your new **Tcl_AppInit** with the Tcl library.

**Tcl_AppInit** is invoked by **Tcl_Main** and **Tk_Main** after their own initialization and before entering the main loop to process commands. Here are some examples of things that **Tcl_AppInit** might do:

1. Call initialization procedures for various packages used by the application. Each initialization procedure adds new commands to *interp* for its package and performs other package-specific initialization.

2. Process command-line arguments, which can be accessed from the Tcl variables **argv** and **argv0** in *interp*.

3. Invoke a startup script to initialize the application.

4. Use the routines **Tcl_SetStartupScript** and **Tcl_GetStartupScript** to set or query the file and encoding that the active **Tcl_Main** or **Tk_Main** routine will use as a startup script. .LP **Tcl_AppInit** returns **TCL_OK** or **TCL_ERROR**. If it returns **TCL_ERROR** then it must leave an error message in for the interpreter's result;  otherwise the result is ignored.


In addition to **Tcl_AppInit**, your application should also contain a procedure **main** that calls **Tcl_Main** as follows:

```
Tcl_Main(argc, argv, Tcl_AppInit);
```

The third argument to **Tcl_Main** gives the address of the application-specific initialization procedure to invoke. This means that you do not have to use the name **Tcl_AppInit** for the procedure, but in practice the name is nearly always **Tcl_AppInit** (in versions before Tcl 7.4 the name **Tcl_AppInit** was implicit;  there was no way to specify the procedure explicitly). The best way to get started is to make a copy of the file **tclAppInit.c** from the Tcl library or source directory. It already contains a **main** procedure and a template for **Tcl_AppInit** that you can modify for your application. 

---
CommandName: Tcl_SetAssocData
ManualSection: 3
Version: 7.5
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - association
 - data
 - deletion procedure
 - interpreter
 - key
Copyright:
 - Copyright (c) 1995-1996 Sun Microsystems, Inc.
---

# Name

Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData - manage associations of string keys and user specified data with Tcl interpreters

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[void *]{.ret} [Tcl_GetAssocData]{.ccmd}[interp, key, delProcPtr]{.cargs}
[Tcl_SetAssocData]{.ccmd}[interp, key, delProc, clientData]{.cargs}
[Tcl_DeleteAssocData]{.ccmd}[interp, key]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter in which to execute the specified command. .AP "const char" *key in Key for association with which to store data or from which to delete or retrieve data.  Typically the module prefix for a package. .AP Tcl_InterpDeleteProc *delProc in Procedure to call when *interp* is deleted. .AP Tcl_InterpDeleteProc **delProcPtr in Pointer to location in which to store address of current deletion procedure for association.  Ignored if NULL. .AP void *clientData in Arbitrary one-word value associated with the given key in this interpreter.  This data is owned by the caller. 

# Description

These procedures allow extensions to associate their own data with a Tcl interpreter. An association consists of a string key, typically the name of the extension, and a one-word value, which is typically a pointer to a data structure holding data specific to the extension. Tcl makes no interpretation of either the key or the value for an association.

Storage management is facilitated by storing with each association a procedure to call when the interpreter is deleted. This procedure can dispose of the storage occupied by the client's data in any way it sees fit.

**Tcl_SetAssocData** creates an association between a string key and a user specified datum in the given interpreter. If there is already an association with the given *key*, **Tcl_SetAssocData** overwrites it with the new information. It is up to callers to organize their use of names to avoid conflicts, for example, by using package names as the keys. If the *deleteProc* argument is non-NULL it specifies the address of a procedure to invoke if the interpreter is deleted before the association is deleted.  *DeleteProc* should have arguments and result that match the type **Tcl_InterpDeleteProc**:

```
typedef void Tcl_InterpDeleteProc(
        void *clientData,
        Tcl_Interp *interp);
```

When *deleteProc* is invoked the *clientData* and *interp* arguments will be the same as the corresponding arguments passed to **Tcl_SetAssocData**. The deletion procedure will *not* be invoked if the association is deleted before the interpreter is deleted.

**Tcl_GetAssocData** returns the datum stored in the association with the specified key in the given interpreter, and if the *delProcPtr* field is non-**NULL**, the address indicated by it gets the address of the delete procedure stored with this association. If no association with the specified key exists in the given interpreter **Tcl_GetAssocData** returns **NULL**.

**Tcl_DeleteAssocData** deletes an association with a specified key in the given interpreter.  Then it calls the deletion procedure.

---
CommandName: Tcl_BackgroundError
ManualSection: 3
Version: 7.5
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - background
 - bgerror
 - error
 - interp
Copyright:
 - Copyright (c) 1992-1994 The Regents of the University of California.
 - Copyright (c) 1994-1996 Sun Microsystems, Inc.
---

# Name

Tcl_BackgroundException, Tcl_BackgroundError - report Tcl exception that occurred in background processing

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_BackgroundException]{.ccmd}[interp, code]{.cargs}
[Tcl_BackgroundError]{.ccmd}[interp]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter in which the exception occurred. .AP int code in The exceptional return code to be reported. 

# Description

This procedure is typically invoked when a Tcl exception (any return code other than TCL_OK) occurs during "background processing" such as executing an event handler. When such an exception occurs, the condition is reported to Tcl or to a widget or some other C code, and there is not usually any obvious way for that code to report the exception to the user. In these cases the code calls **Tcl_BackgroundException** with an *interp* argument identifying the interpreter in which the exception occurred, and a *code* argument holding the return code value of the exception.  The state of the interpreter, including any error message in the interpreter result, and the values of any entries in the return options dictionary, is captured and saved.  **Tcl_BackgroundException** then arranges for the event loop to invoke at some later time the command registered in that interpreter to handle background errors by the **interp bgerror** command, passing the captured values as arguments. The registered handler command is meant to report the exception in an application-specific fashion.  The handler command receives two arguments, the result of the interp, and the return options of the interp at the time the error occurred. If the application registers no handler command, the default handler command will attempt to call **bgerror** to report the error.  If an error condition arises while invoking the handler command, then **Tcl_BackgroundException** reports the error itself by printing a message on the standard error file.

**Tcl_BackgroundException** does not invoke the handler command immediately because this could potentially interfere with scripts that are in process at the time the error occurred. Instead, it invokes the handler command later as an idle callback.

It is possible for many background exceptions to accumulate before the handler command is invoked.  When this happens, each of the exceptions is processed in order.  However, if the handler command returns a break exception, then all remaining error reports for the interpreter are skipped.

The **Tcl_BackgroundError** routine is an older and simpler interface useful when the exception code reported is **TCL_ERROR**.  It is equivalent to:

```
Tcl_BackgroundException(interp, TCL_ERROR);
```

---
CommandName: Tcl_CallWhenDeleted
ManualSection: 3
Version: 7.0
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_CreateExitHandler(3)
 - Tcl_CreateThreadExitHandler(3)
Keywords:
 - callback
 - cleanup
 - delete
 - interpreter
Copyright:
 - Copyright (c) 1993 The Regents of the University of California.
 - Copyright (c) 1994-1996 Sun Microsystems, Inc.
---

# Name

Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted - Arrange for callback when interpreter is deleted

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_CallWhenDeleted]{.ccmd}[interp=, +proc=, +clientData]{.cargs}
[Tcl_DontCallWhenDeleted]{.ccmd}[interp=, +proc=, +clientData]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter with which to associated callback. .AP Tcl_InterpDeleteProc *proc in Procedure to call when *interp* is deleted. .AP void *clientData in Arbitrary one-word value to pass to *proc*.

# Description

**Tcl_CallWhenDeleted** arranges for *proc* to be called by **Tcl_DeleteInterp** if/when *interp* is deleted at some future time.  *Proc* will be invoked just before the interpreter is deleted, but the interpreter will still be valid at the time of the call. *Proc* should have arguments and result that match the type **Tcl_InterpDeleteProc**:

```
typedef void Tcl_InterpDeleteProc(
        void *clientData,
        Tcl_Interp *interp);
```

The *clientData* and *interp* parameters are copies of the *clientData* and *interp* arguments given to **Tcl_CallWhenDeleted**. Typically, *clientData* points to an application-specific data structure that *proc* uses to perform cleanup when an interpreter is about to go away. *Proc* does not return a value.

**Tcl_DontCallWhenDeleted** cancels a previous call to **Tcl_CallWhenDeleted** with the same arguments, so that *proc* will not be called after all when *interp* is deleted. If there is no deletion callback that matches *interp*, *proc*, and *clientData* then the call to **Tcl_DontCallWhenDeleted** has no effect.

Note that if the callback is being used to delete a resource that *must* be released on exit, **Tcl_CreateExitHandler** should be used to ensure that a callback is received even if the application terminates without deleting the interpreter.

---
CommandName: Tcl_CreateChannel
ManualSection: 3
Version: 8.4
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_Close(3)
 - Tcl_OpenFileChannel(3)
 - Tcl_SetErrno(3)
 - Tcl_QueueEvent(3)
 - Tcl_StackChannel(3)
 - Tcl_GetStdChannel(3)
Keywords:
 - blocking
 - channel driver
 - channel registration
 - channel type
 - nonblocking
Copyright:
 - Copyright (c) 1996-1997 Sun Microsystems, Inc.
 - Copyright (c) 1997-2000 Ajuba Solutions.
---

# Name

Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered - procedures for creating and manipulating channels

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_Channel]{.ret} [Tcl_CreateChannel]{.ccmd}[typePtr, channelName, instanceData, mask]{.cargs}
[void *]{.ret} [Tcl_GetChannelInstanceData]{.ccmd}[channel]{.cargs}
[const Tcl_ChannelType *]{.ret} [Tcl_GetChannelType]{.ccmd}[channel]{.cargs}
[const char *]{.ret} [Tcl_GetChannelName]{.ccmd}[channel]{.cargs}
[int]{.ret} [Tcl_GetChannelHandle]{.ccmd}[channel, direction, handlePtr]{.cargs}
[Tcl_ThreadId]{.ret} [Tcl_GetChannelThread]{.ccmd}[channel]{.cargs}
[int]{.ret} [Tcl_GetChannelMode]{.ccmd}[channel]{.cargs}
[int]{.ret} [Tcl_RemoveChannelMode]{.ccmd}[interp, channel, mode]{.cargs}
[int]{.ret} [Tcl_GetChannelBufferSize]{.ccmd}[channel]{.cargs}
[Tcl_SetChannelBufferSize]{.ccmd}[channel, size]{.cargs}
[Tcl_NotifyChannel]{.ccmd}[channel, mask]{.cargs}
[int]{.ret} [Tcl_BadChannelOption]{.ccmd}[interp, optionName, optionList]{.cargs}
[int]{.ret} [Tcl_IsChannelShared]{.ccmd}[channel]{.cargs}
[int]{.ret} [Tcl_IsChannelRegistered]{.ccmd}[interp, channel]{.cargs}
[int]{.ret} [Tcl_IsChannelExisting]{.ccmd}[channelName]{.cargs}
[Tcl_CutChannel]{.ccmd}[channel]{.cargs}
[Tcl_SpliceChannel]{.ccmd}[channel]{.cargs}
[Tcl_ClearChannelHandlers]{.ccmd}[channel]{.cargs}
[int]{.ret} [Tcl_ChannelBuffered]{.ccmd}[channel]{.cargs}
[const char *]{.ret} [Tcl_ChannelName]{.ccmd}[typePtr]{.cargs}
[Tcl_ChannelTypeVersion]{.ret} [Tcl_ChannelVersion]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverBlockModeProc *]{.ret} [Tcl_ChannelBlockModeProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverClose2Proc *]{.ret} [Tcl_ChannelClose2Proc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverInputProc *]{.ret} [Tcl_ChannelInputProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverOutputProc *]{.ret} [Tcl_ChannelOutputProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverWideSeekProc *]{.ret} [Tcl_ChannelWideSeekProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverThreadActionProc *]{.ret} [Tcl_ChannelThreadActionProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverTruncateProc *]{.ret} [Tcl_ChannelTruncateProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverSetOptionProc *]{.ret} [Tcl_ChannelSetOptionProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverGetOptionProc *]{.ret} [Tcl_ChannelGetOptionProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverWatchProc *]{.ret} [Tcl_ChannelWatchProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverGetHandleProc *]{.ret} [Tcl_ChannelGetHandleProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverFlushProc *]{.ret} [Tcl_ChannelFlushProc]{.ccmd}[typePtr]{.cargs}
[Tcl_DriverHandlerProc *]{.ret} [Tcl_ChannelHandlerProc]{.ccmd}[typePtr]{.cargs}
:::

# Arguments

.AP "const Tcl_ChannelType" *typePtr in Points to a structure containing the addresses of procedures that can be called to perform I/O and other functions on the channel. .AP "const char" *channelName in The name of this channel, such as **file3**; must not be in use by any other channel. Can be NULL, in which case the channel is created without a name. If the created channel is assigned to one of the standard channels (**stdin**, **stdout** or **stderr**), the assigned channel name will be the name of the standard channel. .AP void *instanceData in Arbitrary one-word value to be associated with this channel.  This value is passed to procedures in *typePtr* when they are invoked. .AP int mask in OR-ed combination of **TCL_READABLE** and **TCL_WRITABLE** to indicate whether a channel is readable and writable. .AP Tcl_Channel channel in The channel to operate on. .AP int direction in **TCL_READABLE** means the input handle is wanted; **TCL_WRITABLE** means the output handle is wanted. .AP void **handlePtr out Points to the location where the desired OS-specific handle should be stored. .AP Tcl_Size size in The size, in bytes, of buffers to allocate in this channel. .AP int mask in An OR-ed combination of **TCL_READABLE**, **TCL_WRITABLE** and **TCL_EXCEPTION** that indicates events that have occurred on this channel. .AP Tcl_Interp *interp in Current interpreter. (can be NULL) .AP "const char" *optionName in Name of the invalid option. .AP "const char" *optionList in Specific options list (space separated words, without "-") to append to the standard generic options list. Can be NULL for generic options error message only.

# Description

Tcl uses a two-layered channel architecture. It provides a generic upper layer to enable C and Tcl programs to perform input and output using the same APIs for a variety of files, devices, sockets etc. The generic C APIs are described in the manual entry for **Tcl_OpenFileChannel**.

The lower layer provides type-specific channel drivers for each type of device supported on each platform.  This manual entry describes the C APIs used to communicate between the generic layer and the type-specific channel drivers.  It also explains how new types of channels can be added by providing new channel drivers.

Channel drivers consist of a number of components: First, each channel driver provides a **Tcl_ChannelType** structure containing pointers to functions implementing the various operations used by the generic layer to communicate with the channel driver. The **Tcl_ChannelType** structure and the functions referenced by it are described in the section **TCL_CHANNELTYPE**, below.

Second, channel drivers usually provide a Tcl command to create instances of that type of channel. For example, the Tcl **open** command creates channels that use the file and command channel drivers, and the Tcl **socket** command creates channels that use TCP sockets for network communication.

Third, a channel driver optionally provides a C function to open channel instances of that type. For example, **Tcl_OpenFileChannel** opens a channel that uses the file channel driver, and **Tcl_OpenTcpClient** opens a channel that uses the TCP network protocol.  These creation functions typically use **Tcl_CreateChannel** internally to open the channel.

To add a new type of channel you must implement a C API or a Tcl command that opens a channel by invoking **Tcl_CreateChannel**. When your driver calls **Tcl_CreateChannel** it passes in a **Tcl_ChannelType** structure describing the driver's I/O procedures. The generic layer will then invoke the functions referenced in that structure to perform operations on the channel.

**Tcl_CreateChannel** opens a new channel and associates the supplied *typePtr* and *instanceData* with it. The channel is opened in the mode indicated by *mask*. For a discussion of channel drivers, their operations and the **Tcl_ChannelType** structure, see the section **TCL_CHANNELTYPE**, below.

**Tcl_CreateChannel** interacts with the code managing the standard channels. Once a standard channel was initialized either through a call to **Tcl_GetStdChannel** or a call to **Tcl_SetStdChannel** closing this standard channel will cause the next call to **Tcl_CreateChannel** to make the new channel the new standard channel too. See **Tcl_StandardChannels** for a general treatise about standard channels and the behavior of the Tcl library with regard to them.

**Tcl_GetChannelInstanceData** returns the instance data associated with the channel in *channel*. This is the same as the *instanceData* argument in the call to **Tcl_CreateChannel** that created this channel.

**Tcl_GetChannelType** returns a pointer to the **Tcl_ChannelType** structure used by the channel in the *channel* argument. This is the same as the *typePtr* argument in the call to **Tcl_CreateChannel** that created this channel.

**Tcl_GetChannelName** returns a string containing the name associated with the channel, or NULL if the *channelName* argument to **Tcl_CreateChannel** was NULL.

**Tcl_GetChannelHandle** places the OS-specific device handle associated with *channel* for the given *direction* in the location specified by *handlePtr* and returns **TCL_OK**.  If the channel does not have a device handle for the specified direction, then **TCL_ERROR** is returned instead.  Different channel drivers will return different types of handle.  Refer to the manual entries for each driver to determine what type of handle is returned.

**Tcl_GetChannelThread** returns the id of the thread currently managing the specified *channel*. This allows channel drivers to send their file events to the correct event queue even for a multi-threaded core.

**Tcl_GetChannelMode** returns an OR-ed combination of **TCL_READABLE** and **TCL_WRITABLE**, indicating whether the channel is open for input and output.

**Tcl_RemoveChannelMode** removes an access privilege from the channel, either **TCL_READABLE** or **TCL_WRITABLE**, and returns a regular Tcl result code, **TCL_OK**, or **TCL_ERROR**. The function throws an error if either an invalid mode is specified or the result of the removal would be an inaccessible channel. In that case an error message is left in the interp argument, if not NULL.

**Tcl_GetChannelBufferSize** returns the size, in bytes, of buffers allocated to store input or output in *channel*. If the value was not set by a previous call to **Tcl_SetChannelBufferSize**, described below, then the default value of 4096 is returned.

**Tcl_SetChannelBufferSize** sets the size, in bytes, of buffers that will be allocated in subsequent operations on the channel to store input or output. The *size* argument should be between one and one million, allowing buffers of one byte to one million bytes. If *size* is outside this range, **Tcl_SetChannelBufferSize** sets the buffer size to 4096.

**Tcl_NotifyChannel** is called by a channel driver to indicate to the generic layer that the events specified by *mask* have occurred on the channel.  Channel drivers are responsible for invoking this function whenever the channel handlers need to be called for the channel (or other pending tasks like a write flush should be performed). See **WATCHPROC** below for more details.

**Tcl_BadChannelOption** is called from driver specific *setOptionProc* or *getOptionProc* to generate a complete error message.

**Tcl_ChannelBuffered** returns the number of bytes of input currently buffered in the internal buffer (push back area) of the channel itself. It does not report about the data in the overall buffers for the stack of channels the supplied channel is part of.

**Tcl_IsChannelShared** checks the refcount of the specified *channel* and returns whether the *channel* was shared among multiple interpreters (result == 1) or not (result == 0).

**Tcl_IsChannelRegistered** checks whether the specified *channel* is registered in the given *interp*reter (result == 1) or not (result == 0).

**Tcl_IsChannelExisting** checks whether a channel with the specified name is registered in the (thread)-global list of all channels (result == 1) or not (result == 0).

**Tcl_CutChannel** removes the specified *channel* from the (thread)global list of all channels (of the current thread). Application to a channel still registered in some interpreter is not allowed. Also notifies the driver if **Tcl_DriverThreadActionProc** is defined for it.

**Tcl_SpliceChannel** adds the specified *channel* to the (thread)global list of all channels (of the current thread). Application to a channel registered in some interpreter is not allowed. Also notifies the driver if **Tcl_DriverThreadActionProc** is defined for it.

**Tcl_ClearChannelHandlers** removes all channel handlers and event scripts associated with the specified *channel*, thus shutting down all event processing for this channel.

# Tcl_channeltype

A channel driver provides a **Tcl_ChannelType** structure that contains pointers to functions that implement the various operations on a channel; these operations are invoked as needed by the generic layer.  The structure was versioned starting in Tcl 8.3.2/8.4 to correct a problem with stacked channel drivers.  See the **OLD CHANNEL TYPES** section below for details about the old structure.

The **Tcl_ChannelType** structure contains the following fields:

```
typedef struct {
        const char *typeName;
        Tcl_ChannelTypeVersion version;
        void *closeProc; /* Not used any more*/
        Tcl_DriverInputProc *inputProc;
        Tcl_DriverOutputProc *outputProc;
        void *seekProc; /* Not used any more */
        Tcl_DriverSetOptionProc *setOptionProc;
        Tcl_DriverGetOptionProc *getOptionProc;
        Tcl_DriverWatchProc *watchProc;
        Tcl_DriverGetHandleProc *getHandleProc;
        Tcl_DriverClose2Proc *close2Proc;
        Tcl_DriverBlockModeProc *blockModeProc;
        Tcl_DriverFlushProc *flushProc;
        Tcl_DriverHandlerProc *handlerProc;
        Tcl_DriverWideSeekProc *wideSeekProc;
        Tcl_DriverThreadActionProc *threadActionProc;
        Tcl_DriverTruncateProc *truncateProc;
} Tcl_ChannelType;
```

It is not necessary to provide implementations for all channel operations.  Those which are not necessary may be set to NULL in the struct: *blockModeProc*, *seekProc*, *setOptionProc*, *getOptionProc*, *getHandleProc*, and *close2Proc*, in addition to *flushProc*, *handlerProc*, *threadActionProc*, and *truncateProc*.  Other functions that cannot be implemented in a meaningful way should return **EINVAL** when called, to indicate that the operations they represent are not available. Also note that *wideSeekProc* can be NULL if *seekProc* is.

The user should only use the above structure for **Tcl_ChannelType** instantiation.  When referencing fields in a **Tcl_ChannelType** structure, the following functions should be used to obtain the values: **Tcl_ChannelName**, **Tcl_ChannelVersion**, **Tcl_ChannelBlockModeProc**, **Tcl_ChannelClose2Proc**, **Tcl_ChannelInputProc**, **Tcl_ChannelOutputProc**, **Tcl_ChannelWideSeekProc**, **Tcl_ChannelThreadActionProc**, **Tcl_ChannelTruncateProc**, **Tcl_ChannelSetOptionProc**, **Tcl_ChannelGetOptionProc**, **Tcl_ChannelWatchProc**, **Tcl_ChannelGetHandleProc**, **Tcl_ChannelFlushProc**, or **Tcl_ChannelHandlerProc**.

The change to the structures was made in such a way that standard channel types are binary compatible.  However, channel types that use stacked channels (i.e. TLS, Trf) have new versions to correspond to the above change since the previous code for stacked channels had problems.

## Typename

The *typeName* field contains a null-terminated string that identifies the type of the device implemented by this driver, e.g. **file** or **socket**.

This value can be retrieved with **Tcl_ChannelName**, which returns a pointer to the string.

## Version

The *version* field should be set to the version of the structure that you require. **TCL_CHANNEL_VERSION_5** is the minimum supported.

This value can be retrieved with **Tcl_ChannelVersion**.

## Blockmodeproc

The *blockModeProc* field contains the address of a function called by the generic layer to set blocking and nonblocking mode on the device. *BlockModeProc* should match the following prototype:

```
typedef int Tcl_DriverBlockModeProc(
        void *instanceData,
        int mode);
```

The *instanceData* is the same as the value passed to **Tcl_CreateChannel** when this channel was created.  The *mode* argument is either **TCL_MODE_BLOCKING** or **TCL_MODE_NONBLOCKING** to set the device into blocking or nonblocking mode. The function should return zero if the operation was successful, or a nonzero POSIX error code if the operation failed.

If the operation is successful, the function can modify the supplied *instanceData* to record that the channel entered blocking or nonblocking mode and to implement the blocking or nonblocking behavior. For some device types, the blocking and nonblocking behavior can be implemented by the underlying operating system; for other device types, the behavior must be emulated in the channel driver.

This value can be retrieved with **Tcl_ChannelBlockModeProc**, which returns a pointer to the function.

A channel driver **not** supplying a *blockModeProc* has to be very, very careful. It has to tell the generic layer exactly which blocking mode is acceptable to it, and should this also document for the user so that the blocking mode of the channel is not changed to an unacceptable value. Any confusion here may lead the interpreter into a (spurious and difficult to find) deadlock.

## Close2proc

The *close2Proc* field contains the address of a function called by the generic layer to clean up driver-related information when the channel is closed. *Close2Proc* must match the following prototype:

```
typedef int Tcl_DriverClose2Proc(
        void *instanceData,
        Tcl_Interp *interp,
        int flags);
```

If *flags* is 0, the *instanceData* argument is the same as the value provided to **Tcl_CreateChannel** when the channel was created. The function should release any storage maintained by the channel driver for this channel, and close the input and output devices encapsulated by this channel. All queued output will have been flushed to the device before this function is called, and no further driver operations will be invoked on this instance after calling the *closeProc*. If the close operation is successful, the procedure should return zero; otherwise it should return a nonzero POSIX error code. In addition, if an error occurs and *interp* is not NULL, the procedure should store an error message in the interpreter's result.

Alternatively, channels that support closing the read and write sides independently may accept other flag values than 0. Then *close2Proc* will be called with *flags* set to an OR'ed combination of **TCL_CLOSE_READ** or **TCL_CLOSE_WRITE** to indicate that the driver should close the read and/or write side of the channel.  The channel driver may be invoked to perform additional operations on the channel after *close2Proc* is called to close one or both sides of the channel.  In all cases, the *close2Proc* function should return zero if the close operation was successful; otherwise it should return a nonzero POSIX error code. In addition, if an error occurs and *interp* is not NULL, the procedure should store an error message in the interpreter's result.

The *close2Proc* value can be retrieved with **Tcl_ChannelClose2Proc**, which returns a pointer to the function.

## Inputproc

The *inputProc* field contains the address of a function called by the generic layer to read data from the file or device and store it in an internal buffer. *InputProc* must match the following prototype:

```
typedef int Tcl_DriverInputProc(
        void *instanceData,
        char *buf,
        int bufSize,
        int *errorCodePtr);
```

*InstanceData* is the same as the value passed to **Tcl_CreateChannel** when the channel was created.  The *buf* argument points to an array of bytes in which to store input from the device, and the *bufSize* argument indicates how many bytes are available at *buf*.

The *errorCodePtr* argument points to an integer variable provided by the generic layer. If an error occurs, the function should set the variable to a POSIX error code that identifies the error that occurred.

The function should read data from the input device encapsulated by the channel and store it at *buf*.  On success, the function should return a nonnegative integer indicating how many bytes were read from the input device and stored at *buf*. On error, the function should return -1. If an error occurs after some data has been read from the device, that data is lost.

If *inputProc* can determine that the input device has some data available but less than requested by the *bufSize* argument, the function should only attempt to read as much data as is available and return without blocking. If the input device has no data available whatsoever and the channel is in nonblocking mode, the function should return an **EAGAIN** error. If the input device has no data available whatsoever and the channel is in blocking mode, the function should block for the shortest possible time until at least one byte of data can be read from the device; then, it should return as much data as it can read without blocking.

This value can be retrieved with **Tcl_ChannelInputProc**, which returns a pointer to the function.

## Outputproc

The *outputProc* field contains the address of a function called by the generic layer to transfer data from an internal buffer to the output device. *OutputProc* must match the following prototype:

```
typedef int Tcl_DriverOutputProc(
        void *instanceData,
        const char *buf,
        int toWrite,
        int *errorCodePtr);
```

*InstanceData* is the same as the value passed to **Tcl_CreateChannel** when the channel was created. The *buf* argument contains an array of bytes to be written to the device, and the *toWrite* argument indicates how many bytes are to be written from the *buf* argument.

The *errorCodePtr* argument points to an integer variable provided by the generic layer. If an error occurs, the function should set this variable to a POSIX error code that identifies the error.

The function should write the data at *buf* to the output device encapsulated by the channel. On success, the function should return a nonnegative integer indicating how many bytes were written to the output device.  The return value is normally the same as *toWrite*, but may be less in some cases such as if the output operation is interrupted by a signal. If an error occurs the function should return -1.  In case of error, some data may have been written to the device.

If the channel is nonblocking and the output device is unable to absorb any data whatsoever, the function should return -1 with an **EAGAIN** error without writing any data.

This value can be retrieved with **Tcl_ChannelOutputProc**, which returns a pointer to the function.

## Wideseekproc

The *wideSeekProc* field contains the address of a function called by the generic layer to move the access point at which subsequent input or output operations will be applied. *WideSeekProc* must match the following prototype:

```
typedef long long Tcl_DriverWideSeekProc(
        void *instanceData,
        long long offset,
        int seekMode,
        int *errorCodePtr);
```

The *instanceData* argument is the same as the value given to **Tcl_CreateChannel** when this channel was created.  *Offset* and *seekMode* have the same meaning as for the **Tcl_Seek** procedure (described in the manual entry for **Tcl_OpenFileChannel**).

The *errorCodePtr* argument points to an integer variable provided by the generic layer for returning **errno** values from the function.  The function should set this variable to a POSIX error code if an error occurs. The function should store an **EINVAL** error code if the channel type does not implement seeking.

The return value is the new access point or -1 in case of error. If an error occurred, the function should not move the access point.

The *wideSseekProc* value can be retrieved with **Tcl_ChannelWideSeekProc**, which returns a pointer to the function.

## Setoptionproc

The *setOptionProc* field contains the address of a function called by the generic layer to set a channel type specific option on a channel. *setOptionProc* must match the following prototype:

```
typedef int Tcl_DriverSetOptionProc(
        void *instanceData,
        Tcl_Interp *interp,
        const char *optionName,
        const char *newValue);
```

*optionName* is the name of an option to set, and *newValue* is the new value for that option, as a string. The *instanceData* is the same as the value given to **Tcl_CreateChannel** when this channel was created. The function should do whatever channel type specific action is required to implement the new value of the option.

Some options are handled by the generic code and this function is never called to set them, e.g. **-blockmode**. Other options are specific to each channel type and the *setOptionProc* procedure of the channel driver will get called to implement them. The *setOptionProc* field can be NULL, which indicates that this channel type supports no type specific options.

If the option value is successfully modified to the new value, the function returns **TCL_OK**. It should call **Tcl_BadChannelOption** which itself returns **TCL_ERROR** if the *optionName* is unrecognized. If *newValue* specifies a value for the option that is not supported or if a system call error occurs, the function should leave an error message in the result of *interp* if *interp* is not NULL. The function should also call **Tcl_SetErrno** to store an appropriate POSIX error code.

This value can be retrieved with **Tcl_ChannelSetOptionProc**, which returns a pointer to the function.

## Getoptionproc

The *getOptionProc* field contains the address of a function called by the generic layer to get the value of a channel type specific option on a channel. *getOptionProc* must match the following prototype:

```
typedef int Tcl_DriverGetOptionProc(
        void *instanceData,
        Tcl_Interp *interp,
        const char *optionName,
        Tcl_DString *optionValue);
```

*OptionName* is the name of an option supported by this type of channel. If the option name is not NULL, the function stores its current value, as a string, in the Tcl dynamic string *optionValue*. If *optionName* is NULL, the function stores in *optionValue* an alternating list of all supported options and their current values. On success, the function returns **TCL_OK**. It should call **Tcl_BadChannelOption** which itself returns **TCL_ERROR** if the *optionName* is unrecognized. If a system call error occurs, the function should leave an error message in the result of *interp* if *interp* is not NULL. The function should also call **Tcl_SetErrno** to store an appropriate POSIX error code.

Some options are handled by the generic code and this function is never called to retrieve their value, e.g. **-blockmode**. Other options are specific to each channel type and the *getOptionProc* procedure of the channel driver will get called to implement them. The *getOptionProc* field can be NULL, which indicates that this channel type supports no type specific options.

This value can be retrieved with **Tcl_ChannelGetOptionProc**, which returns a pointer to the function.

## Watchproc

The *watchProc* field contains the address of a function called by the generic layer to initialize the event notification mechanism to notice events of interest on this channel. *WatchProc* should match the following prototype:

```
typedef void Tcl_DriverWatchProc(
        void *instanceData,
        int mask);
```

The *instanceData* is the same as the value passed to **Tcl_CreateChannel** when this channel was created. The *mask* argument is an OR-ed combination of **TCL_READABLE**, **TCL_WRITABLE** and **TCL_EXCEPTION**; it indicates events the caller is interested in noticing on this channel.

The function should initialize device type specific mechanisms to notice when an event of interest is present on the channel.  When one or more of the designated events occurs on the channel, the channel driver is responsible for calling **Tcl_NotifyChannel** to inform the generic channel module.  The driver should take care not to starve other channel drivers or sources of callbacks by invoking Tcl_NotifyChannel too frequently.  Fairness can be insured by using the Tcl event queue to allow the channel event to be scheduled in sequence with other events.  See the description of **Tcl_QueueEvent** for details on how to queue an event.

This value can be retrieved with **Tcl_ChannelWatchProc**, which returns a pointer to the function.

## Gethandleproc

The *getHandleProc* field contains the address of a function called by the generic layer to retrieve a device-specific handle from the channel. *GetHandleProc* should match the following prototype:

```
typedef int Tcl_DriverGetHandleProc(
        void *instanceData,
        int direction,
        void **handlePtr);
```

*InstanceData* is the same as the value passed to **Tcl_CreateChannel** when this channel was created. The *direction* argument is either **TCL_READABLE** to retrieve the handle used for input, or **TCL_WRITABLE** to retrieve the handle used for output.

If the channel implementation has device-specific handles, the function should retrieve the appropriate handle associated with the channel, according the *direction* argument.  The handle should be stored in the location referred to by *handlePtr*, and **TCL_OK** should be returned.  If the channel is not open for the specified direction, or if the channel implementation does not use device handles, the function should return **TCL_ERROR**.

This value can be retrieved with **Tcl_ChannelGetHandleProc**, which returns a pointer to the function.

## Flushproc

The *flushProc* field is currently reserved for future use. It should be set to NULL. *FlushProc* should match the following prototype:

```
typedef int Tcl_DriverFlushProc(
        void *instanceData);
```

This value can be retrieved with **Tcl_ChannelFlushProc**, which returns a pointer to the function.

## Handlerproc

The *handlerProc* field contains the address of a function called by the generic layer to notify the channel that an event occurred.  It should be defined for stacked channel drivers that wish to be notified of events that occur on the underlying (stacked) channel. *HandlerProc* should match the following prototype:

```
typedef int Tcl_DriverHandlerProc(
        void *instanceData,
        int interestMask);
```

*InstanceData* is the same as the value passed to **Tcl_CreateChannel** when this channel was created.  The *interestMask* is an OR-ed combination of **TCL_READABLE** or **TCL_WRITABLE**; it indicates what type of event occurred on this channel.

This value can be retrieved with **Tcl_ChannelHandlerProc**, which returns a pointer to the function. 

## Threadactionproc

The *threadActionProc* field contains the address of the function called by the generic layer when a channel is created, closed, or going to move to a different thread, i.e. whenever thread-specific driver state might have to initialized or updated. It can be NULL. The action *TCL_CHANNEL_THREAD_REMOVE* is used to notify the driver that it should update or remove any thread-specific data it might be maintaining for the channel.

The action *TCL_CHANNEL_THREAD_INSERT* is used to notify the driver that it should update or initialize any thread-specific data it might be maintaining using the calling thread as the associate. See **Tcl_CutChannel** and **Tcl_SpliceChannel** for more detail.

```
typedef void Tcl_DriverThreadActionProc(
        void *instanceData,
        int action);
```

*InstanceData* is the same as the value passed to **Tcl_CreateChannel** when this channel was created.

These values can be retrieved with **Tcl_ChannelThreadActionProc**, which returns a pointer to the function.

## Truncateproc

The *truncateProc* field contains the address of the function called by the generic layer when a channel is truncated to some length. It can be NULL.

```
typedef int Tcl_DriverTruncateProc(
        void *instanceData,
        long long length);
```

*InstanceData* is the same as the value passed to **Tcl_CreateChannel** when this channel was created, and *length* is the new length of the underlying file, which should not be negative. The result should be 0 on success or an errno code (suitable for use with **Tcl_SetErrno**) on failure.

These values can be retrieved with **Tcl_ChannelTruncateProc**, which returns a pointer to the function.

# Tcl_badchanneloption

This procedure generates a "bad option" error message in an (optional) interpreter.  It is used by channel drivers when an invalid Set/Get option is requested. Its purpose is to concatenate the generic options list to the specific ones and factorize the generic options error message string.

It always returns **TCL_ERROR**

An error message is generated in *interp*'s result value to indicate that a command was invoked with a bad option. The message has the form

```
    bad option "blah": should be one of
    <...generic options...>+<...specific options...>
```

so you get for instance:

```
    bad option "-blah": should be one of -blocking,
    -buffering, -buffersize, -eofchar, -translation,
    -peername, or -sockname
```

when called with *optionList* equal to "peername sockname"

"blah" is the *optionName* argument and "<specific options>" is a space separated list of specific option words. The function takes good care of inserting minus signs before each option, commas after, and an "or" before the last option.

---
CommandName: Tcl_CreateFileHandler
ManualSection: 3
Version: 8.0
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - fileevent(n)
 - Tcl_CreateTimerHandler(3)
 - Tcl_DoWhenIdle(3)
Keywords:
 - callback
 - file
 - handler
Copyright:
 - Copyright (c) 1990-1994 The Regents of the University of California.
 - Copyright (c) 1994-1997 Sun Microsystems, Inc.
---

# Name

Tcl_CreateFileHandler, Tcl_DeleteFileHandler - associate procedure callbacks with files or devices (Unix only)

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_CreateFileHandler]{.ccmd}[fd, mask, proc, clientData]{.cargs}
[Tcl_DeleteFileHandler]{.ccmd}[fd]{.cargs}
:::

# Arguments

.AP int fd in Unix file descriptor for an open file or device. .AP int mask in Conditions under which *proc* should be called: OR-ed combination of **TCL_READABLE**, **TCL_WRITABLE**, and **TCL_EXCEPTION**.  May be set to 0 to temporarily disable a handler. .AP Tcl_FileProc *proc in Procedure to invoke whenever the file or device indicated by *file* meets the conditions specified by *mask*. .AP void *clientData in Arbitrary one-word value to pass to *proc*.

# Description

**Tcl_CreateFileHandler** arranges for *proc* to be invoked in the future whenever I/O becomes possible on a file or an exceptional condition exists for the file.  The file is indicated by *fd*, and the conditions of interest are indicated by *mask*.  For example, if *mask* is **TCL_READABLE**, *proc* will be called when the file is readable. The callback to *proc* is made by **Tcl_DoOneEvent**, so **Tcl_CreateFileHandler** is only useful in programs that dispatch events through **Tcl_DoOneEvent** or through Tcl commands such as **vwait**.

*Proc* should have arguments and result that match the type **Tcl_FileProc**:

```
typedef void Tcl_FileProc(
        void *clientData,
        int mask);
```

The *clientData* parameter to *proc* is a copy of the *clientData* argument given to **Tcl_CreateFileHandler** when the callback was created.  Typically, *clientData* points to a data structure containing application-specific information about the file.  *Mask* is an integer mask indicating which of the requested conditions actually exists for the file;  it will contain a subset of the bits in the *mask* argument to **Tcl_CreateFileHandler**.

There may exist only one handler for a given file at a given time. If **Tcl_CreateFileHandler** is called when a handler already exists for *fd*, then the new callback replaces the information that was previously recorded.

**Tcl_DeleteFileHandler** may be called to delete the file handler for *fd*;  if no handler exists for the file given by *fd* then the procedure has no effect.

The purpose of file handlers is to enable an application to respond to events while waiting for files to become ready for I/O.  For this to work correctly, the application may need to use non-blocking I/O operations on the files for which handlers are declared.  Otherwise the application may block if it reads or writes too much data; while waiting for the I/O to complete the application will not be able to service other events. Use **Tcl_SetChannelOption** with **-blocking** to set the channel into blocking or nonblocking mode as required.

Note that these interfaces are only supported by the Unix implementation of the Tcl notifier.

---
CommandName: Tcl_DoWhenIdle
ManualSection: 3
Version: 7.5
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - after(n)
 - Tcl_CreateFileHandler(3)
 - Tcl_CreateTimerHandler(3)
Keywords:
 - callback
 - defer
 - idle callback
Copyright:
 - Copyright (c) 1990 The Regents of the University of California.
 - Copyright (c) 1994-1996 Sun Microsystems, Inc.
---

# Name

Tcl_DoWhenIdle, Tcl_CancelIdleCall - invoke a procedure when there are no pending events

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_DoWhenIdle]{.ccmd}[proc, clientData]{.cargs}
[Tcl_CancelIdleCall]{.ccmd}[proc, clientData]{.cargs}
:::

# Arguments

.AP Tcl_IdleProc *proc in Procedure to invoke. .AP void *clientData in Arbitrary one-word value to pass to *proc*.

# Description

**Tcl_DoWhenIdle** arranges for *proc* to be invoked when the application becomes idle.  The application is considered to be idle when **Tcl_DoOneEvent** has been called, could not find any events to handle, and is about to go to sleep waiting for an event to occur.  At this point all pending **Tcl_DoWhenIdle** handlers are invoked.  For each call to **Tcl_DoWhenIdle** there will be a single call to *proc*;  after *proc* is invoked the handler is automatically removed. **Tcl_DoWhenIdle** is only usable in programs that use **Tcl_DoOneEvent** to dispatch events.

*Proc* should have arguments and result that match the type **Tcl_IdleProc**:

```
typedef void Tcl_IdleProc(
        void *clientData);
```

The *clientData* parameter to *proc* is a copy of the *clientData* argument given to **Tcl_DoWhenIdle**.  Typically, *clientData* points to a data structure containing application-specific information about what *proc* should do.

**Tcl_CancelIdleCall** may be used to cancel one or more previous calls to **Tcl_DoWhenIdle**:  if there is a **Tcl_DoWhenIdle** handler registered for *proc* and *clientData*, then it is removed without invoking it.  If there is more than one handler on the idle list that refers to *proc* and *clientData*, all of the handlers are removed.  If no existing handlers match *proc* and *clientData* then nothing happens.

**Tcl_DoWhenIdle** is most useful in situations where (a) a piece of work will have to be done but (b) it is possible that something will happen in the near future that will change what has to be done or require something different to be done.  **Tcl_DoWhenIdle** allows the actual work to be deferred until all pending events have been processed.  At this point the exact work to be done will presumably be known and it can be done exactly once.

For example, **Tcl_DoWhenIdle** might be used by an editor to defer display updates until all pending commands have been processed.  Without this feature, redundant redisplays might occur in some situations, such as the processing of a command file.

# Bugs

At present it is not safe for an idle callback to reschedule itself continuously.  This will interact badly with certain features of Tk that attempt to wait for all idle callbacks to complete.  If you would like for an idle callback to reschedule itself continuously, it is better to use a timer handler with a zero timeout period.

---
CommandName: Tcl_GetEncoding
ManualSection: 3
Version: 8.1
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - encoding(n)
Keywords:
 - utf
 - encoding
 - convert
Copyright:
 - Copyright (c) 1997-1998 Sun Microsystems, Inc.
---

# Name

Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtfDStringEx, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternalDStringEx, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNameForUser, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath - procedures for creating and using encodings

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_Encoding]{.ret} [Tcl_GetEncoding]{.ccmd}[interp, name]{.cargs}
[Tcl_FreeEncoding]{.ccmd}[encoding]{.cargs}
[int]{.ret} [Tcl_GetEncodingFromObj]{.ccmd}[interp, objPtr, encodingPtr]{.cargs}
[char *]{.ret} [Tcl_ExternalToUtfDString]{.ccmd}[encoding, src, srcLen, dstPtr]{.cargs}
[int]{.ret} [Tcl_ExternalToUtfDStringEx]{.ccmd}[interp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr]{.cargs}
[char *]{.ret} [Tcl_UtfToExternalDString]{.ccmd}[encoding, src, srcLen, dstPtr]{.cargs}
[int]{.ret} [Tcl_UtfToExternalDStringEx]{.ccmd}[interp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr]{.cargs}
[int]{.ret} [Tcl_ExternalToUtf]{.ccmd}[interp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr]{.cargs}
[int]{.ret} [Tcl_UtfToExternal]{.ccmd}[interp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr]{.cargs}
[const char *]{.ret} [Tcl_GetEncodingName]{.ccmd}[encoding]{.cargs}
[Tcl_Size]{.ret} [Tcl_GetEncodingNulLength]{.ccmd}[encoding]{.cargs}
[int]{.ret} [Tcl_SetSystemEncoding]{.ccmd}[interp, name]{.cargs}
[const char *]{.ret} [Tcl_GetEncodingNameFromEnvironment]{.ccmd}[bufPtr]{.cargs}
[const char *]{.ret} [Tcl_GetEncodingNameForUser]{.ccmd}[bufPtr]{.cargs}
[Tcl_GetEncodingNames]{.ccmd}[interp]{.cargs}
[Tcl_Encoding]{.ret} [Tcl_CreateEncoding]{.ccmd}[typePtr]{.cargs}
[Tcl_Obj *]{.ret} [Tcl_GetEncodingSearchPath]{.ccmd}[]{.cargs}
[int]{.ret} [Tcl_SetEncodingSearchPath]{.ccmd}[searchPath]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter to use for error reporting, or NULL if no error reporting is desired. .AP "const char" *name in Name of encoding to load. .AP Tcl_Encoding encoding in The encoding to query, free, or use for converting text.  If *encoding* is NULL, the current system encoding is used. .AP Tcl_Obj *objPtr in Name of encoding to get token for. .AP Tcl_Encoding *encodingPtr out Points to storage where encoding token is to be written. .AP "const char" *src in For the **Tcl_ExternalToUtf** functions, an array of bytes in the specified encoding that are to be converted to UTF-8.  For the **Tcl_UtfToExternal** function, an array of UTF-8 characters to be converted to the specified encoding. .AP "const TCHAR" *tsrc in An array of Windows TCHAR characters to convert to UTF-8. .AP Tcl_Size srcLen in Length of *src* or *tsrc* in bytes.  If the length is negative, the encoding-specific length of the string is used. .AP Tcl_DString *dstPtr out Pointer to an uninitialized or free **Tcl_DString** in which the converted result will be stored. .AP int flags in This is a bit mask passed in to control the operation of the encoding functions. **TCL_ENCODING_START** signifies that the source buffer is the first block in a (potentially multi-block) input stream, telling the conversion routine to reset to an initial state and perform any initialization that needs to occur before the first byte is converted. **TCL_ENCODING_END** signifies that the source buffer is the last block in a (potentially multi-block) input stream, telling the conversion routine to perform any finalization that needs to occur after the last byte is converted and then to reset to an initial state. The **TCL_PROFILE_*** bits defined in the **PROFILES** section below control the encoding profile to be used for dealing with invalid data or other errors in the encoding transform. The flag **TCL_ENCODING_STOPONERROR** has no effect, it only has meaning in Tcl 8.x.

Some flags bits may not be usable with some functions as noted in the function descriptions below. .AP Tcl_EncodingState *statePtr in/out Used when converting a (generally long or indefinite length) byte stream in a piece-by-piece fashion.  The conversion routine stores its current state in **statePtr* after *src* (the buffer containing the current piece) has been converted; that state information must be passed back when converting the next piece of the stream so the conversion routine knows what state it was in when it left off at the end of the last piece.  May be NULL, in which case the value specified for *flags* is ignored and the source buffer is assumed to contain the complete string to convert. .AP char *dst out Buffer in which the converted result will be stored.  No more than *dstLen* bytes will be stored in *dst*. .AP int dstLen in The maximum length of the output buffer *dst* in bytes. .AP int *srcReadPtr out Filled with the number of bytes from *src* that were actually converted.  This may be less than the original source length if there was a problem converting some source characters.  May be NULL. .AP int *dstWrotePtr out Filled with the number of bytes that were actually stored in the output buffer as a result of the conversion.  May be NULL. .AP int *dstCharsPtr out Filled with the number of characters that correspond to the number of bytes stored in the output buffer.  May be NULL. .AP Tcl_Size *errorIdxPtr out Filled with the index of the byte or character that caused the encoding transform to fail. May be NULL. .AP Tcl_DString *bufPtr out Storage for the prescribed system encoding name. .AP "const Tcl_EncodingType" *typePtr in Structure that defines a new type of encoding. .AP Tcl_Obj *searchPath in List of filesystem directories in which to search for encoding data files. .AP "const char" *path in A path to the location of the encoding file.

# Introduction

These routines convert between Tcl's internal character representation, UTF-8, and character representations used by various operating systems or file systems, such as Unicode, ASCII, or Shift-JIS.  When operating on strings, such as such as obtaining the names of files or displaying characters using international fonts, the strings must be translated into one or possibly multiple formats that the various system calls can use.  For instance, on a Japanese Unix workstation, a user might obtain a filename represented in the EUC-JP file encoding and then translate the characters to the jisx0208 font encoding in order to display the filename in a Tk widget. The purpose of the encoding package is to help bridge the translation gap. UTF-8 provides an intermediate staging ground for all the various encodings.  In the example above, text would be translated into UTF-8 from whatever file encoding the operating system is using.  Then it would be translated from UTF-8 into whatever font encoding the display routines require.

Some basic encodings are compiled into Tcl.  Others can be defined by the user or dynamically loaded from encoding files in a platform-independent manner.

# Description

**Tcl_GetEncoding** finds an encoding given its *name*.  The name may refer to a built-in Tcl encoding, a user-defined encoding registered by calling **Tcl_CreateEncoding**, or a dynamically-loadable encoding file.  The return value is a token that represents the encoding and can be used in subsequent calls to procedures such as **Tcl_GetEncodingName**, **Tcl_FreeEncoding**, and **Tcl_UtfToExternal**.  If the name did not refer to any known or loadable encoding, NULL is returned and an error message is returned in *interp*.

The encoding package maintains a database of all encodings currently in use. The first time *name* is seen, **Tcl_GetEncoding** returns an encoding with a reference count of 1.  If the same *name* is requested further times, then the reference count for that encoding is incremented without the overhead of allocating a new encoding and all its associated data structures.

When an *encoding* is no longer needed, **Tcl_FreeEncoding** should be called to release it.  When an *encoding* is no longer in use anywhere (i.e., it has been freed as many times as it has been gotten) **Tcl_FreeEncoding** will release all storage the encoding was using and delete it from the database.

**Tcl_GetEncodingFromObj** treats the string representation of *objPtr* as an encoding name, and finds an encoding with that name, just as **Tcl_GetEncoding** does. When an encoding is found, it is cached within the **objPtr** value for future reference, the **Tcl_Encoding** token is written to the storage pointed to by *encodingPtr*, and the value **TCL_OK** is returned. If no such encoding is found, the value **TCL_ERROR** is returned, and no writing to ******encodingPtr* takes place. Just as with **Tcl_GetEncoding**, the caller should call **Tcl_FreeEncoding** on the resulting encoding token when that token will no longer be used.

**Tcl_ExternalToUtfDString** converts a source buffer *src* from the specified *encoding* into UTF-8.  The converted bytes are stored in *dstPtr*, which is then null-terminated.  The caller should eventually call **Tcl_DStringFree** to free any information stored in *dstPtr*. When converting, if any of the characters in the source buffer cannot be represented in the target encoding, a default fallback character will be used.  The return value is a pointer to the value stored in the DString.

**Tcl_ExternalToUtfDStringEx** is a more flexible version of older **Tcl_ExternalToUtfDString** function. It takes three additional parameters, **interp**, **flags** and **errorIdxPtr**. The **flags** parameter may be used to specify the profile to be used for the transform. The **TCL_ENCODING_START** and **TCL_ENCODING_END** bits in **flags** are ignored as the function assumes the entire source string to be decoded is passed into the function. On success, the function returns **TCL_OK** with the converted string stored in ***dstPtr**. For errors *other than conversion errors*, such as invalid flags, the function returns **TCL_ERROR** with an error message in **interp** if it is not NULL. For conversion errors, **Tcl_ExternalToUtfDStringEx** returns one of the **TCL_CONVERT_*** errors listed below for **Tcl_ExternalToUtf**. When one of these conversion errors is returned, an error message is stored in **interp** only if **errorIdxPtr** is NULL. Otherwise, no error message is stored as the function expects the caller is interested the decoded data up to that point and not treating this as an immediate error condition. The index of the error location is stored in ***errorIdxPtr**.

The caller must call **Tcl_DStringFree** to free up the ***dstPtr** resources irrespective of the return value from the function.

**Tcl_ExternalToUtf** converts a source buffer *src* from the specified *encoding* into UTF-8.  Up to *srcLen* bytes are converted from the source buffer and up to *dstLen* converted bytes are stored in *dst*. In all cases, **srcReadPtr* is filled with the number of bytes that were successfully converted from *src* and **dstWrotePtr* is filled with the corresponding number of bytes that were stored in *dst*.  The return value is one of the following:

**TCL_OK**
: All bytes of *src* were converted.

**TCL_CONVERT_NOSPACE**
: The destination buffer was not large enough for all of the converted data; as many characters as could fit were converted though.

**TCL_CONVERT_MULTIBYTE**
: The last few bytes in the source buffer were the beginning of a multibyte sequence, but more bytes were needed to complete this sequence.  A subsequent call to the conversion routine should pass a buffer containing the unconverted bytes that remained in *src* plus some further bytes from the source stream to properly convert the formerly split-up multibyte sequence.

**TCL_CONVERT_SYNTAX**
: The source buffer contained an invalid byte or character sequence.  This may occur if the input stream has been damaged or if the input encoding method was misidentified.

**TCL_CONVERT_UNKNOWN**
: The source buffer contained a character that could not be represented in the target encoding. .LP **Tcl_UtfToExternalDString** converts a source buffer *src* from UTF-8 into the specified *encoding*.  The converted bytes are stored in *dstPtr*, which is then terminated with the appropriate encoding-specific null.  The caller should eventually call **Tcl_DStringFree** to free any information stored in *dstPtr*.  When converting, if any of the characters in the source buffer cannot be represented in the target encoding, a default fallback character will be used.  The return value is a pointer to the value stored in the DString.


**Tcl_UtfToExternalDStringEx** is an enhanced version of **Tcl_UtfToExternalDString** that transforms UTF-8 encoded source data to a specified *encoding*. Except for the direction of the transform, the parameters and return values are identical to those of **Tcl_ExternalToUtfDStringEx**. See that function above for details about the same.

Irrespective of the return code from the function, the caller must free resources associated with ***dstPtr** when the function returns.

**Tcl_UtfToExternal** converts a source buffer *src* from UTF-8 into the specified *encoding*.  Up to *srcLen* bytes are converted from the source buffer and up to *dstLen* converted bytes are stored in *dst*.  In all cases, **srcReadPtr* is filled with the number of bytes that were successfully converted from *src* and **dstWrotePtr* is filled with the corresponding number of bytes that were stored in *dst*.  The return values are the same as the return values for **Tcl_ExternalToUtf**.

**Tcl_GetEncodingName** is roughly the inverse of **Tcl_GetEncoding**. Given an *encoding*, the return value is the *name* argument that was used to create the encoding.  The string returned by **Tcl_GetEncodingName** is only guaranteed to persist until the *encoding* is deleted.  The caller must not modify this string.

**Tcl_GetEncodingNulLength** returns the length of the terminating nul byte sequence for strings in the specified encoding.

**Tcl_SetSystemEncoding** sets the default encoding that should be used whenever the user passes a NULL value for the *encoding* argument to any of the other encoding functions.  If *name* is NULL, the system encoding is reset to the default system encoding, **binary**.  If the name did not refer to any known or loadable encoding, **TCL_ERROR** is returned and an error message is left in *interp*.  Otherwise, this procedure increments the reference count of the new system encoding, decrements the reference count of the old system encoding, and returns **TCL_OK**.

**Tcl_GetEncodingNameFromEnvironment** retrieves the encoding name to use as the system encoding. On non-Windows platforms, this is derived from the **nl_langinfo** system call if available, and environment variables **LC_ALL**, **LC_CTYPE** or **LANG** otherwise. On Windows versions Windows 10 Build 18362 and later the returned value is always **utf-8**. On earlier Windows versions, it is derived from the user settings in the Windows registry. **Tcl_GetEncodingNameForUser** retrieves the encoding name based on the user settings for the current user and is derived in the same manner as **Tcl_GetEncodingNameFromEnvironment** on non-Windows platforms. On Windows, unlike **Tcl_GetEncodingNameFromEnvironment**, it returns the encoding name as per the Windows registry settings irrespective of the Windows version. Both functions accept *bufPtr*, a pointer to an uninitialized or freed **Tcl_DString** and write the encoding name to it. They return **Tcl_DStringValue(bufPtr)** which points to the stored name.

**Tcl_GetEncodingNames** sets the *interp* result to a list consisting of the names of all the encodings that are currently defined or can be dynamically loaded, searching the encoding path specified by **Tcl_SetEncodingSearchPath**.  This procedure does not ensure that the dynamically-loadable encoding files contain valid data, but merely that they exist.

**Tcl_CreateEncoding** defines a new encoding and registers the C procedures that are called back to convert between the encoding and UTF-8.  Encodings created by **Tcl_CreateEncoding** are thereafter visible in the database used by **Tcl_GetEncoding**.  Just as with the **Tcl_GetEncoding** procedure, the return value is a token that represents the encoding and can be used in subsequent calls to other encoding functions.  **Tcl_CreateEncoding** returns an encoding with a reference count of 1. If an encoding with the specified *name* already exists, then its entry in the database is replaced with the new encoding; the token for the old encoding will remain valid and continue to behave as before, but users of the new token will now call the new encoding procedures.

The *typePtr* argument to **Tcl_CreateEncoding** contains information about the name of the encoding and the procedures that will be called to convert between this encoding and UTF-8.  It is defined as follows:

```
typedef struct {
    const char *encodingName;
    Tcl_EncodingConvertProc *toUtfProc;
    Tcl_EncodingConvertProc *fromUtfProc;
    Tcl_EncodingFreeProc *freeProc;
    void *clientData;
    Tcl_Size nullSize;
} Tcl_EncodingType;
```

The *encodingName* provides a string name for the encoding, by which it can be referred in other procedures such as **Tcl_GetEncoding**.  The *toUtfProc* refers to a callback procedure to invoke to convert text from this encoding into UTF-8. The *fromUtfProc* refers to a callback procedure to invoke to convert text from UTF-8 into this encoding.  The *freeProc* refers to a callback procedure to invoke when this encoding is deleted.  The *freeProc* field may be NULL.  The *clientData* contains an arbitrary one-word value passed to *toUtfProc*, *fromUtfProc*, and *freeProc* whenever they are called.  Typically, this is a pointer to a data structure containing encoding-specific information that can be used by the callback procedures.  For instance, two very similar encodings such as **ascii** and **macRoman** may use the same callback procedure, but use different values of *clientData* to control its behavior.  The *nullSize* specifies the number of zero bytes that signify end-of-string in this encoding.  It must be **1** (for single-byte or multi-byte encodings like ASCII or Shift-JIS) or **2** (for double-byte encodings like Unicode). Constant-sized encodings with 3 or more bytes per character (such as CNS11643) are not accepted.

The callback procedures *toUtfProc* and *fromUtfProc* should match the type **Tcl_EncodingConvertProc**:

```
typedef int Tcl_EncodingConvertProc(
        void *clientData,
        const char *src,
        int srcLen,
        int flags,
        Tcl_EncodingState *statePtr,
        char *dst,
        int dstLen,
        int *srcReadPtr,
        int *dstWrotePtr,
        int *dstCharsPtr);
```

The *toUtfProc* and *fromUtfProc* procedures are called by the **Tcl_ExternalToUtf** or **Tcl_UtfToExternal** family of functions to perform the actual conversion.  The *clientData* parameter to these procedures is the same as the *clientData* field specified to **Tcl_CreateEncoding** when the encoding was created.  The remaining arguments to the callback procedures are the same as the arguments, documented at the top, to **Tcl_ExternalToUtf** or **Tcl_UtfToExternal**, with the following exceptions.  If the *srcLen* argument to one of those high-level functions is negative, the value passed to the callback procedure will be the appropriate encoding-specific string length of *src*.  If any of the *srcReadPtr*, *dstWrotePtr*, or *dstCharsPtr* arguments to one of the high-level functions is NULL, the corresponding value passed to the callback procedure will be a non-NULL location.

The callback procedure *freeProc*, if non-NULL, should match the type **Tcl_EncodingFreeProc**:

```
typedef void Tcl_EncodingFreeProc(
        void *clientData);
```

This *freeProc* function is called when the encoding is deleted.  The *clientData* parameter is the same as the *clientData* field specified to **Tcl_CreateEncoding** when the encoding was created.

**Tcl_GetEncodingSearchPath** and **Tcl_SetEncodingSearchPath** are called to access and set the list of filesystem directories searched for encoding data files.

The value returned by **Tcl_GetEncodingSearchPath** is the value stored by the last successful call to **Tcl_SetEncodingSearchPath**.  If no calls to **Tcl_SetEncodingSearchPath** have occurred, Tcl will compute an initial value based on the environment.  There is one encoding search path for the entire process, shared by all threads in the process.

**Tcl_SetEncodingSearchPath** stores *searchPath* and returns **TCL_OK**, unless *searchPath* is not a valid Tcl list, which causes **TCL_ERROR** to be returned.  The elements of *searchPath* are not verified as existing readable filesystem directories.  When searching for encoding data files takes place, and non-existent or non-readable filesystem directories on the *searchPath* are silently ignored.

# Encoding files

Space would prohibit precompiling into Tcl every possible encoding algorithm, so many encodings are stored on disk as dynamically-loadable encoding files.  This behavior also allows the user to create additional encoding files that can be loaded using the same mechanism.  These encoding files contain information about the tables and/or escape sequences used to map between an external encoding and Unicode.  The external encoding may consist of single-byte, multi-byte, or double-byte characters.

Each dynamically-loadable encoding is represented as a text file.  The initial line of the file, beginning with a "#" symbol, is a comment that provides a human-readable description of the file.  The next line identifies the type of encoding file.  It can be one of the following letters:

[1] **S**
: A single-byte encoding, where one character is always one byte long in the encoding.  An example is **iso8859-1**, used by many European languages.

[2] **D**
: A double-byte encoding, where one character is always two bytes long in the encoding.  An example is **big5**, used for Chinese text.

[3] **M**
: A multi-byte encoding, where one character may be either one or two bytes long. Certain bytes are lead bytes, indicating that another byte must follow and that together the two bytes represent one character.  Other bytes are not lead bytes and represent themselves.  An example is **shiftjis**, used by many Japanese computers.

[4] **E**
: An escape-sequence encoding, specifying that certain sequences of bytes do not represent characters, but commands that describe how following bytes should be interpreted.


The rest of the lines in the file depend on the type.

Cases [1], [2], and [3] are collectively referred to as table-based encoding files.  The lines in a table-based encoding file are in the same format as this example taken from the **shiftjis** encoding (this is not the complete file):

```
# Encoding file: shiftjis, multi-byte
M
003F 0 40
00
0000000100020003000400050006000700080009000A000B000C000D000E000F
0010001100120013001400150016001700180019001A001B001C001D001E001F
0020002100220023002400250026002700280029002A002B002C002D002E002F
0030003100320033003400350036003700380039003A003B003C003D003E003F
0040004100420043004400450046004700480049004A004B004C004D004E004F
0050005100520053005400550056005700580059005A005B005C005D005E005F
0060006100620063006400650066006700680069006A006B006C006D006E006F
0070007100720073007400750076007700780079007A007B007C007D203E007F
0080000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
0000FF61FF62FF63FF64FF65FF66FF67FF68FF69FF6AFF6BFF6CFF6DFF6EFF6F
FF70FF71FF72FF73FF74FF75FF76FF77FF78FF79FF7AFF7BFF7CFF7DFF7EFF7F
FF80FF81FF82FF83FF84FF85FF86FF87FF88FF89FF8AFF8BFF8CFF8DFF8EFF8F
FF90FF91FF92FF93FF94FF95FF96FF97FF98FF99FF9AFF9BFF9CFF9DFF9EFF9F
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
81
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
300030013002FF0CFF0E30FBFF1AFF1BFF1FFF01309B309C00B4FF4000A8FF3E
FFE3FF3F30FD30FE309D309E30034EDD30053006300730FC20152010FF0F005C
301C2016FF5C2026202520182019201C201DFF08FF0930143015FF3BFF3DFF5B
FF5D30083009300A300B300C300D300E300F30103011FF0B221200B100D70000
00F7FF1D2260FF1CFF1E22662267221E22342642264000B0203220332103FFE5
FF0400A200A3FF05FF03FF06FF0AFF2000A72606260525CB25CF25CE25C725C6
25A125A025B325B225BD25BC203B301221922190219121933013000000000000
000000000000000000000000000000002208220B2286228722822283222A2229
000000000000000000000000000000002227222800AC21D221D4220022030000
0000000000000000000000000000000000000000222022A52312220222072261
2252226A226B221A223D221D2235222B222C0000000000000000000000000000
212B2030266F266D266A2020202100B6000000000000000025EF000000000000
```

The third line of the file is three numbers.  The first number is the fallback character (in base 16) to use when converting from UTF-8 to this encoding.  The second number is a **1** if this file represents the encoding for a symbol font, or **0** otherwise.  The last number (in base 10) is how many pages of data follow.

Subsequent lines in the example above are pages that describe how to map from the encoding into 2-byte Unicode.  The first line in a page identifies the page number.  Following it are 256 double-byte numbers, arranged as 16 rows of 16 numbers.  Given a character in the encoding, the high byte of that character is used to select which page, and the low byte of that character is used as an index to select one of the double-byte numbers in that page - the value obtained being the corresponding Unicode character. By examination of the example above, one can see that the characters 0x7E and 0x8163 in **shiftjis** map to 203E and 2026 in Unicode, respectively.

Following the first page will be all the other pages, each in the same format as the first: one number identifying the page followed by 256 double-byte Unicode characters.  If a character in the encoding maps to the Unicode character 0000, it means that the character does not actually exist. If all characters on a page would map to 0000, that page can be omitted.

Case [4] is the escape-sequence encoding file.  The lines in an this type of file are in the same format as this example taken from the **iso2022-jp** encoding:

```
# Encoding file: iso2022-jp, escape-driven
E
init		{}
final		{}
iso8859-1	\x1B(B
jis0201		\x1B(J
jis0208		\x1B$@
jis0208		\x1B$B
jis0212		\x1B$(D
gb2312		\x1B$A
ksc5601		\x1B$(C
```

In the file, the first column represents an option and the second column is the associated value.  **init** is a string to emit or expect before the first character is converted, while **final** is a string to emit or expect after the last character.  All other options are names of table-based encodings; the associated value is the escape-sequence that marks that encoding.  Tcl syntax is used for the values; in the above example, for instance, "**{}**" represents the empty string and "**\x1B**" represents character 27.

When **Tcl_GetEncoding** encounters an encoding *name* that has not been loaded, it attempts to load an encoding file called *name***.enc** from the **encoding** subdirectory of each directory that Tcl searches for its script library.  If the encoding file exists, but is malformed, an error message will be left in *interp*.

# Reference count management

**Tcl_GetEncodingFromObj** does not modify the reference count of its *objPtr* argument; it only reads. Note however that this function may set the interpreter result; if that is the only place that is holding a reference to the object, it will be deleted.

**Tcl_GetEncodingSearchPath** returns an object with a reference count of at least 1.

# Profiles

Encoding profiles define the manner in which errors in the encoding transforms are handled by the encoding functions. An application can specify the profile to be used by OR-ing the **flags** parameter passed to the function with at most one of **TCL_ENCODING_PROFILE_TCL8**, **TCL_ENCODING_PROFILE_STRICT** or **TCL_ENCODING_PROFILE_REPLACE**. These correspond to the **tcl8**, **strict** and **replace** profiles respectively. If none are specified, a version-dependent default profile is used. For Tcl 9.0, the default profile is **strict**.

For details about profiles, see the **PROFILES** section in the documentation of the **encoding** command.

---
CommandName: Tcl_PutEnv
ManualSection: 3
Version: 7.5
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - env(n)
Keywords:
 - environment
 - variable
Copyright:
 - Copyright (c) 1997-1998 Sun Microsystems, Inc.
---

# Name

Tcl_PutEnv - procedures to manipulate the environment

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[int]{.ret} [Tcl_PutEnv]{.ccmd}[assignment]{.cargs}
:::

# Arguments

.AP "const char" *assignment in Info about environment variable in the format "*NAME***=***value*". The *assignment* argument is in the system encoding.

# Description

**Tcl_PutEnv** sets an environment variable. The information is passed in a single string of the form "*NAME***=***value*". This procedure is intended to be a stand-in for the UNIX **putenv** system call. All Tcl-based applications using **putenv** should redefine it to **Tcl_PutEnv** so that they will interface properly to the Tcl runtime.

---
CommandName: Tcl_ExprLong
ManualSection: 3
Version: 7.0
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_ExprLongObj
 - Tcl_ExprDoubleObj
 - Tcl_ExprBooleanObj
 - Tcl_ExprObj
Keywords:
 - boolean
 - double
 - evaluate
 - expression
 - integer
 - value
 - string
Copyright:
 - Copyright (c) 1989-1993 The Regents of the University of California.
 - Copyright (c) 1994-1997 Sun Microsystems, Inc.
---

# Name

Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString - evaluate an expression

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[int]{.ret} [Tcl_ExprLong]{.ccmd}[interp, expr, longPtr]{.cargs}
[int]{.ret} [Tcl_ExprDouble]{.ccmd}[interp, expr, doublePtr]{.cargs}
[int]{.ret} [Tcl_ExprBoolean]{.ccmd}[interp, expr, booleanPtr]{.cargs}
[int]{.ret} [Tcl_ExprString]{.ccmd}[interp, expr]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter in whose context to evaluate *expr*. .AP "const char" *expr in Expression to be evaluated. .AP long *longPtr out Pointer to location in which to store the integer value of the expression. .AP int *doublePtr out Pointer to location in which to store the floating-point value of the expression. .AP int *booleanPtr out Pointer to location in which to store the 0/1 boolean value of the expression. 

# Description

These four procedures all evaluate the expression given by the *expr* argument and return the result in one of four different forms. The expression can have any of the forms accepted by the **expr** command. Note that these procedures have been largely replaced by the value-based procedures **Tcl_ExprLongObj**, **Tcl_ExprDoubleObj**, **Tcl_ExprBooleanObj**, and **Tcl_ExprObj**. Those value-based procedures evaluate an expression held in a Tcl value instead of a string. The value argument can retain an internal representation that is more efficient to execute.

The *interp* argument refers to an interpreter used to evaluate the expression (e.g. for variables and nested Tcl commands) and to return error information.

For all of these procedures the return value is a standard Tcl result: **TCL_OK** means the expression was successfully evaluated, and **TCL_ERROR** means that an error occurred while evaluating the expression. If **TCL_ERROR** is returned then the interpreter's result will hold a message describing the error. If an error occurs while executing a Tcl command embedded in the expression then that error will be returned.

If the expression is successfully evaluated, then its value is returned in one of four forms, depending on which procedure is invoked. **Tcl_ExprLong** stores an integer value at **longPtr*. If the expression's actual value is a floating-point number, then it is truncated to an integer. If the expression's actual value is a non-numeric string then an error is returned.

**Tcl_ExprDouble** stores a floating-point value at **doublePtr*. If the expression's actual value is an integer, it is converted to floating-point. If the expression's actual value is a non-numeric string then an error is returned.

**Tcl_ExprBoolean** stores a 0/1 integer value at **booleanPtr*. If the expression's actual value is an integer or floating-point number, then they store 0 at **booleanPtr* if the value was zero and 1 otherwise. If the expression's actual value is a non-numeric string then it must be one of the values accepted by **Tcl_GetBoolean** such as "yes" or "no", or else an error occurs.

**Tcl_ExprString** returns the value of the expression as a string stored in the interpreter's result. 

---
CommandName: Tcl_ExprLongObj
ManualSection: 3
Version: 8.0
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_ExprLong
 - Tcl_ExprDouble
 - Tcl_ExprBoolean
 - Tcl_ExprString
 - Tcl_GetObjResult
Keywords:
 - boolean
 - double
 - evaluate
 - expression
 - integer
 - value
 - string
Copyright:
 - Copyright (c) 1996-1997 Sun Microsystems, Inc.
---

# Name

Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj - evaluate an expression

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[int]{.ret} [Tcl_ExprLongObj]{.ccmd}[interp, objPtr, longPtr]{.cargs}
[int]{.ret} [Tcl_ExprDoubleObj]{.ccmd}[interp, objPtr, doublePtr]{.cargs}
[int]{.ret} [Tcl_ExprBooleanObj]{.ccmd}[interp, objPtr, booleanPtr]{.cargs}
[int]{.ret} [Tcl_ExprObj]{.ccmd}[interp, objPtr, resultPtrPtr]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter in whose context to evaluate *objPtr*. .AP Tcl_Obj *objPtr in Pointer to a value containing the expression to evaluate. .AP long *longPtr out Pointer to location in which to store the integer value of the expression. .AP int *doublePtr out Pointer to location in which to store the floating-point value of the expression. .AP int *booleanPtr out Pointer to location in which to store the 0/1 boolean value of the expression. .AP Tcl_Obj **resultPtrPtr out Pointer to location in which to store a pointer to the value that is the result of the expression. 

# Description

These four procedures all evaluate an expression, returning the result in one of four different forms. The expression is given by the *objPtr* argument, and it can have any of the forms accepted by the **expr** command.

The *interp* argument refers to an interpreter used to evaluate the expression (e.g. for variables and nested Tcl commands) and to return error information.

For all of these procedures the return value is a standard Tcl result: **TCL_OK** means the expression was successfully evaluated, and **TCL_ERROR** means that an error occurred while evaluating the expression. If **TCL_ERROR** is returned, then a message describing the error can be retrieved using **Tcl_GetObjResult**. If an error occurs while executing a Tcl command embedded in the expression then that error will be returned.

If the expression is successfully evaluated, then its value is returned in one of four forms, depending on which procedure is invoked. **Tcl_ExprLongObj** stores an integer value at **longPtr*. If the expression's actual value is a floating-point number, then it is truncated to an integer. If the expression's actual value is a non-numeric string then an error is returned.

**Tcl_ExprDoubleObj** stores a floating-point value at **doublePtr*. If the expression's actual value is an integer, it is converted to floating-point. If the expression's actual value is a non-numeric string then an error is returned.

**Tcl_ExprBooleanObj** stores a 0/1 integer value at **booleanPtr*. If the expression's actual value is an integer or floating-point number, then they store 0 at **booleanPtr* if the value was zero and 1 otherwise. If the expression's actual value is a non-numeric string then it must be one of the values accepted by **Tcl_GetBoolean** such as "yes" or "no", or else an error occurs.

If **Tcl_ExprObj** successfully evaluates the expression, it stores a pointer to the Tcl value containing the expression's value at **resultPtrPtr*. In this case, the caller is responsible for calling **Tcl_DecrRefCount** to decrement the value's reference count when it is finished with the value.

# Reference count management

**Tcl_ExprLongObj**, **Tcl_ExprDoubleObj**, **Tcl_ExprBooleanObj**, and **Tcl_ExprObj** all increment and decrement the reference count of their *objPtr* arguments; you must not pass them any value with a reference count of zero. They also manipulate the interpreter result; you must not count on the interpreter result to hold the reference count of any value over these calls. 

---
CommandName: Tcl_GetOpenFile
ManualSection: 3
Version: 8.0
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - channel
 - file handle
 - permissions
 - pipeline
 - read
 - write
Copyright:
 - Copyright (c) 1996-1997 Sun Microsystems, Inc.
---

# Name

Tcl_GetOpenFile - Return a FILE* for a channel registered in the given interpreter (Unix only)

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[int]{.ret} [Tcl_GetOpenFile]{.ccmd}[interp, chanID, write, checkUsage, filePtr]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Tcl interpreter from which file handle is to be obtained. .AP "const char" *chanID in String identifying channel, such as **stdin** or **file4**. .AP int write in Non-zero means the file will be used for writing, zero means it will be used for reading. .AP int checkUsage in If non-zero, then an error will be generated if the file was not opened for the access indicated by *write*. .AP void **filePtr out Points to word in which to store pointer to FILE structure for the file given by *chanID*. 

# Description

**Tcl_GetOpenFile** takes as argument a file identifier of the form returned by the **open** command and returns at **filePtr* a pointer to the FILE structure for the file. The *write* argument indicates whether the FILE pointer will be used for reading or writing. In some cases, such as a channel that connects to a pipeline of subprocesses, different FILE pointers will be returned for reading and writing. **Tcl_GetOpenFile** normally returns **TCL_OK**. If an error occurs in **Tcl_GetOpenFile** (e.g. *chanID* did not make any sense or *checkUsage* was set and the file was not opened for the access specified by *write*) then **TCL_ERROR** is returned and the interpreter's result will contain an error message. In the current implementation *checkUsage* is ignored and consistency checks are always performed.

Note that this interface is only supported on the Unix platform. 

---
CommandName: Tcl_GetVersion
ManualSection: 3
Version: 7.5
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - version
 - patchlevel
 - major
 - minor
 - alpha
 - beta
 - release
Copyright:
 - Copyright (c) 1999 Scriptics Corporation
---

# Name

Tcl_GetVersion - get the version of the library at runtime

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_GetVersion]{.ccmd}[major, minor, patchLevel, type]{.cargs}
:::

# Arguments

.AP int *major out Major version number of the Tcl library. .AP int *minor out Minor version number of the Tcl library. .AP int *patchLevel out The patch level of the Tcl library (or alpha or beta number). .AP int *type out The type of release, also indicates the type of patch level. Can be one of **TCL_ALPHA_RELEASE**, **TCL_BETA_RELEASE**, or **TCL_FINAL_RELEASE**. 

# Description

**Tcl_GetVersion** should be used to query the version number of the Tcl library at runtime.  This is useful when using a dynamically loaded Tcl library or when writing a stubs-aware extension.  For instance, if you write an extension that is linked against the Tcl stubs library, it could be loaded into a program linked to an older version of Tcl than you expected. Use **Tcl_GetVersion** to verify that fact, and possibly to change the behavior of your extension.

**Tcl_GetVersion** accepts NULL for any of the arguments. For instance if you do not care about the *patchLevel* of the library, pass a NULL for the *patchLevel* argument. 

---
CommandName: Tcl_InitStubs
ManualSection: 3
Version: 8.1
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tk_InitStubs
 - package
Keywords:
 - stubs
Copyright:
 - Copyright (c) 1998-1999 Scriptics Corporation
---

# Name

Tcl_InitStubs - initialize the Tcl stubs mechanism

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[const char *]{.ret} [Tcl_InitStubs]{.ccmd}[interp, version, exact]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Tcl interpreter handle. .AP "const char" *version in A version string, indicating which minimal version of Tcl is accepted. Normally just **"9.0"**. Or **"8.6-"** if both 8.6 and 9.0 are accepted. .AP int exact in 1 means that only the particular version specified by *version* is accepted. 0 means that versions newer than *version* are also accepted. If the*version* ends with **-**, higher major versions are accepted as well, otherwise the major version must be the same as in *version*. Other bits have no effect.

# Introduction

The Tcl stubs mechanism defines a way to dynamically bind extensions to a particular Tcl implementation at run time. This provides two significant benefits to Tcl users:

1. Extensions that use the stubs mechanism can be loaded into multiple versions of Tcl without being recompiled or relinked, as long as the major Tcl version is the same.

2. Extensions that use the stubs mechanism can be dynamically loaded into statically-linked Tcl applications.


The stubs mechanism accomplishes this by exporting function tables that define an interface to the Tcl API.  The extension then accesses the Tcl API through offsets into the function table, so there are no direct references to any of the Tcl library's symbols.  This redirection is transparent to the extension, so an extension writer can continue to use all public Tcl functions as documented.

The stubs mechanism requires no changes to applications incorporating Tcl interpreters.  Only developers creating C-based Tcl extensions need to take steps to use the stubs mechanism with their extensions.

Enabling the stubs mechanism for an extension requires the following steps:

1. Call **Tcl_InitStubs** in the extension before calling any other Tcl functions.

2. Define the **USE_TCL_STUBS** symbol.  Typically, you would include the **-DUSE_TCL_STUBS** flag when compiling the extension.

3. Link the extension with the Tcl stubs library instead of the standard Tcl library.  For example, to use the Tcl 9.0 ABI on Unix platforms, the library name is *libtclstub.a*; on Windows platforms, the library name is *tclstub.lib*.


If the extension also requires the Tk API, it must also call **Tk_InitStubs** to initialize the Tk stubs interface and link with the Tk stubs libraries.  See the **Tk_InitStubs** page for more information.

# Description

**Tcl_InitStubs** attempts to initialize the stub table pointers and ensure that the correct version of Tcl is loaded.  In addition to an interpreter handle, it accepts as arguments a version number and a Boolean flag indicating whether the extension requires an exact version match or not.  If *exact* is 0, then versions newer than *version* are also accepted. If the*version* ends with **-**, higher major versions are accepted as well, otherwise the major version must be the same as in *version*. 1 means that only the specified *version* is accepted. *version* can be any construct as described for **package require** (**PACKAGE** manual page in the section **REQUIREMENT**). Multiple requirement strings like with **package require** are not supported.  **Tcl_InitStubs** returns a string containing the actual version of Tcl satisfying the request, or NULL if the Tcl version is not accepted, does not support stubs, or any other error condition occurred.

---
CommandName: Tcl_LinkVar
ManualSection: 3
Version: 7.5
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_TraceVar(3)
Keywords:
 - boolean
 - integer
 - link
 - read-only
 - real
 - string
 - trace
 - variable
Copyright:
 - Copyright (c) 1993 The Regents of the University of California.
 - Copyright (c) 1994-1996 Sun Microsystems, Inc.
---

# Name

Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar - link Tcl variable to C variable

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[int]{.ret} [Tcl_LinkVar]{.ccmd}[interp, varName, addr, type]{.cargs}
[int]{.ret} [Tcl_LinkArray]{.ccmd}[interp, varName, addr, type, size]{.cargs}
[Tcl_UnlinkVar]{.ccmd}[interp, varName]{.cargs}
[Tcl_UpdateLinkedVar]{.ccmd}[interp, varName]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter that contains *varName*. Also used by **Tcl_LinkVar** to return error messages. .AP "const char" *varName in Name of global variable. .AP void *addr in Address of C variable that is to be linked to *varName*. .sp

::: {.info version="TIP312"}
In **Tcl_LinkArray**, may be NULL to tell Tcl to create the storage for the array in the variable.
:::

.AP int type in Type of C variable for **Tcl_LinkVar** or type of array element for **Tcl_LinkArray**.  Must be one of **TCL_LINK_INT**, **TCL_LINK_UINT**, **TCL_LINK_CHAR**, **TCL_LINK_UCHAR**, **TCL_LINK_SHORT**, **TCL_LINK_USHORT**, **TCL_LINK_LONG**, **TCL_LINK_ULONG**, **TCL_LINK_WIDE_INT**, **TCL_LINK_WIDE_UINT**, **TCL_LINK_FLOAT**, **TCL_LINK_DOUBLE**, **TCL_LINK_BOOLEAN**, or one of the extra ones listed below. .sp In **Tcl_LinkVar**, the additional linked type **TCL_LINK_STRING** may be used. .sp

::: {.info version="TIP312"}
In **Tcl_LinkArray**, the additional linked types **TCL_LINK_CHARS** and **TCL_LINK_BINARY** may be used.
:::

.sp All the above for both functions may be optionally OR'ed with **TCL_LINK_READ_ONLY** to make the Tcl variable read-only. .AP Tcl_Size size in

::: {.info version="TIP312"}
The number of elements in the C array. Must be greater than zero.
:::

# Description

**Tcl_LinkVar** uses variable traces to keep the Tcl variable named by *varName* in sync with the C variable at the address given by *addr*. Whenever the Tcl variable is read the value of the C variable will be returned, and whenever the Tcl variable is written the C variable will be updated to have the same value. **Tcl_LinkVar** normally returns **TCL_OK**;  if an error occurs while setting up the link (e.g. because *varName* is the name of array) then **TCL_ERROR** is returned and the interpreter's result contains an error message.

::: {.info version="TIP312"}
**Tcl_LinkArray** is similar, but for arrays of fixed size (given by the *size* argument). When asked to allocate the backing C array storage (via the *addr* argument being NULL), it writes the address that it allocated to the Tcl interpreter result.
:::

The *type* argument specifies the type of the C variable, or the type of the elements of the C array, and must have one of the following values, optionally OR'ed with **TCL_LINK_READ_ONLY**:

**TCL_LINK_INT**
: The C variable, or each element of the C array, is of type **int**. Any value written into the Tcl variable must have a proper integer form acceptable to **Tcl_GetIntFromObj**;  attempts to write non-integer values into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_UINT**
: The C variable, or each element of the C array, is of type **unsigned int**. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to **Tcl_GetWideIntFromObj** and in the platform's defined range for the **unsigned int** type; attempts to write non-integer values (or values outside the range) into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_CHAR**
: The C variable, or each element of the C array, is of type **char**. Any value written into the Tcl variable must have a proper integer form acceptable to **Tcl_GetIntFromObj** and be in the range of the **char** datatype; attempts to write non-integer or out-of-range values into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.
    If using an array of these, consider using **TCL_LINK_CHARS** instead.

**TCL_LINK_CHARS**
: The C array is of type **char *** and is mapped into Tcl as a string. Any value written into the Tcl variable must have the same length as the underlying storage. Only supported with **Tcl_LinkArray**.

**TCL_LINK_UCHAR**
: The C variable, or each element of the C array, is of type **unsigned char**. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to **Tcl_GetIntFromObj** and in the platform's defined range for the **unsigned char** type; attempts to write non-integer values (or values outside the range) into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.
    If using an array of these, consider using **TCL_LINK_BINARY** instead.

**TCL_LINK_BINARY**
: The C array is of type **unsigned char *** and is mapped into Tcl as a bytearray. Any value written into the Tcl variable must have the same length as the underlying storage. Only supported with **Tcl_LinkArray**.

**TCL_LINK_SHORT**
: The C variable, or each element of the C array, is of type **short**. Any value written into the Tcl variable must have a proper integer form acceptable to **Tcl_GetIntFromObj** and be in the range of the **short** datatype; attempts to write non-integer or out-of-range values into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_USHORT**
: The C variable, or each element of the C array, is of type **unsigned short**. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to **Tcl_GetIntFromObj** and in the platform's defined range for the **unsigned short** type; attempts to write non-integer values (or values outside the range) into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_LONG**
: The C variable, or each element of the C array, is of type **long**. Any value written into the Tcl variable must have a proper integer form acceptable to **Tcl_GetLongFromObj**; attempts to write non-integer or out-of-range values into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_ULONG**
: The C variable, or each element of the C array, is of type **unsigned long**. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to **Tcl_GetWideIntFromObj** and in the platform's defined range for the **unsigned long** type; attempts to write non-integer values (or values outside the range) into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_DOUBLE**
: The C variable, or each element of the C array, is of type **double**. Any value written into the Tcl variable must have a proper real form acceptable to **Tcl_GetDoubleFromObj**;  attempts to write non-real values into *varName* will be rejected with Tcl errors. Incomplete integer or real representations (like the empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_FLOAT**
: The C variable, or each element of the C array, is of type **float**. Any value written into the Tcl variable must have a proper real form acceptable to **Tcl_GetDoubleFromObj** and must be within the range acceptable for a **float**; attempts to write non-real values (or values outside the range) into *varName* will be rejected with Tcl errors. Incomplete integer or real representations (like the empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_WIDE_INT**
: The C variable, or each element of the C array, is of type **Tcl_WideInt** (which is an integer type at least 64-bits wide on all platforms that can support it.) Any value written into the Tcl variable must have a proper integer form acceptable to **Tcl_GetWideIntFromObj**;  attempts to write non-integer values into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_WIDE_UINT**
: The C variable, or each element of the C array, is of type **Tcl_WideUInt** (which is an unsigned integer type at least 64-bits wide on all platforms that can support it.) Any value written into the Tcl variable must have a proper unsigned wideinteger form acceptable to **Tcl_GetWideUIntFromObj**; attempts to write non-integer values into *varName* will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too.

**TCL_LINK_BOOLEAN**
: The C variable, or each element of the C array, is of type **int**. If its value is zero then it will read from Tcl as "0"; otherwise it will read from Tcl as "1". Whenever *varName* is modified, the C variable will be set to a 0 or 1 value. Any value written into the Tcl variable must have a proper boolean form acceptable to **Tcl_GetBooleanFromObj**;  attempts to write non-boolean values into *varName* will be rejected with Tcl errors.

**TCL_LINK_STRING**
: The C variable is of type **char ***. If its value is not NULL then it must be a pointer to a string allocated with **Tcl_Alloc**. Whenever the Tcl variable is modified the current C string will be freed and new memory will be allocated to hold a copy of the variable's new value. If the C variable contains a NULL pointer then the Tcl variable will read as "NULL". This is only supported by **Tcl_LinkVar**.


If the **TCL_LINK_READ_ONLY** flag is present in *type* then the variable will be read-only from Tcl, so that its value can only be changed by modifying the C variable. Attempts to write the variable from Tcl will be rejected with errors.

**Tcl_UnlinkVar** removes the link previously set up for the variable given by *varName*.  If there does not exist a link for *varName* then the procedure has no effect.

**Tcl_UpdateLinkedVar** may be invoked after the C variable has changed to force the Tcl variable to be updated immediately. In many cases this procedure is not needed, since any attempt to read the Tcl variable will return the latest value of the C variable. However, if a trace has been set on the Tcl variable (such as a Tk widget that wishes to display the value of the variable), the trace will not trigger when the C variable has changed. **Tcl_UpdateLinkedVar** ensures that any traces on the Tcl variable are invoked.

Note that, as with any call to a Tcl interpreter, **Tcl_UpdateLinkedVar** must be called from the same thread that created the interpreter. The safest mechanism is to ensure that the C variable is only ever updated from the same thread that created the interpreter (possibly in response to an event posted with **Tcl_ThreadQueueEvent**), but when it is necessary to update the variable in a separate thread, it is advised that **Tcl_AsyncMark** be used to indicate to the thread hosting the interpreter that it is ready to run **Tcl_UpdateLinkedVar**.

---
CommandName: Load
ManualSection: 3
Version: 8.6
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_FSLoadFile(3)
 - Tcl_FSUnloadFile(3)
 - load(n)
 - unload(n)
Keywords:
 - binary code
 - loading
 - shared library
Copyright:
 - Copyright (c) 2009-2010 Kevin B. Kenny
 - Copyright (c) 2010 Donal K. Fellows
---

# Name

Tcl_LoadFile, Tcl_FindSymbol - platform-independent dynamic library loading

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[int]{.ret} [Tcl_LoadFile]{.ccmd}[interp, pathPtr, symbols, flags, procPtrs, loadHandlePtr]{.cargs}
[void *]{.ret} [Tcl_FindSymbol]{.ccmd}[interp, loadHandle, symbol]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter to use for reporting error messages. .AP Tcl_Obj *pathPtr in The name of the file to load. If it is a single name, the library search path of the current environment will be used to resolve it. .AP "const char *const" symbols[] in Array of names of symbols to be resolved during the load of the library, or NULL if no symbols are to be resolved. If an array is given, the last entry in the array must be NULL. .AP int flags in The value should normally be 0, but *TCL_LOAD_GLOBAL* or *TCL_LOAD_LAZY* or a combination of those two is allowed as well. .AP void *procPtrs out Points to an array that will hold the addresses of the functions described in the *symbols* argument. Should be NULL if no symbols are to be resolved. .AP Tcl_LoadHandle *loadHandlePtr out Points to a variable that will hold the handle to the abstract token describing the library that has been loaded. .AP Tcl_LoadHandle loadHandle in Abstract token describing the library to look up a symbol in. .AP "const char" *symbol in The name of the symbol to look up.

# Description

**Tcl_LoadFile** loads a file from the filesystem (including potentially any virtual filesystem that has been installed) and provides a handle to it that may be used in further operations. The *symbols* array, if non-NULL, supplies a set of names of symbols (typically functions) that must be resolved from the library and which will be stored in the array indicated by *procPtrs*. If any of the symbols is not resolved, the loading of the file will fail with an error message left in the interpreter (if that is non-NULL). The result of **Tcl_LoadFile** is a standard Tcl error code. The library may be unloaded with **Tcl_FSUnloadFile**.

**Tcl_FindSymbol** locates a symbol in a loaded library and returns it. If the symbol cannot be found, it returns NULL and sets an error message in the given *interp* (if that is non-NULL). Note that it is unsafe to use this operation on a handle that has been passed to **Tcl_FSUnloadFile**.

# Reference count management

The reference count of the *pathPtr* argument to **Tcl_LoadFile** may be incremented. As such, it should not be given a zero reference count value.

---
CommandName: Tcl_Namespace
ManualSection: 3
Version: 8.5
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_CreateCommand(3)
 - Tcl_ListObjAppendList(3)
 - Tcl_SetVar(3)
Keywords:
 - namespace
 - command
Copyright:
 - Copyright (c) 2003 Donal K. Fellows
---

# Name

Tcl_AppendExportList, Tcl_CreateNamespace, Tcl_DeleteNamespace, Tcl_Export, Tcl_FindCommand, Tcl_FindNamespace, Tcl_ForgetImport, Tcl_GetCurrentNamespace, Tcl_GetGlobalNamespace, Tcl_GetNamespaceUnknownHandler, Tcl_Import, Tcl_SetNamespaceUnknownHandler - manipulate namespaces

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_Namespace *]{.ret} [Tcl_CreateNamespace]{.ccmd}[interp, name, clientData, deleteProc]{.cargs}
[Tcl_DeleteNamespace]{.ccmd}[nsPtr]{.cargs}
[int]{.ret} [Tcl_AppendExportList]{.ccmd}[interp, nsPtr, objPtr]{.cargs}
[int]{.ret} [Tcl_Export]{.ccmd}[interp, nsPtr, pattern, resetListFirst]{.cargs}
[int]{.ret} [Tcl_Import]{.ccmd}[interp, nsPtr, pattern, allowOverwrite]{.cargs}
[int]{.ret} [Tcl_ForgetImport]{.ccmd}[interp, nsPtr, pattern]{.cargs}
[Tcl_Namespace *]{.ret} [Tcl_GetCurrentNamespace]{.ccmd}[interp]{.cargs}
[Tcl_Namespace *]{.ret} [Tcl_GetGlobalNamespace]{.ccmd}[interp]{.cargs}
[Tcl_Namespace *]{.ret} [Tcl_FindNamespace]{.ccmd}[interp, name, contextNsPtr, flags]{.cargs}
[Tcl_Command]{.ret} [Tcl_FindCommand]{.ccmd}[interp, name, contextNsPtr, flags]{.cargs}
[Tcl_Obj *]{.ret} [Tcl_GetNamespaceUnknownHandler]{.ccmd}[interp, nsPtr]{.cargs}
[int]{.ret} [Tcl_SetNamespaceUnknownHandler]{.ccmd}[interp, nsPtr, handlerPtr]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in/out The interpreter in which the namespace exists and where name lookups are performed. Also where error result messages are written. .AP "const char" *name in The name of the namespace or command to be created or accessed. .AP void *clientData in A context pointer by the creator of the namespace.  Not interpreted by Tcl at all. .AP Tcl_NamespaceDeleteProc *deleteProc in A pointer to function to call when the namespace is deleted, or NULL if no such callback is to be performed. .AP Tcl_Namespace *nsPtr in The namespace to be manipulated, or NULL (for other than **Tcl_DeleteNamespace**) to manipulate the current namespace. .AP Tcl_Obj *objPtr out A reference to an unshared value to which the function output will be written. .AP "const char" *pattern in The glob-style pattern (see **Tcl_StringMatch**) that describes the commands to be imported or exported. .AP int resetListFirst in Whether the list of export patterns should be reset before adding the current pattern to it. .AP int allowOverwrite in Whether new commands created by this import action can overwrite existing commands. .AP Tcl_Namespace *contextNsPtr in The location in the namespace hierarchy where the search for a namespace or command should be conducted relative to when the search term is not rooted at the global namespace.  NULL indicates the current namespace. .AP int flags in OR-ed combination of bits controlling how the search is to be performed.  The following flags are supported: **TCL_GLOBAL_ONLY** (indicates that the search is always to be conducted relative to the global namespace), **TCL_NAMESPACE_ONLY** (just for **Tcl_FindCommand**; indicates that the search is always to be conducted relative to the context namespace), and **TCL_LEAVE_ERR_MSG** (indicates that an error message should be left in the interpreter if the search fails.) .AP Tcl_Obj *handlerPtr in A script fragment to be installed as the unknown command handler for the namespace, or NULL to reset the handler to its default.

# Description

Namespaces are hierarchic naming contexts that can contain commands and variables.  They also maintain a list of patterns that describes what commands are exported, and can import commands that have been exported by other namespaces.  Namespaces can also be manipulated through the Tcl command **namespace**.

The *Tcl_Namespace* structure encapsulates a namespace, and is guaranteed to have the following fields in it: *name* (the local name of the namespace, with no namespace separator characters in it, with empty denoting the global namespace), *fullName* (the fully specified name of the namespace), *clientData*, *deleteProc* (the values specified in the call to **Tcl_CreateNamespace**), and *parentPtr* (a pointer to the containing namespace, or NULL for the global namespace.)

**Tcl_CreateNamespace** creates a new namespace.  The *deleteProc* will have the following type signature:

```
typedef void Tcl_NamespaceDeleteProc(
        void *clientData);
```

**Tcl_DeleteNamespace** deletes a namespace, calling the *deleteProc* defined for the namespace (if any).

**Tcl_AppendExportList** retrieves the export patterns for a namespace given namespace and appends them (as list items) to *objPtr*.

**Tcl_Export** sets and appends to the export patterns for a namespace.  Patterns are appended unless the *resetListFirst* flag is true.

**Tcl_Import** imports commands matching a pattern into a namespace.  Note that the pattern must include the name of the namespace to import from.  This function returns TCL_ERROR if an attempt to import a command over an existing command is made, unless the *allowOverwrite* flag has been set.

**Tcl_ForgetImport** removes imports matching a pattern.

**Tcl_GetCurrentNamespace** returns the current namespace for an interpreter.

**Tcl_GetGlobalNamespace** returns the global namespace for an interpreter.

**Tcl_FindNamespace** searches for a namespace named *name* within the context of the namespace *contextNsPtr*.  If the namespace cannot be found, NULL is returned.

**Tcl_FindCommand** searches for a command named *name* within the context of the namespace *contextNsPtr*.  If the command cannot be found, NULL is returned.

**Tcl_GetNamespaceUnknownHandler** returns the unknown command handler for the namespace, or NULL if none is set.

**Tcl_SetNamespaceUnknownHandler** sets the unknown command handler for the namespace. If *handlerPtr* is NULL, then the handler is reset to its default.

# Reference count management

The *objPtr* argument to **Tcl_AppendExportList** should be an unshared object, as it will be modified by this function. The reference count of *objPtr* will not be altered.

**Tcl_GetNamespaceUnknownHandler** returns a possibly shared value. Its reference count should be incremented if the value is to be retained.

The *handlerPtr* argument to **Tcl_SetNamespaceUnknownHandler** will have its reference count incremented if it is a non-empty list.

---
CommandName: Tcl_OOInitStubs
ManualSection: 3
Version: 1.0
TclPart: TclOO
TclDescription: TclOO Library Functions
Keywords:
 - stubs
Links:
 - Tcl_InitStubs(3)
Copyright:
 - Copyright (c) 2012 Donal K. Fellows
---

# Name

Tcl_OOInitStubs - initialize library access to TclOO functionality

# Synopsis

::: {.synopsis} :::
**#include <tclOO.h>**
[const char *]{.ret} [Tcl_OOInitStubs]{.ccmd}[interp]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in The Tcl interpreter that the TclOO API is integrated with and whose C interface is going to be used.

# Description

When an extension library is going to use the C interface exposed by TclOO, it should use **Tcl_OOInitStubs** to initialize its access to that interface from within its *****_Init** (or *****_SafeInit**) function, passing in the *interp* that was passed into that routine as context. If the result of calling **Tcl_OOInitStubs** is NULL, the initialization failed and an error message will have been left in the interpreter's result. Otherwise, the initialization succeeded and the TclOO API may thereafter be used; the version of the TclOO API is returned.

When using this function, either the C #define symbol **USE_TCLOO_STUBS** should be defined and your library code linked against the Tcl stub library, or that #define symbol should *not* be defined and your library code linked against the Tcl main library directly.

# Backward compatibility note

If you are linking against the Tcl 8.5 forward compatibility package for TclOO, *only* the stub-enabled configuration is supported and you should also link against the TclOO independent stub library; that library is an integrated part of the main Tcl stub library in Tcl 8.6.

---
CommandName: Tcl_PkgRequire
ManualSection: 3
Version: 7.5
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - package
 - present
 - provide
 - require
 - version
Links:
 - package(n)
 - Tcl_StaticLibrary(3)
Copyright:
 - Copyright (c) 1996 Sun Microsystems, Inc.
---

# Name

Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgRequireProc, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx - package version control

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[const char *]{.ret} [Tcl_PkgRequire]{.ccmd}[interp, name, version, exact]{.cargs}
[const char *]{.ret} [Tcl_PkgRequireEx]{.ccmd}[interp, name, version, exact, clientDataPtr]{.cargs}
[int]{.ret} [Tcl_PkgRequireProc]{.ccmd}[interp, name, objc, objv, clientDataPtr]{.cargs}
[const char *]{.ret} [Tcl_PkgPresent]{.ccmd}[interp, name, version, exact]{.cargs}
[const char *]{.ret} [Tcl_PkgPresentEx]{.ccmd}[interp, name, version, exact, clientDataPtr]{.cargs}
[int]{.ret} [Tcl_PkgProvide]{.ccmd}[interp, name, version]{.cargs}
[int]{.ret} [Tcl_PkgProvideEx]{.ccmd}[interp, name, version, clientData]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter where package is needed or available. .AP "const char" *name in Name of package. .AP "const char" *version in A version specification string as described for **package require**. .AP int exact in Non-zero means that only the particular version specified by *version* is acceptable. Zero means that newer versions than *version* are also acceptable as long as they have the same major version number as *version*. .AP "const void" *clientData in Arbitrary value to be associated with the package. .AP void *clientDataPtr out Pointer to place to store the value associated with the matching package. It is only changed if the pointer is not NULL and the function completed successfully. The storage can be any pointer type with the same size as a void pointer. .AP Tcl_Size objc in Number of requirements. .AP Tcl_Obj* objv[] in Array of requirements.

# Description

These procedures provide C-level interfaces to Tcl's package and version management facilities.

**Tcl_PkgRequire** is equivalent to the **package require** command, **Tcl_PkgPresent** is equivalent to the **package present** command, and **Tcl_PkgProvide** is equivalent to the **package provide** command.

See the documentation for the Tcl commands for details on what these procedures do.

If **Tcl_PkgPresent** or **Tcl_PkgRequire** complete successfully they return a pointer to the version string for the version of the package that is provided in the interpreter (which may be different than *version*); if an error occurs they return NULL and leave an error message in the interpreter's result.

**Tcl_PkgProvide** returns **TCL_OK** if it completes successfully; if an error occurs it returns **TCL_ERROR** and leaves an error message in the interpreter's result.

**Tcl_PkgProvideEx**, **Tcl_PkgPresentEx** and **Tcl_PkgRequireEx** allow the setting and retrieving of the client data associated with the package. In all other respects they are equivalent to the matching functions.

**Tcl_PkgRequireProc** is the form of **package require** handling multiple requirements. The other forms are present for backward compatibility and translate their invocations to this form.

# Reference count management

The requirements values given (in the *objv* argument) to **Tcl_PkgRequireProc** must have non-zero reference counts.

---
CommandName: Tcl_PrintDouble
ManualSection: 3
Version: 8.0
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - conversion
 - double-precision
 - floating-point
 - string
Copyright:
 - Copyright (c) 1989-1993 The Regents of the University of California.
 - Copyright (c) 1994-1997 Sun Microsystems, Inc.
---

# Name

Tcl_PrintDouble - Convert floating value to string

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_PrintDouble]{.ccmd}[interp, value, dst]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in This argument is ignored. .AP double value in Floating-point value to be converted. .AP char *dst out Where to store the string representing *value*.  Must have at least **TCL_DOUBLE_SPACE** characters of storage.

# Description

**Tcl_PrintDouble** generates a string that represents the value of *value* and stores it in memory at the location given by *dst*.  It uses **%g** format to generate the string, with one special twist: the string is guaranteed to contain either a "." or an "e" so that it does not look like an integer.  Where **%g** would generate an integer with no decimal point, **Tcl_PrintDouble** adds ".0".

The result will have the fewest digits needed to represent the number in such a way that **Tcl_NewDoubleObj** will generate the same number when presented with the given string. IEEE semantics of rounding to even apply to the conversion.

---
CommandName: Tcl_SetErrno
ManualSection: 3
Version: 8.3
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - errno
 - error code
 - global variables
Copyright:
 - Copyright (c) 1996 Sun Microsystems, Inc.
---

# Name

Tcl_SetErrno, Tcl_GetErrno, Tcl_ErrnoId, Tcl_ErrnoMsg, Tcl_WinConvertError - manipulate errno to store and retrieve error codes

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[void]{.ret} [Tcl_SetErrno]{.ccmd}[errorCode]{.cargs}
[int]{.ret} [Tcl_GetErrno]{.ccmd}[]{.cargs}
[const char *]{.ret} [Tcl_ErrnoId]{.ccmd}[]{.cargs}
[const char *]{.ret} [Tcl_ErrnoMsg]{.ccmd}[errorCode]{.cargs}
[void]{.ret} [Tcl_WinConvertError]{.ccmd}[winErrorCode]{.cargs}
:::

# Arguments

.AP int errorCode in A POSIX error code such as **ENOENT**. .AP DWORD winErrorCode in A Windows or Winsock error code such as **ERROR_FILE_NOT_FOUND**. 

# Description

**Tcl_SetErrno** and **Tcl_GetErrno** provide portable access to the **errno** variable, which is used to record a POSIX error code after system calls and other operations such as **Tcl_Gets**. These procedures are necessary because global variable accesses cannot be made across module boundaries on some platforms.

**Tcl_SetErrno** sets the **errno** variable to the value of the *errorCode* argument C procedures that wish to return error information to their callers via **errno** should call **Tcl_SetErrno** rather than setting **errno** directly.

**Tcl_GetErrno** returns the current value of **errno**. Procedures wishing to access **errno** should call this procedure instead of accessing **errno** directly.

**Tcl_ErrnoId** and **Tcl_ErrnoMsg** return string representations of **errno** values.  **Tcl_ErrnoId** returns a machine-readable textual identifier such as "EACCES" that corresponds to the current value of **errno**. **Tcl_ErrnoMsg** returns a human-readable string such as "permission denied" that corresponds to the value of its *errorCode* argument.  The *errorCode* argument is typically the value returned by **Tcl_GetErrno**. The strings returned by these functions are statically allocated and the caller must not free or modify them.

**Tcl_WinConvertError** (Windows only) maps the passed Windows or Winsock error code to a POSIX error and stores it in **errno**. 

---
CommandName: Tcl_SetResult
ManualSection: 3
Version: 9.0
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_AddErrorInfo
 - Tcl_CreateObjCommand
 - Tcl_SetErrorCode
 - Tcl_Interp
 - Tcl_GetReturnOptions
Keywords:
 - append
 - command
 - element
 - list
 - value
 - result
 - return value
 - interpreter
Copyright:
 - Copyright (c) 1989-1993 The Regents of the University of California.
 - Copyright (c) 1994-1997 Sun Microsystems, Inc.
---

# Name

Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult - manipulate Tcl result

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_SetObjResult]{.ccmd}[interp, objPtr]{.cargs}
[Tcl_Obj *]{.ret} [Tcl_GetObjResult]{.ccmd}[interp]{.cargs}
[Tcl_SetResult]{.ccmd}[interp, result, freeProc]{.cargs}
[const char *]{.ret} [Tcl_GetStringResult]{.ccmd}[interp]{.cargs}
[Tcl_AppendResult]{.ccmd}[interp, result, result, ... ,= §(char *)NULL]{.cargs}
[Tcl_ResetResult]{.ccmd}[interp]{.cargs}
[Tcl_TransferResult]{.ccmd}[sourceInterp, code, targetInterp]{.cargs}
[Tcl_AppendElement]{.ccmd}[interp, element]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp out Interpreter whose result is to be modified or read. .AP Tcl_Obj *objPtr in Tcl value to become result for *interp*. .AP char *result in String value to become result for *interp* or to be appended to the existing result. .AP "const char" *element in String value to append as a list element to the existing result of *interp*. .AP Tcl_FreeProc *freeProc in Address of procedure to call to release storage at *result*, or **TCL_STATIC**, **TCL_DYNAMIC**, or **TCL_VOLATILE**. .AP Tcl_Interp *sourceInterp in Interpreter that the result and return options should be transferred from. .AP Tcl_Interp *targetInterp in Interpreter that the result and return options should be transferred to. .AP int code in Return code value that controls transfer of return options.

# Description

The procedures described here are utilities for manipulating the result value in a Tcl interpreter. The interpreter result may be either a Tcl value or a string. For example, **Tcl_SetObjResult** and **Tcl_SetResult** set the interpreter result to, respectively, a value and a string. Similarly, **Tcl_GetObjResult** and **Tcl_GetStringResult** return the interpreter result as a value and as a string. The procedures always keep the string and value forms of the interpreter result consistent. For example, if **Tcl_SetObjResult** is called to set the result to a value, then **Tcl_GetStringResult** is called, it will return the value's string representation.

**Tcl_SetObjResult** arranges for *objPtr* to be the result for *interp*, replacing any existing result. The result is left pointing to the value referenced by *objPtr*. *objPtr*'s reference count is incremented since there is now a new reference to it from *interp*. The reference count for any old result value is decremented and the old result value is freed if no references to it remain.

**Tcl_GetObjResult** returns the result for *interp* as a value. The value's reference count is not incremented; if the caller needs to retain a long-term pointer to the value they should use **Tcl_IncrRefCount** to increment its reference count in order to keep it from being freed too early or accidentally changed.

**Tcl_SetResult** arranges for *result* to be the result for the current Tcl command in *interp*, replacing any existing result. The *freeProc* argument specifies how to manage the storage for the *result* argument; it is discussed in the section **THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT** below. If *result* is **NULL**, then *freeProc* is ignored and **Tcl_SetResult** re-initializes *interp*'s result to point to an empty string.

**Tcl_GetStringResult** returns the result for *interp* as a string. If the result was set to a value by a **Tcl_SetObjResult** call, the value form will be converted to a string and returned. If the value's string representation contains null bytes, this conversion will lose information. For this reason, programmers are encouraged to write their code to use the new value API procedures and to call **Tcl_GetObjResult** instead.

**Tcl_ResetResult** clears the result for *interp* and leaves the result in its normal empty initialized state. If the result is a value, its reference count is decremented and the result is left pointing to an unshared value representing an empty string. If the result is a dynamically allocated string, its memory is free*d and the result is left as a empty string. **Tcl_ResetResult** also clears the error state managed by **Tcl_AddErrorInfo**, **Tcl_AddObjErrorInfo**, and **Tcl_SetErrorCode**.

**Tcl_AppendResult** makes it easy to build up Tcl results in pieces. It takes each of its *result* arguments and appends them in order to the current result associated with *interp*. If the result is in its initialized empty state (e.g. a command procedure was just invoked or **Tcl_ResetResult** was just called), then **Tcl_AppendResult** sets the result to the concatenation of its *result* arguments. **Tcl_AppendResult** may be called repeatedly as additional pieces of the result are produced. **Tcl_AppendResult** takes care of all the storage management issues associated with managing *interp*'s result, such as allocating a larger result area if necessary. It also manages conversion to and from the *result* field of the *interp* so as to handle backward-compatibility with old-style extensions. Any number of *result* arguments may be passed in a single call; the last argument in the list must be (char *)NULL.

**Tcl_TransferResult** transfers interpreter state from *sourceInterp* to *targetInterp*. The two interpreters must have been created in the same thread.  If *sourceInterp* and *targetInterp* are the same, nothing is done. Otherwise, **Tcl_TransferResult** moves the result from *sourceInterp* to *targetInterp*, and resets the result in *sourceInterp*. It also moves the return options dictionary as controlled by the return code value *code* in the same manner as **Tcl_GetReturnOptions**.

# Deprecated interfaces

## Old string procedures

Use of the following procedures is deprecated since they manipulate the Tcl result as a string. Procedures such as **Tcl_SetObjResult** that manipulate the result as a value can be significantly more efficient.

**Tcl_AppendElement** is similar to **Tcl_AppendResult** in that it allows results to be built up in pieces. However, **Tcl_AppendElement** takes only a single *element* argument and it appends that argument to the current result as a proper Tcl list element. **Tcl_AppendElement** adds backslashes or braces if necessary to ensure that *interp*'s result can be parsed as a list and that *element* will be extracted as a single element. Under normal conditions, **Tcl_AppendElement** will add a space character to *interp*'s result just before adding the new list element, so that the list elements in the result are properly separated. However if the new list element is the first in a list or sub-list (i.e. *interp*'s current result is empty, or consists of the single character "{", or ends in the characters " {") then no space is added.

# The tcl_freeproc argument to tcl_setresult

**Tcl_SetResult**'s *freeProc* argument specifies how the Tcl system is to manage the storage for the *result* argument. If **Tcl_SetResult** or **Tcl_SetObjResult** are called at a time when *interp* holds a string result, they do whatever is necessary to dispose of the old string result (see the **Tcl_Interp** manual entry for details on this).

If *freeProc* is **TCL_STATIC** it means that *result* refers to an area of static storage that is guaranteed not to be modified until at least the next call to **Tcl_Eval**. If *freeProc* is **TCL_DYNAMIC** it means that *result* was allocated with a call to **Tcl_Alloc** and is now the property of the Tcl system. **Tcl_SetResult** will arrange for the string's storage to be released by calling **Tcl_Free** when it is no longer needed. If *freeProc* is **TCL_VOLATILE** it means that *result* points to an area of memory that is likely to be overwritten when **Tcl_SetResult** returns (e.g. it points to something in a stack frame). In this case **Tcl_SetResult** will make a copy of the string in dynamically allocated storage and arrange for the copy to be the result for the current Tcl command.

If *freeProc* is not one of the values **TCL_STATIC**, **TCL_DYNAMIC**, and **TCL_VOLATILE**, then it is the address of a procedure that Tcl should call to free the string. This allows applications to use non-standard storage allocators. When Tcl no longer needs the storage for the string, it will call *freeProc*. *FreeProc* should have arguments and result that match the type **Tcl_FreeProc**:

```
typedef void Tcl_FreeProc(
        void *blockPtr);
```

When *freeProc* is called, its *blockPtr* will be set to the value of *result* passed to **Tcl_SetResult**. 

# Reference count management

The interpreter result is one of the main places that owns references to values, along with the bytecode execution stack, argument lists, variables, and the list and dictionary collection values.

**Tcl_SetObjResult** takes a value with an arbitrary reference count *(specifically including zero)* and guarantees to increment the reference count. If code wishes to continue using the value after setting it as the result, it should add its own reference to it with **Tcl_IncrRefCount**.

**Tcl_GetObjResult** returns the current interpreter result value. This will have a reference count of at least 1. If the caller wishes to keep the interpreter result value, it should increment its reference count.

**Tcl_GetStringResult** does not manipulate reference counts, but the string it returns is owned by (and has a lifetime controlled by) the current interpreter result value; it should be copied instead of being relied upon to persist after the next Tcl API call, as most Tcl operations can modify the interpreter result.

**Tcl_SetResult**, **Tcl_AppendResult**, **Tcl_AppendElement**, and **Tcl_ResetResult** all modify the interpreter result. They may cause the old interpreter result to have its reference count decremented and a new interpreter result to be allocated. After they have been called, the reference count of the interpreter result is guaranteed to be 1.

---
CommandName: Tcl_SignalId
ManualSection: 3
Version: 8.3
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - signals
 - signal numbers
Copyright:
 - Copyright (c) 2001 ActiveState Tool Corp.
---

# Name

Tcl_SignalId, Tcl_SignalMsg - Convert signal codes

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[const char *]{.ret} [Tcl_SignalId]{.ccmd}[sig]{.cargs}
[const char *]{.ret} [Tcl_SignalMsg]{.ccmd}[sig]{.cargs}
:::

# Arguments

.AP int sig in A POSIX signal number such as **SIGPIPE**. 

# Description

**Tcl_SignalId** and **Tcl_SignalMsg** return a string representation of the provided signal number (*sig*). **Tcl_SignalId** returns a machine-readable textual identifier such as "SIGPIPE". **Tcl_SignalMsg** returns a human-readable string such as "bus error". The strings returned by these functions are statically allocated and the caller must not free or modify them. 

---
CommandName: Standard Channels
ManualSection: 3
Version: 7.5
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_CreateChannel(3)
 - Tcl_RegisterChannel(3)
 - Tcl_GetChannel(3)
 - Tcl_GetStdChannel(3)
 - Tcl_SetStdChannel(3)
 - Tk_InitConsoleChannels(3)
 - tclsh(1)
 - wish(1)
 - Tcl_Main(3)
 - Tk_MainEx(3)
Keywords:
 - standard channels
Copyright:
 - Copyright (c) 2001 ActiveState Corporation
---

# Name

Tcl_StandardChannels - How the Tcl library deals with the standard channels 

# Description

This page explains the initialization and use of standard channels in the Tcl library.

The term *standard channels* comes out of the Unix world and refers to the three channels automatically opened by the OS for each new application. They are **stdin**, **stdout** and **stderr**. The first is the standard input an application can read from, the other two refer to writable channels, one for regular output and the other for error messages.

Tcl generalizes this concept in a cross-platform way and exposes standard channels to the script level.

## Application programming interfaces

The public API procedures dealing directly with standard channels are **Tcl_GetStdChannel** and **Tcl_SetStdChannel**. Additional public APIs to consider are **Tcl_RegisterChannel**, **Tcl_CreateChannel** and **Tcl_GetChannel**.

# Initialization of tcl standard channels

Standard channels are initialized by the Tcl library in three cases: when explicitly requested, when implicitly required before returning channel information, or when implicitly required during registration of a new channel.

These cases differ in how they handle unavailable platform- specific standard channels.  (A channel is not "available" if it could not be successfully opened; for example, in a Tcl application run as a Windows NT service.)

1. A single standard channel is initialized when it is explicitly specified in a call to **Tcl_SetStdChannel**.  The states of the other standard channels are unaffected.
Missing platform-specific standard channels do not matter here. This approach is not available at the script level.

2. All uninitialized standard channels are initialized to platform-specific default values:

(a)
: when open channels are listed with **Tcl_GetChannelNames** (or the **file channels** script command), or

(b)
: when information about any standard channel is requested with a call to **Tcl_GetStdChannel**, or with a call to **Tcl_GetChannel** which specifies one of the standard names (**stdin**, **stdout** and **stderr**).

In case of missing platform-specific standard channels, the Tcl standard channels are considered as initialized and then immediately closed. This means that the first three Tcl channels then opened by the application are designated as the Tcl standard channels.

3. All uninitialized standard channels are initialized to platform-specific default values when a user-requested channel is registered with **Tcl_RegisterChannel**.


In case of unavailable platform-specific standard channels the channel whose creation caused the initialization of the Tcl standard channels is made a normal channel.  The next three Tcl channels opened by the application are designated as the Tcl standard channels.  In other words, of the first four Tcl channels opened by the application the second to fourth are designated as the Tcl standard channels.

# Re-initialization of tcl standard channels

Once a Tcl standard channel is initialized through one of the methods above, closing this Tcl standard channel will cause the next call to **Tcl_CreateChannel** to make the new channel the new standard channel, too. If more than one Tcl standard channel was closed **Tcl_CreateChannel** will fill the empty slots in the order **stdin**, **stdout** and **stderr**.

**Tcl_CreateChannel** will not try to reinitialize an empty slot if that slot was not initialized before. It is this behavior which enables an application to employ method 1 of initialization, i.e. to create and designate their own Tcl standard channels.

# Shell-specific details

## Tclsh

The Tcl shell (or rather the function **Tcl_Main**, which forms the core of the shell's implementation) uses method 2 to initialize the standard channels.

## Wish

The windowing shell (or rather the function **Tk_MainEx**, which forms the core of the shell's implementation) uses method 1 to initialize the standard channels (See **Tk_InitConsoleChannels**) on non-Unix platforms.  On Unix platforms, **Tk_MainEx** implicitly uses method 2 to initialize the standard channels.

---
CommandName: Tcl_TranslateFileName
ManualSection: 3
Version: 8.1
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - filename(n)
Keywords:
 - file name
 - home directory
 - translate
 - user
Copyright:
 - Copyright (c) 1989-1993 The Regents of the University of California.
 - Copyright (c) 1994-1998 Sun Microsystems, Inc.
---

# Name

Tcl_TranslateFileName - convert file name to native form

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[char *]{.ret} [Tcl_TranslateFileName]{.ccmd}[interp=, +name=, +bufferPtr]{.cargs}
:::

# Arguments

.AP Tcl_Interp *interp in Interpreter in which to report an error, if any. .AP "const char" *name in File name .AP Tcl_DString *bufferPtr in/out If needed, this dynamic string is used to store the new file name. At the time of the call it should be uninitialized or free.  The caller must eventually call **Tcl_DStringFree** to free up anything stored here.

# Description

This utility procedure translates a file name to a platform-specific form which, after being converted to the appropriate encoding, is suitable for passing to the local operating system.  In particular, it converts network names into native form.

However, with the advent of the newer **Tcl_FSGetNormalizedPath** and **Tcl_FSGetNativePath**, there is no longer any need to use this procedure.  In particular, **Tcl_FSGetNativePath** performs all the necessary translation and encoding conversion, is virtual-filesystem aware, and caches the native result for faster repeated calls. Finally **Tcl_FSGetNativePath** does not require you to free anything afterwards.

If **Tcl_TranslateFileName** has to translate the name then it uses the dynamic string at **bufferPtr* to hold the new string it generates. After **Tcl_TranslateFileName** returns a non-NULL result, the caller must eventually invoke **Tcl_DStringFree** to free any information placed in **bufferPtr*.  The caller need not know whether or not **Tcl_TranslateFileName** actually used the string;  **Tcl_TranslateFileName** initializes **bufferPtr* even if it does not use it, so the call to **Tcl_DStringFree** will be safe in either case.

If an error occurs (e.g. because there was no user by the given name) then NULL is returned and an error message will be left in the interpreter's result. When an error occurs, **Tcl_TranslateFileName** frees the dynamic string itself so that the caller need not call **Tcl_DStringFree**.

The caller is responsible for making sure that the interpreter's result has its default empty value when **Tcl_TranslateFileName** is invoked.

---
CommandName: Tcl_UniCharIsAlpha
ManualSection: 3
Version: 8.1
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - unicode
 - classification
Copyright:
 - Copyright (c) 1997 Sun Microsystems, Inc.
---

# Name

Tcl_UniCharIsAlnum, Tcl_UniCharIsAlpha, Tcl_UniCharIsControl, Tcl_UniCharIsDigit, Tcl_UniCharIsGraph, Tcl_UniCharIsLower, Tcl_UniCharIsPrint, Tcl_UniCharIsPunct, Tcl_UniCharIsSpace, Tcl_UniCharIsUpper, Tcl_UniCharIsWordChar - routines for classification of Tcl_UniChar characters

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[int]{.ret} [Tcl_UniCharIsAlnum]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsAlpha]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsControl]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsDigit]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsGraph]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsLower]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsPrint]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsPunct]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsSpace]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsUpper]{.ccmd}[ch]{.cargs}
[int]{.ret} [Tcl_UniCharIsWordChar]{.ccmd}[ch]{.cargs}
:::

# Arguments

.AP int ch in The Unicode character to be examined. 

# Description

All of the routines described examine Unicode characters and return a boolean value. A non-zero return value means that the character does belong to the character class associated with the called routine. The rest of this document just describes the character classes associated with the various routines. 

# Character classes

**Tcl_UniCharIsAlnum** tests if the character is an alphanumeric Unicode character.

**Tcl_UniCharIsAlpha** tests if the character is an alphabetic Unicode character.

**Tcl_UniCharIsControl** tests if the character is a Unicode control character.

**Tcl_UniCharIsDigit** tests if the character is a numeric Unicode character.

**Tcl_UniCharIsGraph** tests if the character is any Unicode print character except space.

**Tcl_UniCharIsLower** tests if the character is a lowercase Unicode character.

**Tcl_UniCharIsPrint** tests if the character is a Unicode print character.

**Tcl_UniCharIsPunct** tests if the character is a Unicode punctuation character.

**Tcl_UniCharIsSpace** tests if the character is a whitespace Unicode character.

**Tcl_UniCharIsUpper** tests if the character is an uppercase Unicode character.

**Tcl_UniCharIsWordChar** tests if the character is alphanumeric or a connector punctuation mark. 

---
CommandName: Utf
ManualSection: 3
Version: 8.1
TclPart: Tcl
TclDescription: Tcl Library Procedures
Keywords:
 - utf
 - unicode
 - backslash
Copyright:
 - Copyright (c) 1997 Sun Microsystems, Inc.
---

# Name

Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfToChar16, Tcl_UtfToWChar, Tcl_UniCharToUtfDString, Tcl_UtfToUniCharDString, Tcl_Char16ToUtfDString, Tcl_UtfToWCharDString, Tcl_UtfToChar16DString, Tcl_WCharToUtfDString, Tcl_WCharLen, Tcl_Char16Len, Tcl_UniCharLen, Tcl_UniCharNcmp, Tcl_UniCharNcasecmp, Tcl_UniCharCaseMatch, Tcl_UtfNcmp, Tcl_UtfNcasecmp, Tcl_UtfCharComplete, Tcl_NumUtfChars, Tcl_UtfFindFirst, Tcl_UtfFindLast, Tcl_UtfNext, Tcl_UtfPrev, Tcl_UniCharAtIndex, Tcl_UtfAtIndex, Tcl_UtfBackslash - routines for manipulating UTF-8 strings

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_Size]{.ret} [Tcl_UniCharToUtf]{.ccmd}[ch, buf]{.cargs}
[Tcl_Size]{.ret} [Tcl_UtfToUniChar]{.ccmd}[src, chPtr]{.cargs}
[Tcl_Size]{.ret} [Tcl_UtfToChar16]{.ccmd}[src, uPtr]{.cargs}
[Tcl_Size]{.ret} [Tcl_UtfToWChar]{.ccmd}[src, wPtr]{.cargs}
[char *]{.ret} [Tcl_UniCharToUtfDString]{.ccmd}[uniStr, numUniChars, dsPtr]{.cargs}
[char *]{.ret} [Tcl_Char16ToUtfDString]{.ccmd}[utf16, numUtf16, dsPtr]{.cargs}
[char *]{.ret} [Tcl_WCharToUtfDString]{.ccmd}[wcharStr, numWChars, dsPtr]{.cargs}
[Tcl_UniChar *]{.ret} [Tcl_UtfToUniCharDString]{.ccmd}[src, numBytes, dsPtr]{.cargs}
[unsigned short *]{.ret} [Tcl_UtfToChar16DString]{.ccmd}[src, numBytes, dsPtr]{.cargs}
[wchar_t *]{.ret} [Tcl_UtfToWCharDString]{.ccmd}[src, numBytes, dsPtr]{.cargs}
[Tcl_Size]{.ret} [Tcl_Char16Len]{.ccmd}[utf16]{.cargs}
[Tcl_Size]{.ret} [Tcl_WCharLen]{.ccmd}[wcharStr]{.cargs}
[Tcl_Size]{.ret} [Tcl_UniCharLen]{.ccmd}[uniStr]{.cargs}
[int]{.ret} [Tcl_UniCharNcmp]{.ccmd}[ucs, uct, uniLength]{.cargs}
[int]{.ret} [Tcl_UniCharNcasecmp]{.ccmd}[ucs, uct, uniLength]{.cargs}
[int]{.ret} [Tcl_UniCharCaseMatch]{.ccmd}[uniStr, uniPattern, nocase]{.cargs}
[int]{.ret} [Tcl_UtfNcmp]{.ccmd}[cs, ct, length]{.cargs}
[int]{.ret} [Tcl_UtfNcasecmp]{.ccmd}[cs, ct, length]{.cargs}
[int]{.ret} [Tcl_UtfCharComplete]{.ccmd}[src, numBytes]{.cargs}
[Tcl_Size]{.ret} [Tcl_NumUtfChars]{.ccmd}[src, numBytes]{.cargs}
[const char *]{.ret} [Tcl_UtfFindFirst]{.ccmd}[src, ch]{.cargs}
[const char *]{.ret} [Tcl_UtfFindLast]{.ccmd}[src, ch]{.cargs}
[const char *]{.ret} [Tcl_UtfNext]{.ccmd}[src]{.cargs}
[const char *]{.ret} [Tcl_UtfPrev]{.ccmd}[src, start]{.cargs}
[int]{.ret} [Tcl_UniCharAtIndex]{.ccmd}[src, index]{.cargs}
[const char *]{.ret} [Tcl_UtfAtIndex]{.ccmd}[src, index]{.cargs}
[Tcl_Size]{.ret} [Tcl_UtfBackslash]{.ccmd}[src, readPtr, dst]{.cargs}
:::

# Arguments

.AP char *buf out Buffer in which the UTF-8 representation of the Tcl_UniChar is stored.  At most 4 bytes are stored in the buffer. .AP int ch in The Unicode character to be converted or examined. .AP Tcl_UniChar *chPtr out Filled with the Tcl_UniChar represented by the head of the UTF-8 string. .AP unsigned short *uPtr out Filled with the utf-16 represented by the head of the UTF-8 string. .AP wchar_t *wPtr out Filled with the wchar_t represented by the head of the UTF-8 string. .AP "const char" *src in Pointer to a UTF-8 string. .AP "const char" *cs in Pointer to a UTF-8 string. .AP "const char" *ct in Pointer to a UTF-8 string. .AP "const Tcl_UniChar" *uniStr in A sequence of **Tcl_UniChar** units with null-termination optional depending on function. .AP "const Tcl_UniChar" *ucs in A null-terminated sequence of **Tcl_UniChar**. .AP "const Tcl_UniChar" *uct in A null-terminated sequence of **Tcl_UniChar**. .AP "const Tcl_UniChar" *uniPattern in A null-terminated sequence of **Tcl_UniChar**. .AP "const unsigned short" *utf16 in A sequence of UTF-16 units with null-termination optional depending on function. .AP "const wchar_t" *wcharStr in A sequence of **wchar_t** units with null-termination optional depending on function. .AP int numBytes in The length of the UTF-8 input in bytes.  If negative, the length includes all bytes until the first null byte. .AP int numUtf16 in The length of the input in UTF-16 units. If negative, the length includes all bytes until the first null. .AP int numUniChars in The length of the input in Tcl_UniChar units. If negative, the length includes all bytes until the first null. .AP int numWChars in The length of the input in wchar_t units. If negative, the length includes all bytes until the first null. .AP "Tcl_DString" *dsPtr in/out A pointer to a previously initialized **Tcl_DString**. .AP "const char" *start in Pointer to the beginning of a UTF-8 string. .AP Tcl_Size index in The index of a character (not byte) in the UTF-8 string. .AP int *readPtr out If non-NULL, filled with the number of bytes in the backslash sequence, including the backslash character. .AP char *dst out Buffer in which the bytes represented by the backslash sequence are stored. At most 4 bytes are stored in the buffer. .AP int nocase in Specifies whether the match should be done case-sensitive (0) or case-insensitive (1). 

# Description

These routines convert between UTF-8 strings and Unicode/Utf-16 characters. A UTF-8 character is a Unicode character represented as a varying-length sequence of up to **4** bytes.  A multibyte UTF-8 sequence consists of a lead byte followed by some number of trail bytes.

**TCL_UTF_MAX** is the maximum number of bytes that **Tcl_UtfToUniChar** can consume in a single call.

**Tcl_UniCharToUtf** stores the character *ch* as a UTF-8 string in starting at *buf*.  The return value is the number of bytes stored in *buf*. The character *ch* can be or'ed with the value TCL_COMBINE to enable special behavior, compatible with Tcl 8.x. Then, if ch is a high surrogate (range U+D800 - U+DBFF), the return value will be 1 and a single byte in the range 0xF0 - 0xF4 will be stored. If *ch* is a low surrogate (range U+DC00 - U+DFFF), an attempt is made to combine the result with the earlier produced bytes, resulting in a 4-byte UTF-8 byte sequence.

**Tcl_UtfToUniChar** reads one UTF-8 character starting at *src* and stores it as a Tcl_UniChar in **chPtr*.  The return value is the number of bytes read from *src*.  The caller must ensure that the source buffer is long enough such that this routine does not run off the end and dereference non-existent or random memory; if the source buffer is known to be null-terminated, this will not happen.  If the input is a byte in the range 0x80 - 0x9F, **Tcl_UtfToUniChar** assumes the cp1252 encoding, stores the corresponding Tcl_UniChar in **chPtr* and returns 1. If the input is otherwise not in proper UTF-8 format, **Tcl_UtfToUniChar** will store the first byte of *src* in **chPtr* as a Tcl_UniChar between 0x00A0 and 0x00FF and return 1.

**Tcl_UniCharToUtfDString** converts the input in the form of a sequence of **Tcl_UniChar** code points to UTF-8, appending the result to the previously initialized output **Tcl_DString**. The return value is a pointer to the UTF-8 representation of the **appended** string.

**Tcl_UtfToUniCharDString** converts the input in the form of a UTF-8 encoded string to a **Tcl_UniChar** sequence appending the result in the previously initialized **Tcl_DString**. The return value is a pointer to the appended result which is also terminated with a **Tcl_UniChar** null character.

**Tcl_WCharToUtfDString** and **Tcl_UtfToWCharDString** are similar to **Tcl_UniCharToUtfDString** and **Tcl_UtfToUniCharDString** except they operate on sequences of **wchar_t** instead of **Tcl_UniChar**.

**Tcl_Char16ToUtfDString** and **Tcl_UtfToChar16DString** are similar to **Tcl_UniCharToUtfDString** and **Tcl_UtfToUniCharDString** except they operate on sequences of **UTF-16** units instead of **Tcl_UniChar**.

**Tcl_Char16Len** corresponds to **strlen** for UTF-16 characters.  It accepts a null-terminated UTF-16 sequence and returns the number of UTF-16 units until the null.

**Tcl_WCharLen** corresponds to **strlen** for **wchar_t** characters.  It accepts a null-terminated **wchar_t** sequence and returns the number of **wchar_t** units until the null.

**Tcl_UniCharLen** corresponds to **strlen** for Unicode characters.  It accepts a null-terminated Unicode string and returns the number of Unicode characters (not bytes) in that string.

**Tcl_UniCharNcmp** and **Tcl_UniCharNcasecmp** correspond to **strncmp** and **strncasecmp**, respectively, for Unicode characters. They accept two null-terminated Unicode strings and the number of characters to compare.  Both strings are assumed to be at least *uniLength* characters long. **Tcl_UniCharNcmp**  compares the two strings character-by-character according to the Unicode character ordering.  It returns an integer greater than, equal to, or less than 0 if the first string is greater than, equal to, or less than the second string respectively.  **Tcl_UniCharNcasecmp** is the Unicode case insensitive version.

**Tcl_UniCharCaseMatch** is the Unicode equivalent to **Tcl_StringCaseMatch**.  It accepts a null-terminated Unicode string, a Unicode pattern, and a boolean value specifying whether the match should be case sensitive and returns whether the string matches the pattern.

**Tcl_UtfNcmp** corresponds to **strncmp** for UTF-8 strings. It accepts two null-terminated UTF-8 strings and the number of characters to compare.  (Both strings are assumed to be at least *length* characters long.)  **Tcl_UtfNcmp** compares the two strings character-by-character according to the Unicode character ordering. It returns an integer greater than, equal to, or less than 0 if the first string is greater than, equal to, or less than the second string respectively.

**Tcl_UtfNcasecmp** corresponds to **strncasecmp** for UTF-8 strings.  It is similar to **Tcl_UtfNcmp** except comparisons ignore differences in case when comparing upper, lower or title case characters.

**Tcl_UtfCharComplete** returns 1 if the source UTF-8 string *src* of *numBytes* bytes is long enough to be decoded by **Tcl_UtfToUniChar**/**Tcl_UtfNext**, or 0 otherwise.  This function does not guarantee that the UTF-8 string is properly formed.  This routine is used by procedures that are operating on a byte at a time and need to know if a full Unicode character has been seen.

**Tcl_NumUtfChars** corresponds to **strlen** for UTF-8 strings.  It returns the number of Tcl_UniChars that are represented by the UTF-8 string *src*.  The length of the source string is *length* bytes.  If the length is negative, all bytes up to the first null byte are used.

**Tcl_UtfFindFirst** corresponds to **strchr** for UTF-8 strings.  It returns a pointer to the first occurrence of the Unicode character *ch* in the null-terminated UTF-8 string *src*.  The null terminator is considered part of the UTF-8 string.

**Tcl_UtfFindLast** corresponds to **strrchr** for UTF-8 strings.  It returns a pointer to the last occurrence of the Unicode character *ch* in the null-terminated UTF-8 string *src*.  The null terminator is considered part of the UTF-8 string.

Given *src*, a pointer to some location in a UTF-8 string, **Tcl_UtfNext** returns a pointer to the next UTF-8 character in the string.  The caller must not ask for the next character after the last character in the string if the string is not terminated by a null character. **Tcl_UtfCharComplete** can be used in that case to make sure enough bytes are available before calling **Tcl_UtfNext**.

**Tcl_UtfPrev** is used to step backward through but not beyond the UTF-8 string that begins at *start*.  If the UTF-8 string is made up entirely of complete and well-formed characters, and *src* points to the lead byte of one of those characters (or to the location one byte past the end of the string), then repeated calls of **Tcl_UtfPrev** will return pointers to the lead bytes of each character in the string, one character at a time, terminating when it returns *start*.

When the conditions of completeness and well-formedness may not be satisfied, a more precise description of the function of **Tcl_UtfPrev** is necessary. It always returns a pointer greater than or equal to *start*; that is, always a pointer to a location in the string. It always returns a pointer to a byte that begins a character when scanning for characters beginning from *start*. When *src* is greater than *start*, it always returns a pointer less than *src* and greater than or equal to (*src* - 4).  The character that begins at the returned pointer is the first one that either includes the byte *src[-1]*, or might include it if the right trail bytes are present at *src* and greater. **Tcl_UtfPrev** never reads the byte *src[0]* nor the byte *start[-1]* nor the byte *src[-5]*.

**Tcl_UniCharAtIndex** corresponds to a C string array dereference or the Pascal Ord() function.  It returns the Unicode character represented at the specified character (not byte) *index* in the UTF-8 string *src*.  The source string must contain at least *index* characters.  If *index* is negative it returns -1.

**Tcl_UtfAtIndex** returns a pointer to the specified character (not byte) *index* in the UTF-8 string *src*.  The source string must contain at least *index* characters.  This is equivalent to calling **Tcl_UtfToUniChar** *index* times.  If *index* is negative, the return pointer points to the first character in the source string.

**Tcl_UtfBackslash** is a utility procedure used by several of the Tcl commands.  It parses a backslash sequence and stores the properly formed UTF-8 character represented by the backslash sequence in the output buffer *dst*.  At most 4 bytes are stored in the buffer. **Tcl_UtfBackslash** modifies **readPtr* to contain the number of bytes in the backslash sequence, including the backslash character. The return value is the number of bytes stored in the output buffer.

See the **Tcl** manual entry for information on the valid backslash sequences.  All of the sequences described in the Tcl manual entry are supported by **Tcl_UtfBackslash**. 

---
CommandName: Tcl_WrongNumArgs
ManualSection: 3
Version: 8.0
TclPart: Tcl
TclDescription: Tcl Library Procedures
Links:
 - Tcl_GetIndexFromObj(3)
Keywords:
 - command
 - error message
 - wrong number of arguments
Copyright:
 - Copyright (c) 1994-1997 Sun Microsystems, Inc.
---

# Name

Tcl_WrongNumArgs - generate standard error message for wrong number of arguments

# Synopsis

::: {.synopsis} :::
**#include <tcl.h>**
[Tcl_WrongNumArgs]{.ccmd}[interp, objc, objv, message]{.cargs}
:::

# Arguments

.AP Tcl_Interp interp in Interpreter in which error will be reported: error message gets stored in its result value. .AP Tcl_Size objc in Number of leading arguments from *objv* to include in error message. .AP "Tcl_Obj *const" objv[] in Arguments to command that had the wrong number of arguments. .AP "const char" *message in Additional error information to print after leading arguments from *objv*.  This typically gives the acceptable syntax of the command.  This argument may be NULL.

# Description

**Tcl_WrongNumArgs** is a utility procedure that is invoked by command procedures when they discover that they have received the wrong number of arguments.  **Tcl_WrongNumArgs** generates a standard error message and stores it in the result value of *interp*.  The message includes the *objc* initial elements of *objv* plus *message*.  For example, if *objv* consists of the values **foo** and **bar**, *objc* is 1, and *message* is "**fileName count**" then *interp*'s result value will be set to the following string:

```
wrong # args: should be "foo fileName count"
```

If *objc* is 2, the result will be set to the following string:

```
wrong # args: should be "foo bar fileName count"
```

*Objc* is usually 1, but may be 2 or more for commands like **string** and the Tk widget commands, which use the first argument as a subcommand.

Some of the values in the *objv* array may be abbreviations for a subcommand.  The command **Tcl_GetIndexFromObj** will convert the abbreviated string value into an *indexObject*.  If an error occurs in the parsing of the subcommand we would like to use the full subcommand name rather than the abbreviation.  If the **Tcl_WrongNumArgs** command finds any *indexObject*s in the *objv* array, it will use the full subcommand name in the error message instead of the abbreviated name that was originally passed in.  Using the above example, let us assume that *bar* is actually an abbreviation for *barfly* and the value is now an *indexObject* because it was passed to **Tcl_GetIndexFromObj**.  In this case the error message would be:

```
wrong # args: should be "foo barfly fileName count"
```

# Reference count management

The *objv* argument to **Tcl_WrongNumArgs** should be the exact arguments passed to the command or method implementation function that is calling **Tcl_WrongNumArgs**. As such, all values referenced in it should have reference counts greater than zero; this is usually a non-issue.

The tcl/doc directory contains 248 manual pages which are divided as follows:


section | number of documents | initial conversion | final conversion
--------|---------------------|--------------------|-----------------
1       | 1                   | 1                  | 0
3       | 108                 | 108                | 0
n       | 139                 | 139                | 0


The tk/doc directory comes next, after finishing Tcl.

Note, that only pages counted under "final conversion" are considered
final markdown versions of the nroff originals. Currently, many of the

				puts "converting $file ..."
				set md [man2markdown [readFile $file]]
				set stem [file rootname [file tail $file]]
				# make sure not to overwrite files in the n section with
				# files from the 3 section having the same name
				# (was no problem previously as they had different
				# file extensions):
				if {$section ne "n" && $stem in {Class Concat Encoding Eval Exit Load Namespace Object RegExp UpVar zipfs}} {append stem $section}
				set fh [open [file join $outDir ${stem}.md] w]
				puts $fh $md
				close $fh
			}
		}
	} else {
		# convert single file (to stdout):