Provided by: tclx8.4-doc_8.4.1-2_all bug

NAME

       TclX - Extended Tcl: Extended command set for Tcl

SYNOPSIS

       package require Tclx

INTRODUCTION

       This  man  page contains the documentation for all of the extensions that are added to Tcl
       by Extended Tcl (TclX).  TclX extends Tcl's capabilities by adding  new  commands  to  it,
       without  changing  the syntax of standard Tcl.  Extended Tcl is a superset of standard Tcl
       and is built alongside the standard Tcl sources.

       Extended  Tcl  was  created  by  Karl  Lehenbauer  and  Mark  Diekhans   and   is   freely
       redistributable for any use without license or fee.

       Available since 1989, Extended Tcl, also known as TclX, not only adds capabilities to Tcl,
       but has also been the source of many of the capabilities  of  the  baseline  Tcl  release,
       including arrays, files, sockets, file events, and date and time handling, among others.

       Extended  Tcl introduces a set of new commands and a user-extensible library of useful Tcl
       procedures, any of which can be automatically loaded on the first attempt to execute it.

       The command descriptions are separated into several sections:

            • General Commands

            • Debugging and Development Commands

            • Unix Access Commands

            • File Commands

            • Network Programming Support

            • File Scanning Commands

            • Math Commands

            • List Manipulation Commands

            • Keyed Lists

            • String and Character Manipulation Commands

            • XPG/3 Message Catalog Commands

            • Help Facility

            • Tcl Loadable Libraries and Packages

GENERAL COMMANDS

       A set of general, useful Tcl commands, includes a command to begin an interactive  session
       with Tcl, a facility for tracing execution, and a looping command.

       dirs   This procedure lists the directories in the directory stack.

       commandloop  ?-async?  ?-interactive  on  |  off  |  tty?  ?-prompt1  cmd?  ?-prompt2 cmd?
       ?-endcommand cmd?

              Create an interactive command loop reading commands from stdin and writing  results
              to  stdout.   Command  loops  are maybe either be blocking or event oriented.  This
              command is useful for Tcl scripts that do not normally converse interactively  with
              a  user  through  a Tcl command interpreter, but which sometimes want to enter this
              mode, perhaps for debugging or user configuration.  The command loop terminates  on
              EOF.

              The following options are available:

              -async A command handler will be associated with stdin.  When input is available on
                     stdin, it will be read and accumulated until a full  command  is  available.
                     That  command  will  then  be  evaluated.  An event loop must be entered for
                     input to be read and processed.

              -interactive on | off | tty
                     Enable or disable interactive command mode.  In interactive  mode,  commands
                     are  prompted  for and the results of comments are printed.  The value maybe
                     any boolean value or tty.  If tty is used, interactive mode  is  enabled  if
                     stdin  is  associated  with a terminal or terminal emulator.  The default is
                     tty.

              -prompt1 cmd
                     If specified, cmd  is used is evaluate and its  result  used  for  the  main
                     command  prompt.   If not specified, the command in tcl_prompt1 is evaluated
                     to output the prompt.  Note the difference in behavior, cmd results is used,
                     while tcl_prompt1 outputs.  This is to allow for future expansion to command
                     loops that write to other than stdout.

              -prompt2 cmd
                     If specified, cmd is used is evaluate and its result used for the  secondary
                     (continuation) command prompt.  If not specified, the command in tcl_prompt2
                     is evaluated to output the prompt.

              -endcommand cmd
                     If specified, cmd is evaluated when the command loop terminates.

                     In interactive mode, the results of set commands with two arguments are  not
                     printed.

                     If  SIGINT  is  configured to generate a Tcl error, it can be used to delete
                     the current command being type without aborting the program in progress.

       echo ?str ...?
              Writes zero or more strings to standard output, followed by a newline.

       infox option

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

              version
                     Return  the version number of Extended Tcl.  The version number for Extended
                     Tcl is generated by combining the base version of the standard Tcl code with
                     another number indicating the version of Extended Tcl being used.

              patchlevel
                     Return the patchlevel for Extended Tcl.

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

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

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

              have_fsync
                     Return  1  if  the  fsync system call is available and the sync command will
                     sync individual files.  0 if it is not available and the sync  command  will
                     always sync all file buffers.

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

              have_msgcats
                     Return 1 if XPG message catalogs are available, 0  if  they  are  not.   The
                     catgets is designed to continue to function without message catalogs, always
                     returning the default string.

              have_posix_signals
                     Return 1 if Posix signals are available (block and unblock options available
                     for the signal command).  0 is returned if Posix signals are not available.

              have_signal_restart
                     Return 1 if restartable signals are available (-restart option available for
                     the  signal  command).   0  is  returned  if  restartable  signals  are  not
                     available.

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

              have_waitpid
                     Return 1 if the waitpid system call is available and the  wait  command  has
                     full functionality.  0 if the wait command has limited functionality.

              appname
                     Return  the symbolic application name of the current application linked with
                     the Extended Tcl library.  The C variable tclAppName  must  be  set  by  the
                     application to return an application specific value for this variable.

              applongname
                     Return  a  natural language name for the current application. The C variable
                     tclLongAppName must be set by  the  application  to  return  an  application
                     specific value for this variable.

              appversion
                     Return  the  version  number  for  the  current application.  The C variable
                     tclAppVersion must be set by  the  application  to  return  an  application-
                     specific value for this variable.

              apppatchlevel
                     Return   the  patchlevel  for  the  current  application.   The  C  variable
                     tclAppPatchlevel must be set by the application to  return  an  application-
                     specific value for this variable.

       for_array_keys var array_name code
              This  procedure performs a foreach-style loop for each key in the named array.  The
              break and continue statements work as with foreach.

       for_recursive_glob var dirlist globlist code
              This procedure performs a foreach-style loop over recursively matched  files.   All
              directories  in  dirlist  are  recursively searched (breadth-first), comparing each
              file found against the file glob patterns in globlist.  For each matched file,  the
              variable var is set to the file path and code is evaluated.  Symbolic links are not
              followed.

       loop var first limit ?increment? body
              Loop is a looping command, similar in behavior to the  Tcl  for  statement,  except
              that  the loop statement achieves substantially higher performance and is easier to
              code when the beginning and ending values  of  a  loop  are  known,  and  the  loop
              variable is to be incremented by a known, fixed amount every time through the loop.

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

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

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

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

       popd   This procedure pops the top directory entry from the directory stack  and  make  it
              the current directory.

       pushd ?dir?
              This  procedure pushes the current directory onto the directory stack and cd to the
              specified directory.  If the directory is not specified, then the current directory
              is pushed, but remains unchanged.

       recursive_glob dirlist globlist
              This  procedure  returns  a  list of recursively matches files.  All directories in
              dirlist are recursively searched (breadth-first), comparing each file found against
              the file glob patterns in globlist.  Symbolic links are not followed.

       showproc ?procname ...?
              This procedure lists the definition of the named procedures.  Loading them if it is
              not already loaded.  If no procedure names are supplied,  the  definitions  of  all
              currently loaded procedures are returned.

       try_eval code catch ?finally?
              The try_eval command evaluates code in the current context.

       If  an  error occurs during the evaluation and catch is not empty, then catch is evaluated
       to handler the error.  The result of the command, containing the error  message,  will  be
       stored  in a global variable errorResult.  The global variables errorResult, errorInfo and
       errorCode will be imported into the current scope, there is no need to  execute  a  global
       command.   The result of the catch command becomes the result of the try_eval command.  If
       the error that caused the catch to be evaluate is to be continued, the  following  command
       should be used:
            error $errorResult $errorCode $errorInfo

       If the finally argument is supplied and not empty, it is evaluated after the evaluation of
       the code and the catch commands.  If an error occurs during the evaluation of the  finally
       command,  it  becomes the result of the try_eval command.  Otherwise, the result of either
       code  or catch is preserved, as described above.

DEBUGGING AND DEVELOPMENT COMMANDS

       This section  contains  information  on  commands  and  procedures  that  are  useful  for
       developing and debugging Tcl scripts.

       cmdtrace level | on ?noeval? ?notruncate? ?procs? ?fileid? ?command cmd?

              Print  a trace statement for all commands executed at depth of level or below (1 is
              the top level).  If on is specified, all commands at any  level  are  traced.   The
              following options are available:

              noeval Causes  arguments  to  be  printed unevaluated.  If noeval is specified, the
                     arguments are  printed  before  evaluation.   Otherwise,  they  are  printed
                     afterwards.

                     If  the command line is longer than 60 characters, it is truncated to 60 and
                     a "..." is postpended to indicate  that  there  was  more  output  than  was
                     displayed.   If  an evaluated argument contains a space, the entire argument
                     will be enclosed inside of braces (`{}') to allow  the  reader  to  visually
                     separate the arguments from each other.

              notruncate
                     Disables the truncation of commands and evaluated arguments.

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

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

              command cmd

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

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

                   cmdtrace on [open cmd.log w]

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

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

              argv   A list of the final argument information that will be passed to the  command
                     after command, variable, and backslash substitution.

              evalLevel
                     The Tcl_Eval call level.

              procLevel
                     The procedure call level.

              The  command should be constructed in such a manner that it will work if additional
              arguments are added in the future.  It is suggested that the command be a proc with
              the final argument being args.

              Tracing  will be turned off while the command is being executed.  The values of the
              errorInfo and errorCode variables will be saved and restored  on  return  from  the
              command.  It is the command's responsibility to preserve all other state.

              If  an  error occurs during the execution of command, an error message is dumped to
              stderr  and  the  tracing  is  disabled.   The  underlying  mechanism   that   this
              functionality is built on does not support returning an error to the interpreter.

       cmdtrace off
              Turn off all tracing.

       cmdtrace depth
              Returns the current maximum trace level, or zero if trace is disabled.

       edprocs ?proc...?
              This procedure writes the named procedures, or all currently defined procedures, to
              a temporary file,  then  calls  an  editor  on  it  (as  specified  by  the  EDITOR
              environment variable, or vi if none is specified), then sources the file back in if
              it was changed.

       profile ?-commands? ?-eval? on

       profile off arrayVar
              This command is used to collect a performance profile of a Tcl script.  It collects
              data at the Tcl procedure level. The number of calls to a procedure, and the amount
              of real and CPU time is collected. Time is also collected for the  global  context.
              The  procedure data is 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
              specified, data on  all  commands  within  a  procedure  is  collected  as  well  a
              procedures.   Multiple  occurrences  of  a  command  within  a  procedure  are  not
              distinguished, but this data may still be useful for 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  (but  not  any  procedures  it
              calls). The list is in the form {count real cpu}.

              Normally,  the variable scope stack is used in reporting where time is spent.  Thus
              upleveled code is reported in the context that it was executed in, not the  context
              that  the  uplevel  was called in.  If the -eval option is specified, the procedure
              evaluation (call) stack is used instead of the procedure  scope  stack.   Upleveled
              code is reported in the context of the procedure that did the uplevel.

              A Tcl procedure profrep is supplied for reducing the data and producing a report.

              On  Windows,  profile  command  only  reports  elapsed  real  time, CPU time is not
              available and is reported as zero.

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

              Listed with indentation below each procedure  or  command  is  the  procedure  call
              stack.   The  first  indented  line  being  the procedure that invoked the reported
              procedure or command.  The next line is the procedure that  invoked  the  procedure
              above it, and so on.  If no indented procedures are shown, the procedure or command
              was called from the global context.  Time actually spent in the global  context  is
              listed  on a line labeled <global>.  Upleveled code is reported in the context that
              it was executed in, not the context that the uplevel was called in.

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

UNIX ACCESS COMMANDS

       These  commands  provide access to many basic Unix facilities, including process handling,
       date and time processing, signal handling and the executing commands via the shell.

       alarm seconds
              Instructs the system to send a SIGALRM signal in the specified number  of  seconds.
              This  is  a  floating point number, so fractions of a section may be specified.  If
              seconds is 0.0, any previous alarm request is canceled.  Only one alarm at  a  time
              may  be  active;  the  command  returns  the number of seconds left in the previous
              alarm.  On systems without the setitimer system call, seconds is rounded up  to  an
              integer number of seconds.

              The alarm command is not available on Windows.

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

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

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

                  kill [id process]

              On Windows, where the fork command is not available, execl starts a new process and
              returns the process id.

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

       fork   Fork  the  current  Tcl  process.   Fork  returns zero to the child process and the
              process number of the child to the parent process.  If the fork fails, a Tcl  error
              is generated.

              If  an  execl is not going to be performed before the child process does output, or
              if a close and dup sequence is going to be performed on stdout or  stderr,  then  a
              flush should be issued against stdout, stderr and any other open output file before
              doing the fork. Otherwise 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 application you must execl before doing any
              window operations in the child or you will receive a BadWindow  error  from  the  X
              server.

              The fork command is not available on Windows.

       id options

              This  command  provides  a means of getting, setting and converting user, group and
              process ids.  The id command has the following options:

              id user ?name?

              id userid ?uid?
                     Set the real and effective user ID to name or uid, if the name (or  uid)  is
                     valid  and permissions allow it.  If the name (or uid) is not specified, the
                     current name (or uid) is returned.

              id convert userid uid

              id convert user name
                     Convert a user ID number to a user name, or vice versa.

              id group ?name?

              id groupid ?gid?
                     Set the real and effective group ID to name or gid, if the name (or gid)  is
                     valid  and  permissions  allow  it.   If  the  group  name  (or  gid) is not
                     specified, the current group name (or gid) is returned.

              id groups

              id groupids
                     Return the current group access list of  the  process.   The  option  groups
                     returns group names and groupids returns id numbers.

              id convert groupid gid

              id convert group name
                     Convert a group ID number to a group name, or vice versa.

              id effective user

              id effective userid
                     Return the effective user name, or effective user ID number, respectively.

              id effective group

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

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

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

              id process
                     Return the process ID of the current process.

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

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

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

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

                     On Windows, only the host and process options are implemented.

       kill ?-pgroup ?signal? idlist

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

              If -pgroup is specified, the numbers in idlist are take as process  group  ids  and
              the signal is sent to all of the process in that process group.  A process group id
              of 0 specifies the current process group.

              On Windows, the kill command is capable  of  terminating  a  process,  but  not  of
              sending an arbitrary signal.

       link ?-sym? srcpath destpath

              Create  a  directory entry, destpath, linking it to the existing file, srcpath.  If
              -sym is specified, a symbolic link, rather than a hard link, is created.  (The -sym
              option is only available on systems that support symbolic links.)

              The  link  command is not available on Windows.  Use the Tcl 8.4+ file link command
              instead.

       nice ?priorityincr?

              Change or return the process priority.  If priorityincr  is  omitted,  the  current
              priority  is  returned.   If  priorityincr  is positive, it is added to the current
              priority level, up to a system defined maximum (normally 19),

              Negative priorityincr values cumulatively increase the program's priority down to a
              system  defined  minimum (normally -19); increasing priority with negative niceness
              values will only work for the superuser.

              The new priority is returned.

              The nice command is not available on Windows.

       readdir ?-hidden? dirPath

              Returns a list containing the contents of the  directory  dirPath.   The  directory
              entries "." and ".." are not returned.

              On  Windows,  -hidden  maybe specified to include hidden files in the result.  This
              flag is ignored on Unix systems.

       signal ?-restart? action siglist ?command?

              Warning:  If signals are being used as an event source (a trap action), rather than
              generating  an  error  to terminate a task; one must use the -restart option.  This
              causes a blocked system call, such as read or waitpid to be restarted  rather  than
              generate  an  error.   Failure  to  do this may results in unexpected errors when a
              signal arrives while in one of these system calls.  When  available,  the  -restart
              option can prevent this problem.

              If  -restart  is specified, restart blocking system calls rather than generating an
              error.  The signal will be handled once the Tcl command that issued the system call
              completes.   The -restart options is not available on all operating systems and its
              use will generate an error when it is not supported.  Use infox have_signal_restart
              to check for availability.

              Specify  the  action  to  take when a Unix signal is received by Extended Tcl, or a
              program that embeds it.  Siglist is a list of either the symbolic or  numeric  Unix
              signal  (the SIG prefix is optional).  Action is one of the following actions to be
              performed on receipt of the signal.  To specify all  modifiable  signals,  use  `*'
              (this will not include SIGKILL and SIGSTOP, as they can not be modified).

              default
                     Perform  system  default  action  when signal is received (see signal system
                     call 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 consisting of the action associated with the signal, a 0  if  the
                     signal  may  be  delivered  (not  block) and a 1 if it is blocked and a flag
                     indicating if restarting of system calls is specified.   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 re-enabled.  After a SIGCHLD signal is received, a
              call to wait must be performed to retrieve the exit status  of  the  child  process
              before issuing another signal SIGCHLD ... command.  For code that is to be portable
              between both types of systems, use this approach.

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

       sleep seconds
              Sleep the Extended Tcl process for seconds seconds.  Seconds,  if  specified  as  a
              decimal number, is truncated to an integer value.

       system cmdstr1 ?cmdstr2...?
              Concatenates   cmdstr1,  cmdstr2 etc with space separators (see the concat command)
              into a single command and then evaluates the  command  using  the  standard  system
              shell.   On Unix systems, this is /bin/sh and on Windows its command.com.  The exit
              code of the command is returned.

              This command differs from the exec  command  in  that  system  doesn't  return  the
              executed  command's  standard  output as the result string, and system goes through
              the Unix shell to provide wild card expansion, redirection, etc, as is normal  from
              an sh command line.

       sync ?fileId?

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

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

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

       times
              Return a list containing the process and child execution times in the form:
                   utime stime cutime cstime
              Also see the times(2) system call manual page.  The values are in milliseconds.

       umask ?octalmask?
              Sets  file-creation  mode  mask  to  the octal value of octalmask.  If octalmask is
              omitted, the current mask is returned.

       wait ?-nohang? ?-untraced? ?-pgroup? ?pid?
              Waits for a process created with the execl command to terminate, either due  to  an
              untrapped  signal or call to exit system call.  If the process id pid is specified,
              they wait on that process, otherwise wait on any child process to terminate.

              If -nohang is specified, then don't block waiting on a process to terminate.  If no
              process  is immediately available, return an empty list.  If -untraced is specified
              then the status of child processes that are stopped, and whose status has  not  yet
              been  reported  since they stopped, are also returned.  If -pgroup is specified and
              pid is not specified, then wait on any child process whose process group ID is they
              same as the calling process. If pid is 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.

              On systems without the waitpid system call,  the  -nohang,  -untraced  and  -pgroup
              options  are  not available.  The infox have_waitpid command maybe use to determine
              if this functionality is available.

FILE COMMANDS

       These commands provide extended file access and  manipulation.   This  includes  searching
       ASCII-sorted  data  files,  copying  files,  duplicating file descriptors, control of file
       access options, retrieving open file status, and creating pipes with the pipe system call.
       Also  linking  files, setting file, process, and user attributes and truncating files.  An
       interface to the select system call is 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 erroneous results will
              occur.

              This command does not work on files containing binary data (bytes of zero).

       chmod [-fileid] mode filelist
              Set permissions of each of the files in the list filelist to mode, where mode is an
              absolute  numeric mode or symbolic permissions as in the UNIX chmod(1) command.  To
              specify a mode as octal, it should be prefixed with a "0" (e.g. 0622).

              If the option -fileid is specified, filelist is a list  of  open  file  identifiers
              rather  than  a  list  of  file  names.   This  option is not available on all Unix
              systems.  Use the infox have_fchmod command to determine if this  functionality  is
              available.

              The chmod command is not available on Windows.

       chown [-fileid] owner | {owner group} filelist
              Set  owner  of each file in the list filelist to owner, which can be a user name or
              numeric user id.  If the first parameter is a list, then the owner is  set  to  the
              first element of the list and the group is set to the second element.  Group can be
              a group name or numeric group id.  If group is {}, then the file group will be  set
              to the login group of the specified user.

              If  the  option  -fileid  is specified, filelist is a list of open file identifiers
              rather than a list of file names.   This  option  is  not  available  on  all  Unix
              systems.   Use  the infox have_fchown command to determine if this functionality is
              available.

              The chown command is not available on Windows.

       chgrp [-fileid] group filelist
              Set the group id of each file in the list filelist to group, which can be either  a
              group name or a numeric group id.

              If  the  option  -fileid  is specified, filelist is a list of open file identifiers
              rather than a list of file names.   This  option  is  not  available  on  all  Unix
              systems.   Use  the infox have_fchown command to determine if this functionality is
              available.

              The chgrp command is not available on Windows.

       dup fileId ?targetFileId?
              Duplicate an open file.  A new file id is opened that addresses the  same  file  as
              fileId.

              If  targetFileId  is  specified,  the  the  file  is dup to this specified file id.
              Normally this is stdin, stdout, or stderr.  The dup command  will  handle  flushing
              output  and  closing  this file.  The new file will be buffered, if its needs to be
              unbuffered, use the fcntl command to set it unbuffered.

              If fileId is a number rather than a Tcl file id, then the  dup  command  will  bind
              that  file  to  a  Tcl file id.  This is useful for accessing files that are passed
              from the parent process.  The  argument  ?targetFileId?  is  not  valid  with  this
              operation.

              On  Windows, only stdin, stdout, or stderr or a non-socket file handle number maybe
              specified for targetFileId.  The dup command does not work on sockets on Windows.

       fcntl fileId attribute ?value?
              This command either sets or clears a file option or returns its current value.   If
              value  is  not  specified,  then  the  current value of attribute is returned.  All
              values are boolean. Some attributes  maybe  only  be  gotten,  not  modified.   The
              following attributes may be specified:

       RDONLY The file is opened for reading only. (Get only)

       WRONLY The file is opened for writing only.  (Get only)

       RDWR   The file is opened for reading and writing.  (Get only)

       READ   If the file is readable. (Get only).

       WRITE  If the file is writable. (Get only).

       APPEND The file is opened for append-only writes.  All writes will be forced to the end of
              the file. (Get or set).

       NONBLOCK
              The file is to be accessed with non-blocking I/O.  See the read system call  for  a
              description of how it affects the behavior of file reads.

       CLOEXEC
              Close  the  file  on an process exec.  If the execl command or some other mechanism
              causes the process to do an exec, the file will be closed if this option is set.

       NOBUF  The file is not buffered. If set, then there no buffering for the file.

       LINEBUF
              Output the file will be line buffered. The buffer will be flushed when a newline is
              written, when the buffer is full, or when input is requested.

       KEEPALIVE
              Keep  a  socket  connection  alive.   If  SIGPIPE  is  enabled,  then it is sent if
              connection is broken and data is written to the socket.  If SIGPIPE is ignored,  an
              error  is  returned  on  the  write.   This attribute is valid only on sockets.  By
              default, SIGPIPE is ignored in Tcl.

              The NONBLOCK, NOBUF and LINEBUF are provided for compatibility with older  scripts.
              Thefconfigure command is preferred method of getting and setting these attributes.

              The APPEND and CLOEXEC options are not available on Windows.

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

              The flock command is not available on Windows 95.  It is available on Windows NT.

       for_file var filename code
              This  procedure  implements  a  loop over the contents of a file.  For each line in
              filename, it sets var to the line and executes code.

              The break and continue commands work as with foreach.

              For example, the command

                   for_file line /etc/passwd {echo $line}

              would echo all the lines in the password file.

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

              The funlock command is not available on Windows 95.  It is available on Windows NT.

       fstat fileId ?item? | ?stat arrayvar?

              Obtain status information about an open file.

              The following keys are used to identify data items:

              atime  The time of last access.

              ctime  The time of last file status change

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

              gid    The group ID of the file's group.

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

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

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

              nlink  The number of links to the file.

              size   The file size in bytes.

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

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

              uid    The user ID of the file's owner.

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

              If stat arrayvar is specified, then  the  information  is  returned  in  the  array
              arrayvar.   Each  of  the above keys indexes an element of the array containing the
              data.

              If only fileId is specified, the command returns the data as a keyed list.

              The following values may be returned only if explicitly asked for, it will  not  be
              returned with the array or keyed list forms:

              remotehost
                     If  fileId  is  a TCP/IP socket connection, then a list is returned with the
                     first element being the remote host IP address.  If the remote host name can
                     be found, it is returned as the second element of the list.  The remote host
                     IP port number is the third element.

              localhost
                     If fileId is a TCP/IP socket connection, then a list is  returned  with  the
                     first  element  being the local host IP address.  If the local host name can
                     be found, it is returned as the second element of the list.  The local  host
                     IP port number is the third element.

       ftruncate [-fileid] file newsize
              Truncate a file to have a length of at most newsize bytes.

              If  the  option -fileid is specified, file is an open file identifier, otherwise it
              is a file path.

              This command is not available or not fully functional if the  underlying  operating
              system  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.

              The -fileid option is not available on Windows.

       lgets fileId ?varName?
              Reads  the next Tcl list from the file given by fileId and discards the terminating
              newline character.  This command differs from the gets command, in  that  it  reads
              Tcl  lists  rather  than lines.  If the list contains newlines or binary data, then
              that newline or bytes of zero will be returned as  part  of  the  result.   Only  a
              newline  not quoted as part of the list indicates the end of the list.  There is no
              corresponding command for outputting lists, as puts will do this correctly.

              If varName is specified, then the line is placed in the variable by that  name  and
              the  return  value  is  a count of the number of characters read (not including the
              newline).  If the end of the file is reached before reading any characters then  -1
              is  returned and varName is set to an empty string.  If varName is specified and an
              error occurs, what ever data was read will be returned in the variable, however the
              resulting string may not be a valid list.

              If  varName  is  not  specified  then  the return value will be the line (minus the
              newline 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.

              The  lgets  command  maybe  used  to  read  and write lists containing binary data,
              however translation must be set to lf or the data maybe corrupted.

              If lgets is currently supported on non-blocking files.

       pipe ?fileId_var_r fileId_var_w?
              Create a pipe.  If fileId_var_r and fileId_var_r are specified, then pipe will  set
              the  a  variable  named  fileId_var_r to contain the fileId of the side of the pipe
              that was opened for reading, and fileId_var_w will contain the fileId of  the  side
              of the pipe that was opened for writing.

              If  the  fileId  variables  are  not specified, then a list containing the read and
              write fileIdw is returned as the result of the command.

       read_file ?-nonewline? fileName

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

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

              The files specified by the readFileIds list are checked to see if data is available
              for  reading.  The  writeFileIds  are  checked if the specified files are clear for
              writing.  The exceptFileIds are checked to see  if  an  exceptional  condition  has
              occurred (typically, an error).  The write and exception checking is most useful on
              devices, 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  becoming  ready,  then  the
              command  returns  an  empty  list.   Otherwise  the command returns a list of three
              elements, each of those elements is a list of the fileIds that  are  ready  in  the
              read, write and exception classes.  If none are ready in a class, then that element
              will be the null list.  For example:

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

              could return

                      {file3 file4} {file6} {}

              or perhaps

                      file3 {} {}

              On Windows, only sockets can be used with the select command.  Pipes,  as  returned
              by the open command, are not supported.

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

NETWORK PROGRAMMING SUPPORT

       TclX  provides  functionality to complement the Tcl socket command.  The host_info command
       is used to get information about a host by name or IP address.  In addition, the fstat and
       fcntl  commands  provide options of querying and controlling connected sockets.  To obtain
       the host name of the system the local system, use the id host command.

       host_info option host
              Obtain information about an Internet host. The argument host can be either  a  host
              name or an IP address.

              The following subcommands are recognized:

              addresses
                     Return the list of IP addresses for host.

              official_name
                     Return official name for host.

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

FILE SCANNING COMMANDS

       These commands provide a facility to scan  files,  matching  lines  of  the  file  against
       regular 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.

              This command does not work on files containing binary data (bytes of zero).

       scanmatch ?-nocase? contexthandle ?regexp? commands

              Specify Tcl commands, to be evaluated when regexp is matched by a scanfile command.
              The  match  is added to the scan context specified by contexthandle.  Any number of
              match statements may be  specified  for  a  give  context.   Regexp  is  a  regular
              expression  (see  the  regexp  command).   If  -nocase  is  specified  as the first
              argument, the pattern is matched regardless of alphabetic case.

              If regexp is not specified, then a default match is specified for the scan context.
              The  default  match  will be executed when a line of the file does not match any of
              the regular expressions in the current scancontext.

              The array matchInfo is  available  to  the  Tcl  code  that  is  executed  when  an
              expression  matches  (or  defaults).   It contains information about the file being
              scanned and where within it the expression was matched.

              matchInfo is local to the top level of the match command unless declared global  at
              that  level by the Tcl global command.  If it is to be used as a global, it must be
              declared global before scanfile is called (since scanfile sets the matchInfo before
              the  match code is executed, a subsequent global will override the local variable).
              The following array entries are available:

              matchInfo(line)
                     Contains the text of the line of the file that was matched.

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

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

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

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

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

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

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

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

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

MATH COMMANDS

       Several  extended  math commands commands make many additional math functions available in
       TclX.  In addition, a set of procedures provide  command  access  to  the  math  functions
       supported by the expr command.

       The  following procedures provide command interfaces to the expr math functions. They take
       the same arguments as the expr functions and may take expressions as arguments.

              abs         acos        asin       atan2
              atan        ceil        cos        cosh
              double      exp         floor      fmod
              hypot       int         log10      log
              pow         round       sin        sinh
              sqrt        tan         tanh

       max num1 ?..numN?

       expr max(num1, num2)
              Returns the argument that has the highest numeric value. Each argument may  be  any
              integer or floating point value.

              This  functionality  is  also  available  as  a  math  function max in the Tcl expr
              command.

       min num1 ?..numN?

       expr min(num1, num2)
              Returns the argument that has the lowest numeric value.  Each argument may  be  any
              integer or floating point value.

              This  functionality  is  also  available  as  a  math  function min in the Tcl expr
              command.

       random limit | seed ?seedval?
              Generate a pseudorandom integer number greater than or equal to zero and less  than
              limit.   If  seed is specified, then the command resets the random number generator
              to a starting point  derived  from  the  seedval.  This  allows  one  to  reproduce
              pseudorandom  number  sequences  for testing purposes.  If seedval is omitted, then
              the seed is set to a value based on current system  state  and  the  current  time,
              providing a reasonably interesting and ever-changing seed.

LIST MANIPULATION COMMANDS

       Extended Tcl provides additional list manipulation commands and procedures.

       intersect lista listb
              Procedure  to return the logical intersection of two lists.  The returned list will
              be sorted.

       intersect3 lista listb
              Procedure to intersects two lists, returning a list containing  three  lists:   The
              first  list  returned is everything in lista that wasn't in listb.  The second list
              contains the intersection of the two lists, and the third  list  contains  all  the
              elements  that  were  in  listb  but  weren't in lista.  The returned lists will be
              sorted.

       lassign list var ?var...?
              Assign successive elements of a list to specified variables.   If  there  are  more
              variable  names  than  fields, the remaining variables are set to the empty string.
              If there are more elements than variables, a list of  the  unassigned  elements  is
              returned.

              For example,

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

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

       lcontain list element
              Determine if the element is a list element of list.  If the element is contained in
              the list, 1 is returned, otherwise, 0 is returned.

       lempty list
              Determine if the specified list is empty.  If empty, 1 is returned, otherwise, 0 is
              returned.  This command is an alternative to comparing a list to an  empty  string,
              however it checks for a string of all whitespaces, which is an empty list.

       lmatch ?mode? list pattern

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

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

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

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

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

              If mode is omitted then it defaults to -glob.

              Only the -exact comparison will work on binary data.

       lrmdups list
              Procedure  to  remove  duplicate  elements  from a list.  The returned list will be
              sorted.

       lvarcat var string ?string...?
              This command treats each string argument as a list and concatenates them to the end
              of  the contents of var, forming a a single list.  The list is stored back into var
              and also returned as the result.  if var does not exist, it is created.

       lvarpop var ?indexExpr? ?string?
              The lvarpop command pops (deletes) the element indexed by the expression  indexExpr
              from  the  list  contained  in  the  variable  var.  If index is omitted, then 0 is
              assumed.  If string, is specified, then the deleted element is replaced by  string.
              The  replaced  or deleted element is returned.  Thus ``lvarpop argv 0'' returns the
              first element of argv, setting argv to contain the remainder of the string.

              If the expression indexExpr starts with the string end, then end is  replaced  with
              the index of the last element in the list.  If the expression starts with len, then
              len is replaced with the length of the list.

       lvarpush var string ?indexExpr?
              The lvarpush command pushes (inserts) string as an element in the list contained in
              the  variable  var.  The element is inserted before position indexExpr in the list.
              If index is omitted, then 0 is assumed.  If var does not exists, it is created.

              If the expression indexExpr starts with the string end, then end is  replaced  with
              the index of the last element in the list.  If the expression starts with len, then
              len is replaced with the length of the list.  Note the a value of end means  insert
              the string before the last element.

       union lista listb
              Procedure  to  return  the logical union of the two specified lists.  Any duplicate
              elements are removed.

KEYED LISTS

       Extended Tcl defines a special type of list referred  to  as  keyed  lists.   These  lists
       provided  a  structured  data  type  built  upon  standard  Tcl  lists.   This  provides a
       functionality similar to structs in the C programming language.

       A keyed list is a list in which each element contains a key and value pair.  These element
       pairs  are stored as lists themselves, where the key is the first element of the list, and
       the value is the second.  The key-value pairs are referred  to  as  fields.   This  is  an
       example of a keyed list:

                  {{NAME {Frank Zappa}} {JOB {musician and composer}}}

       If  the  variable  person  contained the above list, then keylget person NAME would return
       {Frank Zappa}.  Executing the command:

                   keylset person ID 106

       would make person contain

                  {{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}}

       Fields may contain subfields; `.' is the  separator  character.   Subfields  are  actually
       fields  where  the value is another keyed list.  Thus the following list has the top level
       fields ID and NAME, and subfields NAME.FIRST and  NAME.LAST:

                  {ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}

       There is no limit to the recursive depth of subfields, allowing one to build complex  data
       structures.

       Keyed  lists  are  constructed  and  accessed  via  a  number of commands.  All keyed list
       management 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 keys in the keyed list in the variable listvar.  If keys
              is specified, then it is the name of a key field  who's subfield  keys  are  to  be
              retrieve.

       keylset listvar key value ?key2 value2 ...?
              Set  the  value  associated  with  key, in the keyed list contained in the variable
              listvar, to value.  If listvar does not exists, it  is  created.   If  key  is  not
              currently  in the list, it will be added.  If it already exists, value replaces the
              existing value.  Multiple keywords and values may be specified, if desired.

STRING AND CHARACTER MANIPULATION COMMANDS

       The commands provide additional functionality to classify characters,  convert  characters
       between  character  and  numeric  values,  index  into a string, determine the length of a
       string, extract a range of character from a string, replicate a string a number of  times,
       and transliterate a string (similar to the Unix tr program).

       ccollate ?-local? string1 string2
              This  command compares two strings.  If returns -1 if string1 is less than string2,
              0 if they are equal and 1 if string1 is greater than string2.

              If -local is specified,  the  strings  are  compared  according  to  the  collation
              environment of the current locale.

              This command does not work with binary or UTF data.

       cconcat ?string1? ?string2? ?...?
              Concatenate   the   arguments,   returning  the  resulting  string.   While  string
              concatenation is normally performed by the parser, it  is  occasionally  useful  to
              have  a  command  that returns a string.  The is generally useful when a command to
              evaluate is required.  No separators are inserted between the strings.

              This command is UTF-aware.

       cequal string string
              This command compares two strings for  equality.   It  returns  1  if  string1  and
              string2  are  the identical and 0 if they are not.  This command is a short-cut for
              string compare and avoids  the  problems  with  string  expressions  being  treated
              unintentionally as numbers.

              This command is UTF-aware and will also work on binary data.

       cindex string indexExpr
              Returns the character indexed by the expression indexExpr (zero based) from string.

              If  the  expression indexExpr starts with the string end, then end is replaced with
              the index of the last character in the string.  If the expression starts with  len,
              then len is replaced with the length of the string.

              This command is UTF-aware.

       clength string
              Returns the length of string in characters.  This command is a shortcut for:
                  string length string

              This command is UTF-aware.

       crange string firstExpr lastExpr
              Returns  a range of characters from string starting at the character indexed by the
              expression firstExpr (zero-based) until the character  indexed  by  the  expression
              lastExpr.

              If  the  expression  firstExpr  or lastExpr starts with the string end, then end is
              replaced with the index of the last character in the  string.   If  the  expression
              starts with len, then len is replaced with the length of the string.

              This command is UTF-aware.

       csubstr string firstExpr lengthExpr
              Returns  a range of characters from string starting at the character indexed by the
              expression firstExpr (zero-based) for lengthExpr characters.

              If the expression firstExpr or lengthExpr starts with the string end, then  end  is
              replaced  with  the  index  of the last character in the string.  If the expression
              starts with len, then len is replaced with the length of the string.

              This command is UTF-aware.

       ctoken strvar separators
              Parse a token out of a character string.  The string to parse is contained  in  the
              variable  named  strvar.  The string separators contains all of the valid separator
              characters for tokens in the string.  All leading separators are  skipped  and  the
              first  token  is  returned.   The  variable  strvar will be modified to contain the
              remainder of the string following the token.

              This command does not work with binary data.

       ctype ?-failindex var? class string
              ctype determines whether all characters in string are of the specified  class.   It
              returns  1  if  they  are  all of class, and 0 if they are not, or if the string is
              empty.  This command also provides another method  (besides  format  and  scan)  of
              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 the maximum Unicode values.

              ctype ?-failindex var? cntrl string
                     Tests that all characters are  ``control  characters''  as  defined  by  the
                     character set.

              ctype ?-failindex var? digit string
                     Tests that all characters are valid decimal digits, i.e. 0 through 9.

              ctype ?-failindex var? graph string
                     Tests  that all characters within are any character for which ctype print is
                     true, except for space characters.

              ctype ?-failindex var? lower string
                     Tests that all characters are lowercase letters as defined by the  character
                     set.

              ctype ord character
                     Convert  a character into its decimal numeric value.  The first character of
                     the string is converted to its numeric Unicode value.

              ctype ?-failindex var? space string
                     Tests that all characters  are  either  a  space,  horizontal-tab,  carriage
                     return, newline, vertical-tab, or form-feed.

              ctype ?-failindex var? print string
                     Tests that all characters are a space or any character for which ctype alnum
                     or ctype punct is true or other ``printing character''  as  defined  by  the
                     character set.

              ctype ?-failindex var? punct string
                     Tests  that  all  characters are made up of any of the characters other than
                     the ones for which alnum, cntrl, or space is true.

              ctype ?-failindex var? upper string
                     Tests that all characters are uppercase letters as defined by the  character
                     set.

              ctype ?-failindex var? xdigit string
                     Tests that all characters are valid hexadecimal digits, that is 0 through 9,
                     a through f or A through F.

              If -failindex is specified, then the index into string of the first character  that
              did not match the class is returned in var.

       replicate string countExpr
              Returns  string,  replicated  the  number  of  times  indicated  by  the expression
              countExpr.

              This command is UTF-aware and will work with binary data.

       translit inrange outrange string
              Translate characters in string, changing characters occurring  in  inrange  to  the
              corresponding character in outrange. Inrange and outrange may be list of characters
              or a range in the form `A-M'.  For example:
                      translit a-z A-Z foobar

              This command currently only supports characters in ASCII range; UTF-8 characters
              out of this range will generate an error.

XPG/3 MESSAGE CATALOG COMMANDS

       These commands provide a Tcl interface to message catalogs that  are  compliant  with  the
       X/Open Portability Guide, Version 3 (XPG/3).

       Tcl  programmers  can  use  message  catalogs  to  create  applications that are language-
       independent.  Through the use of message catalogs, prompts, messages, menus and  so  forth
       can  exist  for  any  number  of languages, and they can altered, and new languages added,
       without affecting any Tcl or C source code, greatly easing  the  maintenance  difficulties
       incurred by supporting multiple languages.

       A  default  text  message  is  passed  to  the  command  that fetches entries from message
       catalogs.  This allows the Tcl programmer to create message catalogs  containing  messages
       in various languages, but still have a set of default messages available regardless of the
       presence of any message catalogs, and allow the programs to press  on  without  difficulty
       when no catalogs are present.

       Thus,  the  normal  approach  to using message catalogs is to ignore errors on catopen, in
       which case catgets will return the default message that was specified in the call.

       The Tcl message catalog commands normally ignore most  errors.   If  it  is  desirable  to
       detect errors, a special option is provided.  This is normally used only during debugging,
       to insure that message catalogs are being used.  If your Unix implementation does not have
       XPG/3  message  catalog  support,  stubs will be compiled in that will create a version of
       catgets that always returns the default string.  This allows for easy porting of  software
       to environments that don't have support for message catalogs.

       Message  catalogs are global to the process, an application with multiple Tcl interpreters
       within the same process may pass and share message catalog handles.

       catopen ?-fail | -nofail? catname
              Open the message catalog catname.  This may be a relative path name, in which  case
              the  NLSPATH  environment  variable  is  searched  to  find an absolute path to the
              message catalog.  A handle in the form msgcatN is returned.  Normally,  errors  are
              ignored,  and  in  the case of a failed call to catopen, a handle is returned to an
              unopened message catalog.   (This  handle  may  still  be  passed  to  catgets  and
              catclose,  causing catgets to simply return the default string, as described above.
              If the -fail option is specified, an error is returned  if  the  open  fails.   The
              option  -nofail  specifies  the  default  behavior  of  not returning an error when
              catopen fails to open a specified message catalog.  If the  handle  from  a  failed
              catopen is passed to catgets, the default string is returned.

       catgets catHandle setnum msgnum defaultstr
              Retrieve  a  message  form  a  message  catalog.  CatHandle should be a Tcl message
              catalog handle that was returned by catopen.  Setnum is the message set number, and
              msgnum is the message number. If the message catalog was not opened, or the message
              set or message number cannot be found, then  the  default  string,  defaultstr,  is
              returned.

       catclose ?-fail | -nofail? cathandle
              Close  the  message  catalog specified by cathandle.  Normally, errors are ignored.
              If -fail is specified, any errors closing the message catalog  file  are  returned.
              The  option  -nofail specifies the default behavior of not returning an error.  The
              use of -fail only makes sense if it was also specified in the call to catopen.

       mainloop
              This procedure sets up a top-level event loop.  Events are  processed  until  there
              are  no  more active event sources, at which time the process exits.  It is used to
              build event oriented programs using the TclX shell in a style similar to that  used
              with  wish.   If the global variable tcl_interactive exists and has a true value an
              interactive command handler is  started  as  well.    If  the  command  handler  is
              terminated by an EOF, the process will be exited.

HELP FACILITY

       The help facility allows one to look up help pages which where extracted from the standard
       Tcl manual pages and Tcl scripts during Tcl installation.  Help files are structured as  a
       multilevel tree of subjects and help pages.  Help files are found by searching directories
       named help in the directories listed in the auto_path variable.  All of the files  in  the
       list  of  help  directories  form  a  virtual  root  of the help tree.  This method allows
       multiple applications to provide help trees without having the files reside  in  the  same
       directory.

       The help facility can be accessed in two ways, as interactive commands in the Extended Tcl
       shell or as an interactive Tk-based program (if you have built Extended Tcl with Tk).

       To run the Tk-based interactive help program:

           tclhelp ?addpaths?

       Where addpaths are additional paths to search for help directories.  By default, only  the
       auto_path  used  by  tclhelp is search.  This will result in help on Tcl, Extended Tcl and
       Tk.

       The following interactive Tcl commands and options are provided with the help package:

       help
              Help, without arguments, lists of all the help subjects and pages under the current
              help subject.

       help subject
              Displays  all  of  help  pages  and  lower  level subjects (if any exist) under the
              subject subject.

       help subject/helppage
              Display the specified help page.  The help output is passed through a simple  pager
              if  output  exceeds  23  lines, pausing waiting for a return to be entered.  If any
              other character is entered, the output is terminated.

       helpcd ?subject?
              Change the current subject, which is much like  the  Unix  current  directory.   If
              subject  is  not specified, return to the top-level of the help tree.  Help subject
              path names may also include ``..'' elements.

       helppwd
              Displays the current help subject.

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

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

TCL LOADABLE LIBRARIES AND PACKAGES

       Extended  Tcl  supports  standard  Tcl tclIndex libraries and package libraries. A package
       library file can contain  multiple  independent  Tcl  packages.   A  package  is  a  named
       collection of related Tcl procedures and initialization code.

       The  package  library  file  is just a regular Unix text file, editable with your favorite
       text editor, containing packages of Tcl source code. The package library  file  name  must
       have  the  suffix  .tlib.   An  index  file with the same prefix name and the suffix .tndx
       resides the same directory as the .tlib file.  The .tndx  will  be  automatically  created
       whenever it is out of date or missing (provided there is write access to the directory).

       The  variable  auto_path  contains  a list of directories that are searched for libraries.
       The first time an unknown command trap is take, the indexes for the libraries  are  loaded
       into  memory.  If the auto_path variable is changed during execution of a program, it will
       be re-searched. Only the first package of a given name found during  the  execution  of  a
       program is loaded.  This can be overridden with loadlibindex command.

       The start of a package is delimited by:

              #@package: package_name proc1 ?..procN?

       These  lines  must start in column one.  Everything between the #@package: keyword and the
       next #@package: keyword or a #@packend keyword, or the end of the file,  becomes  part  of
       the  named  package.   The specified procedures, proc1..procN, are the entry points of the
       package.  When a command named in a package specification is executed and detected  as  an
       unknown  command,  all code in the specified package will be sourced.  This package should
       define all of the procedures named on the package  line,  define  any  support  procedures
       required by the package and do any package-specific initialization.  Packages declarations
       maybe continued on subsequent lines using standard Tcl backslash line continuations.   The
       #@packend  keyword  is  useful  to  make sure only the minimum required section of code is
       sourced.  Thus for example a large comment block at the beginning of the next  file  won't
       be loaded.

       Care  should  be taken in defining package_name, as the first package found in the path by
       with a given name is loaded.  This can be useful in developing  new  version  of  packages
       installed on the system.

       For example, in a package source file, the presence of the following line:

              #@package: directory_stack pushd popd dirs

       says  that  the  text lines following that line in the package file up to the next package
       line or the end of the file is a package named directory_stack  and  that  an  attempt  to
       execute  either pushd, popd or dirs when the routine is not already defined will cause the
       directory_stack portion of the package file to be loaded.

PACKAGE LIBRARY MANAGEMENT COMMANDS

       Several commands are available for building and managing package libraries.  Commands that
       are  extended  versions  of the standard Tcl library commands are listed here.  All of the
       standard Tcl library management commands and variables are also supported.

       auto_commands ?-loaders?
              Lists the names of all known  loadable  procedures  and  commands  procedures.   If
              -loaders  is  specified, the command that will be executed to load the command will
              also be returned.

       buildpackageindex libfilelist
              Build index files for package libraries.  The argument libfilelist  is  a  list  of
              package  libraries.   Each  name  must  end with the suffix .tlib.  A corresponding
              .tndx file will be built.  The  user  must  have  write  access  to  the  directory
              containing each library.

       convert_lib tclIndex packagelib ?ignore?
              Convert  a  Ousterhout  style tclIndex index file and associate source files into a
              package library packagelib.  If packagelib does not have  a  .tlib  extension,  one
              will be added.  Any files specified in tclIndex that are in the list ignore will be
              skipped.  Files listed in ignore should just be  the  base  file  names,  not  full
              paths.

       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.

       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.