diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2018-12-25 19:55:50 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2018-12-25 19:55:50 (GMT) |
commit | ff51550ee89b473c63df78de6b2a413f21105687 (patch) | |
tree | bcdca927ed2a7b05c647b9a6bfdfd4a7ca5c730e /tcl8.6/doc/tclvars.n | |
parent | 01cbf5b15ea760408c24288ccb5cf8e0af9aa299 (diff) | |
download | blt-ff51550ee89b473c63df78de6b2a413f21105687.zip blt-ff51550ee89b473c63df78de6b2a413f21105687.tar.gz blt-ff51550ee89b473c63df78de6b2a413f21105687.tar.bz2 |
update tcl/tk
Diffstat (limited to 'tcl8.6/doc/tclvars.n')
-rw-r--r-- | tcl8.6/doc/tclvars.n | 566 |
1 files changed, 0 insertions, 566 deletions
diff --git a/tcl8.6/doc/tclvars.n b/tcl8.6/doc/tclvars.n deleted file mode 100644 index adefe40..0000000 --- a/tcl8.6/doc/tclvars.n +++ /dev/null @@ -1,566 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH tclvars n 8.0 Tcl "Tcl Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -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 -.BE -.SH DESCRIPTION -.PP -The following global variables are created and managed automatically -by the Tcl library. Except where noted below, these variables should -normally be treated as read-only by application-specific code and by users. -.TP -\fBauto_path\fR -. -If set, then it must contain a valid Tcl list giving directories to -search during auto-load operations (including for package index -files when using the default \fBpackage unknown\fR handler). -This variable is initialized during startup to contain, in order: -the directories listed in the \fBTCLLIBPATH\fR environment variable, -the directory named by the \fBtcl_library\fR global variable, -the parent directory of \fBtcl_library\fR, -the directories listed in the \fBtcl_pkgPath\fR variable. -Additional locations to look for files and package indices should -normally be added to this variable using \fBlappend\fR. -.RS -.PP -Additional variables relating to package management exist. More -details are listed in the \fBVARIABLES\fR section of the \fBlibrary\fR -manual page. -.RE -.TP -\fBenv\fR -. -This variable is maintained by Tcl as an array -whose elements are the environment variables for the process. -Reading an element will return the value of the corresponding -environment variable. -Setting an element of the array will modify the corresponding -environment variable or create a new one if it does not already -exist. -Unsetting an element of \fBenv\fR will remove the corresponding -environment variable. -Changes to the \fBenv\fR array will affect the environment -passed to children by commands like \fBexec\fR. -If the entire \fBenv\fR array is unset then Tcl will stop -monitoring \fBenv\fR accesses and will not update environment -variables. -.RS -.PP -Under Windows, the environment variables PATH and COMSPEC in any -capitalization are converted automatically to upper case. For instance, the -PATH variable could be exported by the operating system as -.QW path , -.QW Path , -.QW PaTh , -etc., causing otherwise simple Tcl code to have to -support many special cases. All other environment variables inherited by -Tcl are left unmodified. Setting an env array variable to blank is the -same as unsetting it as this is the behavior of the underlying Windows OS. -It should be noted that relying on an existing and empty environment variable -will not work on Windows and is discouraged for cross-platform usage. -.PP -The following elements of \fBenv\fR are special to Tcl: -.TP -\fBenv(HOME)\fR -. -This environment variable, if set, gives the location of the directory -considered to be the current user's home directory, and to which a -call of \fBcd\fR without arguments or with just -.QW ~ -as an argument will change into. Most platforms set this correctly by -default; it does not normally need to be set by user code. -.TP -\fBenv(TCL_LIBRARY)\fR -. -If set, then it specifies the location of the directory containing -library scripts (the value of this variable will be -assigned to the \fBtcl_library\fR variable and therefore returned by -the command \fBinfo library\fR). If this variable is not set then -a default value is used. -.RS -.PP -Note that this environment variable should \fInot\fR normally be set. -.RE -.TP -\fBenv(TCLLIBPATH)\fR -. -If set, then it must contain a valid Tcl list giving directories to -search during auto-load operations. Directories must be specified in -Tcl format, using -.QW / -as the path separator, regardless of platform. -This variable is only used when initializing the \fBauto_path\fR variable. -.TP -\fBenv(TCL_TZ)\fR, \fBenv(TZ)\fR -. -These specify the default timezone used for parsing and formatting times and -dates in the \fBclock\fR command. On many platforms, the TZ environment -variable is set up by the operating system. -.TP -\fBenv(LC_ALL)\fR, \fBenv(LC_MESSAGES)\fR, \fBenv(LANG)\fR -. -These environment variables are used by the \fBmsgcat\fR package to -determine what locale to format messages using. -.TP -\fBenv(TCL_INTERP_DEBUG_FRAME)\fR -. -If existing, it has the same effect as running \fBinterp debug\fR -\fB{} -frame 1\fR -as the very first command of each new Tcl interpreter. -.RE -.TP -\fBerrorCode\fR -. -This variable holds the value of the \fB\-errorcode\fR return option -set by the most recent error that occurred in this interpreter. -This list value represents additional information about the error -in a form that is easy to process with programs. -The first element of the list identifies a general class of -errors, and determines the format of the rest of the list. -The following formats for \fB\-errorcode\fR return options -are used by the Tcl core; individual applications may define -additional formats. -.RS -.TP -\fBARITH\fI code msg\fR -. -This format is used when an arithmetic error occurs (e.g. an attempt -to divide zero by zero in the \fBexpr\fR command). -\fICode\fR identifies the precise error and \fImsg\fR provides a -human-readable description of the error. \fICode\fR will be either -DIVZERO (for an attempt to divide by zero), -DOMAIN (if an argument is outside the domain of a function, such as acos(\-3)), -IOVERFLOW (for integer overflow), -OVERFLOW (for a floating-point overflow), -or UNKNOWN (if the cause of the error cannot be determined). -.RS -.PP -Detection of these errors depends in part on the underlying hardware -and system libraries. -.RE -.TP -\fBCHILDKILLED\fI pid sigName msg\fR -. -This format is used when a child process has been killed because of -a signal. The \fIpid\fR element will be the process's identifier (in decimal). -The \fIsigName\fR element will be the symbolic name of the signal that caused -the process to terminate; it will be one of the names from the -include file signal.h, such as \fBSIGPIPE\fR. -The \fImsg\fR element will be a short human-readable message -describing the signal, such as -.QW "write on pipe with no readers" -for \fBSIGPIPE\fR. -.TP -\fBCHILDSTATUS\fI pid code\fR -. -This format is used when a child process has exited with a non-zero -exit status. The \fIpid\fR element will be the -process's identifier (in decimal) and the \fIcode\fR element will be the exit -code returned by the process (also in decimal). -.TP -\fBCHILDSUSP\fI pid sigName msg\fR -. -This format is used when a child process has been suspended because -of a signal. -The \fIpid\fR element will be the process's identifier, in decimal. -The \fIsigName\fR element will be the symbolic name of the signal that caused -the process to suspend; this will be one of the names from the -include file signal.h, such as \fBSIGTTIN\fR. -The \fImsg\fR element will be a short human-readable message -describing the signal, such as -.QW "background tty read" -for \fBSIGTTIN\fR. -.TP -\fBNONE\fR -. -This format is used for errors where no additional information is -available for an error besides the message returned with the -error. In these cases the \fB\-errorcode\fR return option -will consist of a list containing a single element whose -contents are \fBNONE\fR. -.TP -\fBPOSIX \fIerrName msg\fR -. -If the first element is \fBPOSIX\fR, then -the error occurred during a POSIX kernel call. -The \fIerrName\fR element will contain the symbolic name -of the error that occurred, such as \fBENOENT\fR; this will -be one of the values defined in the include file errno.h. -The \fImsg\fR element will be a human-readable -message corresponding to \fIerrName\fR, such as -.QW "no such file or directory" -for the \fBENOENT\fR case. -.TP -\fBTCL\fR ... -. -Indicates some sort of problem generated in relation to Tcl itself, e.g. a -failure to look up a channel or variable. -.PP -To set the \fB\-errorcode\fR return option, applications should use library -procedures such as \fBTcl_SetObjErrorCode\fR, \fBTcl_SetReturnOptions\fR, -and \fBTcl_PosixError\fR, or they may invoke the \fB\-errorcode\fR -option of the \fBreturn\fR command. -If none of these methods for setting the error code has been used, -the Tcl interpreter will reset the variable to \fBNONE\fR after -the next error. -.RE -.TP -\fBerrorInfo\fR -. -This variable holds the value of the \fB\-errorinfo\fR return option -set by the most recent error that occurred in this interpreter. -This string value will contain one or more lines -identifying the Tcl commands and procedures that were being executed -when the most recent error occurred. -Its contents take the form of a stack trace showing the various -nested Tcl commands that had been invoked at the time of the error. -.TP -\fBtcl_library\fR -. -This variable holds the name of a directory containing the -system library of Tcl scripts, such as those used for auto-loading. -The value of this variable is returned by the \fBinfo library\fR command. -See the \fBlibrary\fR manual entry for details of the facilities -provided by the Tcl script library. -Normally each application or package will have its own application-specific -script library in addition to the Tcl script library; -each application should set a global variable with a name like -\fB$\fIapp\fB_library\fR (where \fIapp\fR is the application's name) -to hold the network file name for that application's library directory. -The initial value of \fBtcl_library\fR is set when an interpreter -is created by searching several different directories until one is -found that contains an appropriate Tcl startup script. -If the \fBTCL_LIBRARY\fR environment variable exists, then -the directory it names is checked first. -If \fBTCL_LIBRARY\fR is not set or doesn't refer to an appropriate -directory, then Tcl checks several other directories based on a -compiled-in default location, the location of the binary containing -the application, and the current working directory. -.TP -\fBtcl_patchLevel\fR -. -When an interpreter is created Tcl initializes this variable to -hold a string giving the current patch level for Tcl, such as -\fB8.4.16\fR for Tcl 8.4 with the first sixteen official patches, or -\fB8.5b3\fR for the third beta release of Tcl 8.5. -The value of this variable is returned by the \fBinfo patchlevel\fR -command. -.TP -\fBtcl_pkgPath\fR -. -This variable holds a list of directories indicating where packages are -normally installed. It is not used on Windows. It typically contains -either one or two entries; if it contains two entries, the first is -normally a directory for platform-dependent packages (e.g., shared library -binaries) and the second is normally a directory for platform-independent -packages (e.g., script files). Typically a package is installed as a -subdirectory of one of the entries in the \fBtcl_pkgPath\fR -variable. The directories in the \fBtcl_pkgPath\fR variable are -included by default in the \fBauto_path\fR -variable, so they and their immediate subdirectories are automatically -searched for packages during \fBpackage require\fR commands. Note: -\fBtcl_pkgPath\fR is not intended to be modified by the application. Its -value is added to \fBauto_path\fR at startup; changes to \fBtcl_pkgPath\fR -are not reflected in \fBauto_path\fR. If you want Tcl to search additional -directories for packages you should add the names of those directories to -\fBauto_path\fR, not \fBtcl_pkgPath\fR. -.TP -\fBtcl_platform\fR -. -This is an associative array whose elements contain information about -the platform on which the application is running, such as the name of -the operating system, its current release number, and the machine's -instruction set. The elements listed below will always -be defined, but they may have empty strings as values if Tcl could not -retrieve any relevant information. In addition, extensions -and applications may add additional values to the array. The -predefined elements are: -.RS -.TP -\fBbyteOrder\fR -. -The native byte order of this machine: either \fBlittleEndian\fR or -\fBbigEndian\fR. -.TP -\fBdebug\fR -. -If this variable exists, then the interpreter was compiled with and linked -to a debug-enabled C run-time. This variable will only exist on Windows, -so extension writers can specify which package to load depending on the -C run-time library that is in use. This is not an indication that this core -contains symbols. -.TP -\fBengine\fR -. -The name of the Tcl language implementation. When the interpreter is first -created, this is always set to the string \fBTcl\fR. -.TP -\fBmachine\fR -. -The instruction set executed by this machine, such as -\fBintel\fR, \fBPPC\fR, \fB68k\fR, or \fBsun4m\fR. On UNIX machines, this -is the value returned by \fBuname -m\fR. -.TP -\fBos\fR -. -The name of the operating system running on this machine, -such as \fBWindows NT\fR or \fBSunOS\fR. -On UNIX machines, this is the value returned by \fBuname -s\fR. -.TP -\fBosVersion\fR -. -The version number for the operating system running on this machine. -On UNIX machines, this is the value returned by \fBuname -r\fR. -.TP -\fBpathSeparator\fR -.VS 8.6 -'\" Defined by TIP #315 -The character that should be used to \fBsplit\fR PATH-like environment -variables into their corresponding list of directory names. -.VE 8.6 -.TP -\fBplatform\fR -. -Either \fBwindows\fR, or \fBunix\fR. This identifies the -general operating environment of the machine. -.TP -\fBpointerSize\fR -. -This gives the size of the native-machine pointer in bytes (strictly, it -is same as the result of evaluating \fIsizeof(void*)\fR in C.) -.TP -\fBthreaded\fR -. -If this variable exists, then the interpreter -was compiled with threads enabled. -.TP -\fBuser\fR -. -This identifies the -current user based on the login information available on the platform. -This value comes from the getuid() and getpwuid() system calls on Unix, -and the value from the GetUserName() system call on Windows. -.TP -\fBwordSize\fR -. -This gives the size of the native-machine word in bytes (strictly, it -is same as the result of evaluating \fIsizeof(long)\fR in C.) -.RE -.TP -\fBtcl_precision\fR -. -This variable controls the number of digits to generate -when converting floating-point values to strings. It defaults -to 0. \fIApplications should not change this value;\fR it is -provided for compatibility with legacy code. -.PP -.RS -The default value of 0 is special, meaning that Tcl should -convert numbers using as few digits as possible while still -distinguishing any floating point number from its nearest -neighbours. It differs from using an arbitrarily high value -for \fItcl_precision\fR in that an inexact number like \fI1.4\fR -will convert as \fI1.4\fR rather than \fI1.3999999999999999\fR -even though the latter is nearer to the exact value of the -binary number. -.RE -.PP -.RS -If \fBtcl_precision\fR is not zero, then when Tcl converts a floating -point number, it creates a decimal representation of at most -\fBtcl_precision\fR significant digits; the result may be shorter if -the shorter result represents the original number exactly. If no -result of at most \fBtcl_precision\fR digits is an exact representation -of the original number, the one that is closest to the original -number is chosen. -If the original number lies precisely between two equally accurate -decimal representations, then the one with an even value for the least -significant digit is chosen; for instance, if \fBtcl_precision\fR is 3, then -0.3125 will convert to 0.312, not 0.313, while 0.6875 will convert to -0.688, not 0.687. Any string of trailing zeroes that remains is trimmed. -.RE -.PP -.RS -a \fBtcl_precision\fR value of 17 digits is -.QW perfect -for IEEE floating-point in that it allows -double-precision values to be converted to strings and back to -binary with no loss of information. For this reason, you will often -see it as a value in legacy code that must run on Tcl versions before -8.5. It is no longer recommended; as noted above, a zero value is the -preferred method. -.RE -.PP -.RS -All interpreters in a thread share a single \fBtcl_precision\fR value: -changing it in one interpreter will affect all other interpreters as -well. Safe interpreters are not allowed to modify the -variable. -.RE -.PP -.RS -Valid values for \fBtcl_precision\fR range from 0 to 17. -.RE -.TP -\fBtcl_rcFileName\fR -. -This variable is used during initialization to indicate the name of a -user-specific startup file. If it is set by application-specific -initialization, then the Tcl startup code will check for the existence -of this file and \fBsource\fR it if it exists. For example, for \fBwish\fR -the variable is set to \fB~/.wishrc\fR for Unix and \fB~/wishrc.tcl\fR -for Windows. -.TP -\fBtcl_traceCompile\fR -. -The value of this variable can be set to control -how much tracing information -is displayed during bytecode compilation. -By default, \fBtcl_traceCompile\fR is zero and no information is displayed. -Setting \fBtcl_traceCompile\fR to 1 generates a one-line summary in \fBstdout\fR -whenever a procedure or top-level command is compiled. -Setting it to 2 generates a detailed listing in \fBstdout\fR of the -bytecode instructions emitted during every compilation. -This variable is useful in -tracking down suspected problems with the Tcl compiler. -.PP -.RS -This variable and functionality only exist if -\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation. -.RE -.TP -\fBtcl_traceExec\fR -. -The value of this variable can be set to control -how much tracing information -is displayed during bytecode execution. -By default, \fBtcl_traceExec\fR is zero and no information is displayed. -Setting \fBtcl_traceExec\fR to 1 generates a one-line trace in \fBstdout\fR -on each call to a Tcl procedure. -Setting it to 2 generates a line of output -whenever any Tcl command is invoked -that contains the name of the command and its arguments. -Setting it to 3 produces a detailed trace showing the result of -executing each bytecode instruction. -Note that when \fBtcl_traceExec\fR is 2 or 3, -commands such as \fBset\fR and \fBincr\fR -that have been entirely replaced by a sequence -of bytecode instructions are not shown. -Setting this variable is useful in -tracking down suspected problems with the bytecode compiler -and interpreter. -.PP -.RS -This variable and functionality only exist if -\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation. -.RE -.TP -\fBtcl_wordchars\fR -. -The value of this variable is a regular expression that can be set to -control what are considered -.QW word -characters, for instances like -selecting a word by double-clicking in text in Tk. It is platform -dependent. On Windows, it defaults to \fB\eS\fR, meaning anything -but a Unicode space character. Otherwise it defaults to \fB\ew\fR, -which is any Unicode word character (number, letter, or underscore). -.TP -\fBtcl_nonwordchars\fR -. -The value of this variable is a regular expression that can be set to -control what are considered -.QW non-word -characters, for instances like -selecting a word by double-clicking in text in Tk. It is platform -dependent. On Windows, it defaults to \fB\es\fR, meaning any Unicode space -character. Otherwise it defaults to \fB\eW\fR, which is anything but a -Unicode word character (number, letter, or underscore). -.TP -\fBtcl_version\fR -. -When an interpreter is created Tcl initializes this variable to -hold the version number for this version of Tcl in the form \fIx.y\fR. -Changes to \fIx\fR represent major changes with probable -incompatibilities and changes to \fIy\fR represent small enhancements and -bug fixes that retain backward compatibility. -The value of this variable is returned by the \fBinfo tclversion\fR -command. -.SH "OTHER GLOBAL VARIABLES" -.PP -The following variables are only guaranteed to exist in \fBtclsh\fR -and \fBwish\fR executables; the Tcl library does not define them -itself but many Tcl environments do. -.TP 6 -\fBargc\fR -. -The number of arguments to \fBtclsh\fR or \fBwish\fR. -.TP 6 -\fBargv\fR -. -Tcl list of arguments to \fBtclsh\fR or \fBwish\fR. -.TP 6 -\fBargv0\fR -. -The script that \fBtclsh\fR or \fBwish\fR started executing (if it was -specified) or otherwise the name by which \fBtclsh\fR or \fBwish\fR -was invoked. -.TP 6 -\fBtcl_interactive\fR -. -Contains 1 if \fBtclsh\fR or \fBwish\fR is running interactively (no -script was specified and standard input is a terminal-like device), 0 -otherwise. -.SH EXAMPLES -.PP -To add a directory to the collection of locations searched by -\fBpackage require\fR, e.g., because of some application-specific -packages that are used, the \fBauto_path\fR variable needs to be -updated: -.PP -.CS -lappend ::\fBauto_path\fR [file join [pwd] "theLibDir"] -.CE -.PP -A simple though not very robust way to handle command line arguments -of the form -.QW "\-foo 1 \-bar 2" -is to load them into an array having first loaded in the default settings: -.CS -array set arguments {-foo 0 -bar 0 -grill 0} -array set arguments $::\fBargv\fR -puts "foo is $arguments(-foo)" -puts "bar is $arguments(-bar)" -puts "grill is $arguments(-grill)" -.CE -.PP -The \fBargv0\fR global variable can be used (in conjunction with the -\fBinfo script\fR command) to determine whether the current script is -being executed as the main script or loaded as a library. This is -useful because it allows a single script to be used as both a library -and a demonstration of that library: -.PP -.CS -if {$::\fBargv0\fR eq [info script]} { - # running as: tclsh example.tcl -} else { - package provide Example 1.0 -} -.CE -.SH "SEE ALSO" -eval(n), library(n), tclsh(1), tkvars(n), wish(1) -.SH KEYWORDS -arithmetic, bytecode, compiler, error, environment, POSIX, precision, -subprocess, user, variables -'\" Local Variables: -'\" mode: nroff -'\" End: |