[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
| 3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
---|
| 4 | '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies |
---|
| 5 | '\" Copyright (c) 1998-2000 Ajuba Solutions |
---|
| 6 | '\" |
---|
| 7 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 8 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 9 | '\" |
---|
| 10 | '\" RCS: @(#) $Id: info.n,v 1.25 2008/03/12 20:16:13 andreas_kupries Exp $ |
---|
| 11 | '\" |
---|
| 12 | .so man.macros |
---|
| 13 | .TH info n 8.4 Tcl "Tcl Built-In Commands" |
---|
| 14 | .BS |
---|
| 15 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
| 16 | .SH NAME |
---|
| 17 | info \- Return information about the state of the Tcl interpreter |
---|
| 18 | .SH SYNOPSIS |
---|
| 19 | \fBinfo \fIoption \fR?\fIarg arg ...\fR? |
---|
| 20 | .BE |
---|
| 21 | |
---|
| 22 | .SH DESCRIPTION |
---|
| 23 | .PP |
---|
| 24 | This command provides information about various internals of the Tcl |
---|
| 25 | interpreter. |
---|
| 26 | The legal \fIoption\fRs (which may be abbreviated) are: |
---|
| 27 | .TP |
---|
| 28 | \fBinfo args \fIprocname\fR |
---|
| 29 | Returns a list containing the names of the arguments to procedure |
---|
| 30 | \fIprocname\fR, in order. \fIProcname\fR must be the name of a |
---|
| 31 | Tcl command procedure. |
---|
| 32 | .TP |
---|
| 33 | \fBinfo body \fIprocname\fR |
---|
| 34 | Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be |
---|
| 35 | the name of a Tcl command procedure. |
---|
| 36 | .TP |
---|
| 37 | \fBinfo cmdcount\fR |
---|
| 38 | Returns a count of the total number of commands that have been invoked |
---|
| 39 | in this interpreter. |
---|
| 40 | .TP |
---|
| 41 | \fBinfo commands \fR?\fIpattern\fR? |
---|
| 42 | If \fIpattern\fR is not specified, |
---|
| 43 | .\" Do not move this .VS above the .TP |
---|
| 44 | .VS 8.5 |
---|
| 45 | returns a list of names of all the Tcl commands visible |
---|
| 46 | (i.e. executable without using a qualified name) to the current namespace, |
---|
| 47 | including both the built-in commands written in C and |
---|
| 48 | the command procedures defined using the \fBproc\fR command. |
---|
| 49 | If \fIpattern\fR is specified, |
---|
| 50 | only those names matching \fIpattern\fR are returned. |
---|
| 51 | Matching is determined using the same rules as for \fBstring match\fR. |
---|
| 52 | \fIpattern\fR can be a qualified name like \fBFoo::print*\fR. |
---|
| 53 | That is, it may specify a particular namespace |
---|
| 54 | using a sequence of namespace names separated by double colons (\fB::\fR), |
---|
| 55 | and may have pattern matching special characters |
---|
| 56 | at the end to specify a set of commands in that namespace. |
---|
| 57 | If \fIpattern\fR is a qualified name, |
---|
| 58 | the resulting list of command names has each one qualified with the name |
---|
| 59 | of the specified namespace, and only the commands defined in the named |
---|
| 60 | namespace are returned. |
---|
| 61 | .\" Technically, most of this hasn't changed; that's mostly just the |
---|
| 62 | .\" way it always worked. Hardly anyone knew that though. |
---|
| 63 | .VE 8.5 |
---|
| 64 | .TP |
---|
| 65 | \fBinfo complete \fIcommand\fR |
---|
| 66 | Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of |
---|
| 67 | having no unclosed quotes, braces, brackets or array element names. |
---|
| 68 | If the command does not appear to be complete then 0 is returned. |
---|
| 69 | This command is typically used in line-oriented input environments |
---|
| 70 | to allow users to type in commands that span multiple lines; if the |
---|
| 71 | command is not complete, the script can delay evaluating it until additional |
---|
| 72 | lines have been typed to complete the command. |
---|
| 73 | .TP |
---|
| 74 | \fBinfo default \fIprocname arg varname\fR |
---|
| 75 | \fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR |
---|
| 76 | must be the name of an argument to that procedure. If \fIarg\fR |
---|
| 77 | does not have a default value then the command returns \fB0\fR. |
---|
| 78 | Otherwise it returns \fB1\fR and places the default value of \fIarg\fR |
---|
| 79 | into variable \fIvarname\fR. |
---|
| 80 | .TP |
---|
| 81 | \fBinfo exists \fIvarName\fR |
---|
| 82 | Returns \fB1\fR if the variable named \fIvarName\fR exists in the |
---|
| 83 | current context (either as a global or local variable) and has been |
---|
| 84 | defined by being given a value, returns \fB0\fR otherwise. |
---|
| 85 | .TP |
---|
| 86 | \fBinfo frame\fR ?\fInumber\fR? |
---|
| 87 | This command provides access to all frames on the stack, even those |
---|
| 88 | hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this |
---|
| 89 | command returns a number giving the frame level of the command. This |
---|
| 90 | is 1 if the command is invoked at top-level. If \fInumber\fR is |
---|
| 91 | specified, then the result is a dictionary containing the location |
---|
| 92 | information for the command at the \fInumber\fRed level on the stack. |
---|
| 93 | .RS |
---|
| 94 | .PP |
---|
| 95 | If \fInumber\fR is positive (> 0) then it selects a particular stack |
---|
| 96 | level (1 refers to the top-most active command, i.e., \fBinfo frame\fR |
---|
| 97 | itself, 2 to the command it was called from, and so on); otherwise it |
---|
| 98 | gives a level relative to the current command (0 refers to the current |
---|
| 99 | command, i.e., \fBinfo frame\fR itself, -1 to its caller, and so on). |
---|
| 100 | .PP |
---|
| 101 | This is similar to how \fBinfo level\fR works, except that this |
---|
| 102 | subcommand reports all frames, like \fBsource\fRd scripts, |
---|
| 103 | \fBeval\fRs, \fBuplevel\fRs, etc. |
---|
| 104 | .PP |
---|
| 105 | Note that for nested commands, like |
---|
| 106 | .QW "foo [bar [x]]" , |
---|
| 107 | only |
---|
| 108 | .QW x |
---|
| 109 | will be seen by an \fBinfo frame\fR invoked within |
---|
| 110 | .QW x . |
---|
| 111 | This is the same as for \fBinfo level\fR and error stack traces. |
---|
| 112 | .PP |
---|
| 113 | The result dictionary may contain the keys listed below, with the |
---|
| 114 | specified meanings for their values: |
---|
| 115 | .TP |
---|
| 116 | \fBtype\fR |
---|
| 117 | This entry is always present and describes the nature of the location |
---|
| 118 | for the command. The recognized values are \fBsource\fR, \fBproc\fR, |
---|
| 119 | \fBeval\fR, and \fBprecompiled\fR. |
---|
| 120 | .RS |
---|
| 121 | .TP |
---|
| 122 | \fBsource\fR\0\0\0\0\0\0\0\0 |
---|
| 123 | means that the command is found in a script loaded by the \fBsource\fR |
---|
| 124 | command. |
---|
| 125 | .TP |
---|
| 126 | \fBproc\fR\0\0\0\0\0\0\0\0 |
---|
| 127 | means that the command is found in dynamically created procedure body. |
---|
| 128 | .TP |
---|
| 129 | \fBeval\fR\0\0\0\0\0\0\0\0 |
---|
| 130 | means that the command is executed by \fBeval\fR or \fBuplevel\fR. |
---|
| 131 | .TP |
---|
| 132 | \fBprecompiled\fR\0\0\0\0\0\0\0\0 |
---|
| 133 | means that the command is found in a precompiled script (loadable by |
---|
| 134 | the package \fBtbcload\fR), and no further information will be |
---|
| 135 | available. |
---|
| 136 | .RE |
---|
| 137 | .TP |
---|
| 138 | \fBline\fR |
---|
| 139 | This entry provides the number of the line the command is at inside of |
---|
| 140 | the script it is a part of. This information is not present for type |
---|
| 141 | \fBprecompiled\fR. For type \fBsource\fR this information is counted |
---|
| 142 | relative to the beginning of the file, whereas for the last two types |
---|
| 143 | the line is counted relative to the start of the script. |
---|
| 144 | .TP |
---|
| 145 | \fBfile\fR |
---|
| 146 | This entry is present only for type \fBsource\fR. It provides the |
---|
| 147 | normalized path of the file the command is in. |
---|
| 148 | .TP |
---|
| 149 | \fBcmd\fR |
---|
| 150 | This entry provides the string representation of the command. This is |
---|
| 151 | usually the unsubstituted form, however for commands which are a pure |
---|
| 152 | list executed by eval it is the substituted form as they have no other |
---|
| 153 | string representation. Care is taken that the pure-List property of |
---|
| 154 | the latter is not spoiled. |
---|
| 155 | .TP |
---|
| 156 | \fBproc\fR |
---|
| 157 | This entry is present only if the command is found in the body of a |
---|
| 158 | regular Tcl procedure. It then provides the name of that procedure. |
---|
| 159 | .TP |
---|
| 160 | \fBlambda\fR |
---|
| 161 | This entry is present only if the command is found in the body of an |
---|
| 162 | anonymous Tcl procedure, i.e. a lambda. It then provides the entire |
---|
| 163 | definition of the lambda in question. |
---|
| 164 | .TP |
---|
| 165 | \fBlevel\fR |
---|
| 166 | This entry is present only if the queried frame has a corresponding |
---|
| 167 | frame returned by \fBinfo level\fR. It provides the index of this |
---|
| 168 | frame, relative to the current level (0 and negative numbers). |
---|
| 169 | .PP |
---|
| 170 | A thing of note is that for procedures statically defined in files the |
---|
| 171 | locations of commands in their bodies will be reported with type |
---|
| 172 | \fBsource\fR and absolute line numbers, and not as type |
---|
| 173 | \fBproc\fR. The same is true for procedures nested in statically |
---|
| 174 | defined procedures, and literal eval scripts in files or statically |
---|
| 175 | defined procedures. |
---|
| 176 | .PP |
---|
| 177 | In contrast, a procedure definition or \fBeval\fR within a dynamically |
---|
| 178 | \fBeval\fRuated environment count linenumbers relative to the start of |
---|
| 179 | their script, even if they would be able to count relative to the |
---|
| 180 | start of the outer dynamic script. That type of number usually makes |
---|
| 181 | more sense. |
---|
| 182 | .PP |
---|
| 183 | A different way of describing this behaviour is that file based |
---|
| 184 | locations are tracked as deeply as possible, and where this is not |
---|
| 185 | possible the lines are counted based on the smallest possible |
---|
| 186 | \fBeval\fR or procedure body, as that scope is usually easier to find |
---|
| 187 | than any dynamic outer scope. |
---|
| 188 | .PP |
---|
| 189 | The syntactic form \fB{*}\fR is handled like \fBeval\fR. I.e. if it |
---|
| 190 | is given a literal list argument the system tracks the linenumber |
---|
| 191 | within the list words as well, and otherwise all linenumbers are |
---|
| 192 | counted relative to the start of each word (smallest scope) |
---|
| 193 | .RE |
---|
| 194 | .TP |
---|
| 195 | \fBinfo functions \fR?\fIpattern\fR? |
---|
| 196 | If \fIpattern\fR is not specified, returns a list of all the math |
---|
| 197 | functions currently defined. |
---|
| 198 | If \fIpattern\fR is specified, only those functions whose name matches |
---|
| 199 | \fIpattern\fR are returned. Matching is determined using the same |
---|
| 200 | rules as for \fBstring match\fR. |
---|
| 201 | .TP |
---|
| 202 | \fBinfo globals \fR?\fIpattern\fR? |
---|
| 203 | If \fIpattern\fR is not specified, returns a list of all the names |
---|
| 204 | of currently-defined global variables. |
---|
| 205 | Global variables are variables in the global namespace. |
---|
| 206 | If \fIpattern\fR is specified, only those names matching \fIpattern\fR |
---|
| 207 | are returned. Matching is determined using the same rules as for |
---|
| 208 | \fBstring match\fR. |
---|
| 209 | .TP |
---|
| 210 | \fBinfo hostname\fR |
---|
| 211 | Returns the name of the computer on which this invocation is being |
---|
| 212 | executed. |
---|
| 213 | Note that this name is not guaranteed to be the fully qualified domain |
---|
| 214 | name of the host. Where machines have several different names (as is |
---|
| 215 | common on systems with both TCP/IP (DNS) and NetBIOS-based networking |
---|
| 216 | installed,) it is the name that is suitable for TCP/IP networking that |
---|
| 217 | is returned. |
---|
| 218 | .TP |
---|
| 219 | \fBinfo level\fR ?\fInumber\fR? |
---|
| 220 | If \fInumber\fR is not specified, this command returns a number |
---|
| 221 | giving the stack level of the invoking procedure, or 0 if the |
---|
| 222 | command is invoked at top-level. If \fInumber\fR is specified, |
---|
| 223 | then the result is a list consisting of the name and arguments for the |
---|
| 224 | procedure call at level \fInumber\fR on the stack. If \fInumber\fR |
---|
| 225 | is positive then it selects a particular stack level (1 refers |
---|
| 226 | to the top-most active procedure, 2 to the procedure it called, and |
---|
| 227 | so on); otherwise it gives a level relative to the current level |
---|
| 228 | (0 refers to the current procedure, -1 to its caller, and so on). |
---|
| 229 | See the \fBuplevel\fR command for more information on what stack |
---|
| 230 | levels mean. |
---|
| 231 | .TP |
---|
| 232 | \fBinfo library\fR |
---|
| 233 | Returns the name of the library directory in which standard Tcl |
---|
| 234 | scripts are stored. |
---|
| 235 | This is actually the value of the \fBtcl_library\fR |
---|
| 236 | variable and may be changed by setting \fBtcl_library\fR. |
---|
| 237 | See the \fBtclvars\fR manual entry for more information. |
---|
| 238 | .TP |
---|
| 239 | \fBinfo loaded \fR?\fIinterp\fR? |
---|
| 240 | Returns a list describing all of the packages that have been loaded into |
---|
| 241 | \fIinterp\fR with the \fBload\fR command. |
---|
| 242 | Each list element is a sub-list with two elements consisting of the |
---|
| 243 | name of the file from which the package was loaded and the name of |
---|
| 244 | the package. |
---|
| 245 | For statically-loaded packages the file name will be an empty string. |
---|
| 246 | If \fIinterp\fR is omitted then information is returned for all packages |
---|
| 247 | loaded in any interpreter in the process. |
---|
| 248 | To get a list of just the packages in the current interpreter, specify |
---|
| 249 | an empty string for the \fIinterp\fR argument. |
---|
| 250 | .TP |
---|
| 251 | \fBinfo locals \fR?\fIpattern\fR? |
---|
| 252 | If \fIpattern\fR is not specified, returns a list of all the names |
---|
| 253 | of currently-defined local variables, including arguments to the |
---|
| 254 | current procedure, if any. |
---|
| 255 | Variables defined with the \fBglobal\fR, \fBupvar\fR and |
---|
| 256 | \fBvariable\fR commands will not be returned. |
---|
| 257 | If \fIpattern\fR is specified, only those names matching \fIpattern\fR |
---|
| 258 | are returned. Matching is determined using the same rules as for |
---|
| 259 | \fBstring match\fR. |
---|
| 260 | .TP |
---|
| 261 | \fBinfo nameofexecutable\fR |
---|
| 262 | Returns the full path name of the binary file from which the application |
---|
| 263 | was invoked. If Tcl was unable to identify the file, then an empty |
---|
| 264 | string is returned. |
---|
| 265 | .TP |
---|
| 266 | \fBinfo patchlevel\fR |
---|
| 267 | Returns the value of the global variable \fBtcl_patchLevel\fR; see |
---|
| 268 | the \fBtclvars\fR manual entry for more information. |
---|
| 269 | .TP |
---|
| 270 | \fBinfo procs \fR?\fIpattern\fR? |
---|
| 271 | If \fIpattern\fR is not specified, returns a list of all the |
---|
| 272 | names of Tcl command procedures in the current namespace. |
---|
| 273 | If \fIpattern\fR is specified, |
---|
| 274 | only those procedure names in the current namespace |
---|
| 275 | matching \fIpattern\fR are returned. |
---|
| 276 | Matching is determined using the same rules as for |
---|
| 277 | \fBstring match\fR. |
---|
| 278 | If \fIpattern\fR contains any namespace separators, they are used to |
---|
| 279 | select a namespace relative to the current namespace (or relative to |
---|
| 280 | the global namespace if \fIpattern\fR starts with \fB::\fR) to match |
---|
| 281 | within; the matching pattern is taken to be the part after the last |
---|
| 282 | namespace separator. |
---|
| 283 | .TP |
---|
| 284 | \fBinfo script\fR ?\fIfilename\fR? |
---|
| 285 | If a Tcl script file is currently being evaluated (i.e. there is a |
---|
| 286 | call to \fBTcl_EvalFile\fR active or there is an active invocation |
---|
| 287 | of the \fBsource\fR command), then this command returns the name |
---|
| 288 | of the innermost file being processed. If \fIfilename\fR is specified, |
---|
| 289 | then the return value of this command will be modified for the |
---|
| 290 | duration of the active invocation to return that name. This is |
---|
| 291 | useful in virtual file system applications. |
---|
| 292 | Otherwise the command returns an empty string. |
---|
| 293 | .TP |
---|
| 294 | \fBinfo sharedlibextension\fR |
---|
| 295 | Returns the extension used on this platform for the names of files |
---|
| 296 | containing shared libraries (for example, \fB.so\fR under Solaris). |
---|
| 297 | If shared libraries are not supported on this platform then an empty |
---|
| 298 | string is returned. |
---|
| 299 | .TP |
---|
| 300 | \fBinfo tclversion\fR |
---|
| 301 | Returns the value of the global variable \fBtcl_version\fR; see |
---|
| 302 | the \fBtclvars\fR manual entry for more information. |
---|
| 303 | .TP |
---|
| 304 | \fBinfo vars\fR ?\fIpattern\fR? |
---|
| 305 | If \fIpattern\fR is not specified, |
---|
| 306 | returns a list of all the names of currently-visible variables. |
---|
| 307 | This includes locals and currently-visible globals. |
---|
| 308 | If \fIpattern\fR is specified, only those names matching \fIpattern\fR |
---|
| 309 | are returned. Matching is determined using the same rules as for |
---|
| 310 | \fBstring match\fR. |
---|
| 311 | \fIpattern\fR can be a qualified name like \fBFoo::option*\fR. |
---|
| 312 | That is, it may specify a particular namespace |
---|
| 313 | using a sequence of namespace names separated by double colons (\fB::\fR), |
---|
| 314 | and may have pattern matching special characters |
---|
| 315 | at the end to specify a set of variables in that namespace. |
---|
| 316 | If \fIpattern\fR is a qualified name, |
---|
| 317 | the resulting list of variable names |
---|
| 318 | has each matching namespace variable qualified with the name |
---|
| 319 | of its namespace. |
---|
| 320 | Note that a currently-visible variable may not yet |
---|
| 321 | .QW exist |
---|
| 322 | if it has not |
---|
| 323 | been set (e.g. a variable declared but not set by \fBvariable\fR). |
---|
| 324 | .SH EXAMPLE |
---|
| 325 | This command prints out a procedure suitable for saving in a Tcl |
---|
| 326 | script: |
---|
| 327 | .PP |
---|
| 328 | .CS |
---|
| 329 | proc printProc {procName} { |
---|
| 330 | set result [list proc $procName] |
---|
| 331 | set formals {} |
---|
| 332 | foreach var [\fBinfo args\fR $procName] { |
---|
| 333 | if {[\fBinfo default\fR $procName $var def]} { |
---|
| 334 | lappend formals [list $var $def] |
---|
| 335 | } else { |
---|
| 336 | # Still need the list-quoting because variable |
---|
| 337 | # names may properly contain spaces. |
---|
| 338 | lappend formals [list $var] |
---|
| 339 | } |
---|
| 340 | } |
---|
| 341 | puts [lappend result $formals [\fBinfo body\fR $procName]] |
---|
| 342 | } |
---|
| 343 | .CE |
---|
| 344 | .SH "SEE ALSO" |
---|
| 345 | global(n), proc(n) |
---|
| 346 | .SH KEYWORDS |
---|
| 347 | command, information, interpreter, level, namespace, procedure, variable |
---|
| 348 | .\" Local Variables: |
---|
| 349 | .\" mode: nroff |
---|
| 350 | .\" End: |
---|