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 environment), 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 sec
tions:
· General Commands
· Debugging and Development Commands
· Unix Access Commands
· File Commands
· Network Programming Support
· File Scanning Commands
· Math Commands
· List Manipulation Commands
· Keyed Lists
· String and Character Manipulation Commands
· XPG/3 Message Catalog Commands
· Help Facility
· Tcl Loadable Libraries and Packages
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 direc
tory 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 ori
ented. This command is useful for Tcl scripts that
do not normally converse interactively with a user
through a Tcl command interpreter, but which some
times want to enter this mode, perhaps for debug
ging or user configuration. The command loop ter
minates 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 accumulated 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 interactive 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 stdout.
-prompt2 cmd
If specified, cmd is used is evaluate and
its result used for the secondary (continua
tion) command prompt. If not specified, the
command in tcl_prompt2 is evaluated to
-endcommand cmd
If specified, cmd is evaluated when the com
mand loop terminates.
In interactive mode, the results of set com
mands 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 pro
gram 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 cur
rent application. The following infox command
options are available:
version
Return the version number of Extended Tcl.
The version number for Extended Tcl is gen
erated by combining the base version of the
standard Tcl code with another number indi
cating the version of Extended Tcl being
used.
patchlevel
Return the patchlevel for Extended Tcl.
have_fchown
Return 1 if the fchown system call is avail
able. This supports the -fileid option on
the chown and chgrp commands.
have_fchmod
Return 1 if the fchmod system call is avail
able. 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 avail
able and the sync command will sync individ
ual files. 0 if it is not available and the
sync command will always sync all file
have_ftruncate
Return 1 if the ftruncate or chsize system
call is available. If it is, the ftruncate
command -fileid option maybe used.
have_msgcats
Return 1 if XPG message catalogs are avail
able, 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 avail
able (-restart option available for the sig
nal 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 command 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 vari
able.
applongname
Return a natural language name for the cur
rent application. The C variable tclLongApp
Name must be set by the application to
return an application specific value for
this variable.
appversion
Return the version number for the current
must be set by the application to return an
application-specific value for this vari
able.
apppatchlevel
Return the patchlevel for the current appli
cation. 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 con
tinue 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 state
ment 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 contain the loop index. The loop index
is set to the value specified 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 parameters 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 expres
sions. They are only evaluated once at the begin
ning of the loop.
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 direc
tory.
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 exe
cute 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 evaluate 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.
This section contains information on commands and proce
dures that are useful for developing and debugging Tcl
scripts.
cmdtrace level | on ?noeval? ?notruncate? ?procs?
?fileid? ?com mand 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 char
acters, 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 argu
ment will be enclosed inside of braces
(`{}') to allow the reader to visually sepa
rate the arguments from each other.
notruncate
Disables the truncation of commands and
evaluated arguments.
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 out
put 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 monitored 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
ally below. This option may not be speci
fied 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 execu
tion of code, so it should be removed when code is
debugged. The following command will enable trac
ing 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 substitu
tion.
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 command'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 trac
ing 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.
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 spec
ified), 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 pro
file of a Tcl script. It collects data at the Tcl
procedure level. The number of calls to a proce
dure, and the amount of real and CPU time is col
lected. Time is also collected for the global con
text. The procedure data is collected by bucketing
it based on the procedure call stack, this allows
determination of how much time is spent in a par
ticular procedure in each of it's calling contexts.
The on option enables profile data collection. If
the -commands option is specified, data on all com
mands within a procedure is collected as well a
procedures. Multiple occurrences of a command
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 containing 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 millisec
onds 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 evalu
ation (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.
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 containing 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. UserTi
tle 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 procedure 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 exe
cuted 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.
These commands provide access to many basic Unix facili
ties, including process handling, date and time process
ing, 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 float
ing point number, so fractions 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 sec
onds left in the previous alarm. On systems with
out 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 argu
ments 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 executing the Tk
version of the exit command. We suggest using the
following command to abort Tk applications after an
execl failure:
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 process. If the fork fails, a
Tcl error is generated.
If an execl is not going to be performed before the
sequence is going to be performed on stdout or
stderr, then a flush should be issued against std
out, stderr and any other open output file before
doing the fork. Otherwise characters from the par
ent 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
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 number, respectively.
id effective group
id effective groupid
Return the effective group name, or effec
tive 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 pro
gram is running on.
id process
Return the process ID of the current pro
cess.
id process parent
Return the process ID of the parent of the
current process.
id process group
Return the process group ID of the current
process.
id process group set
Set the process group ID of the current pro
cess 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 permitted. Signal, if present, is the
signal number or the symbolic name of the signal,
see the signal system call manual page. The lead
ing ``SIG'' is optional when the signal is
signo is 15, SIGTERM.
If -pgroup is specified, the numbers in idlist are
take as process group ids and the signal is sent to
all of the process in that process group. A pro
cess group id of 0 specifies the current 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 cre
ated. (The -sym option is only available on sys
tems that support symbolic links.)
The link command is not available on Windows 95/NT.
nice ?priorityincr?
Change or return the process priority. If priori
tyincr is omitted, the current priority is
returned. If priorityincr is positive, 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
call, such as read or waitpid to be restarted
rather than generate 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 avail
ability.
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 signals, 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 documenta
tion).
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 execution if an error is not
returned by command. The command 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 follow the standard Tcl error
mechanism. Often command will just do an
exit.
fied signals. A keyed list will be returned
were the keys are one of the specified sig
nals and the values are a list consisting 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 indicat
ing if restarting of system calls is speci
fied. 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 signals will not occur. (Posix sys
tems only).
The signal action will remain enabled after the
specified signal has occurred. The exception to
this is SIGCHLD on systems without Posix signals.
For these systems, SIGCHLD is not be automatically
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 comple
tion 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 processes and ignore for processes in
the background).
sleep seconds
Sleep the Extended Tcl process for seconds seconds.
Concatenates cmdstr1, cmdstr2 etc with space sep
arators (see the concat command) into a single com
mand and then evaluates the command using the stan
dard 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 stan
dard output as the result string, and system goes
through the Unix shell to provide wildcard expan
sion, 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 deter
mine if "sync fileId" will do a sync or a fsync.
times
Return a list containing the process and child exe
cution 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
-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 process 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 process 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 contains the signal name. If the process
is currently stopped (on systems that support
SIGSTP), the second element is `STOP', followed 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 com
mand is executed after the process terminates, 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 functionality is avail
able.
These commands provide extended file access and manipula
tion. This includes searching ASCII-sorted data files,
copying files, duplicating file descriptors, control of
file access options, retrieving open file status, and cre
ating 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. Alterna
tively, 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 speci
fied, 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 com
pare_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. Compare_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 permissions as in the UNIX
chmod(1) command. To specify a mode as octal, it
should be prefixed with a "0" (e.g. 0622).
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 specified 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.
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 speci
fied, 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.
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 advi
sory 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 rela
tive to the current access position in the file.
If it is "end", then it is relative to the end-of-
file (a negative is before the EOF, positive 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).
It is available 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 fore
ach.
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 command, 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 iden
tifies 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 mod
ified.
nlink The number of links to the file.
size The file size in bytes.
then 1 otherwise 0.
type The type of the file in symbolic form, which
is one of the following values: file, direc
tory, 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 element of the array contain
ing 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 ele
ment 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 ele
ment 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 identifier, otherwise it is a file path.
This command is not available or not fully func
tional if the underlying operating system support
is not available. The command infox have_truncate
will indicate if this command may truncate by file
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 discards the terminating newline charac
ter. 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 includ
ing 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 charac
ters 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 containing the read and write fileIdw is
read_file ?-nonewline? fileName
read_file fileName numBytes
This proecure reads the file fileName and returns
the contents as a string. If -nonewline is speci
fied, then the last character of the file is dis
carded if it is a newline. The second form speci
fies 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? ?time
out?
This command allows an Extended Tcl program to wait
on zero or more files being ready for for reading,
writing, have an exceptional 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, how
ever, the read checking is very useful when commu
nicating 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 sec
onds. If an empty list is supplied (or the parame
ter 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 element will be the null list.
For example:
could return
{file3 file4} {file6} {}
or perhaps
file3 {} {}
On Windows 95/NT, only sockets can be used with the
select command. Pipes, as returned by the open
command, are not supported.
write_file fileName string ?string...?
This procedure writes the specified strings to the
named file.
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 argu
ment 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 ifconfig(2).)
These commands provide a facility to scan files, matching
lines of the file against regular expressions and execut
ing Tcl code on a match. With this facility you can use
Tcl to do the sort of file processing that is tradition
ally done with awk. And since Tcl's approach is more
declarative, some of the scripts that can be rather diffi
cult 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 state
ments, 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 expres
sions. Multiple scan contexts may be defined and
they may be reused on multiple files. A scan con
text is identified by a context handle. The scan
context command takes the following forms:
scancontext create
Create a new scan context. The scanmatch command
is used to define patterns in the context. A con
texthandle 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 contex
thandle, 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 context, {} is
returned. If a file handle is specified, it
becomes the copy file for this context. If file
handle is {}, then it removes any copy file speci
fication 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
patterns matched.
If the optional -copyfile argument is specified,
the next argument 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
scancontext copyfile command, the file is disasso
ciated 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 contex
thandle. 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 executed 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.
The line number of the line that was
matched. This is relative to the first line
scanned, which is usually, but not necessar
ily, 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 associated 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 -copyfile option. The element does
not exist if -copyfile was not specified.
matchInfo(submatch0)
Will contain the characters matching the
first parenthesized subexpression. The sec
ond 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 sec
ond will be contained in subindex1, etc.
All scanmatch patterns that match a line will be
processed in the order in which their specifica
tions were added to the scan context. The remain
der 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.
Several extended math commands commands make many addi
tional math functions available in TclX. In addition, a
set of procedures provide command access to the math func
tions 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 float
ing 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 command resets the random num
ber generator to a starting point derived from the
seedval. This allows one to reproduce pseudorandom
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, pro
viding a reasonably interesting and ever-changing
seed.
Extended Tcl provides additional list manipulation com
mands and procedures.
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 sec
ond 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 variables 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 element 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 alternative 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:
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 concatenates 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 omit
ted, 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
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.
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 function
ality similar to structs in the C programming 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 com
poser}}}
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 charac
ter. Subfields 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 argu
ment (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
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 speci
fied, if desired.
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 cur
rent 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.
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 character indexed by the expression first
Expr (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 character indexed by the expression first
Expr (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 con
verting between an ASCII character and its numeric
value. The following ctype commands are available:
Tests that all characters are alphabetic or
numeric characters as defined by the charac
ter 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 char
acter (a non-negative number less than
0200).
ctype char number
Converts the numeric value, string, to an
ASCII character. 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 let
ters 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, new
line, 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 charac
ter'' as defined by the character set.
Tests that all characters are made up of any
of the characters other than the ones for
which alnum, cntrl, or space is true.
ctype ?-failindex var? upper string
Tests that all characters are uppercase let
ters as defined by the character set.
ctype ?-failindex var? xdigit string
Tests that all characters are valid hexadec
imal 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 exam
ple:
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.
These commands provide a Tcl interface to message catalogs
that are compliant with the X/Open Portability Guide, Ver
sion 3 (XPG/3).
Tcl programmers can use message catalogs to create appli
cations that are language-independent. Through the use of
message catalogs, prompts, messages, menus and so forth
can exist for any number of languages, and they can
altered, and new languages added, without affecting any
Tcl or C source code, greatly easing the maintenance dif
ficulties 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 message catalogs containing mes
sages 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 normally 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 cre
ate a version of catgets that always returns the default
string. This allows for easy porting of software to envi
ronments that don't have support for message catalogs.
Message catalogs are global to the process, an application
with multiple 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 envi
ronment 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 han
dle 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.
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 mes
sage set number, and msgnum is the message number.
If the message catalog was not opened, or the mes
sage set or message number cannot be found, then
the default string, defaultstr, is returned.
catclose ?-fail | -nofail? cathandle
Close the message catalog specified by cathandle.
Normally, errors are ignored. If -fail is speci
fied, any errors closing the message catalog file
are returned. The option -nofail specifies the
default behavior of not returning an error. The
use of -fail only makes sense if it was also speci
fied in the call to catopen.
tcl ?-qn? ?-f? script? | ?-c command? ?args?
The tcl starts the interactive TclX command interpreter.
The TclX shell provides an environment for writing, debug
ging 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 semicolon-separated series
of commands) is executed, with `argv' containing any args.
The TclX shell is intended as an environment for Tcl pro
gram development 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 command 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. Useful 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. Normally the first argument
that does not start with a `-' is taken as the
script to execute unless the `-c' option is speci
fied. 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 contain series of commands to execute, sepa
rated by `;'. Any following 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
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 dis
played, 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 envi
ronment variable PATH, will be searched for a command of
the same name. If the command is found, it will be exe
cuted 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 devel
oping 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 confusion and mistakes while pro
gramming in Tcl. Scripts should use the Tcl exec or sys
tem 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 program 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 argu
ments 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 func
tion 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.
ing 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 initialization 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
interactively prompting for commands.
tcl_prompt2
Contains code to run to output the prompt used when
interactively 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 message
The tclx_errorHandler command doesn't exist as
built-in part of TclX. Instead, individual appli
cations 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 errorInfo 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 program.
Once the event loop is entered, bgerror will be
called on uncaught errors.
mands 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 with
out 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 pos
sible to continue executing the code in which the
error occurred. This is useful for logging error
Info or e-mailing it to the maintainer.
mainloop
This procedure sets up a top-level event loop.
Events are processed until there are no more active
event sources, at which time the process exits. It
is used to build event oriented programs 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 han
dler is terminated by an EOF, the process will be
exited.
This commands is not useful in wishx, as it auto
matically enters an event loop after processing a
script.
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 struc
tured as a multilevel tree of subjects 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 vir
tual 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 interac
tive commands in the Extended Tcl shell or as an interac
tive 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 sub
jects 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 waiting 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 speci
fied, return to the top-level of the help tree.
Help subject path names may also include ``..''
elements.
helppwd
Displays the current help subject.
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 command).
Extended Tcl supports standard Tcl tclIndex libraries and
package libraries. A package library file can contain mul
tiple independent Tcl packages. A package is a named col
lection 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 pack
ages 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 direc
tory 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
execution of a program is loaded. This can be overridden
with loadlibindex command.
The start of a package is delimited by:
#@package: package_name proc1 ?..procN?
These lines must start in column one. Everything between
the #@package: 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
age file up to the next package line or the end of the
file is a package named directory_stack and that an
attempt to execute either pushd, popd or dirs when the
routine is not already defined will cause the direc
tory_stack portion of the package file to be loaded.
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 management 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 com
mand will also be returned.
buildpackageindex libfilelist
Build index files for package libraries. The argu
ment libfilelist is a list of package libraries.
Each name must end with the suffix .tlib. A corre
sponding .tndx file will be built. The user must
have write access to the directory containing each
library.
convert_lib tclIndex packagelib ?ignore?
Convert a Ousterhout style tclIndex index file and
associate source files into a package library pack
agelib. If packagelib does not have a .tlib exten
sion, 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). Pack
age library indexes along the auto_path are loaded
automatically on the first demand_load; this com
mand 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 permis
sions 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 actu
ally been used from the previously defined package,
the procedures from libfile.tlib will not be
loaded.
auto_packages ?-location?
Returns a list of the names of all defined pack
ages. If -location is specified, a list of pairs of
package name and the .tlib path name, offset and
length of the package within the library.
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.
Man(1) output converted with
man2html