+++ /dev/null
-'\"
-'\" Copyright 1991-1998 by Bell Labs Innovations for Lucent Technologies.
-'\"
-'\" Permission to use, copy, modify, and distribute this software and its
-'\" documentation for any purpose and without fee is hereby granted, provided
-'\" that the above copyright notice appear in all copies and that both that the
-'\" copyright notice and warranty disclaimer appear in supporting documentation,
-'\" and that the names of Lucent Technologies any of their entities not be used
-'\" in advertising or publicity pertaining to distribution of the software
-'\" without specific, written prior permission.
-'\"
-'\" Lucent Technologies disclaims all warranties with regard to this software,
-'\" including all implied warranties of merchantability and fitness. In no event
-'\" shall Lucent Technologies be liable for any special, indirect or
-'\" consequential damages or any damages whatsoever resulting from loss of use,
-'\" data or profits, whether in an action of contract, negligence or other
-'\" tortuous action, arising out of or in connection with the use or performance
-'\" of this software.
-'\"
-'\"
-.so man.macros
-.TH Blt_TreeGetToken 3 BLT_VERSION BLT "BLT Library Procedures"
-.BS
-.SH NAME
-Blt_TreeGetToken \- Grabs a token associated with existing tree data object.
-.SH SYNOPSIS
-.nf
-\fB#include <bltTree.h>\fR
-.sp
-int
-\fBBlt_TreeGetToken\fR(\fIinterp\fR, \fIname\fR, \fItokenPtr\fR)
-.fi
-.SH ARGUMENTS
-.AS Tcl_Interp *interp
-.AP Tcl_Interp *interp in
-Interpreter to report results back to.
-.AP "const char" *name in
-Name of an existing tree data object. Can be qualified by a namespace.
-.AP Blt_Tree *tokenPtr out
-Points to location to store the client tree token.
-.BE
-.SH DESCRIPTION
-.PP
-This procedure obtains a token to a C-based tree data object. The
-arguments are as follows:
-.TP 1i
-\fIinterp\fR
-Interpreter to report results back to. If an error occurs, then
-interp->result will contain an error message.
-.TP 1i
-\fIname\fR
-Name of an existing tree data object. It's an error if a tree
-\fIname\fR doesn't already exist. \fIName\fR can be qualified by
-a namespace such as \fBfred::myTree\fR. If no namespace qualifier
-is used, the tree the current namespace is searched, then the global
-namespace.
-.TP 1i
-\fItokenPtr\fR
-Points to the location where the returned token is stored. A tree
-token is used to work with the tree object.
-.PP
-A token for the tree data object is returned. Tree data objects can
-be shared. For example, the \fBtree\fR and \fBhiertable\fR commands
-may be accessing the same tree data object. Each client grabs a token
-that is associated with the tree. When all tokens are released (see
-\fBBlt_TreeReleaseToken\fR) the tree data object is automatically
-destroyed.
-.PP
-.SH RETURNS
-A standard Tcl result is returned. If TCL_ERROR is returned, then
-\fIinterp->result\fR will contain an error message. The following errors
-may occur:
-.IP \(bu 3
-No tree exists as \fIname\fR. You can use \fBTcl_TreeExists\fR to
-determine if a tree exists beforehand.
-.IP \(bu
-Memory can't be allocated for the token.
-.SH EXAMPLE
-The following example allocated a token for an existing tree.
-.CS
-Blt_Tree token;
-
-if (Blt_TreeGetToken(interp, "myTree", &token) != TCL_OK) {
- return TCL_ERROR;
-}
-printf("tree is %s\\n", Blt_TreeName(token));
-.CE
-.SH SEE ALSO
-Tcl_TreeCreate, Tcl_TreeExists, Tcl_TreeReleaseToken