util/src/TclTk/tcl8.6.12/doc/CrtAlias.3

   1 '\"
   2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH Tcl_CreateAlias 3 7.6 Tcl "Tcl Library Procedures"
   8 .so man.macros
   9 .BS
  10 .SH NAME
  11 Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
  12 .SH SYNOPSIS
  13 .nf
  14 \fB#include <tcl.h>\fR
  15 .sp
  16 int
  17 \fBTcl_IsSafe\fR(\fIinterp\fR)
  18 .sp
  19 int
  20 \fBTcl_MakeSafe\fR(\fIinterp\fR)
  21 .sp
  22 .VS "TIP 581"
  23 Tcl_Interp *
  24 \fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR)
  25 .VE "TIP 581"
  26 .sp
  27 Tcl_Interp *
  28 \fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR)
  29 .sp
  30 .VS "TIP 581"
  31 Tcl_Interp *
  32 \fBTcl_GetChild\fR(\fIinterp, name\fR)
  33 .VE "TIP 581"
  34 .sp
  35 Tcl_Interp *
  36 \fBTcl_GetSlave\fR(\fIinterp, name\fR)
  37 .sp
  38 .VS "TIP 581"
  39 Tcl_Interp *
  40 \fBTcl_GetParent\fR(\fIinterp\fR)
  41 .VE "TIP 581"
  42 .sp
  43 Tcl_Interp *
  44 \fBTcl_GetMaster\fR(\fIinterp\fR)
  45 .sp
  46 int
  47 \fBTcl_GetInterpPath\fR(\fIinterp, childInterp\fR)
  48 .sp
  49 int
  50 \fBTcl_CreateAlias\fR(\fIchildInterp, childCmd, targetInterp, targetCmd,
  51                 argc, argv\fR)
  52 .sp
  53 int
  54 \fBTcl_CreateAliasObj\fR(\fIchildInterp, childCmd, targetInterp, targetCmd,
  55                    objc, objv\fR)
  56 .sp
  57 int
  58 \fBTcl_GetAlias\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr,
  59              argcPtr, argvPtr\fR)
  60 .sp
  61 int
  62 \fBTcl_GetAliasObj\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr,
  63                 objcPtr, objvPtr\fR)
  64 .sp
  65 int
  66 \fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
  67 .sp
  68 int
  69 \fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
  70 .SH ARGUMENTS
  71 .AS "const char *const" **targetInterpPtr out
  72 .AP Tcl_Interp *interp in
  73 Interpreter in which to execute the specified command.
  74 .AP "const char" *name in
  75 Name of child interpreter to create or manipulate.
  76 .AP int isSafe in
  77 If non-zero, a
  78 .QW safe
  79 child that is suitable for running untrusted code
  80 is created, otherwise a trusted child is created.
  81 .AP Tcl_Interp *childInterp in
  82 Interpreter to use for creating the source command for an alias (see
  83 below).
  84 .AP "const char" *childCmd in
  85 Name of source command for alias.
  86 .AP Tcl_Interp *targetInterp in
  87 Interpreter that contains the target command for an alias.
  88 .AP "const char" *targetCmd in
  89 Name of target command for alias in \fItargetInterp\fR.
  90 .AP int argc in
  91 Count of additional arguments to pass to the alias command.
  92 .AP "const char *const" *argv in
  93 Vector of strings, the additional arguments to pass to the alias command.
  94 This storage is owned by the caller.
  95 .AP int objc in
  96 Count of additional value arguments to pass to the aliased command.
  97 .AP Tcl_Obj **objv in
  98 Vector of Tcl_Obj structures, the additional value arguments to pass to
  99 the aliased command.
 100 This storage is owned by the caller.
 101 .AP Tcl_Interp **targetInterpPtr in
 102 Pointer to location to store the address of the interpreter where a target
 103 command is defined for an alias.
 104 .AP "const char" **targetCmdPtr out
 105 Pointer to location to store the address of the name of the target command
 106 for an alias.
 107 .AP int *argcPtr out
 108 Pointer to location to store count of additional arguments to be passed to
 109 the alias. The location is in storage owned by the caller.
 110 .AP "const char" ***argvPtr out
 111 Pointer to location to store a vector of strings, the additional arguments
 112 to pass to an alias. The location is in storage owned by the caller, the
 113 vector of strings is owned by the called function.
 114 .AP int *objcPtr out
 115 Pointer to location to store count of additional value arguments to be
 116 passed to the alias. The location is in storage owned by the caller.
 117 .AP Tcl_Obj ***objvPtr out
 118 Pointer to location to store a vector of Tcl_Obj structures, the additional
 119 arguments to pass to an alias command. The location is in storage
 120 owned by the caller, the vector of Tcl_Obj structures is owned by the
 121 called function.
 122 .AP "const char" *cmdName in
 123 Name of an exposed command to hide or create.
 124 .AP "const char" *hiddenCmdName in
 125 Name under which a hidden command is stored and with which it can be
 126 exposed or invoked.
 127 .BE
 128
 129 .SH DESCRIPTION
 130 .PP
 131 These procedures are intended for access to the multiple interpreter
 132 facility from inside C programs. They enable managing multiple interpreters
 133 in a hierarchical relationship, and the management of aliases, commands
 134 that when invoked in one interpreter execute a command in another
 135 interpreter. The return value for those procedures that return an \fBint\fR
 136 is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
 137 then the interpreter's result contains an error message.
 138 .PP
 139 \fBTcl_CreateSlave\fR creates a new interpreter as a child of \fIinterp\fR.
 140 It also creates a child command named \fIchildName\fR in \fIinterp\fR which
 141 allows \fIinterp\fR to manipulate the new child.
 142 If \fIisSafe\fR is zero, the command creates a trusted child in which Tcl
 143 code has access to all the Tcl commands.
 144 If it is \fB1\fR, the command creates a
 145 .QW safe
 146 child in which Tcl code has access only to set of Tcl commands defined as
 147 .QW "Safe Tcl" ;
 148 see the manual entry for the Tcl \fBinterp\fR command for details.
 149 If the creation of the new child interpreter failed, \fBNULL\fR is returned.
 150 .PP
 151 .VS "TIP 581"
 152 \fBTcl_CreateChild\fR is a synonym for \fBTcl_CreateSlave\fR.
 153 .VE "TIP 581"
 154 .PP
 155 \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
 156 .QW safe
 157 (was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
 158 \fB0\fR otherwise.
 159 .PP
 160 \fBTcl_MakeSafe\fR marks \fIinterp\fR as
 161 .QW safe ,
 162 so that future
 163 calls to \fBTcl_IsSafe\fR will return 1.  It also removes all known
 164 potentially-unsafe core functionality (both commands and variables)
 165 from \fIinterp\fR.  However, it cannot know what parts of an extension
 166 or application are safe and does not make any attempt to remove those
 167 parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
 168 Callers will want to take care with their use of \fBTcl_MakeSafe\fR
 169 to avoid false claims of safety.  For many situations, \fBTcl_CreateSlave\fR
 170 may be a better choice, since it creates interpreters in a known-safe state.
 171 .PP
 172 \fBTcl_GetSlave\fR returns a pointer to a child interpreter of
 173 \fIinterp\fR. The child interpreter is identified by \fIchildName\fR.
 174 If no such child interpreter exists, \fBNULL\fR is returned.
 175 .PP
 176 .VS "TIP 581"
 177 \fBTcl_GetChild\fR is a synonym for \fBTcl_GetSlave\fR.
 178 .VE "TIP 581"
 179 .PP
 180 \fBTcl_GetMaster\fR returns a pointer to the master interpreter of
 181 \fIinterp\fR. If \fIinterp\fR has no master (it is a
 182 top-level interpreter) then \fBNULL\fR is returned.
 183 .PP
 184 .VS "TIP 581"
 185 \fBTcl_GetParent\fR is a synonym for \fBTcl_GetMaster\fR.
 186 .VE "TIP 581"
 187 .PP
 188 \fBTcl_GetInterpPath\fR stores in the result of \fIinterp\fR
 189 the relative path between \fIinterp\fR and \fIchildInterp\fR;
 190 \fIchildInterp\fR must be a child of \fIinterp\fR. If the computation
 191 of the relative path succeeds, \fBTCL_OK\fR is returned, else
 192 \fBTCL_ERROR\fR is returned and an error message is stored as the
 193 result of \fIinterp\fR.
 194 .PP
 195 \fBTcl_CreateAlias\fR creates a command named \fIchildCmd\fR in
 196 \fIchildInterp\fR that when invoked, will cause the command \fItargetCmd\fR
 197 to be invoked in \fItargetInterp\fR. The arguments specified by the strings
 198 contained in \fIargv\fR are always prepended to any arguments supplied in the
 199 invocation of \fIchildCmd\fR and passed to \fItargetCmd\fR.
 200 This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
 201 it fails; in that case, an error message is left in the value result
 202 of \fIchildInterp\fR.
 203 Note that there are no restrictions on the ancestry relationship (as
 204 created by \fBTcl_CreateSlave\fR) between \fIchildInterp\fR and
 205 \fItargetInterp\fR. Any two interpreters can be used, without any
 206 restrictions on how they are related.
 207 .PP
 208 \fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except
 209 that it takes a vector of values to pass as additional arguments instead
 210 of a vector of strings.
 211 .PP
 212 \fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
 213 in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
 214 which case the corresponding datum is not returned. If a result field is
 215 non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
 216 For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
 217 pointer to the string containing the name of the target command.
 218 .PP
 219 \fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
 220 returns a pointer to a vector of Tcl_Obj structures instead of a vector of
 221 strings.
 222 .PP
 223 \fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
 224 the set of hidden commands to the set of exposed commands, putting
 225 it under the name
 226 \fIcmdName\fR.
 227 \fIHiddenCmdName\fR must be the name of an existing hidden
 228 command, or the operation will return \fBTCL_ERROR\fR and
 229 leave an error message as the result of \fIinterp\fR.
 230 If an exposed command named \fIcmdName\fR already exists,
 231 the operation returns \fBTCL_ERROR\fR and leaves an error message as
 232 the result of \fIinterp\fR.
 233 If the operation succeeds, it returns \fBTCL_OK\fR.
 234 After executing this command, attempts to use \fIcmdName\fR in any
 235 script evaluation mechanism will again succeed.
 236 .PP
 237 \fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
 238 exposed commands to the set of hidden commands, under the name
 239 \fIhiddenCmdName\fR.
 240 \fICmdName\fR must be the name of an existing exposed
 241 command, or the operation will return \fBTCL_ERROR\fR and leave an error
 242 message as the result of \fIinterp\fR.
 243 Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
 244 namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
 245 leave an error message as the result of \fIinterp\fR.
 246 The \fICmdName\fR will be looked up in the global namespace, and not
 247 relative to the current namespace, even if the current namespace is not the
 248 global one.
 249 If a hidden command whose name is \fIhiddenCmdName\fR already
 250 exists, the operation also returns \fBTCL_ERROR\fR and an error
 251 message is left as the result of \fIinterp\fR.
 252 If the operation succeeds, it returns \fBTCL_OK\fR.
 253 After executing this command, attempts to use \fIcmdName\fR in
 254 any script evaluation mechanism will fail.
 255 .PP
 256 For a description of the Tcl interface to multiple interpreters, see
 257 \fIinterp(n)\fR.
 258 .SH "SEE ALSO"
 259 interp
 260
 261 .SH KEYWORDS
 262 alias, command, exposed commands, hidden commands, interpreter, invoke,
 263 parent, child