ALPHALINUX5/util/ALPHALINUX5/man/man3/Tcl_IsSafe.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.3 1999/08/21 19:40:47 hobbs 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.3 1999/04/16 00:46:35 stanton 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 4c 8c 12c
 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, srcCmd, targetInterp, targetCmd, argc, argv\fR)
 274 .sp
 275 int
 276 \fBTcl_CreateAliasObj\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, objc, objv\fR)
 277 .VE
 278 .sp
 279 int
 280 \fBTcl_GetAlias\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)
 281 .sp
 282 .VS
 283 int
 284 \fBTcl_GetAliasObj\fR(\fIinterp, srcCmd, 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 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 char *srcCmd 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 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 char **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 argumenst 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 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 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 .AP char *cmdName in
 343 Name of an exposed command to hide or create.
 344 .AP char *hiddenCmdName in
 345 Name under which a hidden command is stored and with which it can be
 346 exposed or invoked.
 347 .VE
 348 .BE
 349
 350 .SH DESCRIPTION
 351 .PP
 352 These procedures are intended for access to the multiple interpreter
 353 facility from inside C programs. They enable managing multiple interpreters
 354 in a hierarchical relationship, and the management of aliases, commands
 355 that when invoked in one interpreter execute a command in another
 356 interpreter. The return value for those procedures that return an \fBint\fR
 357 is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
 358 then the \fBresult\fR field of the interpreter contains an error message.
 359 .PP
 360 \fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR.
 361 It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
 362 allows \fIinterp\fR to manipulate the new slave.
 363 If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
 364 code has access to all the Tcl commands.
 365 If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code
 366 has access only to set of Tcl commands defined as ``Safe Tcl''; see the
 367 manual entry for the Tcl \fBinterp\fR command for details.
 368 If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
 369 .PP
 370 \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created
 371 with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
 372 \fB0\fR otherwise.
 373 .PP
 374 \fBTcl_MakeSafe\fR makes \fIinterp\fR ``safe'' by removing all
 375 non-core and core unsafe functionality. Note that if you call this after
 376 adding some extension to an interpreter, all traces of that extension will
 377 be removed from the interpreter.
 378 .PP
 379 \fBTcl_GetSlave\fR returns a pointer to a slave interpreter of
 380 \fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR.
 381 If no such slave interpreter exists, \fBNULL\fR is returned.
 382 .PP
 383 \fBTcl_GetMaster\fR returns a pointer to the master interpreter of
 384 \fIinterp\fR. If \fIinterp\fR has no master (it is a
 385 top-level interpreter) then \fBNULL\fR is returned.
 386 .PP
 387 \fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
 388 to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
 389 \fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation
 390 of the relative path succeeds, \fBTCL_OK\fR is returned, else
 391 \fBTCL_ERROR\fR is returned and the \fIresult\fR field in
 392 \fIaskingInterp\fR contains the error message.
 393 .PP
 394 .VS
 395 \fBTcl_CreateAlias\fR creates an object command named \fIsrcCmd\fR in
 396 \fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
 397 to be invoked in \fItargetInterp\fR. The arguments specified by the strings
 398 contained in \fIargv\fR are always prepended to any arguments supplied in the
 399 invocation of \fIsrcCmd\fR and passed to \fItargetCmd\fR.
 400 This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
 401 it fails; in that case, an error message is left in the object result
 402 of \fIslaveInterp\fR.
 403 Note that there are no restrictions on the ancestry relationship (as
 404 created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
 405 \fItargetInterp\fR. Any two interpreters can be used, without any
 406 restrictions on how they are related.
 407 .PP
 408 \fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAlias\fR except
 409 that it takes a vector of objects to pass as additional arguments instead
 410 of a vector of strings.
 411 .VE
 412 .PP
 413 \fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
 414 in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
 415 which case the corresponding datum is not returned. If a result field is
 416 non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
 417 For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
 418 pointer to the string containing the name of the target command.
 419 .VS
 420 .PP
 421 \fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
 422 returns a pointer to a vector of Tcl_Obj structures instead of a vector of
 423 strings.
 424 .PP
 425 \fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
 426 the set of hidden commands to the set of exposed commands, putting
 427 it under the name
 428 \fIcmdName\fR.
 429 \fIHiddenCmdName\fR must be the name of an existing hidden
 430 command, or the operation will return \fBTCL_ERROR\fR and leave an error
 431 message in the \fIresult\fR field in \fIinterp\fR.
 432 If an exposed command named \fIcmdName\fR already exists,
 433 the operation returns \fBTCL_ERROR\fR and leaves an error message in the
 434 object result of \fIinterp\fR.
 435 If the operation succeeds, it returns \fBTCL_OK\fR.
 436 After executing this command, attempts to use \fIcmdName\fR in a call to
 437 \fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
 438 .PP
 439 \fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
 440 exposed commands to the set of hidden commands, under the name
 441 \fIhiddenCmdName\fR.
 442 \fICmdName\fR must be the name of an existing exposed
 443 command, or the operation will return \fBTCL_ERROR\fR and leave an error
 444 message in the object result of \fIinterp\fR.
 445 Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
 446 namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
 447 leave an error message in the object result of \fIinterp\fR.
 448 The \fICmdName\fR will be looked up in the global namespace, and not
 449 relative to the current namespace, even if the current namespace is not the
 450 global one.
 451 If a hidden command whose name is \fIhiddenCmdName\fR already
 452 exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
 453 field in \fIinterp\fR contains an error message.
 454 If the operation succeeds, it returns \fBTCL_OK\fR.
 455 After executing this command, attempts to use \fIcmdName\fR in a call to
 456 \fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
 457 .PP
 458 .SH "SEE ALSO"
 459 For a description of the Tcl interface to multiple interpreters, see
 460 \fIinterp(n)\fR.
 461
 462 .SH KEYWORDS
 463 alias, command, exposed commands, hidden commands, interpreter, invoke,
 464 master, slave,
 465