Tcl Source Code

 9. [Tracking Development](#watch)
 10. [Thank You](#thanks)

## <a id="intro">1.</a> Introduction
Tcl provides a powerful platform for creating integration applications that
tie together diverse applications, protocols, devices, and frameworks.
When paired with the Tk toolkit, Tcl provides the fastest and most powerful
way to create GUI applications that run on PCs, Unix, and macOS.
Tcl can also be used for a variety of web-related tasks and for creating
powerful command languages for applications.

Tcl is maintained, enhanced, and distributed freely by the Tcl community.
Source code development and tracking of bug reports and feature requests
take place at [core.tcl-lang.org](https://core.tcl-lang.org/).
Tcl/Tk release and mailing list services are [hosted by

'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_CloseEx, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Channel
\fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR)
.sp

.sp
int
\fBTcl_IsStandardChannel\fR(\fIchannel\fR)
.sp
int
\fBTcl_Close\fR(\fIinterp, channel\fR)
.sp
int
\fBTcl_CloseEx\fR(\fIinterp, channel, closeFlags\fR)
.sp
Tcl_Size
\fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR)
.sp
Tcl_Size
\fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR)
.sp
Tcl_Size

.AP Tcl_Obj *readObjPtr in/out
A pointer to a Tcl value in which to store the characters read from the
channel.
.AP Tcl_Size charsToRead in
The number of characters to read from the channel.  If the channel's encoding
is \fBbinary\fR, this is equivalent to the number of bytes to read from the
channel.
.AP int closeFlags in
If \fB0\fR, the channel is closed in both directions. If \fBTCL_CLOSE_READ\fR,
the channel is only closed for reading. If \fBTCL_CLOSE_WRITE\fR, the channel
is only closed for writing. These flags must not be combined.
.AP int appendFlag in
If non-zero, data read from the channel will be appended to the value.
Otherwise, the data will replace the existing contents of the value.
.AP char *readBuf out
A buffer in which to store the bytes read from the channel.
.AP Tcl_Size bytesToRead in
The number of bytes to read from the channel.  The buffer \fIreadBuf\fR must

.PP
\fBTcl_IsStandardChannel\fR tests whether a channel is one of the
three standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR.
If so, it returns 1, otherwise 0.
.PP
No attempt is made to check whether the given channel or the standard
channels are initialized or otherwise valid.
.SH "TCL_CLOSE AND TCL_CLOSEEX"
.PP
\fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
currently open channel. The channel should not be registered in any
interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to
the channel's output device prior to destroying the channel, and any
buffered input is discarded.  If this is a blocking channel, the call does
not return until all buffered data is successfully sent to the channel's
output device.  If this is a nonblocking channel and there is buffered
output that cannot be written without blocking, the call returns
immediately; output is flushed in the background and the channel will be
closed once all of the buffered data has been output.  In this case errors
during flushing are not reported.
.PP
\fBTcl_CloseEx\fR allows for both full closing and half-closing of channels
depending on its \fBcloseFlags\fR parameter. See the description of the
parameter above. It is an error to attempt to close the channel for
a direction for which it is not open. The channel is destroyed only when
it has been closed for both reading and writing. Only socket and command
pipe channels support half-closing.
.PP
If the channel was closed successfully, \fBTcl_Close\fR and \fBTcl_CloseEx\fR
return \fBTCL_OK\fR. If an error occurs, they return \fBTCL_ERROR\fR and record
a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
If the channel is being closed synchronously and an error occurs during
closing of the channel and \fIinterp\fR is not NULL, an error message is
left in the interpreter's result.
.PP
Note that it is not safe to call the channel closing functions on a channel
that has been registered using \fBTcl_RegisterChannel\fR; see the documentation
for \fBTcl_RegisterChannel\fR, above, for details. If the channel has ever
been given as the \fBchan\fR argument in a call to
\fBTcl_RegisterChannel\fR, you should instead use
\fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR
when all calls to \fBTcl_RegisterChannel\fR have been matched by
corresponding calls to \fBTcl_UnregisterChannel\fR.
.SH "TCL_READCHARS AND TCL_READ"
.PP

    if (bytesPtr == NULL) {
	return TCL_ERROR;
    }
    result = Tcl_ExternalToUtfDStringEx(interp, encoding, bytesPtr, length, flags,
	    &ds, failVarObj ? &errorLocation : NULL);
    /* NOTE: ds must be freed beyond this point even on error */

    switch (result) {
    case TCL_OK:
	errorLocation = TCL_INDEX_NONE;
	break;
    case TCL_ERROR:
	/* Error in parameters. Should not happen. interp will have error */
	goto done;

    default:
	/*
	 * One of the TCL_CONVERT_* errors. If we were not interested in the
	 * error location, interp result would already have been filled in
	 * and we can just return the error. Otherwise, we have to return
	 * what could be decoded and the returned error location.
	 */
	if (failVarObj == NULL) {

	    result = TCL_ERROR;
	    goto done;
	}
	break;
    }

    /*
     * TCL_OK or a TCL_CONVERT_* error where the caller wants back as much
     * data as was converted.
     */
    if (failVarObj) {
	Tcl_Obj *failIndex;
	TclNewIndexObj(failIndex, errorLocation);
	if (Tcl_ObjSetVar2(interp, failVarObj, NULL, failIndex,
		TCL_LEAVE_ERR_MSG) == NULL) {

	    result = TCL_ERROR;
	    goto done;
	}
    }
    /*
     * Note that we cannot use Tcl_DStringResult here because it will
     * truncate the string at the first null byte.
     */

    Tcl_SetObjResult(interp, Tcl_DStringToObj(&ds));
    result = TCL_OK;

done:
    Tcl_DStringFree(&ds);
    if (encoding) {
	Tcl_FreeEncoding(encoding);

    }
    return result;
}

/*
 *----------------------------------------------------------------------
 *
 * EncodingConverttoObjCmd --
 *

    switch (result) {
    case TCL_OK:
	errorLocation = TCL_INDEX_NONE;
	break;
    case TCL_ERROR:
	/* Error in parameters. Should not happen. interp will have error */
	goto done;

    default:
	/*
	 * One of the TCL_CONVERT_* errors. If we were not interested in the
	 * error location, interp result would already have been filled in
	 * and we can just return the error. Otherwise, we have to return
	 * what could be decoded and the returned error location.
	 */
	if (failVarObj == NULL) {

	    result = TCL_ERROR;
	    goto done;
	}
	break;
    }
    /*
     * TCL_OK or a TCL_CONVERT_* error where the caller wants back as much
     * data as was converted.
     */
    if (failVarObj) {
	Tcl_Obj *failIndex;

	TclNewIndexObj(failIndex, errorLocation);
	if (Tcl_ObjSetVar2(interp, failVarObj, NULL, failIndex,
		TCL_LEAVE_ERR_MSG) == NULL) {

	    result = TCL_ERROR;
	    goto done;
	}
    }

    Tcl_SetObjResult(interp, Tcl_NewByteArrayObj(
	    (unsigned char*) Tcl_DStringValue(&ds),
	    Tcl_DStringLength(&ds)));



    result = TCL_OK;

done:
    Tcl_DStringFree(&ds);
    if (encoding) {
	Tcl_FreeEncoding(encoding);
    }
    return result;

}

/*
 *----------------------------------------------------------------------
 *
 * EncodingDirsObjCmd --

	    ignoreStderr = 1;
	    break;
	case EXEC_ENCODING:
	    if (++skip >= objc) {
		Tcl_SetResult(interp, "No value given for option -encoding.",
			TCL_STATIC);
		return TCL_ERROR;
	    } else {
		Tcl_Encoding encoding;
		encodingObj = objv[skip];
		/* Verify validity - bug [da5e1bc7bc] */
		if (Tcl_GetEncodingFromObj(interp, encodingObj, &encoding)
			!= TCL_OK) {
		    return TCL_ERROR;
		}
		Tcl_FreeEncoding(encoding);
	    }
	    break;
	}
    }
    if (objc <= skip) {
	Tcl_WrongNumArgs(interp, 1, objv, "?-option ...? arg ?arg ...?");
	return TCL_ERROR;
    }

	    return TCL_ERROR;
	}
	return TCL_OK;
    }

    /* Bug [0f1ddc0df7] - encoding errors - use replace profile */
    if (Tcl_SetChannelOption(interp, chan, "-profile", "replace") != TCL_OK) {
	goto errorWithOpenChannel;
    }

    /* TIP 716 */
    if (encodingObj &&
	Tcl_SetChannelOption(interp, chan, "-encoding", 
	    Tcl_GetString(encodingObj)) != TCL_OK) {
	goto errorWithOpenChannel;


    }

    TclNewObj(resultPtr);
    if (Tcl_GetChannelHandle(chan, TCL_READABLE, NULL) == TCL_OK) {
	if (Tcl_ReadChars(chan, resultPtr, -1, 0) == TCL_IO_FAILURE) {
	    /*
	     * TIP #219.
	     * Capture error messages put by the driver into the bypass area
	     * and put them into the regular interpreter result. Fall back to
	     * the regular message if nothing was found in the bypass.
	     */

	    if (!TclChanCaughtErrorBypass(interp, chan)) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf(
			"error reading output from command: %s",
			Tcl_PosixError(interp)));
		Tcl_DecrRefCount(resultPtr);
	    }
	    goto errorWithOpenChannel;
	}
    }

    /*
     * If the process produced anything on stderr, it will have been returned
     * in the interpreter result. It needs to be appended to the result
     * string.

	if ((length > 0) && (string[length - 1] == '\n')) {
	    Tcl_SetObjLength(resultPtr, length - 1);
	}
    }
    Tcl_SetObjResult(interp, resultPtr);

    return result;

errorWithOpenChannel:
    /* Interpreter should already contain error. Pass NULL to not overwrite */
    (void)Tcl_CloseEx(NULL, chan, 0);
    return TCL_ERROR;
}

/*
 *---------------------------------------------------------------------------
 *
 * Tcl_FblockedObjCmd --
 *

/*
 *----------------------------------------------------------------------
 *
 * TclMergeReturnOptions --
 *
 *	Parses, checks, and stores the options to the [return] command.
 *
 *	The number of arguments (objc) must be even, with the corresponding
 *	objv holding values to be processed as key value .... key value.
 *
 * Results:
 *	Returns TCL_ERROR if any of the option values are invalid. Otherwise,
 *	returns TCL_OK, and writes the returnOpts, code, and level values to
 *	the pointers provided.
 *
 * Side effects:
 *	None.
 *
 *----------------------------------------------------------------------
 */

static int
ExpandedOptions(
    Tcl_Interp *interp,		/* Current interpreter. */
    Tcl_Obj **keys,		/* Built-in keys (per thread) */
    Tcl_Obj *returnOpts,	/* Options dict we are building */
    int objc,			/* Number of arguments. */
    Tcl_Obj *const objv[])	/* Argument objects. */
{
    for (;  objc > 1;  objv += 2, objc -= 2) {
	const char *opt = TclGetString(objv[0]);
	const char *compare = TclGetString(keys[KEY_OPTIONS]);

	if ((objv[0]->length == keys[KEY_OPTIONS]->length)
		&& (memcmp(opt, compare, objv[0]->length) == 0)) {
	    /* Process the -options switch to emulate {*} expansion.
	     *
	     * Use lists so duplicate keys are not lost.
	     */

	    Tcl_Size nestc;
	    Tcl_Obj **nestv;

	    if (TCL_ERROR == TclListObjGetElements(interp, objv[1],
		    &nestc, &nestv) || (nestc % 2)) {
		Tcl_SetObjResult(interp, Tcl_ObjPrintf(
			"bad -options value: expected dictionary but got"
			" \"%s\"", TclGetString(objv[1])));
		Tcl_SetErrorCode(interp, "TCL", "RESULT", "ILLEGAL_OPTIONS",
			(char *)NULL);
		return TCL_ERROR;
	    }

	    if (TCL_ERROR ==
		    ExpandedOptions(interp, keys, returnOpts, nestc, nestv)) {
		return TCL_ERROR;
	    }
	} else {
	    Tcl_DictObjPut(NULL, returnOpts, objv[0], objv[1]);
	}
    }
    return TCL_OK;
}

int
TclMergeReturnOptions(
    Tcl_Interp *interp,		/* Current interpreter. */
    int objc,			/* Number of arguments. */
    Tcl_Obj *const objv[],	/* Argument objects. */
    Tcl_Obj **optionsPtrPtr,	/* If not NULL, points to space for a (Tcl_Obj
				 * *) where the pointer to the merged return
				 * options dictionary should be written. */
    int *codePtr,		/* If not NULL, points to space where the
				 * -code value should be written. */
    int *levelPtr)		/* If not NULL, points to space where the
				 * -level value should be written. */
{
    int code = TCL_OK;
    int level = 1;
    Tcl_Obj *valuePtr;
    Tcl_Obj *returnOpts;
    Tcl_Obj **keys = GetKeys();





    /* All callers are expected to pass an even value for objc. */







    TclNewObj(returnOpts);





    if (TCL_ERROR == ExpandedOptions(interp, keys, returnOpts, objc, objv)) {





	goto error;

















    }

    /*
     * Check for bogus -code value.
     */

    Tcl_DictObjGet(NULL, returnOpts, keys[KEY_CODE], &valuePtr);

Tcl macOS README
-------------------

This is the README file for the macOS/Darwin version of Tcl.


1. Where to go for support
--------------------------

- The tcl-mac mailing list on sourceforge is the best place to ask questions
specific to Tcl & Tk on Mac OS X:

framework directories:
	$HOME/Library/Frameworks /Library/Frameworks


3. Building Tcl on Mac OS X
---------------------------

- Tcl supports macOS 10.13 and newer.
While Tcl may build on earlier versions of the OS, it is not tested on versions
older than 10.13.  You will need to install an  Apple clang toolchain either by
downloading the Xcode app from Apple's App Store, or by installing the Command
Line Tools. The Command Line Tools can be installed by running the command:
    xcode-select --install
in the Terminal.

- Tcl is most easily built as a macOS framework via the GNUmakefile in tcl/macosx
(see below for details), but can also be built with the standard unix configure
and make buildsystem in tcl/unix as on any other unix platform (indeed, the
GNUmakefile is just a wrapper around the unix buildsystem).
The Mac OS X specific configure flags are --enable-framework and
--disable-corefoundation (which disables CF and notably reverts to the standard
select based notifier).

- To build universal binaries for macOS 10.13 and newer set CFLAGS as follows:
	export CFLAGS="-arch x86_64 -arch arm64 -mmacosx-version-min=10.13"
(This will cause clang to set macOS 11 as the target OS for the arm64 architecture
since Apple Silicon was not supported until macOS 11.)

Universal builds of Tcl TEA extensions are also possible with CFLAGS set as
above, they will be [load]able by universal as well as thin binaries of Tcl.

Detailed Instructions for building with macosx/GNUmakefile
----------------------------------------------------------

- Unpack the Tcl source release archive.

- The following instructions assume the Tcl source tree is named "tcl${ver}",
(where ${ver} is a shell variable containing the Tcl version number e.g. '9.0').
Setup this shell variable as follows:
	ver="9.0"

- Setup environment variables as desired, for example:
	CFLAGS="-arch x86_64 -arch arm64 -mmacosx-version-min=10.13"
	export CFLAGS

- Change to the directory containing the Tcl source tree and build:
	make -C tcl${ver}/macosx

- Install Tcl onto the root volume (admin password required):
	sudo make -C tcl${ver}/macosx install

    } result] $result $::errorCode
} {1 c {a b}}
test cmdMZ-return-2.18 {return option handling} {
    list [catch {
	return -code error -errorstack [list CALL a CALL b] yo
    } -> foo] [dictSort $foo] [info errorstack]
} {2 {-code 1 -errorcode NONE -errorstack {CALL a CALL b} -level 1} {CALL a CALL b}}
test cmdMZ-return-2.19 {return option handling} -body {
    return -level 0 -options {-options {-code break} -code continue}
} -returnCodes continue -result {}
test cmdMZ-return-2.20 {return option handling} {
    list [catch {
	return -level 0 -options {-foo 1} -options {-bar 2} 
    } -> foo] $foo
} {0 {-foo 1 -bar 2 -code 0 -level 0}}
test cmdMZ-return-2.21 {return option handling} {
    list [catch {
	return -level 0 -options {-options {-foo 1} -options {-bar 2}}
    } -> foo] $foo
} {0 {-foo 1 -bar 2 -code 0 -level 0}}

# Check that the result of a [return -options $opts $result] is
# indistinguishable from that of the originally caught script, no matter what
# the script is/does. (TIP 90)
foreach {testid script} {
    cmdMZ-return-3.0 {}
    cmdMZ-return-3.1 {format x}

# no idea how to check it in GHA programmatically, so simply disable it (todo: rewrite with better check later)
if {[testConstraint win] && ![info exists ::env(CI)] &&
    [info exists ::env(LOCALAPPDATA)] &&
    [file exists [file join $::env(LOCALAPPDATA) "Microsoft" "WindowsApps" "winget.exe"]]} {
	testConstraint haveWinget 1
}

testConstraint testhandlecount [expr {[llength [info commands testhandlecount]] != 0}]

unset -nocomplain path

# Utilities that are like Bourne shell stalwarts, but cross-platform.
set path(echo) [makeFile {
    puts -nonewline [lindex $argv 0]
    foreach str [lrange $argv 1 end] {
	puts -nonewline " $str"

} {3 1 4}
set arg {12345678901234567890123456789012345678901234567890}
set arg "$arg$arg$arg$arg$arg$arg"
test exec-1.4 {long command lines} {exec} {
    exec [interpreter] $path(echo) $arg
} $arg
set arg {}
test exec-1.5 {pipelining - handle leaks} -constraints {exec stdio testhandlecount} -body {
    set numHandles [testhandlecount]
    set a [exec [interpreter] $path(echo) a b c d | [interpreter] $path(cat) | [interpreter] $path(wc)]
    list [scan $a "%d %d %d" b c d] $b $c [expr {[testhandlecount] - $numHandles}]
} -result {3 1 4 0}


# I/O redirection: input from Tcl command.

test exec-2.1 {redirecting input from immediate source} {exec stdio} {
    exec [interpreter] $path(cat) << "Sample text"
} {Sample text}
test exec-2.2 {redirecting input from immediate source} {exec stdio} {

    # If it does, this means that the UTF -> external conversion did not occur
    # before writing out the temp file.
    quotenonascii [exec [interpreter] $path(cat) << "\xE9\xE0\xFC\xF1"]
} -cleanup {
    encoding system $sysenc
    rename quotenonascii {}
} -result {\xE9\xE0\xFC\xF1}
test exec-2.7 {handle count redirecting input from immediate source} -constraints {
    exec stdio testhandlecount
} -body {
    set numHandles [testhandlecount]
    list [exec [interpreter] $path(cat) | [interpreter] $path(cat) << "Sample text"] \
        [expr {[testhandlecount] - $numHandles}]
} -result [list {Sample text} 0]

# I/O redirection: output to file.

set path(gorp.file) [makeFile {} gorp.file]
file delete $path(gorp.file)

test exec-3.1 {redirecting output to file} {exec} {

    flush $f
    exec [interpreter] $path(echo) "More text" >@ $f
    exec [interpreter] $path(echo) >@$f "Even more"
    puts $f "Line 3"
    close $f
    exec [interpreter] $path(cat) $path(gorp.file)
} "Line 1\nMore text\nEven more\nLine 3"
test exec-3.8 {handle count redirecting output to file} -constraints {
    exec stdio testhandlecount
} -body {
    set numHandles [testhandlecount]
    exec > $path(gorp.file) [interpreter] $path(echo) "Different simple words" | [interpreter] $path(cat) | [interpreter] $path(cat)
    list [exec [interpreter] $path(cat) $path(gorp.file)] \
        [expr {[testhandlecount] - $numHandles}]
} -result [list "Different simple words" 0]

# I/O redirection: output and stderr to file.

file delete $path(gorp.file)

test exec-4.1 {redirecting output and stderr to file} {exec} {
    exec [interpreter] $path(echo) "test output" >& $path(gorp.file)

} -result {Just a few thoughts}
test exec-5.7 {redirecting input from file} -constraints {exec} -body {
    set f [open $path(gorp.file) r]
    exec <@$f [interpreter] $path(cat)
} -cleanup {
    close $f
} -result {Just a few thoughts}
test exec-5.8 {handle count redirecting input from file} -constraints {
    exec stdio testhandlecount
} -body {
    set numHandles [testhandlecount]
    list [exec [interpreter] $path(cat) | [interpreter] $path(cat) < $path(gorp.file)] \
        [expr {[testhandlecount] - $numHandles}]
} -result [list {Just a few thoughts} 0]

# I/O redirection: standard error through a pipeline.

test exec-6.1 {redirecting stderr through a pipeline} {exec stdio} {
    exec [interpreter] $path(sh) -c "\"$path(echo)\" foo bar" |& [interpreter] $path(cat)
} "foo bar"
test exec-6.2 {redirecting stderr through a pipeline} {exec stdio} {

} 3
test exec-11.5 {commands in background} {exec} {
    set f [open $path(gorp.file) w]
    puts $f [list catch [list exec [info nameofexecutable] $path(echo) foo &]]
    close $f
    exec [interpreter] $path(gorp.file)
} foo
test exec-11.6 {commands in background} -constraints {
    exec stdio testhandlecount
} -body {
    set numHandles [testhandlecount]
    set n [llength [exec [interpreter] $path(sleep) 1 | [interpreter] $path(sleep) 1 | [interpreter] $path(sleep) 1 &]]
    after 1100
    tcl::process::purge
    list $n [expr {([testhandlecount] - $numHandles) <= 0}]; # Could be < 0 if prior processes were reaped
} -result {3 1}

# Make sure that background commands are properly reaped when they
# eventually die.

if {[testConstraint exec] && [testConstraint nonPortable]} {
    after 1300
    exec [interpreter] $path(sleep) 1