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