OSDN Git Service

Please enter the commit message for your changes. Lines starting
[eos/hostdependX86LINUX64.git] / util / X86LINUX64 / man / mann / tcl_traceCompile.n
1 '\"
2 '\" Copyright (c) 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 tclvars n 8.0 Tcl "Tcl Built-In Commands"
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 '\" Note:  do not modify the .SH NAME line immediately below!
278 .SH NAME
279 argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_precision, tcl_rcFileName, tcl_traceCompile, tcl_traceExec, tcl_wordchars, tcl_version \- Variables used by Tcl
280 .BE
281 .SH DESCRIPTION
282 .PP
283 The following global variables are created and managed automatically
284 by the Tcl library.  Except where noted below, these variables should
285 normally be treated as read-only by application-specific code and by users.
286 .TP
287 \fBauto_path\fR
288 .
289 If set, then it must contain a valid Tcl list giving directories to
290 search during auto-load operations (including for package index
291 files when using the default \fBpackage unknown\fR handler).
292 This variable is initialized during startup to contain, in order:
293 the directories listed in the \fBTCLLIBPATH\fR environment variable,
294 the directory named by the \fBtcl_library\fR global variable,
295 the parent directory of \fBtcl_library\fR,
296 the directories listed in the \fBtcl_pkgPath\fR variable.
297 Additional locations to look for files and package indices should
298 normally be added to this variable using \fBlappend\fR.
299 .RS
300 .PP
301 Additional variables relating to package management exist. More
302 details are listed in the \fBVARIABLES\fR section of the \fBlibrary\fR
303 manual page.
304 .RE
305 .TP
306 \fBenv\fR
307 .
308 This variable is maintained by Tcl as an array
309 whose elements are the environment variables for the process.
310 Reading an element will return the value of the corresponding
311 environment variable.
312 Setting an element of the array will modify the corresponding
313 environment variable or create a new one if it does not already
314 exist.
315 Unsetting an element of \fBenv\fR will remove the corresponding
316 environment variable.
317 Changes to the \fBenv\fR array will affect the environment
318 passed to children by commands like \fBexec\fR.
319 If the entire \fBenv\fR array is unset then Tcl will stop
320 monitoring \fBenv\fR accesses and will not update environment
321 variables.
322 .RS
323 .PP
324 Under Windows, the environment variables PATH and COMSPEC in any
325 capitalization are converted automatically to upper case.  For instance, the
326 PATH variable could be exported by the operating system as
327 .QW path ,
328 .QW Path ,
329 .QW PaTh ,
330 etc., causing otherwise simple Tcl code to have to
331 support many special cases.  All other environment variables inherited by
332 Tcl are left unmodified.  Setting an env array variable to blank is the
333 same as unsetting it as this is the behavior of the underlying Windows OS.
334 It should be noted that relying on an existing and empty environment variable
335 will not work on Windows and is discouraged for cross-platform usage.
336 .PP
337 The following elements of \fBenv\fR are special to Tcl:
338 .TP
339 \fBenv(HOME)\fR
340 .
341 This environment variable, if set, gives the location of the directory
342 considered to be the current user's home directory, and to which a
343 call of \fBcd\fR without arguments or with just
344 .QW ~
345 as an argument will change into. Most platforms set this correctly by
346 default; it does not normally need to be set by user code.
347 .TP
348 \fBenv(TCL_LIBRARY)\fR
349 .
350 If set, then it specifies the location of the directory containing
351 library scripts (the value of this variable will be
352 assigned to the \fBtcl_library\fR variable and therefore returned by
353 the command \fBinfo library\fR).  If this variable is not set then
354 a default value is used.
355 .RS
356 .PP
357 Note that this environment variable should \fInot\fR normally be set.
358 .RE
359 .TP
360 \fBenv(TCLLIBPATH)\fR
361 .
362 If set, then it must contain a valid Tcl list giving directories to
363 search during auto-load operations.  Directories must be specified in 
364 Tcl format, using
365 .QW /
366 as the path separator, regardless of platform.
367 This variable is only used when initializing the \fBauto_path\fR variable.
368 .TP
369 \fBenv(TCL_TZ)\fR, \fBenv(TZ)\fR
370 .
371 These specify the default timezone used for parsing and formatting times and
372 dates in the \fBclock\fR command. On many platforms, the TZ environment
373 variable is set up by the operating system.
374 .TP
375 \fBenv(LC_ALL)\fR, \fBenv(LC_MESSAGES)\fR, \fBenv(LANG)\fR
376 .
377 These environment variables are used by the \fBmsgcat\fR package to
378 determine what locale to format messages using.
379 .TP
380 \fBenv(TCL_INTERP_DEBUG_FRAME)\fR
381 .
382 If existing, it has the same effect as running \fBinterp debug\fR
383 \fB{} -frame 1\fR
384 as the very first command of each new Tcl interpreter.
385 .RE
386 .TP
387 \fBerrorCode\fR
388 .
389 This variable holds the value of the \fB\-errorcode\fR return option
390 set by the most recent error that occurred in this interpreter.
391 This list value represents additional information about the error
392 in a form that is easy to process with programs.
393 The first element of the list identifies a general class of
394 errors, and determines the format of the rest of the list.
395 The following formats for \fB\-errorcode\fR return options
396 are used by the Tcl core; individual applications may define
397 additional formats.
398 .RS
399 .TP
400 \fBARITH\fI code msg\fR
401 .
402 This format is used when an arithmetic error occurs (e.g. an attempt
403 to divide zero by zero in the \fBexpr\fR command).
404 \fICode\fR identifies the precise error and \fImsg\fR provides a
405 human-readable description of the error.  \fICode\fR will be either
406 DIVZERO (for an attempt to divide by zero),
407 DOMAIN (if an argument is outside the domain of a function, such as acos(\-3)),
408 IOVERFLOW (for integer overflow),
409 OVERFLOW (for a floating-point overflow),
410 or UNKNOWN (if the cause of the error cannot be determined).
411 .RS
412 .PP
413 Detection of these errors depends in part on the underlying hardware
414 and system libraries.
415 .RE
416 .TP
417 \fBCHILDKILLED\fI pid sigName msg\fR
418 .
419 This format is used when a child process has been killed because of
420 a signal.  The \fIpid\fR element will be the process's identifier (in decimal).
421 The \fIsigName\fR element will be the symbolic name of the signal that caused
422 the process to terminate; it will be one of the names from the
423 include file signal.h, such as \fBSIGPIPE\fR.
424 The \fImsg\fR element will be a short human-readable message
425 describing the signal, such as
426 .QW "write on pipe with no readers"
427 for \fBSIGPIPE\fR.
428 .TP
429 \fBCHILDSTATUS\fI pid code\fR
430 .
431 This format is used when a child process has exited with a non-zero
432 exit status.  The \fIpid\fR element will be the
433 process's identifier (in decimal) and the \fIcode\fR element will be the exit
434 code returned by the process (also in decimal).
435 .TP
436 \fBCHILDSUSP\fI pid sigName msg\fR
437 .
438 This format is used when a child process has been suspended because
439 of a signal.
440 The \fIpid\fR element will be the process's identifier, in decimal.
441 The \fIsigName\fR element will be the symbolic name of the signal that caused
442 the process to suspend; this will be one of the names from the
443 include file signal.h, such as \fBSIGTTIN\fR.
444 The \fImsg\fR element will be a short human-readable message
445 describing the signal, such as
446 .QW "background tty read"
447 for \fBSIGTTIN\fR.
448 .TP
449 \fBNONE\fR
450 .
451 This format is used for errors where no additional information is
452 available for an error besides the message returned with the
453 error.  In these cases the \fB\-errorcode\fR return option
454 will consist of a list containing a single element whose
455 contents are \fBNONE\fR.
456 .TP
457 \fBPOSIX \fIerrName msg\fR
458 .
459 If the first element is \fBPOSIX\fR, then
460 the error occurred during a POSIX kernel call.
461 The \fIerrName\fR element will contain the symbolic name
462 of the error that occurred, such as \fBENOENT\fR; this will
463 be one of the values defined in the include file errno.h.
464 The \fImsg\fR element will be a human-readable
465 message corresponding to \fIerrName\fR, such as
466 .QW "no such file or directory"
467 for the \fBENOENT\fR case.
468 .TP
469 \fBTCL\fR ...
470 .
471 Indicates some sort of problem generated in relation to Tcl itself, e.g. a
472 failure to look up a channel or variable.
473 .PP
474 To set the \fB\-errorcode\fR return option, applications should use library
475 procedures such as \fBTcl_SetObjErrorCode\fR, \fBTcl_SetReturnOptions\fR,
476 and \fBTcl_PosixError\fR, or they may invoke the \fB\-errorcode\fR
477 option of the \fBreturn\fR command.
478 If none of these methods for setting the error code has been used,
479 the Tcl interpreter will reset the variable to \fBNONE\fR after
480 the next error.
481 .RE
482 .TP
483 \fBerrorInfo\fR
484 .
485 This variable holds the value of the \fB\-errorinfo\fR return option
486 set by the most recent error that occurred in this interpreter.
487 This string value will contain one or more lines
488 identifying the Tcl commands and procedures that were being executed
489 when the most recent error occurred.
490 Its contents take the form of a stack trace showing the various
491 nested Tcl commands that had been invoked at the time of the error.
492 .TP
493 \fBtcl_library\fR
494 .
495 This variable holds the name of a directory containing the
496 system library of Tcl scripts, such as those used for auto-loading.
497 The value of this variable is returned by the \fBinfo library\fR command.
498 See the \fBlibrary\fR manual entry for details of the facilities 
499 provided by the Tcl script library.
500 Normally each application or package will have its own application-specific
501 script library in addition to the Tcl script library;
502 each application should set a global variable with a name like
503 \fB$\fIapp\fB_library\fR (where \fIapp\fR is the application's name)
504 to hold the network file name for that application's library directory.
505 The initial value of \fBtcl_library\fR is set when an interpreter
506 is created by searching several different directories until one is
507 found that contains an appropriate Tcl startup script.
508 If the \fBTCL_LIBRARY\fR environment variable exists, then
509 the directory it names is checked first.
510 If \fBTCL_LIBRARY\fR is not set or doesn't refer to an appropriate
511 directory, then Tcl checks several other directories based on a
512 compiled-in default location, the location of the binary containing
513 the application, and the current working directory.
514 .TP
515 \fBtcl_patchLevel\fR
516 .
517 When an interpreter is created Tcl initializes this variable to
518 hold a string giving the current patch level for Tcl, such as
519 \fB8.4.16\fR for Tcl 8.4 with the first sixteen official patches, or
520 \fB8.5b3\fR for the third beta release of Tcl 8.5.
521 The value of this variable is returned by the \fBinfo patchlevel\fR
522 command.
523 .TP
524 \fBtcl_pkgPath\fR
525 .
526 This variable holds a list of directories indicating where packages are
527 normally installed.  It is not used on Windows.  It typically contains
528 either one or two entries; if it contains two entries, the first is
529 normally a directory for platform-dependent packages (e.g., shared library
530 binaries) and the second is normally a directory for platform-independent
531 packages (e.g., script files). Typically a package is installed as a
532 subdirectory of one of the entries in the \fBtcl_pkgPath\fR
533 variable. The directories in the \fBtcl_pkgPath\fR variable are
534 included by default in the \fBauto_path\fR
535 variable, so they and their immediate subdirectories are automatically
536 searched for packages during \fBpackage require\fR commands.  Note:
537 \fBtcl_pkgPath\fR is not intended to be modified by the application.  Its
538 value is added to \fBauto_path\fR at startup; changes to \fBtcl_pkgPath\fR
539 are not reflected in \fBauto_path\fR.  If you want Tcl to search additional
540 directories for packages you should add the names of those directories to
541 \fBauto_path\fR, not \fBtcl_pkgPath\fR.
542 .TP
543 \fBtcl_platform\fR
544 .
545 This is an associative array whose elements contain information about
546 the platform on which the application is running, such as the name of
547 the operating system, its current release number, and the machine's
548 instruction set.  The elements listed below will always
549 be defined, but they may have empty strings as values if Tcl could not
550 retrieve any relevant information.  In addition, extensions
551 and applications may add additional values to the array.  The
552 predefined elements are:
553 .RS
554 .TP
555 \fBbyteOrder\fR
556 .
557 The native byte order of this machine: either \fBlittleEndian\fR or
558 \fBbigEndian\fR. 
559 .TP
560 \fBdebug\fR
561 .
562 If this variable exists, then the interpreter was compiled with and linked
563 to a debug-enabled C run-time.  This variable will only exist on Windows,
564 so extension writers can specify which package to load depending on the
565 C run-time library that is in use.  This is not an indication that this core
566 contains symbols.
567 .TP
568 \fBmachine\fR
569 .
570 The instruction set executed by this machine, such as
571 \fBintel\fR, \fBPPC\fR, \fB68k\fR, or \fBsun4m\fR.  On UNIX machines, this
572 is the value returned by \fBuname -m\fR.
573 .TP
574 \fBos\fR
575 .
576 The name of the operating system running on this machine,
577 such as \fBWindows NT\fR or \fBSunOS\fR.
578 On UNIX machines, this is the value returned by \fBuname -s\fR.
579 .TP
580 \fBosVersion\fR
581 .
582 The version number for the operating system running on this machine.
583 On UNIX machines, this is the value returned by \fBuname -r\fR.
584 .TP
585 \fBpathSeparator\fR
586 .VS 8.6
587 '\" Defined by TIP #315
588 The character that should be used to \fBsplit\fR PATH-like environment
589 variables into their corresponding list of directory names.
590 .VE 8.6
591 .TP
592 \fBplatform\fR
593 .
594 Either \fBwindows\fR, or \fBunix\fR.  This identifies the
595 general operating environment of the machine.
596 .TP
597 \fBpointerSize\fR
598 .
599 This gives the size of the native-machine pointer in bytes (strictly, it
600 is same as the result of evaluating \fIsizeof(void*)\fR in C.)
601 .TP
602 \fBthreaded\fR
603 .
604 If this variable exists, then the interpreter
605 was compiled with threads enabled.
606 .TP
607 \fBuser\fR
608 .
609 This identifies the
610 current user based on the login information available on the platform.
611 This value comes from the getuid() and getpwuid() system calls on Unix,
612 and the value from the GetUserName() system call on Windows.
613 .TP
614 \fBwordSize\fR
615 .
616 This gives the size of the native-machine word in bytes (strictly, it
617 is same as the result of evaluating \fIsizeof(long)\fR in C.)
618 .RE
619 .TP
620 \fBtcl_precision\fR
621 .
622 This variable controls the number of digits to generate
623 when converting floating-point values to strings.  It defaults
624 to 0.  \fIApplications should not change this value;\fR it is
625 provided for compatibility with legacy code.
626 .PP
627 .RS
628 The default value of 0 is special, meaning that Tcl should
629 convert numbers using as few digits as possible while still
630 distinguishing any floating point number from its nearest
631 neighbours.  It differs from using an arbitrarily high value
632 for \fItcl_precision\fR in that an inexact number like \fI1.4\fR
633 will convert as \fI1.4\fR rather than \fI1.3999999999999999\fR
634 even though the latter is nearer to the exact value of the
635 binary number.
636 .RE
637 .PP
638 .RS
639 If \fBtcl_precision\fR is not zero, then when Tcl converts a floating
640 point number, it creates a decimal representation of at most 
641 \fBtcl_precision\fR significant digits; the result may be shorter if
642 the shorter result represents the original number exactly. If no
643 result of at most \fBtcl_precision\fR digits is an exact representation
644 of the original number, the one that is closest to the original
645 number is chosen.
646 If the original number lies precisely between two equally accurate
647 decimal representations, then the one with an even value for the least
648 significant digit is chosen; for instance, if \fBtcl_precision\fR is 3, then
649 0.3125 will convert to 0.312, not 0.313, while 0.6875 will convert to
650 0.688, not 0.687. Any string of trailing zeroes that remains is trimmed.
651 .RE
652 .PP
653 .RS
654 a \fBtcl_precision\fR value of 17 digits is
655 .QW perfect
656 for IEEE floating-point in that it allows
657 double-precision values to be converted to strings and back to
658 binary with no loss of information. For this reason, you will often
659 see it as a value in legacy code that must run on Tcl versions before
660 8.5. It is no longer recommended; as noted above, a zero value is the
661 preferred method.
662 .RE
663 .PP
664 .RS
665 All interpreters in a thread share a single \fBtcl_precision\fR value:
666 changing it in one interpreter will affect all other interpreters as
667 well.  Safe interpreters are not allowed to modify the
668 variable.
669 .RE
670 .PP
671 .RS
672 Valid values for \fBtcl_precision\fR range from 0 to 17.
673 .RE
674 .TP
675 \fBtcl_rcFileName\fR
676 .
677 This variable is used during initialization to indicate the name of a
678 user-specific startup file.  If it is set by application-specific
679 initialization, then the Tcl startup code will check for the existence
680 of this file and \fBsource\fR it if it exists.  For example, for \fBwish\fR
681 the variable is set to \fB~/.wishrc\fR for Unix and \fB~/wishrc.tcl\fR
682 for Windows.
683 .TP
684 \fBtcl_traceCompile\fR
685 .
686 The value of this variable can be set to control
687 how much tracing information
688 is displayed during bytecode compilation.
689 By default, \fBtcl_traceCompile\fR is zero and no information is displayed.
690 Setting \fBtcl_traceCompile\fR to 1 generates a one-line summary in \fBstdout\fR
691 whenever a procedure or top-level command is compiled.
692 Setting it to 2 generates a detailed listing in \fBstdout\fR of the
693 bytecode instructions emitted during every compilation.
694 This variable is useful in
695 tracking down suspected problems with the Tcl compiler.
696 .PP
697 .RS
698 This variable and functionality only exist if
699 \fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation.
700 .RE
701 .TP
702 \fBtcl_traceExec\fR
703 .
704 The value of this variable can be set to control
705 how much tracing information
706 is displayed during bytecode execution.
707 By default, \fBtcl_traceExec\fR is zero and no information is displayed.
708 Setting \fBtcl_traceExec\fR to 1 generates a one-line trace in \fBstdout\fR
709 on each call to a Tcl procedure.
710 Setting it to 2 generates a line of output
711 whenever any Tcl command is invoked
712 that contains the name of the command and its arguments.
713 Setting it to 3 produces a detailed trace showing the result of
714 executing each bytecode instruction.
715 Note that when \fBtcl_traceExec\fR is 2 or 3,
716 commands such as \fBset\fR and \fBincr\fR
717 that have been entirely replaced by a sequence
718 of bytecode instructions are not shown.
719 Setting this variable is useful in
720 tracking down suspected problems with the bytecode compiler
721 and interpreter.
722 .PP
723 .RS
724 This variable and functionality only exist if
725 \fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation.
726 .RE
727 .TP
728 \fBtcl_wordchars\fR
729 .
730 The value of this variable is a regular expression that can be set to
731 control what are considered
732 .QW word
733 characters, for instances like
734 selecting a word by double-clicking in text in Tk.  It is platform
735 dependent.  On Windows, it defaults to \fB\eS\fR, meaning anything
736 but a Unicode space character.  Otherwise it defaults to \fB\ew\fR,
737 which is any Unicode word character (number, letter, or underscore).
738 .TP
739 \fBtcl_nonwordchars\fR
740 .
741 The value of this variable is a regular expression that can be set to
742 control what are considered
743 .QW non-word
744 characters, for instances like
745 selecting a word by double-clicking in text in Tk.  It is platform
746 dependent.  On Windows, it defaults to \fB\es\fR, meaning any Unicode space
747 character.  Otherwise it defaults to \fB\eW\fR, which is anything but a
748 Unicode word character (number, letter, or underscore).
749 .TP
750 \fBtcl_version\fR
751 .
752 When an interpreter is created Tcl initializes this variable to
753 hold the version number for this version of Tcl in the form \fIx.y\fR.
754 Changes to \fIx\fR represent major changes with probable
755 incompatibilities and changes to \fIy\fR represent small enhancements and
756 bug fixes that retain backward compatibility.
757 The value of this variable is returned by the \fBinfo tclversion\fR
758 command.
759 .SH "OTHER GLOBAL VARIABLES"
760 .PP
761 The following variables are only guaranteed to exist in \fBtclsh\fR
762 and \fBwish\fR executables; the Tcl library does not define them
763 itself but many Tcl environments do.
764 .TP 6
765 \fBargc\fR
766 .
767 The number of arguments to \fBtclsh\fR or \fBwish\fR.
768 .TP 6
769 \fBargv\fR
770 .
771 Tcl list of arguments to \fBtclsh\fR or \fBwish\fR.
772 .TP 6
773 \fBargv0\fR
774 .
775 The script that \fBtclsh\fR or \fBwish\fR started executing (if it was
776 specified) or otherwise the name by which \fBtclsh\fR or \fBwish\fR
777 was invoked.
778 .TP 6
779 \fBtcl_interactive\fR
780 .
781 Contains 1 if \fBtclsh\fR or \fBwish\fR is running interactively (no
782 script was specified and standard input is a terminal-like device), 0
783 otherwise.
784 .SH EXAMPLES
785 .PP
786 To add a directory to the collection of locations searched by
787 \fBpackage require\fR, e.g., because of some application-specific
788 packages that are used, the \fBauto_path\fR variable needs to be
789 updated:
790 .PP
791 .CS
792 lappend ::\fBauto_path\fR [file join [pwd] "theLibDir"]
793 .CE
794 .PP
795 A simple though not very robust way to handle command line arguments
796 of the form
797 .QW "\-foo 1 \-bar 2"
798 is to load them into an array having first loaded in the default settings:
799 .CS
800 array set arguments {-foo 0 -bar 0 -grill 0}
801 array set arguments $::\fBargv\fR
802 puts "foo is $arguments(-foo)"
803 puts "bar is $arguments(-bar)"
804 puts "grill is $arguments(-grill)"
805 .CE
806 .PP
807 The \fBargv0\fR global variable can be used (in conjunction with the
808 \fBinfo script\fR command) to determine whether the current script is
809 being executed as the main script or loaded as a library.  This is
810 useful because it allows a single script to be used as both a library
811 and a demonstration of that library:
812 .PP
813 .CS
814 if {$::\fBargv0\fR eq [info script]} {
815     # running as: tclsh example.tcl
816 } else {
817     package provide Example 1.0
818 }
819 .CE
820 .SH "SEE ALSO"
821 eval(n), library(n), tclsh(1), tkvars(n), wish(1)
822 .SH KEYWORDS
823 arithmetic, bytecode, compiler, error, environment, POSIX, precision,
824 subprocess, user, variables
825 '\" Local Variables:
826 '\" mode: nroff
827 '\" End: