Updated to tcl 8.4.1

[pf3gnuchains/pf3gnuchains3x.git] / tcl / doc / Eval.3

diff --git a/tcl/doc/Eval.3 b/tcl/doc/Eval.3
index 080d0ae..70595e9 100644 (file)
--- a/tcl/doc/Eval.3
+++ b/tcl/doc/Eval.3
@@ -1,6 +1,7 @@
 '\"
 '\" Copyright (c) 1989-1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
+'\" Copyright (c) 2000 Scriptics Corporation.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
@@ -53,7 +54,7 @@ A Tcl object containing the script to execute.
 .AP int flags in
 ORed combination of flag bits that specify additional options.
 \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported.
-.AP char *fileName in
+.AP "CONST char" *fileName in
 Name of a file containing a Tcl script.
 .AP int objc in
 The number of objects in the array pointed to by \fIobjPtr\fR;
@@ -65,10 +66,8 @@ value of a single word in the command to execute.
 The number of bytes in \fIscript\fR, not including any
 null terminating character.  If \-1, then all characters up to the
 first null byte are used.
-.AP char *script in
-Points to first byte of script to execute.  This script must be in
-writable memory: temporary modifications are made to it during
-parsing.
+.AP "CONST char" *script in
+Points to first byte of script to execute (NULL terminated and UTF-8).
 .AP char *string in
 String forming part of a Tcl script.
 .AP va_list argList in
@@ -101,6 +100,12 @@ its contents as a Tcl script.  It returns the same information as
 \fBTcl_EvalObjEx\fR.
 If the file couldn't be read then a Tcl error is returned to describe
 why the file couldn't be read.
+.VS 8.4
+The eofchar for files is '\\32' (^Z) for all platforms.
+If you require a ``^Z'' in code for string comparison, you can use
+``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
+interpreter into ``^Z''.
+.VE 8.4
 .PP
 \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a
 script.  The \fIobjc\fR and \fIobjv\fR arguments contain the values
@@ -110,15 +115,18 @@ a completion code and result just like \fBTcl_EvalObjEx\fR.
 .PP
 \fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to
 be executed is supplied as a string instead of an object and no compilation
-occurs.  The string is parsed and executed directly (using
-\fBTcl_EvalObjv\fR) instead of compiling it and executing the bytecodes.
-In situations where it is known that the script will never be executed
-again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
-\fBTcl_Eval\fR returns a completion code and result just like
+occurs.  The string should be a proper UTF-8 string as converted by
+\fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known
+to possibly contain upper ASCII characters who's possible combinations
+might be a UTF-8 special code.  The string is parsed and executed directly
+(using \fBTcl_EvalObjv\fR) instead of compiling it and executing the
+bytecodes.  In situations where it is known that the script will never be
+executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
+ \fBTcl_Eval\fR returns a completion code and result just like 
 \fBTcl_EvalObjEx\fR.  Note: for backward compatibility with versions before
 Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to
 \fIinterp->result\fR (use is deprecated) where it can be accessed directly.
-This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which
+ This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which
 doesn't do the copy.
 .PP
 \fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes
@@ -194,4 +202,3 @@ from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
 
 .SH KEYWORDS
 execute, file, global, object, result, script
-