TclX(TCL)                                                            TclX(TCL)

       TclX - Extended Tcl: Extended command set for Tcl

       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

       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

       infox option
              Return information about Extended Tcl, or the current
              application.  The following infox command options are available:

                   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.

                   Return the patchlevel for Extended Tcl.

                   Return 1 if the fchown system call is available.  This
                   supports the -fileid option on the chown and chgrp

                   Return 1 if the fchmod system call is available.  This
                   supports the -fileid option on the chmod command.

                   Return 1 if the flock command defined,  0 if it is not

                   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

                   Return 1 if the ftruncate or chsize system call is
                   available.  If it is, the ftruncate command -fileid option
                   maybe used.

                   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

                   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.

                   Return 1 if sockets are available (server_* suite and fstat
                   localhost and remotehost options).  0 is returned if
                   sockets are not available.

                   Return 1 if the truncate system call is available.  If it
                   is, the ftruncate command may truncate by file path.

                   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.

                   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.

                   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.

                   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

       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

               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

              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

              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

       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? ?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

            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.

                   Disables the truncation of commands and evaluated

            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

              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

       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

       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

              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.

       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

              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

                  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

       chroot dirname
              Change root directory to dirname, by invoking the POSIX
              chroot(2) system call.  This command only succeeds if running as

              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.

              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

            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

            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

            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,

              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

       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.

              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.

       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

              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

              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

              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

              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.

       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

       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

              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.

       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:

                   Contains the text of the line of the file that was matched.

                   The byte offset into the file of the first character of the
                   line that was matched.

                   The line number of the line that was matched. This is
                   relative to the first line scanned, which is usually, but
                   not necessarily, the first line of the file.  The first
                   line is line number one.

                   The context handle of the context that this scan is
                   associated with.

                   The file id (handle) of the file currently being scanned.

                   The file id (handle) of the file specified by the -copyfile
                   option.  The element does not exist if -copyfile was not

                   Will contain the characters matching the first
                   parenthesized subexpression.  The second will be contained
                   in submatch1, etc.

                   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,

       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.

       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.

       Extended Tcl provides additional list manipulation commands and

       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

              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

              -exact The list element must contain exactly the same string as

              -glob Pattern is a glob-style pattern which is matched against
              each list element using the same rules as the string match

              -regexp Pattern is treated as a regular expression and matched
              against each list element using the same rules as the regexp

              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.

       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.

       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

       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.

       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

       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.

              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.

              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.

              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".

              Contains code to run to output the prompt used when
              interactively prompting for commands.

              Contains code to run to output the prompt used when
              interactively prompting for continuation of an incomplete

              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

              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.

       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, 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.

              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

       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

              #@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.

       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

       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

       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

Tcl                                                                  TclX(TCL)