TclX
TclX(TCL) TclX(TCL)
NAME
TclX - Extended Tcl: Extended command set for Tcl
INTRODUCTION
This man page contains the documentation for all of the extensions that
are added to Tcl 8.0 by Extended Tcl (TclX 8.0.0). TclX extends Tcl's
capabilities by adding new commands to it, without changing the syntax
of standard Tcl. Extended Tcl is a superset of standard Tcl and is
built alongside the standard Tcl sources.
Extended Tcl was created by Karl Lehenbauer (karl@neosoft.com) and Mark
Diekhans (markd@grizzly.com) and is freely redistributable for any use
without license or fee.
Available over the Internet since 1989, Extended Tcl, also known as
TclX, not only adds capabilities to Tcl, but has also been the source
of many of the capabilities of the baseline Tcl release, including
arrays, files, sockets, file events, and date and time handling, among
others.
Extended Tcl has three basic functional areas: A set of new commands, a
Tcl shell (i.e. a Unix shell-style command line and interactive envi-
ronment), and a user-extensible library of useful Tcl procedures, any
of which can be automatically loaded on the first attempt to execute
it.
The command descriptions are separated into several sections:
o General Commands
o Debugging and Development Commands
o Unix Access Commands
o File Commands
o Network Programming Support
o File Scanning Commands
o Math Commands
o List Manipulation Commands
o Keyed Lists
o String and Character Manipulation Commands
o XPG/3 Message Catalog Commands
o Extended Tcl Shell
o Help Facility
o Tcl Loadable Libraries and Packages
GENERAL COMMANDS
A set of general, useful Tcl commands, includes a command to begin an
interactive session with Tcl, a facility for tracing execution, and a
looping command.
dirs This procedure lists the directories in the directory stack.
commandloop ?-async? ?-interactive on | off | tty? ?-prompt1 cmd?
?-prompt2 cmd? ?-endcommand cmd?
Create an interactive command loop reading commands from stdin
and writing results to stdout. Command loops are maybe either
be blocking or event oriented. This command is useful for Tcl
scripts that do not normally converse interactively with a user
through a Tcl command interpreter, but which sometimes want to
enter this mode, perhaps for debugging or user configuration.
The command loop terminates on EOF.
The following options are available:
-async A command handler will be associated with stdin. When
input is available on stdin, it will be read and accumu-
lated until a full command is available. That command
will then be evaluated. An event loop must be entered
for input to be read and processed.
-interactive on | off | tty
Enable or disable interactive command mode. In interac-
tive mode, commands are prompted for and the results of
comments are printed. The value maybe any boolean value
or tty. If tty is used, interactive mode is enabled if
stdin is associated with a terminal or terminal emulator.
The default is tty.
-prompt1 cmd
If specified, cmd is used is evaluate and its result
used for the main command prompt. If not specified, the
command in tcl_prompt1 is evaluated to output the prompt.
Note the difference in behavior, cmd results is used,
while tcl_prompt1 outputs. This is to allow for future
expansion to command loops that write to other than std-
out.
-prompt2 cmd
If specified, cmd is used is evaluate and its result used
for the secondary (continuation) command prompt. If not
specified, the command in tcl_prompt2 is evaluated to
output the prompt.
-endcommand cmd
If specified, cmd is evaluated when the command loop ter-
minates.
In interactive mode, the results of set commands with two
arguments are not printed.
If SIGINT is configured to generate a Tcl error, it can
be used to delete the current command being type without
aborting the program in progress.
echo ?str ...?
Writes zero or more strings to standard output, followed by a
newline.
infox option
Return information about Extended Tcl, or the current applica-
tion. The following infox command options are available:
version
Return the version number of Extended Tcl. The version
number for Extended Tcl is generated by combining the
base version of the standard Tcl code with another number
indicating the version of Extended Tcl being used.
patchlevel
Return the patchlevel for Extended Tcl.
have_fchown
Return 1 if the fchown system call is available. This
supports the -fileid option on the chown and chgrp com-
mands.
have_fchmod
Return 1 if the fchmod system call is available. This
supports the -fileid option on the chmod command.
have_flock
Return 1 if the flock command defined, 0 if it is not
available.
have_fsync
Return 1 if the fsync system call is available and the
sync command will sync individual files. 0 if it is not
available and the sync command will always sync all file
buffers.
have_ftruncate
Return 1 if the ftruncate or chsize system call is avail-
able. If it is, the ftruncate command -fileid option
maybe used.
have_msgcats
Return 1 if XPG message catalogs are available, 0 if they
are not. The catgets is designed to continue to function
without message catalogs, always returning the default
string.
have_posix_signals
Return 1 if Posix signals are available (block and
unblock options available for the signal command). 0 is
returned if Posix signals are not available.
have_signal_restart
Return 1 if restartable signals are available (-restart
option available for the signal command). 0 is returned
if restartable signals are not available.
have_truncate
Return 1 if the truncate system call is available. If it
is, the ftruncate command may truncate by file path.
have_waitpid
Return 1 if the waitpid system call is available and the
wait command has full functionality. 0 if the wait com-
mand has limited functionality.
appname
Return the symbolic application name of the current
application linked with the Extended Tcl library. The C
variable tclAppName must be set by the application to
return an application specific value for this variable.
applongname
Return a natural language name for the current applica-
tion. The C variable tclLongAppName must be set by the
application to return an application specific value for
this variable.
appversion
Return the version number for the current application.
The C variable tclAppVersion must be set by the applica-
tion to return an application-specific value for this
variable.
apppatchlevel
Return the patchlevel for the current application. The C
variable tclAppPatchlevel must be set by the application
to return an application-specific value for this vari-
able.
for_array_keys var array_name code
This procedure performs a foreach-style loop for each key in the
named array. The break and continue statements work as with
foreach.
for_recursive_glob var dirlist globlist code
This procedure performs a foreach-style loop over recursively
matched files. All directories in dirlist are recursively
searched (breadth-first), comparing each file found against the
file glob patterns in globlist. For each matched file, the
variable var is set to the file path and code is evaluated.
Symbolic links are not followed.
loop var first limit ?increment? body
Loop is a looping command, similar in behavior to the Tcl for
statement, except that the loop statement achieves substantially
higher performance and is easier to code when the beginning and
ending values of a loop are known, and the loop variable is to
be incremented by a known, fixed amount every time through the
loop.
The var argument is the name of a Tcl variable that will con-
tain the loop index. The loop index is set to the value speci-
fied by first. The Tcl interpreter is invoked upon body zero or
more times, where var is incremented by increment every time
through the loop, or by one if increment is not specified.
Increment can be negative in which case the loop will count
downwards.
When var reaches limit, the loop terminates without a subsequent
execution of body. For instance, if the original loop parame-
ters would cause loop to terminate, say first was one, limit was
zero and increment was not specified or was non-negative, body
is not executed at all and loop returns.
The first, limit and increment are integer expressions. They
are only evaluated once at the beginning of the loop.
If a continue command is invoked within body then any remaining
commands in the current execution of body are skipped, as in the
for command. If a break command is invoked within body then the
loop command will return immediately. Loop returns an empty
string.
popd This procedure pops the top directory entry from the directory
stack and make it the current directory.
pushd ?dir?
This procedure pushs the current directory onto the directory
stack and cd to the specified directory. If the directory is
not specified, then the current directory is pushed, but remains
unchanged.
recursive_glob dirlist globlist
This procedure returns a list of recursively matches files. All
directories in dirlist are recursively searched (breadth-first),
comparing each file found against the file glob patterns in
globlist. Symbolic links are not followed.
showproc ?procname ...?
This procedure lists the definition of the named procedures.
Loading them if it is not already loaded. If no procedure names
are supplied, the definitions of all currently loaded procedures
are returned.
try_eval code catch ?finally?
The try_eval command evaluates code in the current context.
If an error occurs during the evaluation and catch is not empty, then
catch is evaluated to handler the error. The result of the command,
containing the error message, will be stored in a global variable
errorResult. The global variables errorResult, errorInfo and errorCode
will be imported into the current scope, there is no need to execute a
global command. The result of the catch command becomes the result of
the try_eval command. If the error that caused the catch to be evalu-
ate is to be continued, the following command should be used:
error $errorResult $errorCode $errorInfo
If the finally argument is supplied and not empty, it is evaluated
after the evaluation of the code and the catch commands. If an error
occurs during the evaluation of the finally command, it becomes the
result of the try_eval command. Otherwise, the result of either code
or catch is preserved, as described above.
DEBUGGING AND DEVELOPMENT COMMANDS
This section contains information on commands and procedures that are
useful for developing and debugging Tcl scripts.
cmdtrace level | on ?noeval? ?notruncate? ?procs? ?fileid? ?command
cmd?
Print a trace statement for all commands executed at depth of
level or below (1 is the top level). If on is specified, all
commands at any level are traced. The following options are
available:
noeval Causes arguments to be printed unevaluated. If noeval is
specified, the arguments are printed before evaluation.
Otherwise, they are printed afterwards.
If the command line is longer than 60 characters, it is
truncated to 60 and a "..." is postpended to indicate
that there was more output than was displayed. If an
evaluated argument contains a space, the entire argument
will be enclosed inside of braces (`{}') to allow the
reader to visually separate the arguments from each
other.
notruncate
Disables the truncation of commands and evaluated argu-
ments.
procs Enables the tracing of procedure calls only. Commands
that aren't procedure calls (i.e. calls to commands that
are written in C, C++ or some object-compatible language)
are not traced if the procs option is specified. This
option is particularly useful for greatly reducing the
output of cmdtrace while debugging.
fileid This is a file id as returned by the open command. If
specified, then the trace output will be written to the
file rather than stdout. A stdio buffer flush is done
after every line is written so that the trace may be mon-
itored externally or provide useful information for
debugging problems that cause core dumps.
command cmd
Call the specified command cmd on when each command is
executed instead of tracing to a file. See the descrip-
tion of the functionally below. This option may not be
specified with a fileid.
The most common use of this command is to enable tracing to a
file during the development. If a failure occurs, a trace is
then available when needed. Command tracing will slow down the
execution of code, so it should be removed when code is
debugged. The following command will enable tracing to a file
for the remainder of the program:
cmdtrace on [open cmd.log w]
The command option causes a user specified trace command to be
called for each command executed. The command will have the
following arguments appended to it before evaluation:
command
A string containing the text of the command, before any
argument substitution.
argv A list of the final argument information that will be
passed to the command after command, variable, and
backslash substitution.
evalLevel
The Tcl_Eval call level.
procLevel
The procedure call level.
The command should be constructed in such a manner that it will
work if additional arguments are added in the future. It is
suggested that the command be a proc with the final argument
being args.
Tracing will be turned off while the command is being executed.
The values of the errorInfo and errorCode variables will be
saved and restored on return from the command. It is the com-
mand's responsibility to preserve all other state.
If an error occurs during the execution of command, an error
message is dumped to stderr and the tracing is disabled. The
underlying mechanism that this functionality is built on does
not support returning an error to the interpreter.
cmdtrace off
Turn off all tracing.
cmdtrace depth
Returns the current maximum trace level, or zero if trace is
disabled.
edprocs ?proc...?
This procedure writes the named procedures, or all currently
defined procedures, to a temporary file, then calls an editor on
it (as specified by the EDITOR environment variable, or vi if
none is specified), then sources the file back in if it was
changed.
profile ?-commands? ?-eval? on
profile off arrayVar
This command is used to collect a performance profile of a Tcl
script. It collects data at the Tcl procedure level. The number
of calls to a procedure, and the amount of real and CPU time is
collected. Time is also collected for the global context. The
procedure data is collected by bucketing it based on the proce-
dure call stack, this allows determination of how much time is
spent in a particular procedure in each of it's calling con-
texts.
The on option enables profile data collection. If the -commands
option is specified, data on all commands within a procedure is
collected as well a procedures. Multiple occurrences of a com-
mand within a procedure are not distinguished, but this data may
still be useful for analysis.
The off option turns off profiling and moves the data collected
to the array arrayVar. The array is address by a list contain-
ing the procedure call stack. Element zero is the top of the
stack, the procedure that the data is for. The data in each
entry is a list consisting of the procedure call count and the
real time and CPU time in milliseconds spent in the procedure
(but not any procedures it calls). The list is in the form
{count real cpu}.
Normally, the variable scope stack is used in reporting where
time is spent. Thus upleveled code is reported in the context
that it was executed in, not the context that the uplevel was
called in. If the -eval option is specified, the procedure
evaluation (call) stack is used instead of the procedure scope
stack. Upleveled code is reported in the context of the
procedure that did the uplevel.
A Tcl procedure profrep is supplied for reducing the data and
producing a report.
On Windows 95/NT, profile command only reports elasped real
time, CPU time is not available and is reported as zero.
profrep profDataVar sortKey ?outFile? ?userTitle?
This procedure generates a report from data collect from the
profile command. ProfDataVar is the name of the array contain-
ing the data returned by the profile command. SortKey indicates
which data value to sort by. It should be one of "calls", "cpu"
or "real". OutFile is the name of file to write the report to.
If omitted, stdout is assumed. UserTitle is an optional title
line to add to output.
Listed with indentation below each procedure or command is the
procedure call stack. The first indented line being the proce-
dure that invoked the reported procedure or command. The next
line is the procedure that invoked the procedure above it, and
so on. If no indented procedures are shown, the procedure or
command was called from the global context. Time actually spent
in the global context is listed on a line labeled <global>.
Upleveled code is reported in the context that it was executed
in, not the context that the uplevel was called in.
saveprocs fileName ?proc...?
This procedure saves the definition of the named procedure, or
all currently defined procedures if none is specified, to the
named file.
UNIX ACCESS COMMANDS
These commands provide access to many basic Unix facilities, including
process handling, date and time processing, signal handling and the
executing commands via the shell.
alarm seconds
Instructs the system to send a SIGALRM signal in the specified
number of seconds. This is a floating point number, so frac-
tions of a section may be specified. If seconds is 0.0, any
previous alarm request is canceled. Only one alarm at a time
may be active; the command returns the number of seconds left in
the previous alarm. On systems without the setitimer system
call, seconds is rounded up to an integer number of seconds.
The alarm command is not available on Windows 95/NT.
execl ?-argv0 argv0? prog ?arglist?
Do an execl, replacing the current program (either Extended Tcl
or an application with Extended Tcl embedded into it) with prog
and passing the arguments in the list arglist.
The -argv0 options specifies that argv0 is to be passed to the
program as argv [0] rather than prog.
Note: If you are using execl in a Tk application and it fails,
you may not do anything that accesses the X server or you will
receive a BadWindow error from the X server. This includes exe-
cuting the Tk version of the exit command. We suggest using the
following command to abort Tk applications after an execl fail-
ure:
kill [id process]
On Windows 95/NT, where the fork command is not available, execl
starts a new process and returns the process id.
chroot dirname
Change root directory to dirname, by invoking the POSIX
chroot(2) system call. This command only succeeds if running as
root.
fork Fork the current Tcl process. Fork returns zero to the child
process and the process number of the child to the parent pro-
cess. If the fork fails, a Tcl error is generated.
If an execl is not going to be performed before the child pro-
cess does output, or if a close and dup sequence is going to be
performed on stdout or stderr, then a flush should be issued
against stdout, stderr and any other open output file before
doing the fork. Otherwise characters from the parent process
pending in the buffers will be output by both the parent and
child processes.
Note: If you are forking in a Tk based apllication you must
execl before doing any window operations in the child or you
will receive a BadWindow error from the X server.
The fork command is not available on Windows 95/NT.
id options
This command provides a means of getting, setting and converting
user, group and process ids. The id command has the following
options:
id user ?name?
id userid ?uid?
Set the real and effective user ID to name or uid, if the
name (or uid) is valid and permissions allow it. If the
name (or uid) is not specified, the current name (or uid)
is returned.
id convert userid uid
id convert user name
Convert a user ID number to a user name, or vice versa.
id group ?name?
id groupid ?gid?
Set the real and effective group ID to name or gid, if
the name (or gid) is valid and permissions allow it. If
the group name (or gid) is not specified, the current
group name (or gid) is returned.
id groups
id groupids
Return the current group access list of the process. The
option groups returns group names and groupids returns id
numbers.
id convert groupid gid
id convert group name
Convert a group ID number to a group name, or vice versa.
id effective user
id effective userid
Return the effective user name, or effective user ID num-
ber, respectively.
id effective group
id effective groupid
Return the effective group name, or effective group ID
number, respectively.
id effective groupids
Return all of the groupids the user is a member of.
id host
Return the hostname of the system the program is running
on.
id process
Return the process ID of the current process.
id process parent
Return the process ID of the parent of the current pro-
cess.
id process group
Return the process group ID of the current process.
id process group set
Set the process group ID of the current process to its
process ID.
id host
Returns the standard host name of the machine the process
is executing on.
On Windows 95/NT, only the host and process options are
implemented.
kill ?-pgroup ?signal? idlist
Send a signal to the each process in the list idlist, if permit-
ted. Signal, if present, is the signal number or the symbolic
name of the signal, see the signal system call manual page. The
leading ``SIG'' is optional when the signal is specified by its
symbolic name. The default for signo is 15, SIGTERM.
If -pgroup is specified, the numbers in idlist are take as pro-
cess group ids and the signal is sent to all of the process in
that process group. A process group id of 0 specifies the cur-
rent process group.
The kill command is not available on Windows 95/NT.
link ?-sym? srcpath destpath
Create a directory entry, destpath, linking it to the existing
file, srcpath. If -sym is specified, a symbolic link, rather
than a hard link, is created. (The -sym option is only avail-
able on systems that support symbolic links.)
The link command is not available on Windows 95/NT.
nice ?priorityincr?
Change or return the process priority. If priorityincr is omit-
ted, the current priority is returned. If priorityincr is posi-
tive, it is added to the current priority level, up to a system
defined maximum (normally 19),
Negative priorityincr values cumulatively increase the program's
priority down to a system defined minimum (normally -19);
increasing priority with negative niceness values will only work
for the superuser.
The new priority is returned.
The nice command is not available on Windows 95/NT.
readdir ?-hidden? dirPath
Returns a list containing the contents of the directory dirPath.
The directory entries "." and ".." are not returned.
On Windows 95/NT, -hidden maybe specified to include hidden
files in the result. This flag is ignored on Unix systems.
signal ?-restart? action siglist ?command?
Warning: If signals are being used as an event source (a trap
action), rather than generating an error to terminate a task;
one must use the -restart option. This causes a blocked system
call, such as read or waitpid to be restarted rather than gener-
ate an error. Failure to do this may results in unexpected
errors when a signal arrives while in one of these system calls.
When available, the -restart option can prevent this problem.
If -restart is specified, restart blocking system calls rather
than generating an error. The signal will be handled once the
Tcl command that issued the system call completes. The -restart
options is not available on all operating systems and its use
will generate an error when it is not supported. Use infox
have_signal_restart to check for availability.
Specify the action to take when a Unix signal is received by
Extended Tcl, or a program that embeds it. Siglist is a list of
either the symbolic or numeric Unix signal (the SIG prefix is
optional). Action is one of the following actions to be per-
formed on receipt of the signal. To specify all modifiable sig-
nals, use `*' (this will not include SIGKILL and SIGSTOP, as
they can not be modified).
default
Perform system default action when signal is received
(see signal system call documentation).
ignore Ignore the signal.
error Generate a catchable Tcl error. It will be as if the
command that was running returned an error. The error
code will be in the form:
POSIX SIG signame
For the death of child signal, signame will always be
SIGCHLD, rather than SIGCLD, to allow writing portable
code.
trap When the signal occurs, execute command and continue exe-
cution if an error is not returned by command. The com-
mand will be executed in the global context. The command
will be edited before execution, replacing occurrences of
"%S" with the signal name. Occurrences of "%%" result in
a single "%". This editing occurs just before the trap
command is evaluated. If an error is returned, then fol-
low the standard Tcl error mechanism. Often command will
just do an exit.
get Retrieve the current settings of the specified signals.
A keyed list will be returned were the keys are one of
the specified signals and the values are a list consist-
ing of the action associated with the signal, a 0 if the
signal may be delivered (not block) and a 1 if it is
blocked and a flag indicating if restarting of system
calls is specified. The actions maybe one of
`default',`ignore', `error' or `trap'. If the action is
trap, the third element is the command associated with
the action. The action `unknown' is returned if a non-
Tcl signal handler has been associated with the signal.
set Set signals from a keyed list in the format returned by
the get. For this action, siglist is the keyed list of
signal state. Signals with an action of `unknown' are
not modified.
block Block the specified signals from being received. (Posix
systems only).
unblock
Allow the specified signal to be received. Pending sig-
nals will not occur. (Posix systems only).
The signal action will remain enabled after the specified signal
has occurred. The exception to this is SIGCHLD on systems with-
out Posix signals. For these systems, SIGCHLD is not be auto-
matically reenabled. After a SIGCHLD signal is received, a call
to wait must be performed to retrieve the exit status of the
child process before issuing another signal SIGCHLD ... command.
For code that is to be portable between both types of systems,
use this approach.
Signals are not processed until after the completion of the Tcl
command that is executing when the signal is received. If an
interactive Tcl shell is running, then the SIGINT will be set to
error, non-interactive Tcl sessions leave SIGINT unchanged from
when the process started (normally default for foreground pro-
cesses and ignore for processes in the background).
sleep seconds
Sleep the Extended Tcl process for seconds seconds.
system cmdstr1 ?cmdstr2...?
Concatenates cmdstr1, cmdstr2 etc with space separators (see
the concat command) into a single command and then evaluates the
command using the standard system shell. On Unix systems, this
is /bin/sh and om Windows its command.com. The exit code of the
command is returned.
This command differs from the exec command in that system
doesn't return the executed command's standard output as the
result string, and system goes through the Unix shell to provide
wildcard expansion, redirection, etc, as is normal from an sh
command line.
sync ?fileId?
If fileId is not specified, or if it is and this system does not
support the fsync system call, issues a sync system call to
flush all pending disk output. If fileId is specified and the
system does support the fsync system call, issues an fsync on
the file corresponding to the specified Tcl fileId to force all
pending output to that file out to the disk.
If fileId is specified, the file must be writable. A flush will
be issued against the fileId before the sync.
The infox have_fsync command can be used to determine if "sync
fileId" will do a sync or a fsync.
times
Return a list containing the process and child execution times
in the form:
utime stime cutime cstime
Also see the times(2) system call manual page. The values are
in milliseconds.
umask ?octalmask?
Sets file-creation mode mask to the octal value of octalmask.
If octalmask is omitted, the current mask is returned.
wait ?-nohang? ?-untraced? ?-pgroup? ?pid?
Waits for a process created with the execl command to terminate,
either due to an untrapped signal or call to exit system call.
If the process id pid is specified, they wait on that process,
otherwise wait on any child process to terminate.
If -nohang is specified, then don't block waiting on a process
to terminate. If no process is immediately available, return an
empty list. If -untraced is specified then the status of child
processes that are stopped, and whose status has not yet been
reported since they stopped, are also returned. If -pgroup is
specified and pid is not specified, then wait on any child pro-
cess whose process groupd ID is they same as the calling pro-
cess. If pid is specified with -pgroup, then it is take as a
process group ID, waiting on any process in that process group
to terminate.
Wait returns a list containing three elements: The first element
is the process id of the process that terminated. If the pro-
cess exited normally, the second element is `EXIT', and the
third contains the numeric exit code. If the process terminated
due to a signal, the second element is `SIG', and the third con-
tains the signal name. If the process is currently stopped (on
systems that support SIGSTP), the second element is `STOP', fol-
lowed by the signal name.
Note that it is possible to wait on processes to terminate that
were create in the background with the exec command. However,
if any other exec command is executed after the process termi-
nates, then the process status will be reaped by the exec com-
mand and will not be available to the wait command.
On systems without the waitpid system call, the -nohang,
-untraced and -pgroup options are not available. The infox
have_waitpid command maybe use to determine if this functional-
ity is available.
FILE COMMANDS
These commands provide extended file access and manipulation. This
includes searching ASCII-sorted data files, copying files, duplicating
file descriptors, control of file access options, retrieving open file
status, and creating pipes with the pipe system call. Also linking
files, setting file, process, and user attributes and truncating files.
An interface to the select system call is available on Unix systems
that support it.
It should be noted that Tcl file I/O is implemented on top of the stdio
library. By default, the file is buffered. When communicating to a
process through a pipe, a flush command should be issued to force the
data out. Alternatively, the fcntl command may be used to set the
buffering mode of a file to line-buffered or unbuffered.
bsearch fileId key ?retvar? ?compare_proc?
Search an opened file fileId containing lines of text sorted
into ascending order for a match. Key contains the string to
match. If retvar is specified, then the line from the file is
returned in retvar, and the command returns 1 if key was found,
and 0 if it wasn't. If retvar is not specified or is a null
name, then the command returns the line that was found, or an
empty string if key wasn't found.
By default, the key is matched against the first white-space
separated field in each line. The field is treated as an ASCII
string. If compare_proc is specified, then it defines the name
of a Tcl procedure to evaluate against each line read from the
sorted file during the execution of the bsearch command. Com-
pare_proc takes two arguments, the key and a line extracted from
the file. The compare routine should return a number less than
zero if the key is less than the line, zero if the key matches
the line, or greater than zero if the key is greater than the
line. The file must be sorted in ascending order according to
the same criteria compare_proc uses to compare the key with the
line, or erroneous results will occur.
This command does not work on files containing binary data
(bytes of zero).
chmod [-fileid] mode filelist
Set permissions of each of the files in the list filelist to
mode, where mode is an absolute numeric mode or symbolic permis-
sions as in the UNIX chmod(1) command. To specify a mode as
octal, it should be prefixed with a "0" (e.g. 0622).
If the option -fileid is specified, filelist is a list of open
file identifiers rather than a list of file names. This option
is not available on all Unix systems. Use the infox have_fchmod
command to determine if this functionality is available.
The chmod command is not available on Windows 95/NT.
chown [-fileid] owner | {owner group} filelist
Set owner of each file in the list filelist to owner, which can
be a user name or numeric user id. If the first parameter is a
list, then the owner is set to the first element of the list and
the group is set to the second element. Group can be a group
name or numeric group id. If group is {}, then the file group
will be set to the login group of the specified user.
If the option -fileid is specified, filelist is a list of open
file identifiers rather than a list of file names. This option
is not available on all Unix systems. Use the infox have_fchown
command to determine if this functionality is available.
The chown command is not available on Windows 95/NT.
chgrp [-fileid] group filelist
Set the group id of each file in the list filelist to group,
which can be either a group name or a numeric group id.
If the option -fileid is specified, filelist is a list of open
file identifiers rather than a list of file names. This option
is not available on all Unix systems. Use the infox have_fchown
command to determine if this functionality is available.
The chgrp command is not available on Windows 95/NT.
dup fileId ?targetFileId?
Duplicate an open file. A new file id is opened that addresses
the same file as fileId.
If targetFileId is specified, the the file is dup to this speci-
fied file id. Normally this is stdin, stdout, or stderr. The
dup command will handle flushing output and closing this file.
The new file will be buffered, if its needs to be unbuffered,
use the fcntl command to set it unbuffered.
If fileId is a number rather than a Tcl file id, then the dup
command will bind that file to a Tcl file id. This is usedful
for accessing files that are passed from the parent process.
The argument ?targetFileId? is not valid with this operation.
On Windows 95/NT, only stdin, stdout, or stderr or a non-socket
file handle number maybe specified for targetFileId. The dup
command does not work on sockets on Windows 95/NT.
fcntl fileId attribute ?value?
This command either sets or clears a file option or returns its
current value. If value is not specified, then the current
value of attribute is returned. All values are boolean. Some
attributes maybe only be gotten, not modified. The following
attributes may be specified:
RDONLY The file is opened for reading only. (Get only)
WRONLY The file is opened for writing only. (Get only)
RDWR The file is opened for reading and writing. (Get only)
READ If the file is readable. (Get only).
WRITE If the file is writable. (Get only).
APPEND The file is opened for append-only writes. All writes will be
forced to the end of the file. (Get or set).
NONBLOCK
The file is to be accessed with non-blocking I/O. See the read
system call for a description of how it affects the behavior of
file reads.
CLOEXEC
Close the file on an process exec. If the execl command or some
other mechanism causes the process to do an exec, the file will
be closed if this option is set.
NOBUF The file is not buffered. If set, then there no buffering for
the file.
LINEBUF
Output the file will be line buffered. The buffer will be
flushed when a newline is written, when the buffer is full, or
when input is requested.
KEEPALIVE
Keep a socket connection alive. If SIGPIPE is enabled, then it
is sent if connection is broken and data is written to the
socket. If SIGPIPE is ignored, an error is returned on the
write. This attribute is valid only on sockets. By default,
SIGPIPE is ignored in Tcl.
The NONBLOCK, NOBUF and LINEBUF are provided for compatibility
with older scripts. Thefconfigure command is preferred method
of getting and setting these attributes.
The APPEND and CLOEXEC options are not available on Windows
95/NT.
flock options fileId ?start? ?length? ?origin?
This command places a lock on all or part of the file specified
by fileId. The lock is either advisory or mandatory, depending
on the mode bits of the file. The lock is placed beginning at
relative byte offset start for length bytes. If start or length
is omitted or empty, zero is assumed. If length is zero, then
the lock always extents to end of file, even if the file grows.
If origin is "start", then the offset is relative to the begin-
ning of the file. If it is "current", it is relative to the cur-
rent access position in the file. If it is "end", then it is
relative to the end-of-file (a negative is before the EOF, posi-
tive is after). If origin is omitted, start is assumed.
The following options are recognized:
-read Place a read lock on the file. Multiple processes may be
accessing the file with read-locks.
-write Place a write lock on the file. Only one process may be
accessing a file if there is a write lock.
-nowait
If specified, then the process will not block if the lock
can not be obtained. With this option, the command
returns 1 if the lock is obtained and 0 if it is not.
See your system's fcntl system call documentation for full
details of the behavior of file locking. If locking is being
done on ranges of a file, it is best to use unbuffered file
access (see the fcntl command).
The flock command is not available on Windows 95. It is avail-
able on Windows NT.
for_file var filename code
This procedure implements a loop over the contents of a file.
For each line in filename, it sets var to the line and executes
code.
The break and continue commands work as with foreach.
For example, the command
for_file line /etc/passwd {echo $line}
would echo all the lines in the password file.
funlock fileId ?start? ?length? ?origin?
Remove a locked from a file that was previously placed with the
flock command. The arguments are the same as for the flock com-
mand, see that command for more details.
The funlock command is not available on Windows 95. It is
available on Windows NT.
fstat fileId ?item? | ?stat arrayvar?
Obtain status information about an open file.
The following keys are used to identify data items:
atime The time of last access.
ctime The time of last file status change
dev The device containing a directory for the file. This
value uniquely identifies the file system that contains
the file.
gid The group ID of the file's group.
ino The inode number. This field uniquely identifies the
file in a given file system.
mode The mode of the file (see the mknod system call).
mtime Time when the data in the file was last modified.
nlink The number of links to the file.
size The file size in bytes.
tty If the file is associated with a terminal, then 1 other-
wise 0.
type The type of the file in symbolic form, which is one of
the following values: file, directory, characterSpecial,
blockSpecial, fifo, link, or socket.
uid The user ID of the file's owner.
If one of these keys is specified as item, then that data item
is returned.
If stat arrayvar is specified, then the information is returned
in the array arrayvar. Each of the above keys indexes an ele-
ment of the array containing the data.
If only fileId is specified, the command returns the data as a
keyed list.
The following values may be returned only if explicitly asked
for, it will not be returned with the array or keyed list forms:
remotehost
If fileId is a TCP/IP socket connection, then a list is
returned with the first element being the remote host IP
address. If the remote host name can be found, it is
returned as the second element of the list. The remote
host IP port number is the third element.
localhost
If fileId is a TCP/IP socket connection, then a list is
returned with the first element being the local host IP
address. If the local host name can be found, it is
returned as the second element of the list. The local
host IP port number is the third element.
ftruncate [-fileid] file newsize
Truncate a file to have a length of at most newsize bytes.
If the option -fileid is specified, file is an open file identi-
fier, otherwise it is a file path.
This command is not available or not fully functional if the
underlying operating system support is not available. The com-
mand infox have_truncate will indicate if this command may trun-
cate by file path. The command infox have_ftruncate will indi-
cate if this command may truncate by file id.
The -fileid option is not available on Windows 95/NT.
lgets fileId ?varName?
Reads the next Tcl list from the file given by fileId and dis-
cards the terminating newline character. This command differs
from the gets command, in that it reads Tcl lists rather than
lines. If the list contains newlines or binary data, then that
newline or bytes of zero will be returned as part of the result.
Only a newline not quoted as part of the list indicates the end
of the list. There is no corresponding command for outputting
lists, as puts will do this correctly.
If varName is specified, then the line is placed in the variable
by that name and the return value is a count of the number of
characters read (not including the newline). If the end of the
file is reached before reading any characters then -1 is
returned and varName is set to an empty string. If varName is
specified and an error occurs, what ever data was read will be
returned in the variable, however the resulting string may not
be a valid list.
If varName is not specified then the return value will be the
line (minus the newline character) or an empty string if the end
of the file is reached before reading any characters. An empty
string will also be returned if a line contains no characters
except the newline, so eof may have to be used to determine what
really happened.
The lgets command maybe used to read and write lists containing
binary data, however translation must be set to lf or the data
maybe corrupted.
If lgets is currently supported on non-blocking files.
pipe ?fileId_var_r fileId_var_w?
Create a pipe. If fileId_var_r and fileId_var_r are specified,
then pipe will set the a variable named fileId_var_r to contain
the fileId of the side of the pipe that was opened for reading,
and fileId_var_w will contain the fileId of the side of the pipe
that was opened for writing.
If the fileId variables are not specified, then a list contain-
ing the read and write fileIdw is returned as the result of the
command.
read_file ?-nonewline? fileName
read_file fileName numBytes
This proecure reads the file fileName and returns the contents
as a string. If -nonewline is specified, then the last charac-
ter of the file is discarded if it is a newline. The second
form specifies exactly how many bytes will be read and returned,
unless there are fewer than numBytes bytes left in the file; in
this case, all the remaining bytes are returned.
select readfileIds ?writefileIds? ?exceptfileIds? ?timeout?
This command allows an Extended Tcl program to wait on zero or
more files being ready for for reading, writing, have an excep-
tional condition pending, or for a timeout period to expire.
readFileIds, writeFileIds, exceptFileIds are each lists of
fileIds, as returned from open, to query. An empty list ({})
may be specified if a category is not used.
The files specified by the readFileIds list are checked to see
if data is available for reading. The writeFileIds are checked
if the specified files are clear for writing. The exceptFileIds
are checked to see if an exceptional condition has occurred
(typically, an error). The write and exception checking is most
useful on devices, however, the read checking is very useful
when communicating with multiple processes through pipes.
Select considers data pending in the stdio input buffer for read
files as being ready for reading, the files do. not have to be
unbuffered.
Timeout is a floating point timeout value, in seconds. If an
empty list is supplied (or the parameter is omitted), then no
timeout is set. If the value is zero, then the select command
functions as a poll of the files, returning immediately even if
none are ready.
If the timeout period expires with none of the files becoming
ready, then the command returns an empty list. Otherwise the
command returns a list of three elements, each of those elements
is a list of the fileIds that are ready in the read, write and
exception classes. If none are ready in a class, then that ele-
ment will be the null list. For example:
select {file3 file4 file5} {file6 file7} {} 10.5
could return
{file3 file4} {file6} {}
or perhaps
file3 {} {}
On Windows 95/NT, only sockets can be used with the select com-
mand. Pipes, as returned by the open command, are not sup-
ported.
write_file fileName string ?string...?
This procedure writes the specified strings to the named file.
NETWORK PROGRAMMING SUPPORT
TclX provides functionality to complement the Tcl socket command. The
host_info command is used to get information about a host by name or IP
address. In addition, the fstat and fcntl commands provide options of
querying and controlling connected sockets. To obtain the host name of
the system the local system, use the id host command.
host_info addresses host
host_info official_name host
host_info aliases host
Obtain information about a internet host. The argument host can
be either a host name or an IP address.
The following subcommands are recognized:
addresses
Return the list of IP addresses for host.
official_name
Return official name for host.
aliases
Return the list of aliases for host. (Note that these
are IP number aliases, not DNS CNAME aliases. See ifcon-
fig(2).)
FILE SCANNING COMMANDS
These commands provide a facility to scan files, matching lines of the
file against regular expressions and executing Tcl code on a match.
With this facility you can use Tcl to do the sort of file processing
that is traditionally done with awk. And since Tcl's approach is more
declarative, some of the scripts that can be rather difficult to write
in awk are simple to code in Tcl.
File scanning in Tcl centers around the concept of a scan context. A
scan context contains one or more match statements, which associate
regular expressions to scan for with Tcl code to be executed when the
expressions are matched.
scancontext ?option?
This command manages file scan contexts. A scan context is a
collection of regular expressions and commands to execute when
that regular expression matches a line of the file. A context
may also have a single default match, to be applied against
lines that do not match any of the regular expressions. Multi-
ple scan contexts may be defined and they may be reused on mul-
tiple files. A scan context is identified by a context handle.
The scancontext command takes the following forms:
scancontext create
Create a new scan context. The scanmatch command is used to
define patterns in the context. A contexthandle is returned,
which the Tcl programmer uses to refer to the newly created scan
context in calls to the Tcl file scanning commands.
scancontext delete contexthandle
Delete the scan context identified by contexthandle, and free
all of the match statements and compiled regular expressions
associated with the specified context.
scancontext copyfile contexthandle ?filehandle?
Set or return the file handle that unmatched lines are copied
to. (See scanfile). If filehandle is omitted, the copy file
handle is returned. If no copy file is associated with the con-
text, {} is returned. If a file handle is specified, it becomes
the copy file for this context. If filehandle is {}, then it
removes any copy file specification for the context.
scanfile ?-copyfile copyFileId? contexthandle fileId
Scan the file specified by fileId, starting from the current
file position. Check all patterns in the scan context specified
by contexthandle against it, executing the match commands corre-
sponding to patterns matched.
If the optional -copyfile argument is specified, the next argu-
ment is a file ID to which all lines not matched by any pattern
(excluding the default pattern) are to be written. If the copy
file is specified with this flag, instead of using the scancon-
text copyfile command, the file is disassociated from the scan
context at the end of the scan.
This command does not work on files containing binary data
(bytes of zero).
scanmatch ?-nocase? contexthandle ?regexp? commands
Specify Tcl commands, to be evaluated when regexp is matched by
a scanfile command. The match is added to the scan context
specified by contexthandle. Any number of match statements may
be specified for a give context. Regexp is a regular expression
(see the regexp command). If -nocase is specified as the first
argument, the pattern is matched regardless of alphabetic case.
If regexp is not specified, then a default match is specified
for the scan context. The default match will be executed when a
line of the file does not match any of the regular expressions
in the current scancontext.
The array matchInfo is available to the Tcl code that is exe-
cuted when an expression matches (or defaults). It contains
information about the file being scanned and where within it the
expression was matched.
matchInfo is local to the top level of the match command unless
declared global at that level by the Tcl global command. If it
is to be used as a global, it must be declared global before
scanfile is called (since scanfile sets the matchInfo before the
match code is executed, a subsequent global will override the
local variable). The following array entries are available:
matchInfo(line)
Contains the text of the line of the file that was
matched.
matchInfo(offset)
The byte offset into the file of the first character of
the line that was matched.
matchInfo(linenum)
The line number of the line that was matched. This is
relative to the first line scanned, which is usually, but
not necessarily, the first line of the file. The first
line is line number one.
matchInfo(context)
The context handle of the context that this scan is asso-
ciated with.
matchInfo(handle)
The file id (handle) of the file currently being scanned.
matchInfo(copyHandle)
The file id (handle) of the file specified by the -copy-
file option. The element does not exist if -copyfile was
not specified.
matchInfo(submatch0)
Will contain the characters matching the first parenthe-
sized subexpression. The second will be contained in
submatch1, etc.
matchInfo(subindex0)
Will contain the a list of the starting and ending
indices of the string matching the first parenthesized
subexpression. The second will be contained in
subindex1, etc.
All scanmatch patterns that match a line will be processed in
the order in which their specifications were added to the scan
context. The remainder of the scanmatch pattern-command pairs
may be skipped for a file line if a continue is executed by the
Tcl code of a preceding, matched pattern.
If a return is executed in the body of the match command, the
scanfile command currently in progress returns, with the value
passed to return as its return value.
MATH COMMANDS
Several extended math commands commands make many additional math func-
tions available in TclX. In addition, a set of procedures provide com-
mand access to the math functions supported by the expr command.
The following procedures provide command interfaces to the expr math
functions. They take the same arguments as the expr functions and may
take expressions as arguments.
abs acos asin atan2
atan ceil cos cosh
double exp floor fmod
hypot int log10 log
pow round sin sinh
sqrt tan tanh
max num1 ?..numN?
expr max(num1, num2)
Returns the argument that has the highest numeric value. Each
argument may be any integer or floating point value.
This functionality is also available as a math function max in
the Tcl expr command.
min num1 ?..numN?
expr min(num1, num2)
Returns the argument that has the lowest numeric value. Each
argument may be any integer or floating point value.
This functionality is also available as a math function min in
the Tcl expr command.
random limit | seed ?seedval?
Generate a pseudorandom integer number greater than or equal to
zero and less than limit. If seed is specified, then the com-
mand resets the random number generator to a starting point
derived from the seedval. This allows one to reproduce pseudo-
random number sequences for testing purposes. If seedval is
omitted, then the seed is set to a value based on current system
state and the current time, providing a reasonably interesting
and ever-changing seed.
LIST MANIPULATION COMMANDS
Extended Tcl provides additional list manipulation commands and proce-
dures.
intersect lista listb
Procedure to return the logical intersection of two lists. The
returned list will be sorted.
intersect3 lista listb
Procedure to intersects two lists, returning a list containing
three lists: The first list returned is everything in lista
that wasn't in listb. The second list contains the intersection
of the two lists, and the third list contains all the elements
that were in listb but weren't in lista. The returned lists
will be sorted.
lassign list var ?var...?
Assign successive elements of a list to specified variables. If
there are more variable names than fields, the remaining vari-
ables are set to the empty string. If there are more elements
than variables, a list of the unassigned elements is returned.
For example,
lassign {dave 100 200 {Dave Foo}} name uid gid longName
Assigns name to ``dave'', uid to ``100'', gid to ``200'', and
longName to ``Dave Foo''.
lcontain list element
Determine if the element is a list element of list. If the ele-
ment is contained in the list, 1 is returned, otherwise, 0 is
returned.
lempty list
Determine if the specified list is empty. If empty, 1 is
returned, otherwise, 0 is returned. This command is an alterna-
tive to comparing a list to an empty string, however it checks
for a string of all whitespaces, which is an empty list.
lmatch ?mode? list pattern
Search the elements of list, returning a list of all elements
matching pattern. If none match, an empty list is returned.
The mode argument indicates how the elements of the list are to
be matched against pattern and it must have one of the following
values:
-exact The list element must contain exactly the same string as
pattern.
-glob Pattern is a glob-style pattern which is matched against
each list element using the same rules as the string
match command.
-regexp
Pattern is treated as a regular expression and matched
against each list element using the same rules as the
regexp command.
If mode is omitted then it defaults to -glob.
Only the -exact comparison will work on binary data.
lrmdups list
Procedure to remove duplicate elements from a list. The
returned list will be sorted.
lvarcat var string ?string...?
This command treats each string argument as a list and concate-
nates them to the end of the contents of var, forming a a single
list. The list is stored back into var and also returned as the
result. if var does not exist, it is created.
lvarpop var ?indexExpr? ?string?
The lvarpop command pops (deletes) the element indexed by the
expression indexExpr from the list contained in the variable
var. If index is omitted, then 0 is assumed. If string, is
specified, then the deleted element is replaced by string. The
replaced or deleted element is returned. Thus ``lvarpop argv
0'' returns the first element of argv, setting argv to contain
the remainder of the string.
If the expression indexExpr starts with the string end, then end
is replaced with the index of the last element in the list. If
the expression starts with len, then len is replaced with the
length of the list.
lvarpush var string ?indexExpr?
The lvarpush command pushes (inserts) string as an element in
the list contained in the variable var. The element is inserted
before position indexExpr in the list. If index is omitted, then
0 is assumed. If var does not exists, it is created.
If the expression indexExpr starts with the string end, then end
is replaced with the index of the last element in the list. If
the expression starts with len, then len is replaced with the
length of the list. Note the a value of end means insert the
string before the last element.
union lista listb
Procedure to return the logical union of the two specified
lists. Any duplicate elements are removed.
KEYED LISTS
Extended Tcl defines a special type of list referred to as keyed lists.
These lists provided a structured data type built upon standard Tcl
lists. This provides a functionality similar to structs in the C pro-
gramming language.
A keyed list is a list in which each element contains a key and value
pair. These element pairs are stored as lists themselves, where the
key is the first element of the list, and the value is the second. The
key-value pairs are referred to as fields. This is an example of a
keyed list:
{{NAME {Frank Zappa}} {JOB {musician and composer}}}
If the variable person contained the above list, then keylget person
NAME would return {Frank Zappa}. Executing the command:
keylset person ID 106
would make person contain
{{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}}
Fields may contain subfields; `.' is the separator character. Sub-
fields are actually fields where the value is another keyed list. Thus
the following list has the top level fields ID and NAME, and subfields
NAME.FIRST and NAME.LAST:
{ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
There is no limit to the recursive depth of subfields, allowing one to
build complex data structures.
Keyed lists are constructed and accessed via a number of commands. All
keyed list management commands take the name of the variable containing
the keyed list as an argument (i.e. passed by reference), rather than
passing the list directly.
keyldel listvar key
Delete the field specified by key from the keyed list in the
variable listvar. This removes both the key and the value from
the keyed list.
keylget listvar ?key? ?retvar | {}?
Return the value associated with key from the keyed list in the
variable listvar. If retvar is not specified, then the value
will be returned as the result of the command. In this case, if
key is not found in the list, an error will result.
If retvar is specified and key is in the list, then the value is
returned in the variable retvar and the command returns 1 if the
key was present within the list. If key isn't in the list, the
command will return 0, and retvar will be left unchanged. If {}
is specified for retvar, the value is not returned, allowing the
Tcl programmer to determine if a key is present in a keyed list
without setting a variable as a side-effect.
If key is omitted, then a list of all the keys in the keyed list
is returned.
keylkeys listvar ?key?
Return the a list of the keys in the keyed list in the variable
listvar. If keys is specified, then it is the name of a key
field who's subfield keys are to be retrieve.
keylset listvar key value ?key2 value2 ...?
Set the value associated with key, in the keyed list contained
in the variable listvar, to value. If listvar does not exists,
it is created. If key is not currently in the list, it will be
added. If it already exists, value replaces the existing value.
Multiple keywords and values may be specified, if desired.
STRING AND CHARACTER MANIPULATION COMMANDS
The commands provide additional functionality to classify characters,
convert characters between character and numeric values, index into a
string, determine the length of a string, extract a range of character
from a string, replicate a string a number of times, and transliterate
a string (similar to the Unix tr program).
ccollate ?-local? string1 string2
This command compares two strings. If returns -1 if string1 is
less than string2, 0 if they are equal and 1 if string1 is
greater than string2.
If -local is specified, the strings are compared according to
the collation environment of the current locale.
This command does not work with binary or UTF data.
cconcat ?string1? ?string2? ?...?
Concatenate the arguments, returning the resulting string.
While string concatenation is normally performed by the parser,
it is occasionally useful to have a command that returns a
string. The is generally useful when a command to evaluate is
required. No separators are inserted between the strings.
This command is UTF-aware.
cequal string string
This command compares two strings for equality. It returns 1 if
string1 and string2 are the identical and 0 if they are not.
This command is a short-cut for string compare and avoids the
problems with string expressions being treated unintentionally
as numbers.
This command is UTF-aware and will also work on binary data.
cindex string indexExpr
Returns the character indexed by the expression indexExpr (zero
based) from string.
If the expression indexExpr starts with the string end, then end
is replaced with the index of the last character in the string.
If the expression starts with len, then len is replaced with the
length of the string.
This command is UTF-aware.
clength string
Returns the length of string in characters. This command is a
shortcut for:
string length string
This command is UTF-aware.
crange string firstExpr lastExpr
Returns a range of characters from string starting at the char-
acter indexed by the expression firstExpr (zero-based) until the
character indexed by the expression lastExpr.
If the expression firstExpr or lastExpr starts with the string
end, then end is replaced with the index of the last character
in the string. If the expression starts with len, then len is
replaced with the length of the string.
This command is UTF-aware.
csubstr string firstExpr lengthExpr
Returns a range of characters from string starting at the char-
acter indexed by the expression firstExpr (zero-based) for
lengthExpr characters.
If the expression firstExpr or lengthExpr starts with the string
end, then end is replaced with the index of the last character
in the string. If the expression starts with len, then len is
replaced with the length of the string.
This command is UTF-aware.
ctoken strvar separators
Parse a token out of a character string. The string to parse is
contained in the variable named strvar. The string separators
contains all of the valid separator characters for tokens in the
string. All leading separators are skipped and the first token
is returned. The variable strvar will be modified to contain
the remainder of the string following the token.
This command does not work with binary data.
ctype ?-failindex var? class string
ctype determines whether all characters in string are of the
specified class. It returns 1 if they are all of class, and 0
if they are not, or if the string is empty. This command also
provides another method (besides format and scan) of converting
between an ASCII character and its numeric value. The following
ctype commands are available:
ctype ?-failindex var? alnum string
Tests that all characters are alphabetic or numeric char-
acters as defined by the character set.
ctype ?-failindex var? alpha string
Tests that all characters are alphabetic characters as
defined by the character set.
ctype ?-failindex var? ascii string
Tests that all characters are an ASCII character (a non-
negative number less than 0200).
ctype char number
Converts the numeric value, string, to an ASCII charac-
ter. Number must be in the range 0 through the maximum
Unicode values.
ctype ?-failindex var? cntrl string
Tests that all characters are ``control characters'' as
defined by the character set.
ctype ?-failindex var? digit string
Tests that all characters are valid decimal digits, i.e.
0 through 9.
ctype ?-failindex var? graph string
Tests that all characters within are any character for
which ctype print is true, except for space characters.
ctype ?-failindex var? lower string
Tests that all characters are lowercase letters as
defined by the character set.
ctype ord character
Convert a character into its decimal numeric value. The
first character of the string is converted to its numeric
Unicode value.
ctype ?-failindex var? space string
Tests that all characters are either a space, horizontal-
tab, carriage return, newline, vertical-tab, or form-
feed.
ctype ?-failindex var? print string
Tests that all characters are a space or any character
for which ctype alnum or ctype punct is true or other
``printing character'' as defined by the character set.
ctype ?-failindex var? punct string
Tests that all characters are made up of any of the char-
acters other than the ones for which alnum, cntrl, or
space is true.
ctype ?-failindex var? upper string
Tests that all characters are uppercase letters as
defined by the character set.
ctype ?-failindex var? xdigit string
Tests that all characters are valid hexadecimal digits,
that is 0 through 9, a through f or A through F.
If -failindex is specified, then the index into string of the
first character that did not match the class is returned in var.
replicate string countExpr
Returns string, replicated the number of times indicated by the
expression countExpr.
This command is UTF-aware and will work with binary data.
translit inrange outrange string
Translate characters in string, changing characters occurring in
inrange to the corresponding character in outrange. Inrange and
outrange may be list of characters or a range in the form `A-M'.
For example:
translit a-z A-Z foobar
This command currently only supports characters in ASCII range; UTF-8 characters
out of this range will generate an error.
XPG/3 MESSAGE CATALOG COMMANDS
These commands provide a Tcl interface to message catalogs that are
compliant with the X/Open Portability Guide, Version 3 (XPG/3).
Tcl programmers can use message catalogs to create applications that
are language-independent. Through the use of message catalogs,
prompts, messages, menus and so forth can exist for any number of lan-
guages, and they can altered, and new languages added, without affect-
ing any Tcl or C source code, greatly easing the maintenance difficul-
ties incurred by supporting multiple languages.
A default text message is passed to the command that fetches entries
from message catalogs. This allows the Tcl programmer to create mes-
sage catalogs containing messages in various languages, but still have
a set of default messages available regardless of the presence of any
message catalogs, and allow the programs to press on without difficulty
when no catalogs are present.
Thus, the normal approach to using message catalogs is to ignore errors
on catopen, in which case catgets will return the default message that
was specified in the call.
The Tcl message catalog commands normally ignore most errors. If it is
desirable to detect errors, a special option is provided. This is nor-
mally used only during debugging, to insure that message catalogs are
being used. If your Unix implementation does not have XPG/3 message
catalog support, stubs will be compiled in that will create a version
of catgets that always returns the default string. This allows for
easy porting of software to environments that don't have support for
message catalogs.
Message catalogs are global to the process, an application with multi-
ple Tcl interpreters within the same process may pass and share message
catalog handles.
catopen ?-fail | -nofail? catname
Open the message catalog catname. This may be a relative path
name, in which case the NLSPATH environment variable is searched
to find an absolute path to the message catalog. A handle in
the form msgcatN is returned. Normally, errors are ignored, and
in the case of a failed call to catopen, a handle is returned to
an unopened message catalog. (This handle may still be passed
to catgets and catclose, causing catgets to simply return the
default string, as described above. If the -fail option is
specified, an error is returned if the open fails. The option
-nofail specifies the default behavior of not returning an error
when catopen fails to open a specified message catalog. If the
handle from a failed catopen is passed to catgets, the default
string is returned.
catgets catHandle setnum msgnum defaultstr
Retrieve a message form a message catalog. CatHandle should be a
Tcl message catalog handle that was returned by catopen. Setnum
is the message set number, and msgnum is the message number. If
the message catalog was not opened, or the message set or mes-
sage number cannot be found, then the default string, default-
str, is returned.
catclose ?-fail | -nofail? cathandle
Close the message catalog specified by cathandle. Normally,
errors are ignored. If -fail is specified, any errors closing
the message catalog file are returned. The option -nofail spec-
ifies the default behavior of not returning an error. The use
of -fail only makes sense if it was also specified in the call
to catopen.
EXTENDED TCL SHELL
tcl ?-qn? ?-f? script? | ?-c command? ?args?
The tcl starts the interactive TclX command interpreter. The TclX
shell provides an environment for writing, debugging and executing Tcl
scripts. The functionality of the TclX shell can be easily obtained by
any application that includes TclX.
The tcl command, issued without any arguments, invokes an interactive
Tcl shell, allowing the user to interact directly with Tcl, executing
any Tcl commands at will and viewing their results.
If script is specified, then the script is executed non-interactively
with any additional arguments, args, being supplied in the global Tcl
variable `argv'. If command is supplied, then this command (or semi-
colon-separated series of commands) is executed, with `argv' containing
any args.
The TclX shell is intended as an environment for Tcl program develop-
ment and execution. While it is not a full-featured interactive shell,
it provides a comfortable environment for the interactive development
of Tcl code.
The following command line flags are recognized by the Tcl shell com-
mand line parser:
-q Quick initialization flag. The Tcl initiaization file is not
evaluated and the auto_path variable is not set. Tcl auto-load
libraries will not be available.
-n No procedure call stack dump. The procedure call stack will not
be displayed when an error occurs, only the error message. Use-
ful in the #! line of already debugged scripts.
-f Takes the next argument as a script for Tcl to source, rather
than entering interactive mode. The -f flag is optional. Nor-
mally the first argument that does not start with a `-' is taken
as the script to execute unless the `-c' option is specified.
Any following arguments are passed to the script via argv, thus
any other Tcl shell command-line flags must precede this option.
-c Take the next argument as a Tcl command to execute. It may con-
tain series of commands to execute, separated by `;'. Any fol-
lowing arguments are passed in argv, thus, as with -f, any other
Tcl shell flags must precede this option.
-- Mark the end of the arguments to the Tcl shell. All arguments
following this are passed in the Tcl variable argv. This is
useful to pass arguments without attempting to execute a Tcl
script.
The result string returned by a command executed from the Tcl shell
command line is normally echoed back to the user. If an error occurs,
then the string result is displayed, along with the error message. The
error message will be preceded by the string ``Error:''.
The set command is a special case. If the command is called to set a
variable (i.e. with two arguments), then the result will not be echoed.
If only one argument, the name of a variable, is supplied to set, then
the result will be echoed.
If an unknown Tcl command is entered from the command line, then the
Unix command path, specified in the environment variable PATH, will be
searched for a command of the same name. If the command is found, it
will be executed with any arguments remaining on the Tcl command line
being passed as arguments to the command. This feature is provided to
enhance the interactive environment for developing Tcl scripts.
Automatic execution of programs in this manner is only supported from
the command line, not in script files or in procedures, to reduce con-
fusion and mistakes while programming in Tcl. Scripts should use the
Tcl exec or system commands to run Unix commands.
The following variables are set and/or used by the Tcl shell.
argv0 Contains the name of the Tcl program specified on the command
line or the name that the Tcl shell was invoked under if no pro-
gram was specified. argc Contains a count of the number of argv
arguments (0 if none). argv A list containing the arguments
passed in from the command line, excluding arguments used by the
Tcl shell. The first element is the first passed argument, not
the program name.
tcl_interactive
Set to 1 if Tcl shell is invoked interactively, or 0 if the Tcl
shell is directly executing a script. Normally checked by
scripts so that they can function as a standalone application if
specified on the command line, but merely load in and not exe-
cute if loaded during an interactive invocation of Tcl.
auto_path
Path to search to locate Tcl autoload libraries. Used by the
both the Tcl and TclX library autoloading facility.
tclx_library
Path to the TclX runtime library. If your running the TclX
shell or an application based on it (like wishx). The TclX ini-
tialization file normally adds this to the auto_path.
tkx_library
Path to the TkX runtime library. This is set only if your
application has called Tkx_Init. The TkX initialization file
normally adds this to the auto_path.
tcl_prompt1
Contains code to run to output the prompt used when interac-
tively prompting for commands.
tcl_prompt2
Contains code to run to output the prompt used when interac-
tively prompting for continuation of an incomplete command.
TCLXENV
Array that contains information used internally by various Tcl
procedures that are part of the TclX shell. Don't change this
array unless you know what your doing. tclx_errorHandler mes-
sage
The tclx_errorHandler command doesn't exist as built-in part of
TclX. Instead, individual applications or users can define
a tclx_errorHandler command (e.g. as a Tcl procedure) if they
wish to handle uncaught errors. The procedure will be passed a
single argument of the error message, with errorCode and error-
Info having values reflecting the error that occurred.
The tclx_errorHandler command is called when an error that is
not caught returns to the top level command evaluation in the
TclX shell or wishx. The difference between tclx_errorHandler
and bgerror is that tclx_errorHandler is called during the syn-
chronous execution of a script while bgerror is called as a
result of an uncaught error in an event handler. In a non-event
oriented Tcl script tclx_errorHandler will be called on all
errors that are not caught and bgerror is not used. In a wishx
script or event oriented script executed with the TclX shell,
tclx_errorHandler will be called on uncaught errors during the
execution of the main script that set up the event oriented pro-
gram. Once the event loop is entered, bgerror will be called on
uncaught errors.
This procedure is not called in response to commands entered via
an interactive command loop, only from the evaluation of scripts
or Tcl commands passed via the command line. If the procedure
returns normally, the program will just exit without any error
being issued by the shell. Generally the procedure should exit
with a non-zero exit code once the error has been processed. It
is not possible to continue executing the code in which the
error occurred. This is useful for logging errorInfo or e-mail-
ing it to the maintainer.
mainloop
This procedure sets up a top-level event loop. Events are pro-
cessed until there are no more active event sources, at which
time the process exits. It is used to build event oriented pro-
grams using the TclX shell in a style similar to that used with
wish. If the global variable tcl_interactive exists and has a
true value an interactive command handler is started as well.
If the command handler is terminated by an EOF, the process will
be exited.
This commands is not useful in wishx, as it automatically enters
an event loop after processing a script.
HELP FACILITY
The help facility allows one to look up help pages which where
extracted from the standard Tcl manual pages and Tcl scripts during Tcl
installation. Help files are structured as a multilevel tree of sub-
jects and help pages. Help files are found by searching directories
named help in the directories listed in the auto_path variable. All of
the files in the list of help directories form a virtual root of the
help tree. This method allows multiple applications to provide help
trees without having the files reside in the same directory.
The help facility can be accessed in two ways, as interactive commands
in the Extended Tcl shell or as an interactive Tk-based program (if you
have built Extended Tcl with Tk).
To run the Tk-based interactive help program:
tclhelp ?addpaths?
Where addpaths are additional paths to search for help directories. By
default, only the auto_path used by tclhelp is search. This will
result in help on Tcl, Extended Tcl and Tk.
The following interactive Tcl commands and options are provided with
the help package:
help
Help, without arguments, lists of all the help subjects and
pages under the current help subject.
help subject
Displays all of help pages and lower level subjects (if any
exist) under the subject subject.
help subject/helppage
Display the specified help page. The help output is passed
through a simple pager if output exceeds 23 lines, pausing wait-
ing for a return to be entered. If any other character is
entered, the output is terminated.
helpcd ?subject?
Change the current subject, which is much like the Unix current
directory. If subject is not specified, return to the top-level
of the help tree. Help subject path names may also include
``..'' elements.
helppwd
Displays the current help subject.
help help | ?
Displays help on the help facility at any directory level.
apropos pattern
This command locates subjects by searching their one-line
descriptions for a pattern. Apropos is useful when you can
remember part of the name or description of a command, and want
to search through the one-line summaries for matching lines.
Full regular expressions may be specified (see the regexp com-
mand).
TCL LOADABLE LIBRARIES AND PACKAGES
Extended Tcl supports standard Tcl tclIndex libraries and package
libraries. A package library file can contain multiple independent Tcl
packages. A package is a named collection of related Tcl procedures
and initialization code.
The package library file is just a regular Unix text file, editable
with your favorite text editor, containing packages of Tcl source code.
The package library file name must have the suffix .tlib. An index
file with the same prefix name and the suffix .tndx resides the same
directory as the .tlib file. The .tndx will be automatically created
whenever it is out of date or missing (provided there is write access
to the directory).
The variable auto_path contains a list of directories that are searched
for libraries. The first time an unknown command trap is take, the
indexes for the libraries are loaded into memory. If the auto_path
variable is changed during execution of a program, it will be re-
searched. Only the first package of a given name found during the exe-
cution of a program is loaded. This can be overridden with loadli-
bindex command.
The start of a package is delimited by:
#@package: package_name proc1 ?..procN?
These lines must start in column one. Everything between the #@pack-
age: keyword and the next #@package: keyword or a #@packend keyword, or
the end of the file, becomes part of the named package. The specified
procedures, proc1..procN, are the entry points of the package. When a
command named in a package specification is executed and detected as an
unknown command, all code in the specified package will be sourced.
This package should define all of the procedures named on the package
line, define any support procedures required by the package and do any
package-specific initialization. Packages declarations maybe continued
on subsequent lines using standard Tcl backslash line continuations.
The #@packend keyword is useful to make sure only the minimum required
section of code is sourced. Thus for example a large comment block at
the beginning of the next file won't be loaded.
Care should be taken in defining package_name, as the first package
found in the path by with a given name is loaded. This can be useful
in developing new version of packages installed on the system.
For example, in a package source file, the presence of the following
line:
#@package: directory_stack pushd popd dirs
says that the text lines following that line in the package file up to
the next package line or the end of the file is a package named direc-
tory_stack and that an attempt to execute either pushd, popd or dirs
when the routine is not already defined will cause the directory_stack
portion of the package file to be loaded.
PACKAGE LIBRARY MANAGEMENT COMMANDS
Several commands are available for building and managing package
libraries. Commands that are extended versions of the standard Tcl
library commands are listed here. All of the standard Tcl library man-
agement commands and variables are also supported.
auto_commands ?-loaders?
Lists the names of all known loadable procedures and commands
procedures. If -loaders is specified, the command that will be
executed to load the command will also be returned.
buildpackageindex libfilelist
Build index files for package libraries. The argument lib-
filelist is a list of package libraries. Each name must end
with the suffix .tlib. A corresponding .tndx file will be
built. The user must have write access to the directory con-
taining each library.
convert_lib tclIndex packagelib ?ignore?
Convert a Ousterhout style tclIndex index file and associate
source files into a package library packagelib. If packagelib
does not have a .tlib extension, one will be added. Any files
specified in tclIndex that are in the list ignore will be
skipped. Files listed in ignore should just be the base file
names, not full paths.
loadlibindex libfile.tlib
Load the package library index of the library file libfile
(which must have the suffix .tlib). Package library indexes
along the auto_path are loaded automatically on the first
demand_load; this command is provided to explicitly load
libraries that are not in the path. If the index file (with a
.tndx suffix) does not exists or is out of date, it will be
rebuilt if the user has directory permissions to create it. If a
package with the same name as a package in libfile.tlib has
already been loaded, its definition will be overridden by the
new package. However, if any procedure has actually been used
from the previously defined package, the procedures from lib-
file.tlib will not be loaded.
auto_packages ?-location?
Returns a list of the names of all defined packages. If -loca-
tion is specified, a list of pairs of package name and the .tlib
path name, offset and length of the package within the library.
auto_load_file file
Source a file, as with the source command, except search
auto_path for the file.
searchpath path file
Search all directories in the specified path, which is a Tcl
list, for the specified file. Returns the full path name of the
file, or an empty string if the requested file could not be
found.
Tcl TclX(TCL)
