rm tcl/tk 8.6.7

1 files changed, 0 insertions, 312 deletions

diff --git a/tcl8.6/doc/AddErrInfo.3 b/tcl8.6/doc/AddErrInfo.3
deleted file mode 100644
index caba125..0000000
--- a/tcl8.6/doc/AddErrInfo.3
+++ /dev/null
@@ -1,312 +0,0 @@
-'\"
-'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-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_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-Tcl_Obj *
-\fBTcl_GetReturnOptions\fR(\fIinterp, code\fR)
-.sp
-int
-\fBTcl_SetReturnOptions\fR(\fIinterp, options\fR)
-.sp
-\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
-.sp
-\fBTcl_AppendObjToErrorInfo\fR(\fIinterp, objPtr\fR)
-.sp
-\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
-.sp
-\fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR)
-.sp
-\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR)
-.sp
-\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
-.sp
-\fBTcl_GetErrorLine\fR(\fIinterp\fR)
-.sp
-\fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR)
-.sp
-const char *
-\fBTcl_PosixError\fR(\fIinterp\fR)
-.sp
-void
-\fBTcl_LogCommandInfo\fR(\fIinterp, script, command, commandLength\fR)
-.SH ARGUMENTS
-.AS Tcl_Interp commandLength
-.AP Tcl_Interp *interp in
-Interpreter in which to record information.
-.AP int code
-The code returned from script evaluation.
-.AP Tcl_Obj *options
-A dictionary of return options.
-.AP char *message in
-For \fBTcl_AddErrorInfo\fR,
-this is a conventional C string to append to the \fB\-errorinfo\fR return option.
-For \fBTcl_AddObjErrorInfo\fR,
-this points to the first byte of an array of \fIlength\fR bytes
-containing a string to append to the \fB\-errorinfo\fR return option.
-This byte array may contain embedded null bytes
-unless \fIlength\fR is negative.
-.AP Tcl_Obj *objPtr in
-A message to be appended to the \fB\-errorinfo\fR return option
-in the form of a Tcl_Obj value.
-.AP int length in
-The number of bytes to copy from \fImessage\fR when
-appending to the \fB\-errorinfo\fR return option.
-If negative, all bytes up to the first null byte are used.
-.AP Tcl_Obj *errorObjPtr in
-The \fB\-errorcode\fR return option will be set to this value.
-.AP char *element in
-String to record as one element of the \fB\-errorcode\fR return option.
-Last \fIelement\fR argument must be NULL.
-.AP va_list argList in
-An argument list which must have been initialized using
-\fBva_start\fR, and cleared using \fBva_end\fR.
-.AP int lineNum
-The line number of a script where an error occurred.
-.AP "const char" *script in
-Pointer to first character in script containing command (must be <= command)
-.AP "const char" *command in
-Pointer to first character in command that generated the error
-.AP int commandLength in
-Number of bytes in command; -1 means use all bytes up to first null byte
-.BE
-.SH DESCRIPTION
-.PP
-The \fBTcl_SetReturnOptions\fR and \fBTcl_GetReturnOptions\fR
-routines expose the same capabilities as the \fBreturn\fR and
-\fBcatch\fR commands, respectively, in the form of a C interface.
-.PP
-\fBTcl_GetReturnOptions\fR retrieves the dictionary of return options
-from an interpreter following a script evaluation.
-Routines such as \fBTcl_Eval\fR are called to evaluate a
-script in an interpreter.  These routines return an integer
-completion code.  These routines also leave in the interpreter
-both a result and a dictionary of return options generated
-by script evaluation.  Just as \fBTcl_GetObjResult\fR retrieves
-the result, \fBTcl_GetReturnOptions\fR retrieves the dictionary
-of return options.  The integer completion code should be
-passed as the \fIcode\fR argument to \fBTcl_GetReturnOptions\fR
-so that all required options will be present in the dictionary.
-Specifically, a \fIcode\fR value of \fBTCL_ERROR\fR will
-ensure that entries for the keys \fB\-errorinfo\fR,
-\fB\-errorcode\fR, and \fB\-errorline\fR will appear in the
-dictionary.  Also, the entries for the keys \fB\-code\fR
-and \fB\-level\fR will be adjusted if necessary to agree
-with the value of \fIcode\fR.  The \fB(Tcl_Obj *)\fR returned
-by \fBTcl_GetReturnOptions\fR points to an unshared
-\fBTcl_Obj\fR with reference count of zero.  The dictionary
-may be written to, either adding, removing, or overwriting
-any entries in it, without the need to check for a shared value.
-As with any \fBTcl_Obj\fR with reference count of zero, it is up to
-the caller to arrange for its disposal with \fBTcl_DecrRefCount\fR or
-to a reference to it via \fBTcl_IncrRefCount\fR (or one of the many
-functions that call that, notably including \fBTcl_SetObjResult\fR and
-\fBTcl_SetVar2Ex\fR).
-.PP
-A typical usage for \fBTcl_GetReturnOptions\fR is to
-retrieve the stack trace when script evaluation returns
-\fBTCL_ERROR\fR, like so:
-.PP
-.CS
-int code = Tcl_Eval(interp, script);
-if (code == TCL_ERROR) {
-    Tcl_Obj *options = \fBTcl_GetReturnOptions\fR(interp, code);
-    Tcl_Obj *key = Tcl_NewStringObj("-errorinfo", -1);
-    Tcl_Obj *stackTrace;
-    Tcl_IncrRefCount(key);
-    Tcl_DictObjGet(NULL, options, key, &stackTrace);
-    Tcl_DecrRefCount(key);
-    /* Do something with stackTrace */
-    Tcl_DecrRefCount(options);
-}
-.CE
-.PP
-\fBTcl_SetReturnOptions\fR sets the return options
-of \fIinterp\fR to be \fIoptions\fR.  If \fIoptions\fR
-contains any invalid value for any key, TCL_ERROR will
-be returned, and the interp result will be set to an
-appropriate error message.  Otherwise, a completion code
-in agreement with the \fB\-code\fR and \fB\-level\fR
-keys in \fIoptions\fR will be returned.
-.PP
-As an example, Tcl's \fBreturn\fR command itself could
-be implemented in terms of \fBTcl_SetReturnOptions\fR
-like so:
-.PP
-.CS
-if ((objc % 2) == 0) { /* explicit result argument */
-    objc--;
-    Tcl_SetObjResult(interp, objv[objc]);
-}
-return \fBTcl_SetReturnOptions\fR(interp, Tcl_NewListObj(objc-1, objv+1));
-.CE
-.PP
-(It is not really implemented that way.  Internal access
-privileges allow for a more efficient alternative that meshes
-better with the bytecode compiler.)
-.PP
-Note that a newly created \fBTcl_Obj\fR may be passed
-in as the \fIoptions\fR argument without the need to tend
-to any reference counting.  This is analogous to
-\fBTcl_SetObjResult\fR.
-.PP
-While \fBTcl_SetReturnOptions\fR provides a general interface
-to set any collection of return options, there are a handful
-of return options that are very frequently used.  Most
-notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return
-options should be set properly when the command procedure
-of a command returns \fBTCL_ERROR\fR.  The \fB\-errorline\fR
-return option is also read by commands that evaluate scripts
-and wish to supply detailed error location information in
-the stack trace text they append to the \fB\-errorinfo\fR option.
-Tcl provides several simpler interfaces to more directly set
-these return options.
-.PP
-The \fB\-errorinfo\fR option holds a stack trace of the
-operations that were in progress when an error occurred,
-and is intended to be human-readable.
-The \fB\-errorcode\fR option holds a Tcl list of items that
-are intended to be machine-readable.
-The first item in the \fB\-errorcode\fR value identifies the class of
-error that occurred
-(e.g., POSIX means an error occurred in a POSIX system call)
-and additional elements hold additional pieces
-of information that depend on the class.
-See the manual entry on the \fBerrorCode\fR variable for details on the
-various formats for the \fB\-errorcode\fR option used by Tcl's built-in
-commands.
-.PP
-The \fB\-errorinfo\fR option value is gradually built up as an
-error unwinds through the nested operations.
-Each time an error code is returned to \fBTcl_Eval\fR, or
-any of the routines that performs script evaluation,
-the procedure \fBTcl_AddErrorInfo\fR is called to add
-additional text to the \fB\-errorinfo\fR value describing the
-command that was being executed when the error occurred.
-By the time the error has been passed all the way back
-to the application, it will contain a complete trace
-of the activity in progress when the error occurred.
-.PP
-It is sometimes useful to add additional information to
-the \fB\-errorinfo\fR value beyond what can be supplied automatically
-by the script evaluation routines.
-\fBTcl_AddErrorInfo\fR may be used for this purpose:
-its \fImessage\fR argument is an additional
-string to be appended to the \fB\-errorinfo\fR option.
-For example, when an error arises during the \fBsource\fR command,
-the procedure \fBTcl_AddErrorInfo\fR is called to
-record the name of the file being processed and the
-line number on which the error occurred.
-Likewise, when an error arises during evaluation of a
-Tcl procedures, the procedure name and line number
-within the procedure are recorded, and so on.
-The best time to call \fBTcl_AddErrorInfo\fR is just after
-a script evaluation routine has returned \fBTCL_ERROR\fR.
-The value of the \fB\-errorline\fR return option (retrieved
-via a call to \fBTcl_GetReturnOptions\fR) often makes up
-a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR.
-.PP
-\fBTcl_AppendObjToErrorInfo\fR is an alternative interface to the
-same functionality as \fBTcl_AddErrorInfo\fR.  \fBTcl_AppendObjToErrorInfo\fR
-is called when the string value to be appended to the \fB\-errorinfo\fR option
-is available as a \fBTcl_Obj\fR instead of as a \fBchar\fR array.
-.PP
-\fBTcl_AddObjErrorInfo\fR is nearly identical
-to \fBTcl_AddErrorInfo\fR, except that it has an additional \fIlength\fR
-argument.  This allows the \fImessage\fR string to contain
-embedded null bytes.  This is essentially never a good idea.
-If the \fImessage\fR needs to contain the null character \fBU+0000\fR,
-Tcl's usual internal encoding rules should be used to avoid
-the need for a null byte.  If the \fBTcl_AddObjErrorInfo\fR
-interface is used at all, it should be with a negative \fIlength\fR value.
-.PP
-The procedure \fBTcl_SetObjErrorCode\fR is used to set the
-\fB\-errorcode\fR return option to the list value \fIerrorObjPtr\fR
-built up by the caller.
-\fBTcl_SetObjErrorCode\fR is typically invoked just
-before returning an error. If an error is
-returned without calling \fBTcl_SetObjErrorCode\fR or
-\fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
-the \fB\-errorcode\fR return option to \fBNONE\fR.
-.PP
-The procedure \fBTcl_SetErrorCode\fR is also used to set the
-\fB\-errorcode\fR return option. However, it takes one or more strings to
-record instead of a value. Otherwise, it is similar to
-\fBTcl_SetObjErrorCode\fR in behavior.
-.PP
-\fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
-instead of taking a variable number of arguments it takes an argument list.
-.PP
-The procedure \fBTcl_GetErrorLine\fR is used to read the integer value
-of the \fB\-errorline\fR return option without the overhead of a full
-call to \fBTcl_GetReturnOptions\fR.  Likewise, \fBTcl_SetErrorLine\fR
-sets the \fB\-errorline\fR return option value.
-.PP
-\fBTcl_PosixError\fR
-sets the \fB\-errorcode\fR variable after an error in a POSIX kernel call.
-It reads the value of the \fBerrno\fR C variable and calls
-\fBTcl_SetErrorCode\fR to set the \fB\-errorcode\fR return
-option in the \fBPOSIX\fR format.
-The caller must previously have called \fBTcl_SetErrno\fR to set
-\fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
-is linked into an application as a shared library, or when the error
-occurs in a dynamically loaded extension. See the manual entry for
-\fBTcl_SetErrno\fR for more information.
-.PP
-\fBTcl_PosixError\fR returns a human-readable diagnostic message
-for the error
-(this is the same value that will appear as the third element
-in the \fB\-errorcode\fR value).
-It may be convenient to include this string as part of the
-error message returned to the application in
-the interpreter's result.
-.PP
-\fBTcl_LogCommandInfo\fR is invoked after an error occurs in an
-interpreter.  It adds information about the command that was being
-executed when the error occurred to the \fB\-errorinfo\fR value, and
-the line number stored internally in the interpreter is set.
-.PP
-In older releases of Tcl, there was no \fBTcl_GetReturnOptions\fR
-routine.  In its place, the global Tcl variables \fBerrorInfo\fR
-and \fBerrorCode\fR were the only place to retrieve the error
-information.  Much existing code written for older Tcl releases
-still access this information via those global variables.
-.PP
-It is important to realize that while reading from those
-global variables remains a supported way to access these
-return option values, it is important not to assume that
-writing to those global variables will properly set the
-corresponding return options.  It has long been emphasized
-in this manual page that it is important to
-call the procedures described here rather than
-setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
-\fBTcl_ObjSetVar2\fR.
-.PP
-If the procedure \fBTcl_ResetResult\fR is called,
-it clears all of the state of the interpreter associated with
-script evaluation, including the entire return options dictionary.
-In particular, the \fB\-errorinfo\fR and \fB\-errorcode\fR options
-are reset.
-If an error had occurred, the \fBTcl_ResetResult\fR call will
-clear the error state to make it appear as if no error had
-occurred after all.
-The global variables \fBerrorInfo\fR and
-\fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR
-so they continue to hold a record of information about the
-most recent error seen in an interpreter.
-.SH "SEE ALSO"
-Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3),
-Tcl_SetErrno(3), errorCode(n), errorInfo(n)
-.SH KEYWORDS
-error, value, value result, stack, trace, variable