util/X86LINUX64/man/man3/Tcl_CreateCommand.3

   1 '\"
   2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
   9 .\" The -*- nroff -*- definitions below are for supplemental macros used
  10 .\" in Tcl/Tk 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 ?manpage?
  54 .\"     Start of list of standard options for a Tk widget. The manpage
  55 .\"     argument defines where to look up the standard options; if
  56 .\"     omitted, defaults to "options". The options follow on successive
  57 .\"     lines, in three columns separated by tabs.
  58 .\"
  59 .\" .SE
  60 .\"     End of list of standard options for a Tk widget.
  61 .\"
  62 .\" .OP cmdName dbName dbClass
  63 .\"     Start of description of a specific option.  cmdName gives the
  64 .\"     option's name as specified in the class command, dbName gives
  65 .\"     the option's name in the option database, and dbClass gives
  66 .\"     the option's class in the option database.
  67 .\"
  68 .\" .UL arg1 arg2
  69 .\"     Print arg1 underlined, then print arg2 normally.
  70 .\"
  71 .\" .QW arg1 ?arg2?
  72 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  73 .\"
  74 .\" .PQ arg1 ?arg2?
  75 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  76 .\"     (for trailing punctuation) and then a closing parenthesis.
  77 .\"
  78 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  79 .if t .wh -1.3i ^B
  80 .nr ^l \n(.l
  81 .ad b
  82 .\"     # Start an argument description
  83 .de AP
  84 .ie !"\\$4"" .TP \\$4
  85 .el \{\
  86 .   ie !"\\$2"" .TP \\n()Cu
  87 .   el          .TP 15
  88 .\}
  89 .ta \\n()Au \\n()Bu
  90 .ie !"\\$3"" \{\
  91 \&\\$1 \\fI\\$2\\fP (\\$3)
  92 .\".b
  93 .\}
  94 .el \{\
  95 .br
  96 .ie !"\\$2"" \{\
  97 \&\\$1  \\fI\\$2\\fP
  98 .\}
  99 .el \{\
 100 \&\\fI\\$1\\fP
 101 .\}
 102 .\}
 103 ..
 104 .\"     # define tabbing values for .AP
 105 .de AS
 106 .nr )A 10n
 107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 108 .nr )B \\n()Au+15n
 109 .\"
 110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 112 ..
 113 .AS Tcl_Interp Tcl_CreateInterp in/out
 114 .\"     # BS - start boxed text
 115 .\"     # ^y = starting y location
 116 .\"     # ^b = 1
 117 .de BS
 118 .br
 119 .mk ^y
 120 .nr ^b 1u
 121 .if n .nf
 122 .if n .ti 0
 123 .if n \l'\\n(.lu\(ul'
 124 .if n .fi
 125 ..
 126 .\"     # BE - end boxed text (draw box now)
 127 .de BE
 128 .nf
 129 .ti 0
 130 .mk ^t
 131 .ie n \l'\\n(^lu\(ul'
 132 .el \{\
 133 .\"     Draw four-sided box normally, but don't draw top of
 134 .\"     box if the box started on an earlier page.
 135 .ie !\\n(^b-1 \{\
 136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 137 .\}
 138 .el \}\
 139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 140 .\}
 141 .\}
 142 .fi
 143 .br
 144 .nr ^b 0
 145 ..
 146 .\"     # VS - start vertical sidebar
 147 .\"     # ^Y = starting y location
 148 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 149 .de VS
 150 .if !"\\$2"" .br
 151 .mk ^Y
 152 .ie n 'mc \s12\(br\s0
 153 .el .nr ^v 1u
 154 ..
 155 .\"     # VE - end of vertical sidebar
 156 .de VE
 157 .ie n 'mc
 158 .el \{\
 159 .ev 2
 160 .nf
 161 .ti 0
 162 .mk ^t
 163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 164 .sp -1
 165 .fi
 166 .ev
 167 .\}
 168 .nr ^v 0
 169 ..
 170 .\"     # Special macro to handle page bottom:  finish off current
 171 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 172 .\"     # page bottom macro.
 173 .de ^B
 174 .ev 2
 175 'ti 0
 176 'nf
 177 .mk ^t
 178 .if \\n(^b \{\
 179 .\"     Draw three-sided box if this is the box's first page,
 180 .\"     draw two sides but no top otherwise.
 181 .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
 182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .\}
 184 .if \\n(^v \{\
 185 .nr ^x \\n(^tu+1v-\\n(^Yu
 186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 187 .\}
 188 .bp
 189 'fi
 190 .ev
 191 .if \\n(^b \{\
 192 .mk ^y
 193 .nr ^b 2
 194 .\}
 195 .if \\n(^v \{\
 196 .mk ^Y
 197 .\}
 198 ..
 199 .\"     # DS - begin display
 200 .de DS
 201 .RS
 202 .nf
 203 .sp
 204 ..
 205 .\"     # DE - end display
 206 .de DE
 207 .fi
 208 .RE
 209 .sp
 210 ..
 211 .\"     # SO - start of list of standard options
 212 .de SO
 213 'ie '\\$1'' .ds So \\fBoptions\\fR
 214 'el .ds So \\fB\\$1\\fR
 215 .SH "STANDARD OPTIONS"
 216 .LP
 217 .nf
 218 .ta 5.5c 11c
 219 .ft B
 220 ..
 221 .\"     # SE - end of list of standard options
 222 .de SE
 223 .fi
 224 .ft R
 225 .LP
 226 See the \\*(So manual entry for details on the standard options.
 227 ..
 228 .\"     # OP - start of full description for a single option
 229 .de OP
 230 .LP
 231 .nf
 232 .ta 4c
 233 Command-Line Name:      \\fB\\$1\\fR
 234 Database Name:  \\fB\\$2\\fR
 235 Database Class: \\fB\\$3\\fR
 236 .fi
 237 .IP
 238 ..
 239 .\"     # CS - begin code excerpt
 240 .de CS
 241 .RS
 242 .nf
 243 .ta .25i .5i .75i 1i
 244 ..
 245 .\"     # CE - end code excerpt
 246 .de CE
 247 .fi
 248 .RE
 249 ..
 250 .\"     # UL - underline word
 251 .de UL
 252 \\$1\l'|0\(ul'\\$2
 253 ..
 254 .\"     # QW - apply quotation marks to word
 255 .de QW
 256 .ie '\\*(lq'"' ``\\$1''\\$2
 257 .\"" fix emacs highlighting
 258 .el \\*(lq\\$1\\*(rq\\$2
 259 ..
 260 .\"     # PQ - apply parens and quotation marks to word
 261 .de PQ
 262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 263 .\"" fix emacs highlighting
 264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 265 ..
 266 .\"     # QR - quoted range
 267 .de QR
 268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 269 .\"" fix emacs highlighting
 270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 271 ..
 272 .\"     # MT - "empty" string
 273 .de MT
 274 .QW ""
 275 ..
 276 .BS
 277 .SH NAME
 278 Tcl_CreateCommand \- implement new commands in C
 279 .SH SYNOPSIS
 280 .nf
 281 \fB#include <tcl.h>\fR
 282 .sp
 283 Tcl_Command
 284 \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
 285 .SH ARGUMENTS
 286 .AS Tcl_CmdDeleteProc *deleteProc
 287 .AP Tcl_Interp *interp in
 288 Interpreter in which to create new command.
 289 .AP "const char" *cmdName in
 290 Name of command.
 291 .AP Tcl_CmdProc *proc in
 292 Implementation of new command:  \fIproc\fR will be called whenever
 293 \fIcmdName\fR is invoked as a command.
 294 .AP ClientData clientData in
 295 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
 296 .AP Tcl_CmdDeleteProc *deleteProc in
 297 Procedure to call before \fIcmdName\fR is deleted from the interpreter;
 298 allows for command-specific cleanup.  If NULL, then no procedure is
 299 called before the command is deleted.
 300 .BE
 301 .SH DESCRIPTION
 302 .PP
 303 \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
 304 it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
 305 invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
 306 will call \fIproc\fR to process the command.
 307 It differs from \fBTcl_CreateObjCommand\fR in that a new string-based
 308 command is defined;
 309 that is, a command procedure is defined that takes an array of
 310 argument strings instead of values.
 311 The value-based command procedures registered by \fBTcl_CreateObjCommand\fR
 312 can execute significantly faster than the string-based command procedures
 313 defined by \fBTcl_CreateCommand\fR.
 314 This is because they take Tcl values as arguments
 315 and those values can retain an internal representation that
 316 can be manipulated more efficiently.
 317 Also, Tcl's interpreter now uses values internally.
 318 In order to invoke a string-based command procedure
 319 registered by \fBTcl_CreateCommand\fR,
 320 it must generate and fetch a string representation
 321 from each argument value before the call.
 322 New commands should be defined using \fBTcl_CreateObjCommand\fR.
 323 We support \fBTcl_CreateCommand\fR for backwards compatibility.
 324 .PP
 325 The procedures \fBTcl_DeleteCommand\fR, \fBTcl_GetCommandInfo\fR,
 326 and \fBTcl_SetCommandInfo\fR are used in conjunction with
 327 \fBTcl_CreateCommand\fR.
 328 .PP
 329 \fBTcl_CreateCommand\fR will delete an existing command \fIcmdName\fR,
 330 if one is already associated with the interpreter.
 331 It returns a token that may be used to refer
 332 to the command in subsequent calls to \fBTcl_GetCommandName\fR.
 333 If \fIcmdName\fR contains any \fB::\fR namespace qualifiers,
 334 then the command is added to the specified namespace;
 335 otherwise the command is added to the global namespace.
 336 If \fBTcl_CreateCommand\fR is called for an interpreter that is in
 337 the process of being deleted, then it does not create a new command
 338 and it returns NULL.
 339 \fIProc\fR should have arguments and result that match the type
 340 \fBTcl_CmdProc\fR:
 341 .PP
 342 .CS
 343 typedef int \fBTcl_CmdProc\fR(
 344         ClientData \fIclientData\fR,
 345         Tcl_Interp *\fIinterp\fR,
 346         int \fIargc\fR,
 347         const char *\fIargv\fR[]);
 348 .CE
 349 .PP
 350 When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
 351 parameters will be copies of the \fIclientData\fR and \fIinterp\fR
 352 arguments given to \fBTcl_CreateCommand\fR.
 353 Typically, \fIclientData\fR points to an application-specific
 354 data structure that describes what to do when the command procedure
 355 is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
 356 the command, \fIargc\fR giving the number of arguments (including
 357 the command name) and \fIargv\fR giving the values of the arguments
 358 as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
 359 the first \fIargc\fR values point to the argument strings, and the
 360 last value is NULL.
 361 Note that the argument strings should not be modified as they may
 362 point to constant strings or may be shared with other parts of the
 363 interpreter.
 364 .PP
 365 Note that the argument strings are encoded in normalized UTF-8 since
 366 version 8.1 of Tcl.
 367 .PP
 368 \fIProc\fR must return an integer code that is expected to be one of
 369 \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
 370 \fBTCL_CONTINUE\fR.  See the Tcl overview man page
 371 for details on what these codes mean.  Most normal commands will only
 372 return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
 373 the interpreter result;
 374 in the case of a \fBTCL_OK\fR return code this gives the result
 375 of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
 376 The \fBTcl_SetResult\fR procedure provides an easy interface for setting
 377 the return value;  for complete details on how the interpreter result
 378 field is managed, see the \fBTcl_Interp\fR man page.
 379 Before invoking a command procedure,
 380 \fBTcl_Eval\fR sets the interpreter result to point to an empty string,
 381 so simple commands can return an empty result by doing nothing at all.
 382 .PP
 383 The contents of the \fIargv\fR array belong to Tcl and are not
 384 guaranteed to persist once \fIproc\fR returns:  \fIproc\fR should
 385 not modify them, nor should it set the interpreter result to point
 386 anywhere within the \fIargv\fR values.
 387 Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
 388 to return something from the \fIargv\fR array.
 389 .PP
 390 \fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted. This can
 391 occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
 392 or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
 393 \fIDeleteProc\fR is invoked before the command is deleted, and gives the
 394 application an opportunity to release any structures associated
 395 with the command.  \fIDeleteProc\fR should have arguments and
 396 result that match the type \fBTcl_CmdDeleteProc\fR:
 397 .PP
 398 .CS
 399 typedef void \fBTcl_CmdDeleteProc\fR(
 400         ClientData \fIclientData\fR);
 401 .CE
 402 .PP
 403 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 404 argument passed to \fBTcl_CreateCommand\fR.
 405 .SH "SEE ALSO"
 406 Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo,
 407 Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
 408 .SH KEYWORDS
 409 bind, command, create, delete, interpreter, namespace