CELLLINUX64/util/CELLLINUX64/man/man3/Tcl_MakeSafe.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 '\" RCS: @(#) $Id: CrtSlave.3,v 1.8.2.2 2003/07/18 15:20:51 dgp Exp $
   8 '\"
   9 '\" The definitions below are for supplemental macros used in Tcl/Tk
  10 '\" manual entries.
  11 '\"
  12 '\" .AP type name in/out ?indent?
  13 '\"     Start paragraph describing an argument to a library procedure.
  14 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 '\"     needed;  use .AS below instead)
  18 '\"
  19 '\" .AS ?type? ?name?
  20 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 '\"     name are examples of largest possible arguments that will be passed
  22 '\"     to .AP later.  If args are omitted, default tab stops are used.
  23 '\"
  24 '\" .BS
  25 '\"     Start box enclosure.  From here until next .BE, everything will be
  26 '\"     enclosed in one large box.
  27 '\"
  28 '\" .BE
  29 '\"     End of box enclosure.
  30 '\"
  31 '\" .CS
  32 '\"     Begin code excerpt.
  33 '\"
  34 '\" .CE
  35 '\"     End code excerpt.
  36 '\"
  37 '\" .VS ?version? ?br?
  38 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 '\"     of man pages.  The first argument is ignored and used for recording
  40 '\"     the version when the .VS was added, so that the sidebars can be
  41 '\"     found and removed when they reach a certain age.  If another argument
  42 '\"     is present, then a line break is forced before starting the sidebar.
  43 '\"
  44 '\" .VE
  45 '\"     End of vertical sidebar.
  46 '\"
  47 '\" .DS
  48 '\"     Begin an indented unfilled display.
  49 '\"
  50 '\" .DE
  51 '\"     End of indented unfilled display.
  52 '\"
  53 '\" .SO
  54 '\"     Start of list of standard options for a Tk widget.  The
  55 '\"     options follow on successive lines, in four columns separated
  56 '\"     by tabs.
  57 '\"
  58 '\" .SE
  59 '\"     End of list of standard options for a Tk widget.
  60 '\"
  61 '\" .OP cmdName dbName dbClass
  62 '\"     Start of description of a specific option.  cmdName gives the
  63 '\"     option's name as specified in the class command, dbName gives
  64 '\"     the option's name in the option database, and dbClass gives
  65 '\"     the option's class in the option database.
  66 '\"
  67 '\" .UL arg1 arg2
  68 '\"     Print arg1 underlined, then print arg2 normally.
  69 '\"
  70 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
  71 '\"
  72 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  73 .if t .wh -1.3i ^B
  74 .nr ^l \n(.l
  75 .ad b
  76 '\"     # Start an argument description
  77 .de AP
  78 .ie !"\\$4"" .TP \\$4
  79 .el \{\
  80 .   ie !"\\$2"" .TP \\n()Cu
  81 .   el          .TP 15
  82 .\}
  83 .ta \\n()Au \\n()Bu
  84 .ie !"\\$3"" \{\
  85 \&\\$1  \\fI\\$2\\fP    (\\$3)
  86 .\".b
  87 .\}
  88 .el \{\
  89 .br
  90 .ie !"\\$2"" \{\
  91 \&\\$1  \\fI\\$2\\fP
  92 .\}
  93 .el \{\
  94 \&\\fI\\$1\\fP
  95 .\}
  96 .\}
  97 ..
  98 '\"     # define tabbing values for .AP
  99 .de AS
 100 .nr )A 10n
 101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 102 .nr )B \\n()Au+15n
 103 .\"
 104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 106 ..
 107 .AS Tcl_Interp Tcl_CreateInterp in/out
 108 '\"     # BS - start boxed text
 109 '\"     # ^y = starting y location
 110 '\"     # ^b = 1
 111 .de BS
 112 .br
 113 .mk ^y
 114 .nr ^b 1u
 115 .if n .nf
 116 .if n .ti 0
 117 .if n \l'\\n(.lu\(ul'
 118 .if n .fi
 119 ..
 120 '\"     # BE - end boxed text (draw box now)
 121 .de BE
 122 .nf
 123 .ti 0
 124 .mk ^t
 125 .ie n \l'\\n(^lu\(ul'
 126 .el \{\
 127 .\"     Draw four-sided box normally, but don't draw top of
 128 .\"     box if the box started on an earlier page.
 129 .ie !\\n(^b-1 \{\
 130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 131 .\}
 132 .el \}\
 133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 134 .\}
 135 .\}
 136 .fi
 137 .br
 138 .nr ^b 0
 139 ..
 140 '\"     # VS - start vertical sidebar
 141 '\"     # ^Y = starting y location
 142 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 143 .de VS
 144 .if !"\\$2"" .br
 145 .mk ^Y
 146 .ie n 'mc \s12\(br\s0
 147 .el .nr ^v 1u
 148 ..
 149 '\"     # VE - end of vertical sidebar
 150 .de VE
 151 .ie n 'mc
 152 .el \{\
 153 .ev 2
 154 .nf
 155 .ti 0
 156 .mk ^t
 157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 158 .sp -1
 159 .fi
 160 .ev
 161 .\}
 162 .nr ^v 0
 163 ..
 164 '\"     # Special macro to handle page bottom:  finish off current
 165 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 166 '\"     # page bottom macro.
 167 .de ^B
 168 .ev 2
 169 'ti 0
 170 'nf
 171 .mk ^t
 172 .if \\n(^b \{\
 173 .\"     Draw three-sided box if this is the box's first page,
 174 .\"     draw two sides but no top otherwise.
 175 .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
 176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 177 .\}
 178 .if \\n(^v \{\
 179 .nr ^x \\n(^tu+1v-\\n(^Yu
 180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 181 .\}
 182 .bp
 183 'fi
 184 .ev
 185 .if \\n(^b \{\
 186 .mk ^y
 187 .nr ^b 2
 188 .\}
 189 .if \\n(^v \{\
 190 .mk ^Y
 191 .\}
 192 ..
 193 '\"     # DS - begin display
 194 .de DS
 195 .RS
 196 .nf
 197 .sp
 198 ..
 199 '\"     # DE - end display
 200 .de DE
 201 .fi
 202 .RE
 203 .sp
 204 ..
 205 '\"     # SO - start of list of standard options
 206 .de SO
 207 .SH "STANDARD OPTIONS"
 208 .LP
 209 .nf
 210 .ta 5.5c 11c
 211 .ft B
 212 ..
 213 '\"     # SE - end of list of standard options
 214 .de SE
 215 .fi
 216 .ft R
 217 .LP
 218 See the \\fBoptions\\fR manual entry for details on the standard options.
 219 ..
 220 '\"     # OP - start of full description for a single option
 221 .de OP
 222 .LP
 223 .nf
 224 .ta 4c
 225 Command-Line Name:      \\fB\\$1\\fR
 226 Database Name:  \\fB\\$2\\fR
 227 Database Class: \\fB\\$3\\fR
 228 .fi
 229 .IP
 230 ..
 231 '\"     # CS - begin code excerpt
 232 .de CS
 233 .RS
 234 .nf
 235 .ta .25i .5i .75i 1i
 236 ..
 237 '\"     # CE - end code excerpt
 238 .de CE
 239 .fi
 240 .RE
 241 ..
 242 .de UL
 243 \\$1\l'|0\(ul'\\$2
 244 ..
 245 .TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
 246 .BS
 247 .SH NAME
 248 Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands.
 249 .SH SYNOPSIS
 250 .nf
 251 \fB#include <tcl.h>\fR
 252 .sp
 253 int
 254 \fBTcl_IsSafe\fR(\fIinterp\fR)
 255 .sp
 256 int
 257 \fBTcl_MakeSafe\fR(\fIinterp\fR)
 258 .sp
 259 Tcl_Interp *
 260 \fBTcl_CreateSlave\fR(\fIinterp, slaveName, isSafe\fR)
 261 .sp
 262 Tcl_Interp *
 263 \fBTcl_GetSlave\fR(\fIinterp, slaveName\fR)
 264 .sp
 265 Tcl_Interp *
 266 \fBTcl_GetMaster\fR(\fIinterp\fR)
 267 .sp
 268 int
 269 \fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
 270 .sp
 271 .VS
 272 int
 273 \fBTcl_CreateAlias\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd, argc, argv\fR)
 274 .sp
 275 int
 276 \fBTcl_CreateAliasObj\fR(\fIslaveInterp, slaveCmd, targetInterp, targetCmd, objc, objv\fR)
 277 .VE
 278 .sp
 279 int
 280 \fBTcl_GetAlias\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)
 281 .sp
 282 .VS
 283 int
 284 \fBTcl_GetAliasObj\fR(\fIinterp, slaveCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr\fR)
 285 .sp
 286 int
 287 \fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
 288 .sp
 289 int
 290 \fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
 291 .SH ARGUMENTS
 292 .AS Tcl_InterpDeleteProc **hiddenCmdName
 293 .AP Tcl_Interp *interp in
 294 Interpreter in which to execute the specified command.
 295 .AP "CONST char" *slaveName in
 296 Name of slave interpreter to create or manipulate.
 297 .AP int isSafe in
 298 If non-zero, a ``safe'' slave that is suitable for running untrusted code
 299 is created, otherwise a trusted slave is created.
 300 .AP Tcl_Interp *slaveInterp in
 301 Interpreter to use for creating the source command for an alias (see
 302 below).
 303 .AP "CONST char" *slaveCmd in
 304 Name of source command for alias.
 305 .AP Tcl_Interp *targetInterp in
 306 Interpreter that contains the target command for an alias.
 307 .AP "CONST char" *targetCmd in
 308 Name of target command for alias in \fItargetInterp\fR.
 309 .AP int argc in
 310 Count of additional arguments to pass to the alias command.
 311 .AP "CONST char * CONST" *argv in
 312 Vector of strings, the additional arguments to pass to the alias command.
 313 This storage is owned by the caller.
 314 .AP int objc in
 315 Count of additional object arguments to pass to the alias object command.
 316 .AP Tcl_Object **objv in
 317 Vector of Tcl_Obj structures, the additional object arguments to pass to
 318 the alias object command.
 319 This storage is owned by the caller.
 320 .AP Tcl_Interp **targetInterpPtr in
 321 Pointer to location to store the address of the interpreter where a target
 322 command is defined for an alias.
 323 .AP "CONST char" **targetCmdPtr out
 324 Pointer to location to store the address of the name of the target command
 325 for an alias.
 326 .AP int *argcPtr out
 327 Pointer to location to store count of additional arguments to be passed to
 328 the alias. The location is in storage owned by the caller.
 329 .AP "CONST char" ***argvPtr out
 330 Pointer to location to store a vector of strings, the additional arguments
 331 to pass to an alias. The location is in storage owned by the caller, the
 332 vector of strings is owned by the called function.
 333 .AP int *objcPtr out
 334 Pointer to location to store count of additional object arguments to be
 335 passed to the alias. The location is in storage owned by the caller.
 336 .AP Tcl_Obj ***objvPtr out
 337 Pointer to location to store a vector of Tcl_Obj structures, the additional
 338 arguments to pass to an object alias command. The location is in storage
 339 owned by the caller, the vector of Tcl_Obj structures is owned by the
 340 called function.
 341 .VS
 342 .VS 8.4
 343 .AP "CONST char" *cmdName in
 344 .VE
 345 Name of an exposed command to hide or create.
 346 .VS 8.4
 347 .AP "CONST char" *hiddenCmdName in
 348 .VE
 349 Name under which a hidden command is stored and with which it can be
 350 exposed or invoked.
 351 .VE
 352 .BE
 353
 354 .SH DESCRIPTION
 355 .PP
 356 These procedures are intended for access to the multiple interpreter
 357 facility from inside C programs. They enable managing multiple interpreters
 358 in a hierarchical relationship, and the management of aliases, commands
 359 that when invoked in one interpreter execute a command in another
 360 interpreter. The return value for those procedures that return an \fBint\fR
 361 is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
 362 then the \fBresult\fR field of the interpreter contains an error message.
 363 .PP
 364 \fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR.
 365 It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
 366 allows \fIinterp\fR to manipulate the new slave.
 367 If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
 368 code has access to all the Tcl commands.
 369 If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code
 370 has access only to set of Tcl commands defined as ``Safe Tcl''; see the
 371 manual entry for the Tcl \fBinterp\fR command for details.
 372 If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
 373 .PP
 374 \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created
 375 with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
 376 \fB0\fR otherwise.
 377 .PP
 378 \fBTcl_MakeSafe\fR marks \fIinterp\fR as ``safe'', so that future
 379 calls to \fBTcl_IsSafe\fR will return 1.  It also removes all known
 380 potentially-unsafe core functionality (both commands and variables)
 381 from \fIinterp\fR.  However, it cannot know what parts of an extension
 382 or application are safe and does not make any attempt to remove those
 383 parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
 384 Callers will want to take care with their use of \fBTcl_MakeSafe\fR
 385 to avoid false claims of safety.  For many situations, \fBTcl_CreateSlave\fR
 386 may be a better choice, since it creates interpreters in a known-safe state.
 387 .PP
 388 \fBTcl_GetSlave\fR returns a pointer to a slave interpreter of
 389 \fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR.
 390 If no such slave interpreter exists, \fBNULL\fR is returned.
 391 .PP
 392 \fBTcl_GetMaster\fR returns a pointer to the master interpreter of
 393 \fIinterp\fR. If \fIinterp\fR has no master (it is a
 394 top-level interpreter) then \fBNULL\fR is returned.
 395 .PP
 396 \fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
 397 to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
 398 \fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation
 399 of the relative path succeeds, \fBTCL_OK\fR is returned, else
 400 \fBTCL_ERROR\fR is returned and the \fIresult\fR field in
 401 \fIaskingInterp\fR contains the error message.
 402 .PP
 403 .VS
 404 \fBTcl_CreateAlias\fR creates an object command named \fIslaveCmd\fR in
 405 \fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
 406 to be invoked in \fItargetInterp\fR. The arguments specified by the strings
 407 contained in \fIargv\fR are always prepended to any arguments supplied in the
 408 invocation of \fIslaveCmd\fR and passed to \fItargetCmd\fR.
 409 This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
 410 it fails; in that case, an error message is left in the object result
 411 of \fIslaveInterp\fR.
 412 Note that there are no restrictions on the ancestry relationship (as
 413 created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
 414 \fItargetInterp\fR. Any two interpreters can be used, without any
 415 restrictions on how they are related.
 416 .PP
 417 \fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except
 418 that it takes a vector of objects to pass as additional arguments instead
 419 of a vector of strings.
 420 .VE
 421 .PP
 422 \fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
 423 in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
 424 which case the corresponding datum is not returned. If a result field is
 425 non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
 426 For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
 427 pointer to the string containing the name of the target command.
 428 .VS
 429 .PP
 430 \fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
 431 returns a pointer to a vector of Tcl_Obj structures instead of a vector of
 432 strings.
 433 .PP
 434 \fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
 435 the set of hidden commands to the set of exposed commands, putting
 436 it under the name
 437 \fIcmdName\fR.
 438 \fIHiddenCmdName\fR must be the name of an existing hidden
 439 command, or the operation will return \fBTCL_ERROR\fR and leave an error
 440 message in the \fIresult\fR field in \fIinterp\fR.
 441 If an exposed command named \fIcmdName\fR already exists,
 442 the operation returns \fBTCL_ERROR\fR and leaves an error message in the
 443 object result of \fIinterp\fR.
 444 If the operation succeeds, it returns \fBTCL_OK\fR.
 445 After executing this command, attempts to use \fIcmdName\fR in a call to
 446 \fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
 447 .PP
 448 \fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
 449 exposed commands to the set of hidden commands, under the name
 450 \fIhiddenCmdName\fR.
 451 \fICmdName\fR must be the name of an existing exposed
 452 command, or the operation will return \fBTCL_ERROR\fR and leave an error
 453 message in the object result of \fIinterp\fR.
 454 Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
 455 namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
 456 leave an error message in the object result of \fIinterp\fR.
 457 The \fICmdName\fR will be looked up in the global namespace, and not
 458 relative to the current namespace, even if the current namespace is not the
 459 global one.
 460 If a hidden command whose name is \fIhiddenCmdName\fR already
 461 exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
 462 field in \fIinterp\fR contains an error message.
 463 If the operation succeeds, it returns \fBTCL_OK\fR.
 464 After executing this command, attempts to use \fIcmdName\fR in a call to
 465 \fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
 466 .PP
 467 For a description of the Tcl interface to multiple interpreters, see
 468 \fIinterp(n)\fR.
 469 .SH "SEE ALSO"
 470 interp
 471
 472 .SH KEYWORDS
 473 alias, command, exposed commands, hidden commands, interpreter, invoke,
 474 master, slave