Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume25/tcl/part06

Text File | 1991-11-14 | 48.8 KB | 1,641 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Karl Lehenbauer)
Subject:  v25i074:  tcl - tool command language, version 6.1, Part06/33
Message-ID: <[e-mail]>
X-Md4-Signature: f8f861ad2561cc4aa548718f616aed14
Date: Thu, 14 Nov 1991 20:27:36 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Karl Lehenbauer)
Posting-number: Volume 25, Issue 74
Archive-name: tcl/part06
Environment: UNIX

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 6 (of 33)."
# Contents:  tcl6.1/doc/AddErrInfo.man tcl6.1/doc/CrtCommand.man
#   tcl6.1/doc/CrtTrace.man tcl6.1/doc/Fork.man
#   tcl6.1/doc/SplitList.man
# Wrapped by karl@one on Tue Nov 12 19:44:15 1991
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'tcl6.1/doc/AddErrInfo.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'tcl6.1/doc/AddErrInfo.man'\"
else
echo shar: Extracting \"'tcl6.1/doc/AddErrInfo.man'\" \(8975 characters\)
sed "s/^X//" >'tcl6.1/doc/AddErrInfo.man' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\"
X'\" $Header: /user6/ouster/tcl/doc/RCS/AddErrInfo.man,v 1.6 91/08/20 09:47:45 ouster Exp $ SPRITE (Berkeley)
X'\"
X.\" The definitions below are for supplemental macros used in Sprite
X.\" manual entries.
X.\"
X.\" .HS name section [date [version]]
X.\"    Replacement for .TH in other man pages.  See below for valid
X.\"    section names.
X.\"
X.\" .AP type name in/out [indent]
X.\"    Start paragraph describing an argument to a library procedure.
X.\"    type is type of argument (int, etc.), in/out is either "in", "out",
X.\"    or "in/out" to describe whether procedure reads or modifies arg,
X.\"    and indent is equivalent to second arg of .IP (shouldn't ever be
X.\"    needed;  use .AS below instead)
X.\"
X.\" .AS [type [name]]
X.\"    Give maximum sizes of arguments for setting tab stops.  Type and
X.\"    name are examples of largest possible arguments that will be passed
X.\"    to .AP later.  If args are omitted, default tab stops are used.
X.\"
X.\" .BS
X.\"    Start box enclosure.  From here until next .BE, everything will be
X.\"    enclosed in one large box.
X.\"
X.\" .BE
X.\"    End of box enclosure.
X.\"
X.\" .VS
X.\"    Begin vertical sidebar, for use in marking newly-changed parts
X.\"    of man pages.
X.\"
X.\" .VE
X.\"    End of vertical sidebar.
X.\"
X.\" .DS
X.\"    Begin an indented unfilled display.
X.\"
X.\" .DE
X.\"    End of indented unfilled display.
X.\"
X'    # Heading for Sprite man pages
X.de HS
X.if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
X.if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
X.if t .wh -1.3i ^B
X.nr ^l \\n(.l
X.ad b
X..
X'    # Start an argument description
X.de AP
X.ie !"\\$4"" .TP \\$4
X.el \{\
X.   ie !"\\$2"" .TP \\n()Cu
X.   el          .TP 15
X.\}
X.ie !"\\$3"" \{\
X.ta \\n()Au \\n()Bu
X\&\\$1    \\fI\\$2\\fP    (\\$3)
X.\".b
X.\}
X.el \{\
X.br
X.ie !"\\$2"" \{\
X\&\\$1    \\fI\\$2\\fP
X.\}
X.el \{\
X\&\\fI\\$1\\fP
X.\}
X.\}
X..
X'    # define tabbing values for .AP
X.de AS
X.nr )A 10n
X.if !"\\$1"" .nr )A \\w'\\$1'u+3n
X.nr )B \\n()Au+15n
X.\"
X.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
X.nr )C \\n()Bu+\\w'(in/out)'u+2n
X..
X'    # BS - start boxed text
X'    # ^y = starting y location
X'    # ^b = 1
X.de BS
X.br
X.mk ^y
X.nr ^b 1u
X.if n .nf
X.if n .ti 0
X.if n \l'\\n(.lu\(ul'
X.if n .fi
X..
X'    # BE - end boxed text (draw box now)
X.de BE
X.nf
X.ti 0
X.mk ^t
X.ie n \l'\\n(^lu\(ul'
X.el \{\
X.\"    Draw four-sided box normally, but don't draw top of
X.\"    box if the box started on an earlier page.
X.ie !\\n(^b-1 \{\
X\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.el \}\
X\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.\}
X.fi
X.br
X.nr ^b 0
X..
X'    # VS - start vertical sidebar
X'    # ^Y = starting y location
X'    # ^v = 1 (for troff;  for nroff this doesn't matter)
X.de VS
X.mk ^Y
X.ie n 'mc \s12\(br\s0
X.el .nr ^v 1u
X..
X'    # VE - end of vertical sidebar
X.de VE
X.ie n 'mc
X.el \{\
X.ev 2
X.nf
X.ti 0
X.mk ^t
X\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
X.sp -1
X.fi
X.ev
X.\}
X.nr ^v 0
X..
X'    # Special macro to handle page bottom:  finish off current
X'    # box/sidebar if in box/sidebar mode, then invoked standard
X'    # page bottom macro.
X.de ^B
X.ev 2
X'ti 0
X'nf
X.mk ^t
X.if \\n(^b \{\
X.\"    Draw three-sided box if this is the box's first page,
X.\"    draw two sides but no top otherwise.
X.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.\}
X.if \\n(^v \{\
X.nr ^x \\n(^tu+1v-\\n(^Yu
X\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
X.\}
X.bp
X'fi
X.ev
X.if \\n(^b \{\
X.mk ^y
X.nr ^b 2
X.\}
X.if \\n(^v \{\
X.mk ^Y
X.\}
X..
X'    # DS - begin display
X.de DS
X.RS
X.nf
X.sp
X..
X'    # DE - end display
X.de DE
X.fi
X.RE
X.sp .5
X..
X.HS Tcl_AddErrorInfo tcl
X.BS
X.SH NAME
XTcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_UnixError, Tcl_CheckStatus \- record information about errors
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xchar *
X\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
X.sp
X.VS
Xvoid
X\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fR)
X.sp
Xchar
X\fBTcl_UnixError\fR(\fIinterp\fR)
X.VE
X.SH ARGUMENTS
X.AS Tcl_Interp *interp
X.AP Tcl_Interp *interp in
XInterpreter in which to record information.
X.AP char *message in
XIdentifying string to record in \fBerrorInfo\fR variable.
X.AP char *element in
X.VS
XString to record as one element of \fBerrorCode\fR variable.
XLast \fIelement\fR argument must be NULL.
X.VE
X.BE
X
X.SH DESCRIPTION
X.PP
X.VS
XThese procedures are used to manipulate two global variables
Xthat hold information about errors.
XThe variable \fBerrorInfo\fR holds a stack trace of the
Xoperations that were in progress when an error occurred, and
Xis intended to be human-readable.
XThe variable \fBerrorCode\fR holds a list of items that
Xare intended to be machine-readable.
XThe first item in \fBerrorCode\fR identifies the class of
Xerror that occurred (e.g. UNIX means an error occurred in
Xa Unix system call) and additional elements in \fBerrorCode\fR
Xhold additional pieces of information that depend on the class.
XSee the Tcl overview manual entry for details on the various
Xformats for \fBerrorCode\fR.
X.PP
XThe \fBerrorInfo\fR variable is gradually built up as an
Xerror unwinds through the nested operations.
XEach time an error code is returned to \fBTcl_Eval\fR
Xit calls the procedure \fBTcl_AddErrorInfo\fR to add
Xadditional text to \fBerrorInfo\fR describing the
Xcommand that was being executed when the error occurred.
XBy the time the error has been passed all the way back
Xto the application, it will contain a complete trace
Xof the activity in progress when the error occurred.
X.PP
XIt is sometimes useful to add additional information to
X\fBerrorInfo\fR beyond what can be supplied automatically
Xby \fBTcl_Eval\fR.
X\fBTcl_AddErrorInfo\fR may be used for this purpose:
Xits \fImessage\fR argument contains an additional
Xstring to be appended to \fBerrorInfo\fR.
XFor example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR
Xto record the name of the file being processed and the
Xline number on which the error occurred;  for Tcl procedures, the
Xprocedure name and line number within the procedure are recorded,
Xand so on.
XThe best time to call \fBTcl_AddErrorInfo\fR is just after
X\fBTcl_Eval\fR has returned \fBTCL_ERROR\fR.
XIn calling \fBTcl_AddErrorInfo\fR, you may find it useful to
Xuse the \fBerrorLine\fR field of the interpreter (see the
X\fBTcl_Interp\fR manual entry for details).
X.PP
XThe procedure \fBTcl_SetErrorCode\fR is used to set the
X\fBerrorCode\fR variable.
XIts \fIelement\fR arguments give one or more strings to record
Xin \fBerrorCode\fR:  each \fIelement\fR will become one item
Xof a properly-formed Tcl list stored in \fBerrorCode\fR.
X\fBTcl_SetErrorCode\fR is typically invoked just before returning
Xan error.
XIf an error is returned without calling \fBTcl_SetErrorCode\fR
Xthen the Tcl interpreter automatically sets \fBerrorCode\fR
Xto \fBNONE\fR.
X.PP
X\fBTcl_UnixError\fR sets the \fBerrorCode\fR variable after an error
Xin a UNIX kernel call.
XIt reads the value of the \fBerrno\fR C variable and calls
X\fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the
X\fBUNIX\fR format.
XIn addition, \fBTcl_UnixError\fR returns a human-readable
Xdiagnostic message for the error (this is the same value that
Xwill appear as the third element in \fBerrorCode\fR).
XIt may be convenient to include this string as part of the
Xerror message returned to the application in \fIinterp->result\fR.
X.PP
XIt is important to call the procedures described here rather than
Xsetting \fBerrorInfo\fR or \fBerrorCode\fR directly with
X\fBTcl_SetVar\fR.
XThe reason for this is that the Tcl interpreter keeps information
Xabout whether these procedures have been called.
XFor example, the first time \fBTcl_AppendResult\fR is called
Xfor an error, it clears the existing value of \fBerrorInfo\fR
Xand adds the error message in \fIinterp->result\fR to the variable
Xbefore appending \fImessage\fR;  in subsequent calls, it just
Xappends the new \fImessage\fR.
XWhen \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
Xthat \fBerrorCode\fR has been set;  this allows the Tcl interpreter
Xto set \fBerrorCode\fR to \fBNONE\fB if it receives an error return
Xwhen \fBTcl_SetErrorCode\fR hasn't been called.
X.PP
XIf the procedure \fBTcl_ResetResult\fR is called, it clears all
Xof the state associated with \fBerrorInfo\fR and \fBerrorCode\fR
X(but it doesn't actually modify the variables).
XIf an error had occurred, this will clear the error state to
Xmake it appear as if no error had occurred after all.
X.VE
X
X.SH "SEE ALSO"
XTcl_ResetResult, Tcl_Interp
X
X.SH KEYWORDS
Xerror, stack, trace, variable
END_OF_FILE
if test 8975 -ne `wc -c <'tcl6.1/doc/AddErrInfo.man'`; then
    echo shar: \"'tcl6.1/doc/AddErrInfo.man'\" unpacked with wrong size!
fi
# end of 'tcl6.1/doc/AddErrInfo.man'
fi
if test -f 'tcl6.1/doc/CrtCommand.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'tcl6.1/doc/CrtCommand.man'\"
else
echo shar: Extracting \"'tcl6.1/doc/CrtCommand.man'\" \(8815 characters\)
sed "s/^X//" >'tcl6.1/doc/CrtCommand.man' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\"
X'\" $Header: /user6/ouster/tcl/man/RCS/CrtCommand.man,v 1.5 91/11/01 14:41:04 ouster Exp $ SPRITE (Berkeley)
X'\"
X.\" The definitions below are for supplemental macros used in Sprite
X.\" manual entries.
X.\"
X.\" .HS name section [date [version]]
X.\"    Replacement for .TH in other man pages.  See below for valid
X.\"    section names.
X.\"
X.\" .AP type name in/out [indent]
X.\"    Start paragraph describing an argument to a library procedure.
X.\"    type is type of argument (int, etc.), in/out is either "in", "out",
X.\"    or "in/out" to describe whether procedure reads or modifies arg,
X.\"    and indent is equivalent to second arg of .IP (shouldn't ever be
X.\"    needed;  use .AS below instead)
X.\"
X.\" .AS [type [name]]
X.\"    Give maximum sizes of arguments for setting tab stops.  Type and
X.\"    name are examples of largest possible arguments that will be passed
X.\"    to .AP later.  If args are omitted, default tab stops are used.
X.\"
X.\" .BS
X.\"    Start box enclosure.  From here until next .BE, everything will be
X.\"    enclosed in one large box.
X.\"
X.\" .BE
X.\"    End of box enclosure.
X.\"
X.\" .VS
X.\"    Begin vertical sidebar, for use in marking newly-changed parts
X.\"    of man pages.
X.\"
X.\" .VE
X.\"    End of vertical sidebar.
X.\"
X.\" .DS
X.\"    Begin an indented unfilled display.
X.\"
X.\" .DE
X.\"    End of indented unfilled display.
X.\"
X'    # Heading for Sprite man pages
X.de HS
X.if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
X.if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
X.if t .wh -1.3i ^B
X.nr ^l \\n(.l
X.ad b
X..
X'    # Start an argument description
X.de AP
X.ie !"\\$4"" .TP \\$4
X.el \{\
X.   ie !"\\$2"" .TP \\n()Cu
X.   el          .TP 15
X.\}
X.ie !"\\$3"" \{\
X.ta \\n()Au \\n()Bu
X\&\\$1    \\fI\\$2\\fP    (\\$3)
X.\".b
X.\}
X.el \{\
X.br
X.ie !"\\$2"" \{\
X\&\\$1    \\fI\\$2\\fP
X.\}
X.el \{\
X\&\\fI\\$1\\fP
X.\}
X.\}
X..
X'    # define tabbing values for .AP
X.de AS
X.nr )A 10n
X.if !"\\$1"" .nr )A \\w'\\$1'u+3n
X.nr )B \\n()Au+15n
X.\"
X.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
X.nr )C \\n()Bu+\\w'(in/out)'u+2n
X..
X'    # BS - start boxed text
X'    # ^y = starting y location
X'    # ^b = 1
X.de BS
X.br
X.mk ^y
X.nr ^b 1u
X.if n .nf
X.if n .ti 0
X.if n \l'\\n(.lu\(ul'
X.if n .fi
X..
X'    # BE - end boxed text (draw box now)
X.de BE
X.nf
X.ti 0
X.mk ^t
X.ie n \l'\\n(^lu\(ul'
X.el \{\
X.\"    Draw four-sided box normally, but don't draw top of
X.\"    box if the box started on an earlier page.
X.ie !\\n(^b-1 \{\
X\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.el \}\
X\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.\}
X.fi
X.br
X.nr ^b 0
X..
X'    # VS - start vertical sidebar
X'    # ^Y = starting y location
X'    # ^v = 1 (for troff;  for nroff this doesn't matter)
X.de VS
X.mk ^Y
X.ie n 'mc \s12\(br\s0
X.el .nr ^v 1u
X..
X'    # VE - end of vertical sidebar
X.de VE
X.ie n 'mc
X.el \{\
X.ev 2
X.nf
X.ti 0
X.mk ^t
X\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
X.sp -1
X.fi
X.ev
X.\}
X.nr ^v 0
X..
X'    # Special macro to handle page bottom:  finish off current
X'    # box/sidebar if in box/sidebar mode, then invoked standard
X'    # page bottom macro.
X.de ^B
X.ev 2
X'ti 0
X'nf
X.mk ^t
X.if \\n(^b \{\
X.\"    Draw three-sided box if this is the box's first page,
X.\"    draw two sides but no top otherwise.
X.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.\}
X.if \\n(^v \{\
X.nr ^x \\n(^tu+1v-\\n(^Yu
X\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
X.\}
X.bp
X'fi
X.ev
X.if \\n(^b \{\
X.mk ^y
X.nr ^b 2
X.\}
X.if \\n(^v \{\
X.mk ^Y
X.\}
X..
X'    # DS - begin display
X.de DS
X.RS
X.nf
X.sp
X..
X'    # DE - end display
X.de DE
X.fi
X.RE
X.sp .5
X..
X.HS Tcl_CreateCommand tcl
X.BS
X.SH NAME
XTcl_CreateCommand, Tcl_DeleteCommand \- define application-specific command bindings
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
X\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
X.sp
Xint
X\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
X.SH ARGUMENTS
X.AS Tcl_CmdDeleteProc (*deleteProc)()
X.AP Tcl_Interp *interp in
XInterpreter in which to create new command.
X.AP char *cmdName in
XName of command to create or delete.
X.AP Tcl_CmdProc *proc in
XImplementation of new command:  \fIproc\fR will be called whenever
X\fIcmdName\fR is invoked as a command.
X.AP ClientData clientData in
XArbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
X.AP Tcl_CmdDeleteProc *deleteProc in
XProcedure to call before \fIcmdName\fR is deleted from the interpreter;
Xallows for command-specific cleanup.  If NULL, then no procedure is
Xcalled before the command is deleted.
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
Xit with procedure \fIproc\fR such that whenever \fIcmdName\fR is
Xinvoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
Xwill call \fIproc\fR
Xto process the command.  If there is already a command \fIcmdName\fR
Xassociated with the interpreter, it is deleted.  \fIProc\fP should
Xhave arguments and result that match the type \fBTcl_CmdProc\fR:
X.nf
X.RS
Xtypedef int Tcl_CmdProc(
X.RS
XClientData \fIclientData\fR,
XTcl_Interp *\fIinterp\fR,
Xint \fIargc\fR,
Xchar *\fIargv\fR[]);
X.RE
X.RE
X.fi
XWhen \fIproc\fR is invoked the \fIclientData\fP and \fIinterp\fR
Xparameters will be copies of the \fIclientData\fP and \fIinterp\fR
Xarguments given to \fBTcl_CreateCommand\fR.
XTypically, \fIclientData\fR points to an application-specific
Xdata structure that describes what to do when the command procedure
Xis invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
Xthe command, \fIargc\fR giving the number of arguments (including
Xthe command name) and \fIargv\fR giving the values of the arguments
Xas strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
Xthe first \fIargc\fR values point to the argument strings, and the
Xlast value is NULL.
X.PP
X\fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
X\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
Xfor details on what these codes mean.  Most normal commands will only
Xreturn \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
X\fIinterp->result\fR to point to a string value;
Xin the case of a \fBTCL_OK\fR return code this gives the result
Xof the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
XThe \fBTcl_SetResult\fR procedure provides an easy interface for setting
Xthe return value;  for complete details on how the \fIinterp->result\fR
Xfield is managed, see the \fBTcl_Interp\fR man page.
XBefore invoking a command procedure,
X\fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
Xcommands can return an empty result by doing nothing at all.
X.PP
XThe contents of the \fIargv\fR array are copies made by the Tcl interpreter
Xfor the use of \fIproc\fR.  \fIProc\fR may alter any of the strings
Xin \fIargv\fR.  However, the \fIargv\fR array
Xis recycled as soon as \fIproc\fR returns, so \fIproc\fR must not set
X\fIinterp->result\fR to point anywhere within the \fIargv\fR values
X(call Tcl_SetResult
Xwith status \fBTCL_VOLATILE\fR if you want to return something from the
X\fIargv\fR array).
X.PP
X\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
XThis can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
Xor by replacing \fIcmdName\fR in another call to Tcl_CreateCommand.
X\fIDeleteProc\fR is invoked before the command is deleted, and gives the
Xapplication an opportunity to release any structures associated
Xwith the command.  \fIDeleteProc\fR should have arguments and
Xresult that match the type \fBTcl_CmdDeleteProc\fR:
X.nf
X.RS
X.sp
Xtypedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
X.sp
X.RE
X.fi
XThe \fIclientData\fR argument will be the same as the \fIclientData\fR
Xargument passed to \fBTcl_CreateCommand\fR.
X.PP
X\fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
XOnce the call completes, attempts to invoke \fIcmdName\fR in
X\fIinterp\fR will result in errors.
XIf \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
X\fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
Xit returns 0.
XThere are no restrictions on \fIcmdName\fR:  it may refer to
Xa built-in command, an application-specific command, or a Tcl procedure.
X
X.SH KEYWORDS
Xbind, command, create, delete, interpreter
END_OF_FILE
if test 8815 -ne `wc -c <'tcl6.1/doc/CrtCommand.man'`; then
    echo shar: \"'tcl6.1/doc/CrtCommand.man'\" unpacked with wrong size!
fi
# end of 'tcl6.1/doc/CrtCommand.man'
fi
if test -f 'tcl6.1/doc/CrtTrace.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'tcl6.1/doc/CrtTrace.man'\"
else
echo shar: Extracting \"'tcl6.1/doc/CrtTrace.man'\" \(8294 characters\)
sed "s/^X//" >'tcl6.1/doc/CrtTrace.man' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\"
X'\" $Header: /user6/ouster/tcl/man/RCS/CrtTrace.man,v 1.4 91/11/01 14:41:15 ouster Exp $ SPRITE (Berkeley)
X'\"
X.\" The definitions below are for supplemental macros used in Sprite
X.\" manual entries.
X.\"
X.\" .HS name section [date [version]]
X.\"    Replacement for .TH in other man pages.  See below for valid
X.\"    section names.
X.\"
X.\" .AP type name in/out [indent]
X.\"    Start paragraph describing an argument to a library procedure.
X.\"    type is type of argument (int, etc.), in/out is either "in", "out",
X.\"    or "in/out" to describe whether procedure reads or modifies arg,
X.\"    and indent is equivalent to second arg of .IP (shouldn't ever be
X.\"    needed;  use .AS below instead)
X.\"
X.\" .AS [type [name]]
X.\"    Give maximum sizes of arguments for setting tab stops.  Type and
X.\"    name are examples of largest possible arguments that will be passed
X.\"    to .AP later.  If args are omitted, default tab stops are used.
X.\"
X.\" .BS
X.\"    Start box enclosure.  From here until next .BE, everything will be
X.\"    enclosed in one large box.
X.\"
X.\" .BE
X.\"    End of box enclosure.
X.\"
X.\" .VS
X.\"    Begin vertical sidebar, for use in marking newly-changed parts
X.\"    of man pages.
X.\"
X.\" .VE
X.\"    End of vertical sidebar.
X.\"
X.\" .DS
X.\"    Begin an indented unfilled display.
X.\"
X.\" .DE
X.\"    End of indented unfilled display.
X.\"
X'    # Heading for Sprite man pages
X.de HS
X.if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
X.if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
X.if t .wh -1.3i ^B
X.nr ^l \\n(.l
X.ad b
X..
X'    # Start an argument description
X.de AP
X.ie !"\\$4"" .TP \\$4
X.el \{\
X.   ie !"\\$2"" .TP \\n()Cu
X.   el          .TP 15
X.\}
X.ie !"\\$3"" \{\
X.ta \\n()Au \\n()Bu
X\&\\$1    \\fI\\$2\\fP    (\\$3)
X.\".b
X.\}
X.el \{\
X.br
X.ie !"\\$2"" \{\
X\&\\$1    \\fI\\$2\\fP
X.\}
X.el \{\
X\&\\fI\\$1\\fP
X.\}
X.\}
X..
X'    # define tabbing values for .AP
X.de AS
X.nr )A 10n
X.if !"\\$1"" .nr )A \\w'\\$1'u+3n
X.nr )B \\n()Au+15n
X.\"
X.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
X.nr )C \\n()Bu+\\w'(in/out)'u+2n
X..
X'    # BS - start boxed text
X'    # ^y = starting y location
X'    # ^b = 1
X.de BS
X.br
X.mk ^y
X.nr ^b 1u
X.if n .nf
X.if n .ti 0
X.if n \l'\\n(.lu\(ul'
X.if n .fi
X..
X'    # BE - end boxed text (draw box now)
X.de BE
X.nf
X.ti 0
X.mk ^t
X.ie n \l'\\n(^lu\(ul'
X.el \{\
X.\"    Draw four-sided box normally, but don't draw top of
X.\"    box if the box started on an earlier page.
X.ie !\\n(^b-1 \{\
X\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.el \}\
X\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.\}
X.fi
X.br
X.nr ^b 0
X..
X'    # VS - start vertical sidebar
X'    # ^Y = starting y location
X'    # ^v = 1 (for troff;  for nroff this doesn't matter)
X.de VS
X.mk ^Y
X.ie n 'mc \s12\(br\s0
X.el .nr ^v 1u
X..
X'    # VE - end of vertical sidebar
X.de VE
X.ie n 'mc
X.el \{\
X.ev 2
X.nf
X.ti 0
X.mk ^t
X\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
X.sp -1
X.fi
X.ev
X.\}
X.nr ^v 0
X..
X'    # Special macro to handle page bottom:  finish off current
X'    # box/sidebar if in box/sidebar mode, then invoked standard
X'    # page bottom macro.
X.de ^B
X.ev 2
X'ti 0
X'nf
X.mk ^t
X.if \\n(^b \{\
X.\"    Draw three-sided box if this is the box's first page,
X.\"    draw two sides but no top otherwise.
X.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.\}
X.if \\n(^v \{\
X.nr ^x \\n(^tu+1v-\\n(^Yu
X\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
X.\}
X.bp
X'fi
X.ev
X.if \\n(^b \{\
X.mk ^y
X.nr ^b 2
X.\}
X.if \\n(^v \{\
X.mk ^Y
X.\}
X..
X'    # DS - begin display
X.de DS
X.RS
X.nf
X.sp
X..
X'    # DE - end display
X.de DE
X.fi
X.RE
X.sp .5
X..
X.HS Tcl_CreateTrace tcl
X.BS
X.SH NAME
XTcl_CreateTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
XTcl_Trace
X\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)
X.sp
X\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
X.SH ARGUMENTS
X.AS Tcl_CmdTraceProc (clientData)()
X.AP Tcl_Interp *interp in
XInterpreter containing command to be traced or untraced.
X.AP int level in
XOnly commands at or below this nesting level will be traced.  1 means
Xtop-level commands only, 2 means top-level commands or those that are
Xinvoked as immediate consequences of executing top-level commands
X(procedure bodies, bracketed commands, etc.) and so on.
X.AP Tcl_CmdTraceProc *proc in
XProcedure to call for each command that's executed.  See below for
Xdetails on the calling sequence.
X.AP ClientData clientData in
XArbitrary one-word value to pass to \fIproc\fR.
X.AP Tcl_Trace trace in
XToken for trace to be removed (return value from previous call
Xto \fBTcl_CreateTrace\fR).
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_CreateTrace\fR arranges for command tracing.  From now on, \fIproc\fR
Xwill be invoked before Tcl calls command procedures to process
Xcommands in \fIinterp\fR.  The return value from
X\fBTcl_CreateTrace\fR is a token for the trace,
Xwhich may be passed to \fBTcl_DeleteTrace\fR to remove the trace.  There may
Xbe many traces in effect simultaneously for the same command interpreter.
X.PP
X\fIProc\fR should have arguments and result that match the
Xtype \fBTcl_CmdTraceProc\fR:
X.nf
X.sp
X.RS
Xtypedef void Tcl_CmdTraceProc(
X.RS
XClientData \fIclientData\fR,
XTcl_Interp *\fIinterp\fR,
Xint \fIlevel\fR,
Xchar *\fIcommand\fR,
XTcl_CmdProc *\fIcmdProc\fR,
XClientData \fIcmdClientData\fR,
Xint \fIargc\fR,
Xchar *\fIargv\fR[]));
X.sp
X.RE
X.RE
X.fi
XThe \fIclientData\fP and \fIinterp\fP parameters are
Xcopies of the corresponding arguments given to \fBTcl_CreateTrace\fR.
X\fIClientData\fR typically points to an application-specific
Xdata structure that describes what to do when \fIproc\fR
Xis invoked.  \fILevel\fR gives the nesting level of the command
X(1 for top-level commands passed to \fBTcl_Eval\fR by the application,
X2 for the next-level commands passed to \fBTcl_Eval\fR as part of parsing
Xor interpreting level-1 commands, and so on).  \fICommand\fR
Xpoints to a string containing the text of the
Xcommand, before any argument substitution.
X\fICmdProc\fR contains the address of the command procedure that
Xwill be called to process the command (i.e. the \fIproc\fR argument
Xof some previous call to \fBTcl_CreateCommand\fR) and \fIcmdClientData\fR
Xcontains the associated client data for \fIcmdProc\fR (the \fIclientData\fR
Xvalue passed to \fBTcl_CreateCommand\fR).  \fIArgc\fR and \fIargv\fR give
Xthe final argument information that will be passed to \fIcmdProc\fR, after
Xcommand, variable, and backslash substitution.
X\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
X.PP
XTracing will only occur for commands at nesting level less than
Xor equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
Xparameter to \fIproc\fR will always be less than or equal to the
X\fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
X.PP
XCalls to \fIproc\fR will be made by the Tcl parser immediately before
Xit calls the command procedure for the command (\fIcmdProc\fR).  This
Xoccurs after argument parsing and substitution, so tracing for
Xsubstituted commands occurs before tracing of the commands
Xcontaining the substitutions.  If there is a syntax error in a
Xcommand, or if there is no command procedure associated with a
Xcommand name, then no tracing will occur for that command.  If a
Xstring passed to Tcl_Eval contains multiple commands (bracketed, or
Xon different lines) then multiple calls to \fIproc\fR will occur,
Xone for each command.  The \fIcommand\fR string for each of these
Xtrace calls will reflect only a single command, not the entire string
Xpassed to Tcl_Eval.
X.PP
X\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be
Xmade to the procedure associated with the trace.  After \fBTcl_DeleteTrace\fR
Xreturns, the caller should never again use the \fItrace\fR token.
X
X.SH KEYWORDS
Xcommand, create, delete, interpreter, trace
END_OF_FILE
if test 8294 -ne `wc -c <'tcl6.1/doc/CrtTrace.man'`; then
    echo shar: \"'tcl6.1/doc/CrtTrace.man'\" unpacked with wrong size!
fi
# end of 'tcl6.1/doc/CrtTrace.man'
fi
if test -f 'tcl6.1/doc/Fork.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'tcl6.1/doc/Fork.man'\"
else
echo shar: Extracting \"'tcl6.1/doc/Fork.man'\" \(9119 characters\)
sed "s/^X//" >'tcl6.1/doc/Fork.man' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\"
X'\" $Header: /user6/ouster/tcl/doc/RCS/Fork.man,v 1.2 91/10/09 11:58:25 ouster Exp $ SPRITE (Berkeley)
X'\"
X.\" The definitions below are for supplemental macros used in Sprite
X.\" manual entries.
X.\"
X.\" .HS name section [date [version]]
X.\"    Replacement for .TH in other man pages.  See below for valid
X.\"    section names.
X.\"
X.\" .AP type name in/out [indent]
X.\"    Start paragraph describing an argument to a library procedure.
X.\"    type is type of argument (int, etc.), in/out is either "in", "out",
X.\"    or "in/out" to describe whether procedure reads or modifies arg,
X.\"    and indent is equivalent to second arg of .IP (shouldn't ever be
X.\"    needed;  use .AS below instead)
X.\"
X.\" .AS [type [name]]
X.\"    Give maximum sizes of arguments for setting tab stops.  Type and
X.\"    name are examples of largest possible arguments that will be passed
X.\"    to .AP later.  If args are omitted, default tab stops are used.
X.\"
X.\" .BS
X.\"    Start box enclosure.  From here until next .BE, everything will be
X.\"    enclosed in one large box.
X.\"
X.\" .BE
X.\"    End of box enclosure.
X.\"
X.\" .VS
X.\"    Begin vertical sidebar, for use in marking newly-changed parts
X.\"    of man pages.
X.\"
X.\" .VE
X.\"    End of vertical sidebar.
X.\"
X.\" .DS
X.\"    Begin an indented unfilled display.
X.\"
X.\" .DE
X.\"    End of indented unfilled display.
X.\"
X'    # Heading for Sprite man pages
X.de HS
X.if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
X.if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
X.if t .wh -1.3i ^B
X.nr ^l \\n(.l
X.ad b
X..
X'    # Start an argument description
X.de AP
X.ie !"\\$4"" .TP \\$4
X.el \{\
X.   ie !"\\$2"" .TP \\n()Cu
X.   el          .TP 15
X.\}
X.ie !"\\$3"" \{\
X.ta \\n()Au \\n()Bu
X\&\\$1    \\fI\\$2\\fP    (\\$3)
X.\".b
X.\}
X.el \{\
X.br
X.ie !"\\$2"" \{\
X\&\\$1    \\fI\\$2\\fP
X.\}
X.el \{\
X\&\\fI\\$1\\fP
X.\}
X.\}
X..
X'    # define tabbing values for .AP
X.de AS
X.nr )A 10n
X.if !"\\$1"" .nr )A \\w'\\$1'u+3n
X.nr )B \\n()Au+15n
X.\"
X.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
X.nr )C \\n()Bu+\\w'(in/out)'u+2n
X..
X'    # BS - start boxed text
X'    # ^y = starting y location
X'    # ^b = 1
X.de BS
X.br
X.mk ^y
X.nr ^b 1u
X.if n .nf
X.if n .ti 0
X.if n \l'\\n(.lu\(ul'
X.if n .fi
X..
X'    # BE - end boxed text (draw box now)
X.de BE
X.nf
X.ti 0
X.mk ^t
X.ie n \l'\\n(^lu\(ul'
X.el \{\
X.\"    Draw four-sided box normally, but don't draw top of
X.\"    box if the box started on an earlier page.
X.ie !\\n(^b-1 \{\
X\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.el \}\
X\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.\}
X.fi
X.br
X.nr ^b 0
X..
X'    # VS - start vertical sidebar
X'    # ^Y = starting y location
X'    # ^v = 1 (for troff;  for nroff this doesn't matter)
X.de VS
X.mk ^Y
X.ie n 'mc \s12\(br\s0
X.el .nr ^v 1u
X..
X'    # VE - end of vertical sidebar
X.de VE
X.ie n 'mc
X.el \{\
X.ev 2
X.nf
X.ti 0
X.mk ^t
X\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
X.sp -1
X.fi
X.ev
X.\}
X.nr ^v 0
X..
X'    # Special macro to handle page bottom:  finish off current
X'    # box/sidebar if in box/sidebar mode, then invoked standard
X'    # page bottom macro.
X.de ^B
X.ev 2
X'ti 0
X'nf
X.mk ^t
X.if \\n(^b \{\
X.\"    Draw three-sided box if this is the box's first page,
X.\"    draw two sides but no top otherwise.
X.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.\}
X.if \\n(^v \{\
X.nr ^x \\n(^tu+1v-\\n(^Yu
X\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
X.\}
X.bp
X'fi
X.ev
X.if \\n(^b \{\
X.mk ^y
X.nr ^b 2
X.\}
X.if \\n(^v \{\
X.mk ^Y
X.\}
X..
X'    # DS - begin display
X.de DS
X.RS
X.nf
X.sp
X..
X'    # DE - end display
X.de DE
X.fi
X.RE
X.sp .5
X..
X.HS Tcl_Fork tcl
X.BS
X.VS
X.SH NAME
XTcl_Fork, Tcl_WaitPids, Tcl_DetachPids \- manage child processes
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xint
X\fBTcl_Fork\fR( )
X.sp
Xint
X\fBTcl_WaitPids\fR(\fInumPids, pidPtr, statusPtr\fR)
X.sp
Xint
X\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
X.SH ARGUMENTS
X.AS Tcl_Interp *statusPtr
X.AP int numPids in
XNumber of process ids contained in the array pointed to by \fIpidPtr\fR.
X.AP int *pidPtr in
XAddress of array containing \fInumPids\fR process ids.
X.AP int *statusPtr out
XAddress of place to store status returned by exited/suspended process.
X.BE
X
X.SH DESCRIPTION
X.PP
XThese procedures keep track of child processes in order to make it
Xeasier for one application to manage several children.
XIf an application uses
Xthe UNIX \fIfork\fR and \fIwait\fR kernel calls directly,
Xproblems occur in situations like the following:
X.IP [1]
XOne part of an application creates child C1.  It plans to
Xlet the child run in background, then later wait for it to
Xcomplete.
X.IP [2]
XSome other part of the application creates another child C2,
Xnot knowing anything about C1.
X.IP [3]
XThe second part of the application uses \fIwait\fR to wait for C2
Xto complete.
X.IP [4]
XC1 completes before C2, so C1 is returned by the
X\fIwait\fR kernel call.
X.IP [5]
XThe second part of the application doesn't recognize C1, so it
Xignores it and calls \fIwait\fR again.  This time C2
Xcompletes.
X.IP [6]
XThe first part of the application eventually decides to wait
Xfor its child to complete.  When it calls \fIwait\fR there are
Xno children left, so \fIwait\fR returns an error and the
Xapplication never gets to examine the exit status for C1.
X.PP
XThe procedures \fBTcl_Fork\fR, \fBTcl_WaitPids\fR, and \fBTcl_DetachPids\fR
Xget around this problem by keeping a table of child processes and
Xtheir exit statuses.
XThey also provide a more flexible waiting
Xmechanism than the \fIwait\fR kernel call.
XTcl-based applications should never call \fIfork\fR and
X\fIwait\fR directly;  they should use \fBTcl_Fork\fR,
X\fBTcl_WaitPids\fR, and \fBTcl_DetachPids\fR.
X.PP
X\fBTcl_Fork\fR calls \fIfork\fR and returns the result of
Xthe \fIfork\fR kernel call.
XIf the \fIfork\fR call was successful then \fBTcl_Fork\fR also
Xenters the new process into its internal table of child
Xproceses.
XIf \fIfork\fR returns an error then \fBTcl_Fork\fR returns that
Xsame error.
X.PP
X\fBTcl_WaitPids\fR calls \fIwait\fR repeatedly until one of the processes
Xin the \fIpidPtr\fR array has exited or been killed or suspended by a
Xsignal.
XWhen this occurs, \fBTcl_WaitPids\fR returns the process
Xidentifier for the process and stores its wait status at
X\fI*statusPtr\fR.
XIf the process no longer exists (it exited or was killed by a signal),
Xthen \fBTcl_WaitPids\fR removes its entry from the internal
Xprocess table.
XIf \fIwait\fR returns a process that isn't
Xin the \fIpidPtr\fR array, \fBTcl_WaitPids\fR saves its wait
Xstatus in the internal process table and calls \fIwait\fR again.
XIf one of the processes in the \fIpidPtr\fR array has already
Xexited (or suspended or been killed) when \fBTcl_WaitPids\fR
Xis called, that process and its wait status are returned
Ximmediately without calling \fIwait\fR.
X.PP
X\fBTcl_WaitPids\fR provides two advantages.  First, it allows
Xprocesses to exit in any order, and saves their wait statuses.
XSecond, it allows waiting on a number of processes simultaneously,
Xreturning when any of the processes is returned by \fIwait\fR.
X.PP
X\fBTcl_DetachPids\fR is used to indicate that the application
Xno longer cares about the processes given by the \fIpidPtr\fR
Xarray and will never use \fBTcl_WaitPids\fR to wait for them.
XThis occurs, for example, if one or more children are to be
Xexecuted in background and the parent doesn't care whether
Xthey complete successfully.
XWhen \fBTcl_DetachPids\fR is called, the internal process
Xtable entries for the processes are marked so that the
Xentries will be removed as soon as the processes exit or
Xare killed.
X.PP
XIf none of the pids passed to \fBTcl_WaitPids\fR exists in
Xthe internal process table, then -1 is returned and \fIerrno\fR
Xis set to ECHILD.
XIf a \fIwait\fR kernel call returns an error,
Xthen \fBTcl_WaitPids\fR returns that same error.
XIf a \fIwait\fR kernel call returns a process that isn't in
Xthe internal process table,  \fBTcl_WaitPids\fR panics and
Xaborts the application.
XIf this situation occurs, it means that a process has been
Xcreated without calling \fBTcl_Fork\fR and that its exit
Xstatus is about to be lost.
X.PP
X\fBTcl_WaitPids\fR defines wait statuses to have type \fIint\fR,
Xwhich is correct for POSIX and many variants of UNIX.
XSome BSD-based UNIX systems still use type \fIunion wait\fR for
Xwait statuses;  it should be safe to cast a pointer to a
X\fIunion wait\fR structure to \fI(int *)\fR before passing
Xit to \fBTcl_WaitPids\fR as in the following code:
X.nf
X.RS
X
X\fBunion wait status;
Xint pid1, pid2;
X\&...
Xpid2 = Tcl_WaitPids(1, &pid1, (int *) &status);\fR
X.RE
X.fi
X
X.SH KEYWORDS
Xbackground, child, detach, fork, process, status, wait
X.VE
END_OF_FILE
if test 9119 -ne `wc -c <'tcl6.1/doc/Fork.man'`; then
    echo shar: \"'tcl6.1/doc/Fork.man'\" unpacked with wrong size!
fi
# end of 'tcl6.1/doc/Fork.man'
fi
if test -f 'tcl6.1/doc/SplitList.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'tcl6.1/doc/SplitList.man'\"
else
echo shar: Extracting \"'tcl6.1/doc/SplitList.man'\" \(9107 characters\)
sed "s/^X//" >'tcl6.1/doc/SplitList.man' <<'END_OF_FILE'
X'\" Copyright 1989-1991 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\"
X'\" $Header: /user6/ouster/tcl/doc/RCS/SplitList.man,v 1.5 91/07/10 11:08:18 ouster Exp $ SPRITE (Berkeley)
X'\"
X.\" The definitions below are for supplemental macros used in Sprite
X.\" manual entries.
X.\"
X.\" .HS name section [date [version]]
X.\"    Replacement for .TH in other man pages.  See below for valid
X.\"    section names.
X.\"
X.\" .AP type name in/out [indent]
X.\"    Start paragraph describing an argument to a library procedure.
X.\"    type is type of argument (int, etc.), in/out is either "in", "out",
X.\"    or "in/out" to describe whether procedure reads or modifies arg,
X.\"    and indent is equivalent to second arg of .IP (shouldn't ever be
X.\"    needed;  use .AS below instead)
X.\"
X.\" .AS [type [name]]
X.\"    Give maximum sizes of arguments for setting tab stops.  Type and
X.\"    name are examples of largest possible arguments that will be passed
X.\"    to .AP later.  If args are omitted, default tab stops are used.
X.\"
X.\" .BS
X.\"    Start box enclosure.  From here until next .BE, everything will be
X.\"    enclosed in one large box.
X.\"
X.\" .BE
X.\"    End of box enclosure.
X.\"
X.\" .VS
X.\"    Begin vertical sidebar, for use in marking newly-changed parts
X.\"    of man pages.
X.\"
X.\" .VE
X.\"    End of vertical sidebar.
X.\"
X.\" .DS
X.\"    Begin an indented unfilled display.
X.\"
X.\" .DE
X.\"    End of indented unfilled display.
X.\"
X'    # Heading for Sprite man pages
X.de HS
X.if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
X.if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
X.if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
X.if t .wh -1.3i ^B
X.nr ^l \\n(.l
X.ad b
X..
X'    # Start an argument description
X.de AP
X.ie !"\\$4"" .TP \\$4
X.el \{\
X.   ie !"\\$2"" .TP \\n()Cu
X.   el          .TP 15
X.\}
X.ie !"\\$3"" \{\
X.ta \\n()Au \\n()Bu
X\&\\$1    \\fI\\$2\\fP    (\\$3)
X.\".b
X.\}
X.el \{\
X.br
X.ie !"\\$2"" \{\
X\&\\$1    \\fI\\$2\\fP
X.\}
X.el \{\
X\&\\fI\\$1\\fP
X.\}
X.\}
X..
X'    # define tabbing values for .AP
X.de AS
X.nr )A 10n
X.if !"\\$1"" .nr )A \\w'\\$1'u+3n
X.nr )B \\n()Au+15n
X.\"
X.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
X.nr )C \\n()Bu+\\w'(in/out)'u+2n
X..
X'    # BS - start boxed text
X'    # ^y = starting y location
X'    # ^b = 1
X.de BS
X.br
X.mk ^y
X.nr ^b 1u
X.if n .nf
X.if n .ti 0
X.if n \l'\\n(.lu\(ul'
X.if n .fi
X..
X'    # BE - end boxed text (draw box now)
X.de BE
X.nf
X.ti 0
X.mk ^t
X.ie n \l'\\n(^lu\(ul'
X.el \{\
X.\"    Draw four-sided box normally, but don't draw top of
X.\"    box if the box started on an earlier page.
X.ie !\\n(^b-1 \{\
X\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.el \}\
X\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
X.\}
X.\}
X.fi
X.br
X.nr ^b 0
X..
X'    # VS - start vertical sidebar
X'    # ^Y = starting y location
X'    # ^v = 1 (for troff;  for nroff this doesn't matter)
X.de VS
X.mk ^Y
X.ie n 'mc \s12\(br\s0
X.el .nr ^v 1u
X..
X'    # VE - end of vertical sidebar
X.de VE
X.ie n 'mc
X.el \{\
X.ev 2
X.nf
X.ti 0
X.mk ^t
X\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
X.sp -1
X.fi
X.ev
X.\}
X.nr ^v 0
X..
X'    # Special macro to handle page bottom:  finish off current
X'    # box/sidebar if in box/sidebar mode, then invoked standard
X'    # page bottom macro.
X.de ^B
X.ev 2
X'ti 0
X'nf
X.mk ^t
X.if \\n(^b \{\
X.\"    Draw three-sided box if this is the box's first page,
X.\"    draw two sides but no top otherwise.
X.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
X.\}
X.if \\n(^v \{\
X.nr ^x \\n(^tu+1v-\\n(^Yu
X\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
X.\}
X.bp
X'fi
X.ev
X.if \\n(^b \{\
X.mk ^y
X.nr ^b 2
X.\}
X.if \\n(^v \{\
X.mk ^Y
X.\}
X..
X'    # DS - begin display
X.de DS
X.RS
X.nf
X.sp
X..
X'    # DE - end display
X.de DE
X.fi
X.RE
X.sp .5
X..
X.HS Tcl_SplitList tcl
X.BS
X.SH NAME
XTcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement \- manipulate Tcl lists
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xint
X\fBTcl_SplitList\fR(\fIinterp, list, argcPtr, argvPtr\fR)
X.sp
Xchar *
X\fBTcl_Merge\fR(\fIargc, argv\fR)
X.sp
X.VS
Xint
X\fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR)
X.sp
Xint
X\fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
X.VE
X.AS Tcl_Interp *argvPtr
X.SH ARGUMENTS
X.AP Tcl_Interp *interp out
XInterpreter to use for error reporting.
X.AP char *list in
XPointer to a string with proper list structure.
X.AP int *argcPtr out
XFilled in with number of elements in \fIlist\fR.
X.AP char ***argvPtr out
X\fI*argvPtr\fR will be filled in with the address of an array of
Xpointers to the strings that are the extracted elements of \fIlist\fR.
XThere will be \fI*argcPtr\fR valid entries in the array, followed by
Xa NULL entry.
X.AP int argc in
XNumber of elements in \fIargv\fR.
X.AP char **argv in
XArray of strings to merge together into a single list.
XEach string will become a separate element of the list.
X.AP char *src in
X.VS
XString that is to become an element of a list.
X.AP int *flagsPtr in
XPointer to word to fill in with information about \fIsrc\fR.
XThe value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR.
X.AP char *dst in
XPlace to copy converted list element.  Must contain enough characters
Xto hold converted string.
X.AP int flags in
XInformation about \fIsrc\fR, which must have been returned by previous
Xcall to \fBTcl_ScanElement\fR.
X.VE
X.BE
X
X.SH DESCRIPTION
X.PP
XThese procedures may be used to disassemble and reassemble Tcl lists.
X\fBTcl_SplitList\fR breaks a list up into its constituent elements,
Xreturning an array of pointers to the elements using
X\fIargcPtr\fR and \fIargvPtr\fR.
XWhile extracting the arguments, \fBTcl_SplitList\fR obeys the usual
Xrules for backslash substitutions and braces.  The area of
Xmemory pointed to by \fI*argvPtr\fR is dynamically allocated;  in
Xaddition to the array of pointers, it
Xalso holds copies of all the list elements.  It is the caller's
Xresponsibility to free up all of this storage by calling
X.DS
X\fBfree\fR((char *) \fI*argvPtr\fR)
X.DE
Xwhen the list elements are no longer needed.
X.PP
X\fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was
Xsuccessfully parsed.
XIf there was a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned
Xand \fIinterp->result\fR will point to an error message describing the
Xproblem.
XIf \fBTCL_ERROR\fR is returned then no memory is allocated and \fI*argvPtr\fR
Xis not modified.
X.PP
X\fBTcl_Merge\fR is the inverse of \fBTcl_SplitList\fR:  it
Xtakes a collection of strings given by \fIargc\fR
Xand \fIargv\fR and generates a result string
Xthat has proper list structure.
XThis means that commands like \fBindex\fR may be used to
Xextract the original elements again.
XIn addition, if the result of \fBTcl_Merge\fR is passed to \fBTcl_Eval\fR,
Xit will be parsed into \fIargc\fR words whose values will
Xbe the same as the \fIargv\fR strings passed to \fBTcl_Merge\fR.
X\fBTcl_Merge\fR will modify the list elements with braces and/or
Xbackslashes in order to produce proper Tcl list structure.
XThe result string is dynamically allocated
Xusing \fBmalloc()\fR;  the caller must eventually release the space
Xusing \fBfree()\fR.
X.PP
XIf the result of \fBTcl_Merge\fR is passed to \fBTcl_SplitList\fR,
Xthe elements returned by \fBTcl_SplitList\fR will be identical to
Xthose passed into \fBTcl_Merge\fR.
XHowever, the converse is not true:  if \fBTcl_SplitList\fR
Xis passed a given string, and the resulting \fIargc\fR and
X\fIargv\fR are passed to \fBTcl_Merge\fR, the resulting string
Xmay not be the same as the original string passed to \fBTcl_SplitList\fR.
XThis is because \fBTcl_Merge\fR may use backslashes and braces
Xdifferently than the original string.
X.PP
X.VS
X\fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR are the
Xprocedures that do all of the real work of \fBTcl_Merge\fR.
X\fBTcl_ScanElement\fR scans its \fIsrc\fR argument
Xand determines how to use backslashes and braces
Xwhen converting it to a list element.
XIt returns an overestimate of the number of characters
Xrequired to represent \fIsrc\fR as a list element, and
Xit stores information in \fI*flagsPtr\fR that is needed
Xby \fBTcl_ConvertElement\fR.
X.PP
X\fBTcl_ConvertElement\fR is a companion procedure to \fBTcl_ScanElement\fR.
XIt does the actual work of converting a string to a list element.
XIts \fIflags\fR argument must be the same as the value returned
Xby \fBTcl_ScanElement\fR.
X\fBTcl_ConvertElement\fR writes a proper list element to memory
Xstarting at *\fIdst\fR and returns a count of the total number
Xof characters written, which will be no more than the result
Xreturned by \fBTcl_ScanElement\fR.
X\fBTcl_ConvertElement\fR writes out only the actual list element
Xwithout any leading or trailing spaces: it is up to the caller to
Xinclude spaces between adjacent list elements.
X.VE
X
X.SH KEYWORDS
Xbackslash, convert, element, list, merge, split, strings
END_OF_FILE
if test 9107 -ne `wc -c <'tcl6.1/doc/SplitList.man'`; then
    echo shar: \"'tcl6.1/doc/SplitList.man'\" unpacked with wrong size!
fi
# end of 'tcl6.1/doc/SplitList.man'
fi
echo shar: End of archive 6 \(of 33\).
cp /dev/null ark6isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 33 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0

exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].