NAME
TclX - Extended Tcl: Extended command set for Tcl
INTRODUCTION
This man page contains the documentation for all of the
extensions that are added to Tcl 7.4 by Extended Tcl (TclX
7.4a). These extensions provide extend 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 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
sections:
o General Commands
o Debugging and Development Commands
o Unix Access Commands
o File Commands
o TCP/IP Server Access
o File Scanning Commands
o Math Commands
o List Maninipulation Commands
o Keyed Lists
o String and Character Manipulation Commands
o XPG/3 Message Catalog Commands
o Extended Tcl Shell
o Help Facility
o Tcl Loadable Libraries and Packages
GENERAL COMMANDS
A set of general, useful Tcl commands, includes a command to
begin an interactive session with Tcl, a facility for
tracing execution, and a looping command.
dirs This procedure lists the directories in the directory
stack.
commandloop ?prompt1? ?prompt2?
Create an interactive command loop for the current TCL
interpreter. This command receives commands from stdin
and executes them. It is useful TCL scripts that do
not normally converse interactively with a user through
a Tcl command interpreter, but which sometimes want to
enter this mode.
Prompt1 is a Tcl command that is evaluated to output a
prompt string. The old value of tcl_prompt1 is saved
and it is set to this value for the duration of the
command loop. Prompt2 is a command that is evaluated
to output the ``downlevel prompt'', which is the prompt
which is issued for continuation input. The old value
of tcl_prompt2 is saved and it is set to this value for
the duration of the command loop.
When the command terminates, the variables for the
prompt hooks will be set to their old value. If these
arguments are not specified, the prompt hooks use their
current value.
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 command options are
available:
version
Return the version number of Extended Tcl. The
version number for Extended Tcl is generated by
combining the base version of the standard Tcl
code with a letter indicating the version of
Extended Tcl being used. This is the
documentation for version 7.4a.
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 individual files. 0 if
it is not available and the sync command will
always sync all file buffers.
have_ftruncate
Return 1 if the ftruncate or chsize system call is
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_sockets
Return 1 if sockets are available (server_* suite
and fstat localhost and remotehost options). 0 is
returned if sockets 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.
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 tclLongAppName must be
set by the application to return an application
specific value for this variable.
appversion
Return the version number for the current
application. The C variable tclAppVersion must be
set by the application to return an application-
specific value for this variable.
apppatchlevel
Return the patchlevel for the current application.
The C variable tclAppPatchlevel must be set by the
application to return an application-specific
value for this variable.
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
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 expressions.
They are only evaulated once at the beginning of the
loop.
If a continue command is invoked within body then any
remaining commands in the current execution of body are
skipped, as in the for command. If a break command is
invoked within body then the loop command will return
immediately. Loop returns an empty string.
popd
This procedure pops the top directory entry from the
directory stack and make it the current directory.
pushd ?dir?
This procedure pushs the current directory onto the
directory stack and cd to the specified directory. If
the directory is not specified, then the current
directory is pushed, but remains unchanged.
recursive_glob dirlist globlist
This procedure returns a list of recursively matches
files. All directories in dirlist are recursively
searched (breadth-first), comparing each file found
against the file glob patterns in globlist. Symbolic
links are not followed.
showproc ?procname ...?
This procedure lists the definition of the named
procedures. Loading them if it is not already loaded.
If no procedure names are supplied, the definitions of
all currently loaded procedures are returned.
This section contains information on commands and procdures
that are useful for developing and debugging Tcl scripts.
cmdtrace level|on ?noeval? ?notruncate? ?procs? ?fileid?
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 executed. The command will have
the following arguments appended to it before evaluation:
1) command -A string containing the text of the
command, before any argument substitution.
2) argv - A list of the final argument information that
will be passed to the command after command, variable,
and backslash substitution.
3) evalLevel - The Tcl_Eval call level.
4) 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 tracing is disabled.
The underlying mechanism that this functionality is built on
does not support returning an error to the interpreter.
cmdtrace off
Turn off all tracing.
cmdtrace depth
Returns the current maximum trace level, or zero if
trace is disabled.
edprocs ?proc...?
This procedure writes the named procedures, or all
currently defined procedures, to a temporary file, then
calls an editor on it (as specified by the EDITOR
environment variable, or vi if none is specified), then
sources the file back in if it was changed.
profile ?-commands? on
profile off arrayVar
This command is used to collect a performance profile
of a Tcl script. It collects data at the Tcl procedure
level. The number of calls to a procedure, and the
amount of real and CPU time is collected. Time is also
collected for the global context. The procedure data
is collected by bucketing it based on the 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 specifed, 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 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 milliseconds spent in the
procedure (and all procedures it called). The list is
in the form {count real cpu}. A Tcl procedure profrep
is supplied for reducing the data and producing a
report
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.
saveprocs fileName ?proc...?
This prodcure saves the definition of the named
procedure, or all currently defined procedures if none
is specified, to the named file.
UNIX ACCESS COMMANDS
These commands provide access to many basic Unix facilities,
including process handling, date and time processing, signal
handling and the executing commands via the shell.
alarm seconds
Instructs the system to send a SIGALRM signal in the
specified number of seconds. This is a floating point
number, so 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.
convertclock dateString ?GMT|{}? ?baseClock?
Convert dateString to an integer clock value (see
getclock). This command can parse and convert
virtually any standard date and/or time string, which
can include standard time zone mnemonics. If only a
time is specified, the current date is assumed. If the
string does not contain a time zone mnemonic, the local
time zone is assumed, unless the GMT argument is
specified, in which case the clock value is calculated
assuming that the specified time is relative to
Greenwich Mean Time.
If baseClock is specified, it should contain an integer
clock value. Only the date in this value is used, not
the time. This is useful for determining the time on a
specific day or doing other date-relative conversions.
The character string consists of zero or more
specifications of the following form:
time - A time of day, which is of the form hh[:mm[:ss]]
[meridian] [zone] or hhmm [meridian] [zone]. If no
meridian is specified, hh is interpreted on a 24-hour
clock.
date - A specific month and day with optional year.
The acceptable formats are mm/dd[/yy], monthname dd[,
yy], dd monthname [yy], and day, dd monthname yy. The
default year is the current year. If the year is less
then 100, then 1900 is added to it.
relative time - A specification relative to the current
time. The format is number unit; acceptable units are
year, fortnight, month, week, day, hour, minute (or
min), and second (or sec). The unit can be specified
as a singular or plural, as in 3 weeks. These
modifiers may also be specified: tomorrow, yesterday,
today, now, last, this, next, ago.
The actual date is calculated according to the
following steps. First, any absolute date and/or time
is processed and converted. Using that time as the
base, day-of-week specifications are added. Next,
relative specifications are used. If a date or day is
specified, and no absolute or relative time is given,
midnight is used. Finally, a correction is applied so
that the correct hour of the day is produced after
allowing for daylight savings time differences.
convertclock ignores case when parsing all words. The
names of the months and days of the week can be
abbreviated to their first three letters, with optional
trailing period. Periods are ignored in any timezone
or meridian values.
Note that convertclock will convert symbolic time-zone
names, but these are not standardized and there are
conflicts with various parts of the world. Use GMT
when trying to produce a portable time that can then be
converted back to a numeric value.
The only dates in the range 1902 and 2037 may be
converted. Some examples are:
convertclock "14 Feb 92"
convertclock "Feb 14, 1992 12:20 PM PST"
convertclock "12:20 PM Feb 14, 1992"
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]
fmtclock clockval ?format? ?GMT|{}?
Converts a Unix integer time value, typically returned
by getclock, convertclock, or the atime, mtime, or
ctime options of the file command, to human-readable
form. The format argument is a string that describes
how the date and time are to be formatted. Field
descriptors consist of a ``%'' followed by a field
descriptor character. All other characters are copied
into the result. Valid field descriptors are:
%% - Insert a %.
%a - Abbreviated weekday name.
%A - Full weekday name
%b - Abbreviated month name.
%B - Full month name.
%d - Day of month (01 - 31).
%D - Date as %m/%d/%y.
%e - Day of month (1-31), no leading zeros.
%h - Abbreviated month name.
%H - Hour (00 - 23).
%I - Hour (00 - 12).
%j - Day number of year (001 - 366).
%m - Month number (01 - 12).
%M - Minute (00 - 59).
%n - Insert a new line.
%p - AM or PM.
%r - Time as %I:%M:%S %p.
%R - Time as %H:%M.
%S - Seconds (00 - 59).
%t - Insert a tab.
%T - Time as %H:%M:%S.
%U - Week number of year (01 - 52), Sunday is the first
day of the week.
%w - Weekday number (Sunday = 0).
%W - Week number of year (01 - 52), Monday is the first
day of the week.
%x - Local specific date format.
%X - Local specific time format.
%y - Year within century (00 - 99).
%Y - Year as ccyy (e.g. 1990)
%Z - Time zone name.
If format is not specified, "%a %b %d %H:%M:%S %Z %Y"
is used. If GMT is specified, the time will be
formated as Greenwich Mean Time. If the argument is not
specified or is empty, then the local timezone will be
used as defined by the operating environment.
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 characters from the parent process pending in
the buffers will be output by both the parent and child
processes.
Note: If you are forking in a Tk based apllication you
must execl before doing any window operations in the
child or you will receive a BadWindow error from the X
server.
getclock
Return the current date and time as a system-dependent
integer value. The unit of the value is seconds,
allowing it to be used for relative time calculations.
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.
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 current process group.
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.)
mkdir ?-path? dirList
Create each of the directories in the list dirList.
The mode on the new directories is 777, modified by the
umask. If -path is specified, then any non-existent
parent directories in the specified path(s) are also
created.
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.
readdir dirPath
Returns a list containing the contents of the directory
dirPath. The directory entries "." and ".." are not
returned.
rmdir ?-nocomplain? dirList
Remove each of the directories in the list dirList. If
-nocomplain is specified, then errors will be ignored.
signal action siglist ?command?
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 documentation).
ignore - Ignore the signal.
error - Generate a catchable Tcl error. It will be as
if the command that was running returned an error. The
error code will be in the form:
POSIX SIG signame
For the death of child signal, signame will always be
SIGCHLD, rather than SIGCLD, to allow writing portable
code.
trap - When the signal occurs, execute command and
continue 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 cosisting of the action associated with the
signal, a 0 if the signal may be delivered (not block)
and a 1 if it is blocked. 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 systems 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.
system command
Executes command via the system(3) call. Differs from
exec in that system doesn't return the executed
command's standard output as the result string, and
system goes through the Unix shell to provide wildcard
expansion, redirection, etc, as is normal from an sh
command line. The exit code of the command is
returned.
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.
unlink ?-nocomplain? filelist
Delete (unlink) the files whose names are in the list
filelist. If -nocomplain is specified, then errors
will be ignored.
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
specfied and pid is not specified, then wait on any
child process whose process groupd ID is they same as
the calling process. 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 command is
executed after the process terminates, then the process
status will be reaped by the exec command and will not
be available to the wait command.
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 and
unlinking files, setting file, process, and user attributes
and truncating files. An interface to the select system
call is available on Unix systems that support it.
It should be noted that Tcl file I/O is implemented on top
of the stdio library. By default, the file is buffered.
When communicating to a process through a pipe, a flush
command should be issued to force the data out.
Alternatively, the fcntl command may be used to set the
buffering mode of a file to line-buffered or unbuffered.
bsearch fileId key ?retvar? ?compare_proc?
Search an opened file fileId containing lines of text
sorted into ascending order for a match. Key contains
the string to match. If retvar is specified, then the
line from the file is returned in retvar, and the
command returns 1 if key was found, and 0 if it wasn't.
If retvar is not specified or is a null name, then the
command returns the line that was found, or an empty
string if key wasn't found.
By default, the key is matched against the first
white-space separated field in each line. The field is
treated as an ASCII string. If compare_proc is
specified, then it defines the name of a Tcl procedure
to evaluate against each line read from the sorted file
during the execution of the bsearch command.
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 errouenous results will occur.
copyfile ?-bytes num|-maxbytes num? fromFileId toFileId
Copies the rest of the file specified by fromFileId,
starting from its current position, to the file
specified by toFileId, starting from its current
position.
If -bytes is specified, then num bytes are copied. If
less than num bytes are available, an error is
returned. If -maxbytes is specified, then num bytes
are copied but no error is returned if less are
available.
The command returns the number of bytes that were
copied.
The -bytes option is particularly useful for mixing
binary data in with ASCII commands or data in a data
stream.
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 functionallity is available.
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 functionallity is available.
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 functionallity is available.
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 usedful for accessing files that are passed
from the parent process. The argument ?targetFileId?
is not valid with this operation.
fcntl fileId attribute ?value?
This command either sets or clears a file option or
returns its current value. If value are not specified,
then the current value of attribute is returned. 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.
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
stdio 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.
The APPEND, NONBLOCK, and CLOEXEC attributes may be set
or cleared by specifying the attribute name and a value
1 to set the attribute and 0 to clear it.
The NOBUF and LINEBUF attributes may only be set (a
value of 1) and only one of the options may be
selected. Once set, it may not be changed. These
options should be set before any I/O operations have
been done on the file or data may be lost.
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 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).
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.
fstat fileId ?item?|?stat arrayvar?
Obtain status information about an open file.
The following keys are used to identify data items:
o atime - The time of last access.
o ctime - The time of last file status change
o dev - The device containing a directory for the file.
This value uniquely identifies the file system that
contains the file.
o gid - The group ID of the file's group.
o ino - The inode number. This field uniquely
identifies the file in a given file system.
o mode - The mode of the file (see the mknod system
call).
o mtime - Time when the data in the file was last
modified.
o nlink - The number of links to the file.
o size - The file size in bytes.
o tty - If the file is associated with a terminal, then
1 otherwise 0.
o type - The type of the file in symbolic form, which
is one of the following values: file, directory,
characterSpecial, blockSpecial, fifo, link, or socket.
o 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 arrrayvar. 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:
o 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 returned
as the this element.
o 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 returned as the
this 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 support 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.
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 a
newline, then that newline 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 outputing 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 not specified then the return value will be
the line (minus the newline character) or an empty
string if the end of the file is reached before reading
any characters. An empty string will also be returned
if a line contains no characters except the newline, so
eof may have to be used to determine what really
happened.
frename oldPath newPath
Renames oldPath to newPath. This command does not
support renaming across file systems.
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 returned as
the result of the command.
read_file ?-nonewline? fileName
read_file fileName numBytes
This proecure reads the file fileName and returns the
contents as a string. If -nonewline is specified, then
the last 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 reading. The
writeFileIds are checked if the specified files are
clear for writing. The exceptFileIds are checked to
see if an exceptional condition has occured (typically,
an error). The write and exception checking is most
useful on devices, however, the read checking is very
useful when communicating with multiple processes
through pipes. Select considers data pending in the
stdio input buffer for read files as being ready for
reading, the files do. not have to be unbuffered.
Timeout is a floating point timeout value, in seconds.
If an empty list is supplied (or the parameter is
omitted), then no timeout is set. If the value is
zero, then the select command functions as a poll of
the files, returning immediately even if none are
ready.
If the timeout period expires with none of the files
becomming 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 {} {}
write_file fileName string ?string...?
This procedure writes the specified strings to the
named file.
TCP/IP SERVER ACCESS
Commands are provided to access TCP/IP-based servers, and to
create them. It is easy to build servers using Extended Tcl
that run under inetd, or even servers that run standalone
and accept and manage multiple simultaneous connections.
The socket file handles maybe be read using the either the
gets or read command and written using either the puts or
server_send command.
The fstat remotehost and fstat localhost requests are useful
both for clients and servers. To obtain the host name of
the system the script is running on, use id host.
If a TclX script is setup to run under inetd, it is launched
with its stdin, stdout and stderr associated with the client
socket. The standard Tcl file ids stdin, stdout and stderr
maybe then be used to communicate with the client.
server_connect ?options? host service
Open a TCP/IP connection to a server of host on the
port specified by service. The server is then accessed
using the standard Tcl file I/O commands. Host may be
a host name or an IP address. Port may be a port
number of a service name.
If a destination host name is supplied and more that
one address is valid for the host, the host's addresses
will be tried in the order returned until one can be
connected to, or the list is exhausted. You may also
use the server_info command to obtain the list of valid
address.
The options are:
o -buf - Specifies that the file is buffered. When
writing to the file, the flush command must be used to
force data in the buffer to be sent to the server.
Buffered access will result in significantly better
performance when reading data, and will also improve
the performance of a series of writes done without
intervening reads. The buffering is only used when
accessing the file via the gets, read, and puts
commands. The server_send command does not use the
buffer.
o -nobuf - The file is unbuffered. A single file id,
open for both reading and writing, is returned.
o -twoids - Return a pair of file ids in a list. The
first id is open for read access, the second for write
access. The close command must be called against both
file ids when you are done using the socket and they
maybe closed independently. This option is primarily
intended to implement compatibility procedures for
deprecated commands, however it maybe useful for code
that needs to independently manage the read and write
ends of the socket.
o -myip ipNumber - Define the IP number for your side
of the connection. This is useful for multi-homed
hosts (hosts with more than one IP address). Note that
only IP addresses corresponding to network interfaces
on your machine may be used. If -myip is not specified,
the operating system will assign the IP number for you.
o -myport portNumber - Define the port number for your
side of the connection. If the port number is already
in use, an error will be returned. If the port number
is in the privileged range, the Tcl program will have
to be running as superuser, or an error will be
returned.
server_create ?options?
Creates a TCP/IP server socket on the local machine. A
file handle is returned upon successful creation. When
a connection request is made to the server, the file
handle becomes read-ready. Connections can be accepted
using server_accept.
The file handle can be detected as read-ready using
select, by using fcntl to make the handle nonblocking
and then calling server_accept, or by using the Tk
fileevent command.
Options are:
o -myip ipNumber - Define the IP number for your side
of the connection. This is useful for multi-homed
hosts (hosts with more than one IP address). Note that
only IP addresses corresponding to network interfaces
on your machine may be used. If -myip is not specified,
the operating system will assign the IP number for you.
o -myport portNumber - Define the port number for your
side of the connection. If the port number is already
in use, an error will be returned. If the port number
is in the privileged range, the Tcl program will have
to be running as superuser, or an error will be
returned.
o -backlog count - Maximum length the queue of pending
connections may grow to. If a connection request
arrives with the queue full, the client may receive an
error with an indication of ECONNREFUSED, or, if the
underlying protocol supports retransmission, the
request may be ignored so that retries may succeed.
Note that on at least some BSD-based systems the
backlog is silently limited to 5, regardless of the
value specified. The default is 5.
o -reuseaddr - Allow reuse of local addresses.
server_accept ?options? fileid
Accept a TCP/IP connection to the server socket
associated with fileid. Options are -buf, -nobuf and
-twoids. See the server_connect command for a
description of these options. A file handle (or a pair
of file handles when -twoids) is return.
server_info addresses host
server_info official_name host
server_info aliases host
Optain information about a TCP/IP server. The argument
host can be either a host name or an IP address.
The following subcommands are recognized:
o addresses - Return the list of IP addresses for host.
o official_name - Return official name for host.
o aliases - Return the list of aliases for host. (Note
that these are IP number aliases, not DNS CNAME
aliases. See ifconfig(2).)
server_send ?options? fileid string
Send the specified string to the TCP/IP connection
corresponding to fileid. Theserver_send command is
provide as an option to puts for writing to a socket as
it is better at detecting lost connections and other
IP-related error conditions. File buffering is ignored
for server_send. There is no need to flush after a
server_send. The results of mixing server_send with
puts without flushing the puts output is indeterminate.
Options are:
o -nonewline - Don't append a newline character to the
end of the message. The default is to append a newline
character.
o -dontroute - Requests that routing be bypassed and
the direct interface used (usually used only by
diagnostic or routing programs)
o -outofband - Send out-of-band data on the socket.
server_cntl fileid attribute [value]
Set or get the value of a socket attribute.
Attributes are:
o KEEPALIVE - Keep connection alive. If SIGPIPE is
enabled, then it is sent if connection is broken and
data is written to the socket. Note that SIGPIPE is
set to be ignored by the Tcl library to support pipes
to processes in the exec and open commands. If SIGPIPE
is ignored, an error is returned on the write. Use
server_send to detect dropped connections reliably,
Boolean value.
If value is specifice, the options is set to that
value. Otherwise, the value is returned.
FILE SCANNING COMMANDS
These commands provide a facility to scan files, matching
lines of the file against regular expressions and executing
Tcl code on a match. With this facility you can use Tcl to
do the sort of file processing that is traditionally done
with awk. And since Tcl's approach is more declarative,
some of the scripts that can be rather difficult to write in
awk are simple to code in Tcl.
File scanning in Tcl centers around the concept of a scan
context. A scan context contains one or more match
statements, which associate regular expressions to scan for
with Tcl code to be executed when the expressions are
matched.
scancontext ?option?
This command manages file scan contexts. A scan
context is a collection of regular expressions and
commands to execute when that regular expression
matches a line of the file. A context may also have a
single default match, to be applied against lines that
do not match any of the regular expressions. 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 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 filehandle is {}, then it removes any copy
file specification for the context.
scanfile ?-copyfile copyFileId? contexthandle fileId
Scan the file specified by fileId, starting from the
current file position. Check all patterns in the scan
context specified by contexthandle against it,
executing the match commands 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.
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 contans information about the file being scanned and
where within it the expression was matched.
matchInfo is local to the top level of the match
command unless declared global at that level by the Tcl
global command. If it is to be used as a global, it
must be declared global before scanfile is called
(since scanfile sets the matchInfo before the match
code is executed, a subsequent global will override the
local variable). The following array entries are
available:
matchInfo(line)
Contains the text of the line of the file that was
matched.
matchInfo(offset)
The byte offset into the file of the first
character of the line that was matched.
matchInfo(linenum)
The line number of the line that was matched. This
is relative to the first line scanned, which is
usually, but not necessarily, the first line of
the file. The first line is line number one.
matchInfo(context)
The context handle of the context that this scan
is 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 specifications were added to the
scan context. The remainder of the scanmatch pattern-
command pairs may be skipped for a file line if a continue
is executed by the Tcl code of a preceding, matched pattern.
If a return is executed in the body of the match command,
the scanfile command currently in progress returns, with the
value passed to return as its return value.
MATH COMMANDS
Several extended math commands commands make many additional
math functions available in TclX. In addition, a set of
procedures provide command access to the math functions
supported by the expr command.
The following procedures provide command interfaces to the
expr math functions. They take the same arguments as the
expr functions and may take expressions as arguments.
abs acos asin atan2
atan ceil cos cosh
double exp floor fmod
hypot int log10 log
pow round sin sinh
sqrt tan tanh
max num1 num2 ?..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 num2 ?..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 testing purposes. If seedval is omitted,
then the seed is set to a value based on current system
state and the current time, providing a reasonably
interesting and ever-changing seed.
LIST MANINIPULATION 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 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''.
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.
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.
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 variable var. The
element is inserted before position indexExpr in the
list. If index is omitted, then 0 is assumed. If var
does not exists, it is created.
If the expression indexExpr starts with the string end,
then end is replaced with the index of the last element
in the list. If the expression starts with len, then
len is replaced with the length of the list. Note the
a value of end means insert the string before the last
element.
union lista listb
Procedure to return the logical union of the two
specified lists. Any duplicate elements are removed.
KEYED LISTS
Extended Tcl defines a special type of list referred to as
keyed lists. These lists provided a structured data type
built upon standard Tcl lists. This provides a
functionality similar to structs in the C 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
refered 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 seperator
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 commands take the name
of the variable containing the keyed list as an argument
(i.e. passed by reference), rather than passing the list
directly.
keyldel listvar key
Delete the field specified by key from the keyed list
in the variable listvar. This removes both the key and
the value from the keyed list.
keylget listvar ?key? ?retvar | {}?
Return the value associated with key from the keyed
list in the variable listvar. If retvar is not
specified, then the value will be returned as the
result of the command. In this case, if key is not
found in the list, an error will result.
If retvar is specified and key is in the list, then the
value is returned in the variable retvar and the
command returns 1 if the key was present within the
list. If key isn't in the list, the command will
return 0, and retvar will be left unchanged. If {} is
specified for retvar, the value is not returned,
allowing the Tcl programmer to determine if a key is
present in a keyed list without setting a variable as a
side-effect.
If key is omitted, then a list of all the keys in the
keyed list is returned.
keylkeys listvar ?key?
Return the a list of the keyes in the keyed list in the
variable listvar. If keys is specified, then it is the
name of a key field who's subfield keys are to be
retrieve.
keylset listvar key value ?key2 value2 ...?
Set the value associated with key, in the keyed list
contained in the variable listvar, to value. If
listvar does not exists, it is created. If key is not
currently in the list, it will be added. If it already
exists, value replaces the existing value. Multiple
keywords and values may be specified, if desired.
STRING AND CHARACTER MANIPULATION COMMANDS
The commands provide additional functionality to classify
characters, convert characters between character and numeric
values, index into a string, determine the length of a
string, extract a range of character from a string,
replicate a string a number of times, and transliterate a
string (similar to the Unix tr program).
ccollate ?-local? string1 string2
This command compares two strings. If returns -1 if
string1 is less than string2, 0 if they are equal amd 1
if string1 is greater than string2.
If -local is specified, the strings are compared
according to the collation environment of the current
locale.
cequal string1 string2
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.
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.
clength string
Returns the length of string in characters. This
command is a shortcut for:
string length string
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.
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.
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.
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 character
set.
ctype ?-failindex var? alpha string
Tests that all characters are alphabetic
characters as defined by the character set.
ctype ?-failindex var? ascii string
Tests that all characters are an ASCII character
(a non-negative number less than 0200).
ctype char number
Converts the numeric value, string, to an ASCII
character. Number must be in the range 0 through
255.
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.
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.
translit inrange outrange string
Translate characters in string, changing characters
occuring 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
returns "FOOBAR".
XPG/3 MESSAGE CATALOG COMMANDS
These commands provide a Tcl interface to message catalogs
that are compliant with the X/Open Portability Guide,
Version 3 (XPG/3).
Tcl programmers can use message catalogs to create
applications that are language-independent. Through the use
of message catalogs, prompts, messages, menus and so forth
can exist for any number of 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 catalogs are being used.
If your Unix implementation does not have XPG/3 message
catalog support, stubs will be compiled in that will create
a version of catgets that always returns the default string.
This allows for easy porting of software to environments
that don't have support for message catalogs.
Message catalogs are global to the process, an application
with 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 catgets, the default string is returned.
catgets catHandle setnum msgnum defaultstr
Retrieve a message form a message catalog. CatHandle
should be a Tcl message catalog handle that was
returned by catopen. Setnum is the message set number,
and msgnum is the message number. If the message
catalog was not opened, or the message set or 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 specifies the default
behavior of not returning an error. The use of -fail
only makes sense if it was also specified in the call
to catopen.
EXTENDED TCL SHELL
tcl ?-qn? ?-f? script?|?-c command? ?args?
Tcl starts the interactive Tcl command interpreter. The Tcl
shell provides an environment for writing, debugging and
executing Tcl scripts. The functionality of the Tcl shell
can be easily obtained by any application that includes Tcl.
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 Tcl shell is intended as an environment for Tcl program
development and execution. While it is not a full-featured
interactive shell, it provides a comfortable environment for
the interactive development of Tcl code. Note that the
package library code described here overrides the unknown
command provided as part of the standard Berkeley Tcl
library facility, although Tcl source libraries coded to
that standard can be loaded and used by Extended Tcl.
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 specified. Any following
arguments are passed to the script via argv, thus any
other Tcl shell command-line flags must precede this
option.
-c Take the next argument as a Tcl command to execute. It
may contain series of commands to execute, separated 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
arguments following this are passed in the Tcl variable
argv. This is useful to pass arguments without
attempting to execute a Tcl script.
The result string returned by a command executed from the
Tcl shell command line is normally echoed back to the user.
If an error occurs, then the string result is displayed,
along with the error message. The error message will be
preceded by the string ``Error:''.
The set command is a special case. If the command is called
to set a variable (i.e. with two arguments), then the result
will not be echoed. If only one argument, the name of a
variable, is supplied to set, then the result will be
echoed.
If an unknown Tcl command is entered from the command line,
then the Unix command path, specified in the environment
variable PATH, will be searched for a command of the same
name. If the command is found, it will be executed with any
arguments remaining on the Tcl command line being passed as
arguments to the command. This feature is provided to
enhance the interactive environment for developing Tcl
scripts.
Automatic execution of programs in this manner is only
supported from the command line, not in script files or in
procedures, to reduce confusion and mistakes while
programming in Tcl. Scripts should use the Tcl exec or
system commands to run Unix commands.
The following variables are set and/or used by the Tcl
shell.
argv0
Contains the name of the Tcl program specified on the
command line or the name that the Tcl shell was invoked
under if no 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 arguments used by the Tcl
shell. The first element is the first passed argument,
not the program name.
tcl_interactive
Set to 1 if Tcl shell is invoked interactively, or 0 if
the Tcl shell is directly executing a script. Normally
checked by scripts so that they can function as a
standalone application if specified on the command
line, but merely load in and not execute if loaded
during an interactive invocation of Tcl.
auto_path
Path to search to locate Tcl scripts. Used by the
auto_load command and the TclX unknown command handler.
The path is a Tcl list of directory names.
tclx_library
Path to the TclX runtime library. If your running the
TclX shell or an appilcation based on it (like wishx),
this is the same value returned by "info library".
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.
tclx_errorHandler
If this variable is set to the name of a procedure,
that procedure will be call if an uncaught error
occurs. The procedure will be passed a single argument
of the error message, however to allow future
expansion, the procedure should have a final argument
of args. The procedure is only called in non-
interactive shells. If the procedure returns normally,
the program will just exit without any error being
issued by the shell. Generally the procedure should
exit with a non-zero exit code once the error has been
processed. It is not possible to continue executing
the code in which the error occurred. This is useful
for logging errorInfo or e-mailing it to the
maintainer.
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.
When Extended Tcl is installed, the standard runtime files
are places in the Tcl master directory, which is configured
when Tcl is built. This master directory normally contains
the Tcl initialization file (TclInit.tcl), the standard Tcl
library file (tcl.tlib) and the help files. The Tcl master
directory is named after the version of Tcl it is associated
with, e.g. /usr/local/tclX/7.4a. The path to the Tcl master
directory is available from the info library command. The
location of the Tcl master directory can be overridden with
the TCL_LIBRARY environment variable.
The first step in initializing the Tcl shell is to locate
the Tcl initialization file, normally TclInit.tcl. If an
environment variable TCLINIT exists, it contains the path to
the Tcl initialization file. If the TCLINIT environment
variable is not set, the file TclInit.tcl is used from the
default Tcl master directory.
Tcl then evaulates the Tcl initialization file. The
auto_path variable is initialized to the Tcl master
directory and may be augmented by the intialization file or
the application. Other procedures and variables used by the
Extended Tcl shell are also defined by this file.
If the Tcl is invoked interactively, it will source a file
named .tclrc in the user's home directory, if it exists.
Tcl is viewed primarily as a programming language, not an
interactive shell, so the .tclrc is intended for use for
loading development utilities, not to support applications,
which should not have to rely on the user's environment in
such a manner.
The Extended Tcl Tk shell, wishx, has an additional master
directory and initialization file. It use the environment
variable TK_LIBRARY to override the default location of the
Tk master directory.
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 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 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 procedures and initialization
code.
The package library file is just a regular Unix text file,
editable with your favorite text editor, containing packages
of Tcl source code. The package library file name must have
the suffix .tlib. An index file with the suffix .tndx,
corresponding to the package library. The .tndx will be
automatically created by Tcl 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
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.
auto_load ?command?
Attempt to load the specified command from a loadable
library. loading the package containing the procedure.
If the package indexes have not been loaded for all
package libraries in auto_path, they will be loaded.
Out-of-date library indexes will be rebuilt if they are
writable. The procedure returns 1 if the command was
sucessfully loaded, or 0 if it was not.
Duplicated package names are skipped, the first package
of a given name found in the path is loaded. If the
auto_path has changed since the last load, indexes will
be reloaded (duplicate packages will not be redefined).
If command is not specified, the indexes will be
loaded, if they have not alreay been loaded or if the
auto_path variable has changed, but no command will be
loaded.
This command overrides the standard Tcl procedure of the
same name.
loadlibindex libfile.tlib
Load the package library index of the library file
libfile (which must have the suffix .tlib). Package
library indexes along the auto_path are loaded
automatically on the first demand_load; this command is
provided to explicitly load libraries that are not in
the path. If the index file (with a .tndx suffix) does
not exists or is out of date, it will be rebuilt if the
user has directory permissions to create it. If a
package with the same name as a package in libfile.tlib
has already been loaded, its definition will be
overridden by the new package. However, if any
procedure has actually been used from the previously
defined package, the procedures from libfile.tlib will
not be loaded.
This command will also load an index built by
mkindex.tcl program supplied with standard Tcl. This
file must be named "tclIndex".
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.