TclX(TCL) TclX(TCL)
NAME
TclX - Extended Tcl: Extended command set for Tcl
SYNOPSIS
package require Tclx
INTRODUCTION
This man page contains the documentation for all of the extensions that are added to Tcl by Extended
Tcl (TclX). TclX extends Tcl's capabilities by adding new commands to it, without changing the syn-tax syntax
tax 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 and Mark Diekhans and is freely redistributable for any
use without license or fee.
Available 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 introduces a set of new commands 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:
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
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 inter-preter, interpreter,
preter, but which sometimes want to enter this mode, perhaps for debugging or user configura-tion. configuration.
tion. 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 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) (continuation)
tion) 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 terminates.
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 application. The following infox com-mand command
mand options are available:
version
Return the version number of Extended Tcl. The version number for Extended Tcl is gen-erated generated
erated by combining the base version of the standard Tcl code with another number indi-cating indicating
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 available. This supports the -fileid option on
the chown and chgrp commands.
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 individ-ual individual
ual 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 available. 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 func-tionality. functionality.
tionality. 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 variable.
applongname
Return a natural language name for the current application. The C variable tclLongApp-Name tclLongAppName
Name 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 application to return an application-specific value for this vari-able. variable.
able.
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. variable.
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 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 down-wards. downwards.
wards.
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 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 execu-tion execution
tion 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 pushes 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 vari-able variable
able 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 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.
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 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 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 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
file. See the description 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 exe-cuted. executed.
cuted. 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 com-mand, command,
mand, 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 command's
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 tempo-rary temporary
rary 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 col-lected collected
lected by bucketing it based on the procedure call stack, this allows determination of how
much time is spent in a particular procedure in each of it's calling contexts.
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
command within a procedure are not distinguished, but this data may still be useful for analy-sis. analysis.
sis.
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 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 proce-dure procedure
dure that did the uplevel.
A Tcl procedure profrep is supplied for reducing the data and producing a report.
On Windows, profile command only reports elapsed 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. 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 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 actu-ally actually
ally 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 proce-dures procedures
dures 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 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 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.
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
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, 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 child process 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 charac-ters characters
ters 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 application 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.
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 number, 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 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 process to its process ID.
id host
Returns the standard host name of the machine the process is executing on.
On Windows, 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 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 process 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 current
rent process group.
On Windows, the kill command is capable of terminating a process, but not of sending an arbi-trary arbitrary
trary signal.
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
available on systems that support symbolic links.)
The link command is not available on Windows. Use the Tcl 8.4+ file link command instead.
nice ?priorityincr?
Change or return the process priority. If priorityincr 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.
readdir ?-hidden? dirPath
Returns a list containing the contents of the directory dirPath. The directory entries "."
and ".." are not returned.
On Windows, -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 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 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 performed 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 documen-tation). documentation).
tation).
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.
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 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 indicating if restarting of system calls is speci-fied. specified.
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 systems
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 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 processes and ignore for processes in the background).
sleep seconds
Sleep the Extended Tcl process for seconds seconds. Seconds, if specified as a decimal num-ber, number,
ber, is truncated to an integer value.
system cmdstr1 ?cmdstr2...?
Concatenates cmdstr1, cmdstr2 etc with space separators (see the concat command) into a sin-gle single
gle command and then evaluates the command using the standard system shell. On Unix systems,
this is /bin/sh and on 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 com-mand's command's
mand's standard output as the result string, and system goes through the Unix shell to provide
wild card 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 process whose process group ID is they same as the calling process. If pid is speci-fied specified
fied 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 sec-ond second
ond 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 command is executed after the process ter-minates, terminates,
minates, then the process status will be reaped by the exec command 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
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 avail-able available
able 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. 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 cri-teria criteria
teria 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).
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.
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.
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.
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.
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 useful for accessing files that are passed from the parent process. The
argument ?targetFileId? is not valid with this operation.
On Windows, 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.
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 bro-ken broken
ken 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. Thefcon-figure Thefconfigure
figure command is preferred method of getting and setting these attributes.
The APPEND and CLOEXEC options are not available on Windows.
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 beginning of the file. If it
is "current", it is relative 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 ori-gin origin
gin 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. readlocks.
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 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 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 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 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 otherwise 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 element 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 ele-ment. element.
ment.
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 identifier, otherwise it is a file
path.
This command is not available or not fully functional if the underlying operating system sup-port support
port is not available. The command infox have_truncate will indicate if this command may
truncate by file path. The command infox have_ftruncate will indicate if this command may
truncate by file id.
The -fileid option is not available on Windows.
lgets fileId ?varName?
Reads the next Tcl list from the file given by fileId and discards 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 charac-ter) character)
ter) 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 transla-tion translation
tion 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 vari-able variable
able 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 returned as the result of the command.
read_file ?-nonewline? fileName
read_file fileName numBytes
This procedure reads the file fileName and returns the contents as a string. If -nonewline is
specified, then the last character 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 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 read-ing. reading.
ing. The writeFileIds are checked if the specified files are clear for writing. The except-FileIds exceptFileIds
FileIds 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 pend-ing pending
ing 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 element 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, 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.
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 pro-vide provide
vide 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 ifconfig(2).)
FILE SCANNING COMMANDS
These commands provide a facility to scan files, matching lines of the file against regular expres-sions expressions
sions 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 expres-sions expressions
sions and commands to execute when that regular expression matches a line of the file. A con-text context
text may also have a single default match, to be applied against lines that do not match any
of the regular expressions. Multiple scan contexts may be defined and they may be reused on
multiple 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 file-handle filehandle
handle 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 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 pat-terns patterns
terns in the scan context specified by contexthandle against it, executing the match commands
corresponding to 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 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 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 avail-able: available:
able:
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 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 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 speci-fications specifications
fications 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 functions available in TclX. In
addition, a set of procedures provide command access to the math functions supported by the expr com-mand. command.
mand.
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 command resets the random number generator to a starting point
derived from the seedval. This allows one to reproduce pseudorandom number sequences for test-ing testing
ing 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 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 second list contains the intersec-tion intersection
tion 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:
-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 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 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 vari-able variable
able 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 ele-ment. element.
ment.
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 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 sec-ond. second.
ond. 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. 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 com-mands commands
mands take the name of the variable containing the keyed list as an argument (i.e. passed by refer-ence), reference),
ence), 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 ret-var retvar
var 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 speci-fied, specified,
fied, 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 nor-mally normally
mally 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 character 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 character 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 vari-able variable
able 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 characters as defined by the char-acter character
acter 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 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 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 characters 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 Porta-bility Portability
bility 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 languages, and they can altered, and new languages added, without affecting any Tcl or C source
code, greatly easing the maintenance difficulties 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 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 normally used only during debugging, to insure that message cat-alogs catalogs
alogs 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 cata-logs. catalogs.
logs.
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
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 cat-gets, catgets,
gets, 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 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
specified, any errors closing the message catalog file are returned. The option -nofail spec-ifies specifies
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.
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 vari-able variable
able 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.
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
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 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 sub-ject. subject.
ject.
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
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 command).
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 proce-dures procedures
dures 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 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 #@pack-age: #@package:
age: 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 pack-age package
age 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 continua-tions. continuations.
tions. 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 directory_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 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 command will also be returned.
buildpackageindex libfilelist
Build index files for package libraries. The argument libfilelist 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 containing 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 lib-file.tlib libfile.tlib
file.tlib has already been loaded, its definition will be overridden by the new package. How-ever, However,
ever, if any procedure has actually been used from the previously defined package, the proce-dures procedures
dures from libfile.tlib will not be loaded.
auto_packages ?-location?
Returns a list of the names of all defined packages. 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.
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)
|