Return to Tcl_Interp.man CVS log

Up to [Research Unix] / researchv10no / cmd / worm / scsi / tcl

Annotation of researchv10no/cmd/worm/scsi/tcl/Tcl_Interp.man, revision 1.1

1.1     ! root        1: '\" Copyright 1989 Regents of the University of California
        !             2: '\" Permission to use, copy, modify, and distribute this
        !             3: '\" documentation for any purpose and without fee is hereby
        !             4: '\" granted, provided that this notice appears in all copies.
        !             5: '\" The University of California makes no representations about
        !             6: '\" the suitability of this material for any purpose.  It is
        !             7: '\" provided "as is" without express or implied warranty.
        !             8: '\" 
        !             9: '\" $Header: /sprite/src/lib/tcl/RCS/Tcl_Interp.man,v 1.3 90/01/15 14:58:40 ouster Exp $ SPRITE (Berkeley)
        !            10: '\" 
        !            11: .so \*(]ltmac.sprite
        !            12: .HS Tcl_Interp tcl
        !            13: .BS
        !            14: .SH NAME
        !            15: Tcl_Interp \- client-visible fields of interpreter structures
        !            16: .SH SYNOPSIS
        !            17: .nf
        !            18: \fB#include <tcl.h>\fR
        !            19: .sp
        !            20: typedef struct {
        !            21:        char *\fIresult\fR;
        !            22:        int \fIdynamic\fR;
        !            23:        int \fIerrorLine\fR;
        !            24: } Tcl_Interp;
        !            25: .BE
        !            26: 
        !            27: .SH DESCRIPTION
        !            28: .PP
        !            29: The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
        !            30: structure.  This pointer is then passed into other Tcl procedures
        !            31: to process commands in the interpreter and perform other operations
        !            32: on the interpreter.  Interpreter structures contain many many fields
        !            33: that are used by Tcl, but only three that may be accessed by
        !            34: clients:  \fIresult\fR and \fIdynamic\fR.  These fields are used by
        !            35: Tcl command procedures to return strings that form part of the result
        !            36: of each command.  When Tcl_Eval returns, the string pointed to be
        !            37: the \fIresult\fR field will be used by Tcl_Eval's caller
        !            38: as a return value or error message.
        !            39: .PP
        !            40: The easiest way for command procedures to manipulate the \fIresult\fR
        !            41: and \fIdynamic\fR fields is to call Tcl_Return;  Tcl_Return
        !            42: will hide all the details of managing these fields.
        !            43: The description below is for those procedures that manipulate the
        !            44: fields directly.
        !            45: .PP
        !            46: Whenever a command procedure returns, it must ensure
        !            47: that the \fIresult\fR field of its interpreter points to the string
        !            48: being returned by the command.  Normally, these strings are assumed
        !            49: to be statically allocated;  in this case, the \fIdynamic\fR field
        !            50: must be zero.  As an alternative, a command procedure may dynamically
        !            51: allocate its return value and store a pointer to it in \fIinterp->result\fR.
        !            52: In this case, the command procedure must also set \fIinterp->dynamic\fR
        !            53: to non-zero.  If \fIinterp->dynamic\fR is non-zero, then Tcl will free
        !            54: the space pointed to by \fIinterp->result\fR before it invokes the next command.
        !            55: If a client procedure overwrites \fIinterp->result\fR field when
        !            56: \fIinterp->dynamic\fR is non-zero, then it is responsible for freeing the
        !            57: old \fIinterp->result\fR.  Once again, if clients use the
        !            58: \fBTcl_Result\fR procedure to manage these fields, they need not worry
        !            59: about these issues.
        !            60: .PP
        !            61: As part of processing each command, \fBTcl_Eval\fR initializes
        !            62: \fIinterp->result\fR
        !            63: and \fIinterp->dynamic\fR just before calling the command procedure for
        !            64: the command.  The \fIdynamic\fR field will be initialized to zero,
        !            65: and \fIinterp->result\fR will point to an empty string.  Commands that
        !            66: do not return any value can simply leave the fields alone.
        !            67: Furthermore, the empty string pointed to by \fIresult\fR is actually
        !            68: part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
        !            69: If a command wishes to return a short string, it can simply copy
        !            70: it to the area pointed to by \fIinterp->result\fR.  Or, it can use
        !            71: the sprintf procedure to generate a short result string at the location
        !            72: pointed to by \fIinterp->result\fR.
        !            73: .PP
        !            74: If a command procedure calls a lower-level procedure that sets
        !            75: \fIinterp->result\fR and \fIinterp->dynamic\fR (such as a recursive
        !            76: instance of \fBTcl_Eval\fR), then the command procedure must reset
        !            77: \fIinterp->result\fR if it wishes to return a value different
        !            78: than that returned by the lower-level procedure.  As part of
        !            79: resetting \fIinterp->result\fR, it must free the space if
        !            80: \fIinterp->dynamic\fR is set.  Once again, the easiest way to
        !            81: make sure this gets done right is to call \fBTcl_Result\fR.
        !            82: .PP
        !            83: The \fIerrorLine\fR
        !            84: .VS
        !            85: field is valid only after \fBTcl_Eval\fR returns
        !            86: a \fBTCL_ERROR\fR return code.  In this situation the \fIerrorLine\fR
        !            87: field identifies the line number of the command being executed when
        !            88: the error occurred.  The line numbers are relative to the command
        !            89: being executed:  1 means the first line of the command passed to
        !            90: \fBTcl_Eval\fR, 2 means the second line, and so on.  \fIErrorLine\fR
        !            91: should not normally be modified except by \fBTcl_Eval\fR.
        !            92: .VE
        !            93: 
        !            94: .SH KEYWORDS
        !            95: dynamic, interpreter, result

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.