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: |
---|