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

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

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

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

               The var argument is the name of a Tcl variable that will contain
              the loop index.  The loop index is set to the value specified by
              first.  The Tcl interpreter is invoked upon body zero or more
              times, where var is incremented by increment every time through
              the loop, or by one if increment is not specified.  Increment can
              be negative in which case the loop will count downwards.

              When var reaches limit, the loop terminates without a subsequent
              execution of body.  For instance, if the original loop parameters
              would cause loop to terminate, say first was one, limit was zero
              and increment was not specified or was non-negative, body is not
              executed at all and loop returns.

              The first, limit and increment are integer expressions.  They are
              only evaulated once at the beginning of the loop.

              If a continue command is invoked within body then any remaining
              commands in the current execution of body are skipped, as in the
              for command.  If a break command is invoked within body then the
              loop command will return immediately.  Loop returns an empty

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

            procs  Enables the tracing of procedure calls only.  Commands that
                   aren't procedure calls (i.e. calls to commands that are
                   written in C, C++ or some object-compatible language) are not
                   traced if the procs option is specified.  This option is
                   particularly useful for greatly reducing the output of
                   cmdtrace while debugging.

            fileid This is a file id as returned by the open command.  If
                   specified, then the trace output will be written to the file
                   rather than stdout.  A stdio buffer flush is done after every
                   line is written so that the trace may be monitored externally
                   or provide useful information for debugging problems that
                   cause core dumps.

            command cmd
                   Call the specified command cmd on when each command is
                   executed instead of tracing to a file.  See the description
                   of the functionally below.  This option may not be specified
                   with a fileid.

       The most common use of this command is to enable tracing to a file during
       the development.  If a failure occurs, a trace is then available when
       needed.  Command tracing will slow down the execution of code, so it
       should be removed when code is debugged.  The following command will
       enable tracing to a file for the remainder of the program:

                cmdtrace on [open cmd.log w]

       The command option causes a user specified trace command to be called for
       each command executed.  The command will have the following arguments
       appended to it before evaluation:

              1) command -A string containing the text of the command, before
              any argument substitution.

              2) argv - A list of the final argument information that will be
              passed to the command after command, variable, and backslash

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

       profile ?-commands? on

       profile off arrayVar
              This command is used to collect a performance profile of a Tcl
              script.  It collects data at the Tcl procedure level. The number
              of calls to a procedure, and the amount of real and CPU time is
              collected. Time is also collected for the global context.  The
              procedure data is collected by bucketing it based on the procedure
              call stack, this allows determination of how much time is spent in
              a particular procedure in each of it's calling contexts.

              The on option enables profile data collection. If the -commands
              option is specifed, data on all commands within a procedure is
              collected as well a procedures.  Multiple occurrences of a command
              within a procedure are not distinguished, but this data may still
              be useful for analysis.

              The off option turns off profiling and moves the data collected to
              the array arrayVar.  The array is address by a list containing the
              procedure call stack.  Element zero is the top of the stack, the
              procedure that the data is for.  The data in each entry is a list
              consisting of the procedure call count and the real time and CPU
              time in milliseconds spent in the procedure (and all procedures it
              called). The list is in the form {count real cpu}.  A Tcl
              procedure profrep is supplied for reducing the data and producing
              a report

       profrep profDataVar sortKey ?outFile? ?userTitle?
              This procedure generates a report from data collect from the
              profile command.  ProfDataVar is the name of the array containing
              the data returned by the profile command. SortKey indicates which
              data value to sort by.  It should be one of "calls", "cpu" or
              "real".  OutFile is the name of file to write the report to.  If
              omitted, stdout is assumed.  UserTitle is an optional title line
              to add to output.

       saveprocs fileName ?proc...?
              This prodcure saves the definition of the named procedure, or all
              currently defined procedures if none is specified, to the named

       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

              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

              convertclock ignores case when parsing all words.  The names of
              the months and days of the week can be abbreviated to their first
              three letters, with optional trailing period.  Periods are ignored
              in any timezone or meridian values.

              Note that convertclock will convert symbolic time-zone names, but
              these are not standardized and there are conflicts with various
              parts of the world.  Use GMT when trying to produce a portable
              time that can then be converted back to a numeric value.

              The only dates in the range 1902 and 2037 may be converted.  Some
              examples are:

                  convertclock "14 Feb 92"
                  convertclock "Feb 14, 1992 12:20 PM PST"
                  convertclock "12:20 PM Feb 14, 1992"

       execl ?-argv0 argv0? prog ?arglist?
              Do an execl, replacing the current program (either Extended Tcl or
              an application with Extended Tcl embedded into it) with prog and
              passing the arguments in the list arglist.

              The -argv0 options specifies that argv0 is to be passed to the
              program as argv [0] rather than prog.

              Note: If you are using execl in a Tk application and it fails, you
              may not do anything that accesses the X server or you will receive
              a BadWindow error from the X server.  This includes executing the
              Tk version of the exit command.  We suggest using the following
              command to abort Tk applications after an execl failure:

                  kill [id process]

       fmtclock clockval ?format? ?GMT|{}?
              Converts a Unix integer time value, typically returned by
              getclock, convertclock, or the atime, mtime, or ctime options of
              the file command, to human-readable form.  The format argument is
              a string that describes how the date and time are to be formatted.
              Field descriptors consist of a ``%'' followed by a field
              descriptor character.  All other characters are copied into the
              result.  Valid field descriptors are:

                  %% - Insert a %.
                  %a - Abbreviated weekday name.
                  %A - Full weekday name
                  %b - Abbreviated month name.
                  %B - Full month name.
                  %d - Day of month (01 - 31).
                  %D - Date as %m/%d/%y.
                  %e - Day of month (1-31), no leading zeros.
                  %h - Abbreviated month name.
                  %H - Hour (00 - 23).
                  %I - Hour (00 - 12).
                  %j - Day number of year (001 - 366).
                  %m - Month number (01 - 12).
                  %M - Minute (00 - 59).
                  %n - Insert a new line.
                  %p - AM or PM.
                  %r - Time as %I:%M:%S %p.
                  %R - Time as %H:%M.
                  %S - Seconds (00 - 59).
                  %t - Insert a tab.
                  %T - Time as %H:%M:%S.
                  %U - Week number of year (01 - 52), Sunday is the first
                       day of the week.
                  %w - Weekday number (Sunday = 0).
                  %W - Week number of year (01 - 52), Monday is the first
                       day of the week.
                  %x - Local specific date format.
                  %X - Local specific time format.
                  %y - Year within century (00 - 99).
                  %Y - Year as ccyy (e.g. 1990)
                  %Z - Time zone name.

              If format is not specified, "%a %b %d %H:%M:%S %Z %Y" is used.  If
              GMT is specified, the time will be formated as Greenwich Mean
              Time. If the argument is not specified or is empty, then the local
              timezone will be used as defined by the operating environment.

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

              Fork 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

            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,

            id effective group

            id effective groupid
                   Return the effective group name, or effective group ID
                   number, respectively.

            id effective groupids
                   Return all of the groupids the user is a member of.

            id host
                   Return the hostname of the system the program is running on.

            id process
                   Return the process ID of the current process.

            id process parent
                   Return the process ID of the parent of the current process.

            id process group
                   Return the process group ID of the current process.

            id process group set
                   Set the process group ID of the current process to its
                   process ID.

            id host
                   Returns the standard host name of the machine the process is
                   executing on.

       kill ?-pgroup ?signal? idlist
              Send a signal to the each process in the list idlist, if
              permitted.  Signal, if present, is the signal number or the
              symbolic name of the signal, see the signal system call manual
              page.  The leading ``SIG'' is optional when the signal is
              specified by its symbolic name.  The default for signo is 15,

              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

              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

              Signals are not processed until after the completion of the Tcl
              command that is executing when the signal is received.  If an
              interactive Tcl shell is running, then the SIGINT will be set to
              error, non-interactive Tcl sessions leave SIGINT unchanged from
              when the process started (normally default for foreground
              processes and ignore for processes in the background).

       sleep seconds
              Sleep the Extended Tcl process for seconds seconds.

       system command
              Executes command via the system(3) call.  Differs from exec in
              that system doesn't return the executed command's standard output
              as the result string, and system goes through the Unix shell to
              provide wildcard expansion, redirection, etc, as is normal from an
              sh command line.  The exit code of the command is returned.

       sync ?fileId?
              If fileId is not specified, or if it is and this system does not
              support the fsync system call, issues a sync system call to flush
              all pending disk output.  If fileId is specified and the system
              does support the fsync system call, issues an fsync on the file
              corresponding to the specified Tcl fileId to force all pending
              output to that file out to the disk.

              If fileId is specified, the file must be writable.  A flush will
              be issued against the fileId before the sync.

              The infox have_fsync command can be used to determine if "sync
              fileId" will do a sync or a fsync.

              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

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

              The break and continue commands work as with foreach.

              For example, the command

                   for_file line /etc/passwd {echo $line}

              would echo all the lines in the password file.

       funlock fileId ?start? ?length? ?origin?
              Remove a locked from a file that was previously placed with the
              flock command.  The arguments are the same as for the flock
              command, see that command for more details.

       fstat fileId ?item?|?stat arrayvar?
              Obtain status information about an open file.

              The following keys are used to identify data items:

              o atime - The time of last access.

              o ctime - The time of last file status change

              o dev - The device containing a directory for the file.  This
              value uniquely identifies the file system that contains the file.

              o gid - The group ID of the file's group.

              o ino - The inode number.  This field uniquely identifies the file
              in a given file system.

              o mode - The mode of the file (see the mknod system call).

              o mtime - Time when the data in the file was last modified.

              o nlink - The number of links to the file.

              o size - The file size in bytes.

              o tty - If the file is associated with a terminal, then 1
              otherwise 0.

              o type - The type of the file in symbolic form, which is one of
              the following values: file, directory, characterSpecial,
              blockSpecial, fifo, link, or socket.

              o uid - The user ID of the file's owner.

              If one of these keys is specified as item, then that data item is

              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

       read_file ?-nonewline? fileName
              read_file fileName numBytes
              This proecure reads the file fileName and returns the contents as
              a string.  If -nonewline is specified, then the last character of
              the file is discarded if it is a newline.  The second form
              specifies exactly how many bytes will be read and returned, unless
              there are fewer than numBytes bytes left in the file; in this
              case, all the remaining bytes are returned.

       select readfileIds ?writefileIds? ?exceptfileIds? ?timeout?
              This command allows an Extended Tcl program to wait on zero or
              more files being ready for for reading, writing, have an
              exceptional condition pending, or for a timeout period to expire.
              readFileIds, writeFileIds, exceptFileIds are each lists of
              fileIds, as returned from open, to query.  An empty list ({}) may
              be specified if a category is not used.

              The files specified by the readFileIds list are checked to see if
              data is available for reading. The writeFileIds are checked if the
              specified files are clear for writing.  The exceptFileIds are
              checked to see if an exceptional condition has occured (typically,
              an error).  The write and exception checking is most useful on
              devices, however, the read checking is very useful when
              communicating with multiple processes through pipes.  Select
              considers data pending in the stdio input buffer for read files as
              being ready for reading, the files do.  not have to be unbuffered.

              Timeout is a floating point timeout value, in seconds.  If an
              empty list is supplied (or the parameter is omitted), then no
              timeout is set.  If the value is zero, then the select command
              functions as a poll of the files, returning immediately even if
              none are ready.

              If the timeout period expires with none of the files becomming
              ready, then the command returns an empty list.  Otherwise the
              command returns a list of three elements, each of those elements
              is a list of the fileIds that are ready in the read, write and
              exception classes.  If none are ready in a class, then that
              element will be the null list.  For example:

                      select {file3 file4 file5} {file6 file7} {} 10.5

              could return

                      {file3 file4} {file6} {}

              or perhaps

                      file3 {} {}

       write_file fileName string ?string...?
              This procedure writes the specified strings to the named file.

       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

              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

              o -myport portNumber - Define the port number for your side of the
              connection.  If the port number is already in use, an error will
              be returned.  If the port number is in the privileged range, the
              Tcl program will have to be running as superuser, or an error will
              be returned.

              o -backlog count - Maximum length the queue of pending connections
              may grow to.  If a connection request arrives with the queue full,
              the client may receive an error with an indication of
              ECONNREFUSED, or, if the underlying protocol supports
              retransmission, the request may be ignored so that retries may
              succeed.  Note that on at least some BSD-based systems the backlog
              is silently limited to 5, regardless of the value specified.  The
              default is 5.

              o -reuseaddr - Allow reuse of local addresses.

       server_accept ?options? fileid
              Accept a TCP/IP connection to the server socket associated with
              fileid.  Options are -buf, -nobuf and -twoids.  See the
              server_connect command for a description of these options.  A file
              handle (or a pair of file handles when -twoids) is return.

       server_info addresses host
              server_info official_name host
              server_info aliases host
              Optain information about a TCP/IP server. The argument host can be
              either a host name or an IP address.

              The following subcommands are recognized:

              o addresses - Return the list of IP addresses for host.

              o official_name - Return official name for host.

              o aliases - Return the list of aliases for host.  (Note that these
              are IP number aliases, not DNS CNAME aliases. See ifconfig(2).)

       server_send ?options? fileid string
              Send the specified string to the TCP/IP connection corresponding
              to fileid.  Theserver_send command is provide as an option to puts
              for writing to a socket as it is better at detecting lost
              connections and other IP-related error conditions.  File buffering
              is ignored for server_send. There is no need to flush after a
              server_send.  The results of mixing server_send with puts without
              flushing the puts output is indeterminate.

              Options are:

              o -nonewline - Don't append a newline character to the end of the
              message.  The default is to append a newline character.

              o -dontroute - Requests that routing be bypassed and the direct
              interface used (usually used only by diagnostic or routing

              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,

                   Will contain the a list of the starting and ending indices of
                   the string matching the first parenthesized subexpression.
                   The second will be contained in subindex1, etc.

       All scanmatch patterns that match a line will be processed in the order
       in which their specifications were added to the scan context.  The
       remainder of the scanmatch pattern-command pairs may be skipped for a
       file line if a continue is executed by the Tcl code of a preceding,
       matched pattern.

       If a return is executed in the body of the match command, the scanfile
       command currently in progress returns, with the value passed to return as
       its return value.

       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

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

              For example,

                 lassign {dave 100 200 {Dave Foo}} name uid gid longName

              Assigns name to ``dave'', uid to ``100'', gid to ``200'', and
              longName to ``Dave Foo''.

       lempty list
              Determine if the specified list is empty.  If empty, 1 is
              returned, otherwise, 0 is returned.  This command is an
              alternative to comparing a list to an empty string.

       lmatch ?mode? list pattern
              Search the elements of list, returning a list of all elements
              matching pattern.  If none match, an empty list is returned.

              The mode argument indicates how the elements of the list are to be
              matched against pattern and it must have one of the following

              -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

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

                  {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

       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

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

              If this variable is set to the name of a procedure, that procedure
              will be call if an uncaught error occurs.  The procedure will be
              passed a single argument of the error message, however to allow
              future expansion, the procedure should have a final argument of
              args.  The procedure is only called in non-interactive shells.  If
              the procedure returns normally, the program will just exit without
              any error being issued by the shell.  Generally the procedure
              should exit with a non-zero exit code once the error has been
              processed.  It is not possible to continue executing the code in
              which the error occurred.  This is useful for logging errorInfo or
              e-mailing it to the maintainer.

              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 ``..''

              Displays the current help subject.

       help help | ?
              Displays help on the help facility at any directory level.

       apropos pattern
              This command locates subjects by searching their one-line
              descriptions for a pattern.  Apropos is useful when you can
              remember part of the name or description of a command, and want to
              search through the one-line summaries for matching lines.  Full
              regular expressions may be specified (see the regexp command).

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

       auto_packages ?-location?
              Returns a list of the names of all defined packages. If -location
              is specified, a list of pairs of package name and the .tlib path
              name, offset and length of the package within the library.

       auto_load_file file
              Source a file, as with the source command, except search auto_path
              for the file.

       searchpath path file
              Search all directories in the specified path, which is a Tcl list,
              for the specified file.  Returns the full path name of the file,
              or an empty string if the requested file could not be found.

Tcl                                                                    TclX(TCL)