# TclX

         NAME
              TclX - Extended Tcl: Extended command set for Tcl

         INTRODUCTION
              This man page contains the  documentation  for  all  of  the
              extensions  that  are added to Tcl 7.4 by Extended Tcl (TclX
              7.4a).  These extensions provide extend  Tcl's  capabilities
              by adding new commands to it, without changing the syntax of
              standard Tcl.  Extended Tcl is a superset  of  standard  Tcl
              and  is  built alongside the standard Tcl sources.  Extended
              Tcl has three basic functional areas: A set of new commands,
              a  Tcl  shell  (i.e.  a  Unix  shell-style  command line and
              interactive environment),  and a user-extensible library  of
              useful  Tcl  procedures,  any  of which can be automatically
              loaded on the first attempt to execute it.

              The  command  descriptions  are   separated   into   several
              sections:

                   o General Commands

                   o Debugging and Development Commands

                   o Unix Access Commands

                   o File Commands

                   o Network Programming Support

                   o File Scanning Commands

                   o Math Commands

                   o List Manipulation Commands

                   o Keyed Lists

                   o String and Character Manipulation Commands

                   o XPG/3 Message Catalog Commands

                   o Extended Tcl Shell

                   o Help Facility

                   o Tcl Loadable Libraries and Packages

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

              dirs This procedure lists the directories in  the  directory
                   stack.

              commandloop ?-async? ?-interactive on|off|tty? ?-
                   prompt1 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  to  make  for  input  to  be
                        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  a  letter  indicating  the  version of
                        Extended   Tcl   being   used.    This   is    the
                        documentation for version 7.4a.

                   patchlevel
                        Return the patchlevel for Extended Tcl.

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

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

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

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

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

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

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

                   have_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 pushs the  current  directory  onto  the
                   directory  stack and cd to the specified directory.  If
                   the  directory  is  not  specified,  then  the  current
                   directory is pushed, but remains unchanged.

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

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

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

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

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

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

                   notruncate
                        Disables the truncation of commands and  evaluated
                        arguments.

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

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

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

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

                     cmdtrace on [open cmd.log w]

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

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

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

                   3) evalLevel - The Tcl_Eval call level.

                   4) procLevel - The procedure call level.

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

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

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

              cmdtrace off
                   Turn off all tracing.

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

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

              profile ?-commands? on

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

                   The on option enables profile data collection.  If  the
                   -commands  option  is  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  (and  all procedures it called). The list is
                   in the form {count real cpu}.  A Tcl procedure  profrep
                   is  supplied  for  reducing  the  data  and producing a
                   report

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

              saveprocs fileName ?proc...?
                   This  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.

              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]

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

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

                   If an execl is not going to  be  performed  before  the
                   child  process  does  output,  or  if  a  close and dup
                   sequence is going to be performed on stdout or  stderr,
                   then  a  flush  should be issued against stdout, stderr
                   and any other open output file before doing  the  fork.
                   Otherwise characters from the parent process pending in
                   the buffers will be output by both the parent and child
                   processes.

                   Note: If you are forking in a Tk based apllication  you
                   must  execl  before  doing any window operations in the
                   child or you will receive a BadWindow error from the  X
                   server.

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

                   id user ?name?

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

                   id convert userid uid

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

                   id group ?name?

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

                   id groups

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

                   id convert groupid gid

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

                   id effective user

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

                   id effective group

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

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

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

                   id process
                        Return the process ID of the current process.

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

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

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

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

              kill ?-pgroup ?signal? idlist
                   Send a signal to the each process in the  list  idlist,
                   if permitted.  Signal, if present, is the signal number
                   or the symbolic name of  the  signal,  see  the  signal
                   system  call  manual  page.   The  leading  ``SIG''  is
                   optional when the signal is specified by  its  symbolic
                   name.  The default for signo is 15, SIGTERM.
                   If -pgroup is specified, the numbers in idlist are take
                   as  process  group ids and the signal is sent to all of
                   the process in that process group.  A process group  id
                   of 0 specifies the current process group.

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

              mkdir ?-path? dirList
                   Create each of the directories  in  the  list  dirList.
                   The mode on the new directories is 777, modified by the
                   umask.  If -path is specified,  then  any  non-existent
                   directories in the specified path(s) are created.

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

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

                   The new priority is returned.

              readdir ?-hidden? dirPath
                   Returns a list containing the contents of the directory
                   dirPath.   The  directory  entries "." and ".." are not
                   returned.
                   On MS Windows systems, -hidden maybe specified  include
                   hidden  files  in  the result.  This flag is ignored on
                   Unix systems.

              rmdir ?-nocomplain? dirList
                   Remove each of the directories in the list dirList.  If
                   -nocomplain is specified, then errors will be ignored.

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

                   default - Perform system default action when signal  is
                   received (see signal system call documentation).

                   ignore - Ignore the signal.

                   error - Generate a catchable Tcl error.  It will be  as
                   if the command that was running returned an error.  The
                   error code will be in the form:
                       POSIX SIG signame
                   For the death of child signal, signame will  always  be
                   SIGCHLD,  rather than SIGCLD, to allow writing portable
                   code.

                   trap - When the  signal  occurs,  execute  command  and
                   continue  execution  if  an  error  is  not returned by
                   command.  The command will be executed  in  the  global
                   context.   The command will be edited before execution,
                   replacing occurrences of "%S"  with  the  signal  name.
                   Occurrences  of  "%%"  result  in  a  single "%".  This
                   editing  occurs  just  before  the  trap   command   is
                   evaluated.  If  an  error  is returned, then follow the
                   standard Tcl error mechanism.  Often command will  just
                   do an exit.

                   get - Retrieve the current settings  of  the  specified
                   signals.   A  keyed list will be returned were the keys
                   are one of the specified signals and the values  are  a
                   list  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. The actions maybe one of
                   `default',`ignore', `error' or `trap.  If the action is
                   trap,  the third element is the command associated with
                   the action.  The action  `unknown'  is  returned  if  a
                   non-Tcl  signal  handler  has  been associated with the
                   signal.

                   set - Set signals from  a  keyed  list  in  the  format
                   returned  by  the get.  For this action, siglist is the
                   keyed list of signal state.  Signals with an action  of
                   `unknown' are not modified.

                   block  -  Block  the  specified  signals   from   being
                   received. (Posix systems only).

                   unblock - Allow the specified signal  to  be  received.
                   Pending signals will not occur. (Posix systems only).

                   The  signal  action  will  remain  enabled  after   the
                   specified  signal  has occurred.  The exception to this
                   is SIGCHLD on systems without Posix signals.  For these
                   systems,  SIGCHLD  is  not  be automatically reenabled.
                   After a SIGCHLD signal is received, a call to wait must
                   be  performed  to retrieve the exit status of the child
                   process  before  issuing  another  signal  SIGCHLD  ...
                   command.   For code that is to be portable between both
                   types of systems, use this approach.

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

              sleep seconds
                   Sleep the Extended Tcl process for seconds seconds.

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

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

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

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

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

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

              unlink ?-nocomplain? filelist
                   Delete (unlink) the files whose names are in  the  list
                   filelist.   If  -nocomplain  is  specified, then errors
                   will be ignored.

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

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

                   Wait returns a  list  containing  three  elements:  The
                   first  element  is  the  process id of the process that
                   terminated.  If the process exited normally, the second
                   element  is  `EXIT', and the third contains the numeric
                   exit code.  If the process terminated due to a  signal,
                   the second element is `SIG', and the third contains the
                   signal name.  If the process is currently  stopped  (on
                   systems  that  support  SIGSTP),  the second element is
                   `STOP', followed by the signal name.

                   Note that it  is  possible  to  wait  on  processes  to
                   terminate  that  were create in the background with the
                   exec command.  However, if any other  exec  command  is
                   executed after the process terminates, then the process
                   status will be reaped by the exec command and will  not
                   be available to the wait command.

                   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  and
              unlinking  files, setting file, process, and user attributes
              and truncating files.  An interface  to  the  select  system
              call is available on Unix systems that support it.

              It should be noted that Tcl file I/O is implemented  on  top
              of  the  stdio  library.   By default, the file is buffered.
              When communicating to a process  through  a  pipe,  a  flush
              command   should   be   issued   to   force  the  data  out.
              Alternatively, the fcntl command may  be  used  to  set  the
              buffering mode of a file to line-buffered or unbuffered.

              bsearch fileId key ?retvar? ?compare_proc?
                   Search an opened file fileId containing lines  of  text
                   sorted  into ascending order for a match.  Key contains
                   the string to match.  If retvar is specified, then  the
                   line  from  the  file  is  returned  in retvar, and the
                   command returns 1 if key was found, and 0 if it wasn't.
                   If  retvar is not specified or is a null name, then the
                   command returns the line that was found,  or  an  empty
                   string if key wasn't found.

                   By default,  the  key  is  matched  against  the  first
                   white-space separated field in each line.  The field is
                   treated  as  an  ASCII  string.   If  compare_proc   is
                   specified,  then it defines the name of a Tcl procedure
                   to evaluate against each line read from the sorted file
                   during   the   execution   of   the   bsearch  command.
                   Compare_proc takes two arguments, the key  and  a  line
                   extracted  from  the  file.  The compare routine should
                   return a number less than zero if the key is less  than
                   the  line, zero if the key matches the line, or greater
                   than zero if the key is greater  than  the  line.   The
                   file must be sorted in ascending order according to the
                   same criteria compare_proc uses to compare the key with
                   the line, or erroneous results will occur.

              copyfile ?-bytes num|-maxbytes num? ?-translate? fromFileId
                   Copies the rest of the file  specified  by  fromFileId,
                   starting   from  its  current  position,  to  the  file
                   specified  by  toFileId,  starting  from  its   current
                   position.   By default, newline translation is disabled
                   for the duration of the copy.

                   If -bytes is specified, then num bytes are copied.   If
                   less   than  num  bytes  are  available,  an  error  is
                   returned.  If -maxbytes is specified,  then  num  bytes
                   are  copied  but  no  error  is  returned  if  less are
                   available.

                   If -translate is specified,  then  newline  translation
                   will not be disabled for the copy.

                   The command returns  the  number  of  bytes  that  were
                   copied.

                   The -bytes option is  particularly  useful  for  mixing
                   binary  data  in  with ASCII commands or data in a data
                   stream.

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

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

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

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

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

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

              dup fileId ?targetFileId?
                   Duplicate an open file.  A new file id is  opened  that
                   addresses the same file as fileId.
                   If targetFileId is specified, the the file  is  dup  to
                   this  specified  file  id.   Normally  this  is  stdin,
                   stdout,  or  stderr.   The  dup  command  will   handle
                   flushing  output  and  closing this file.  The new file
                   will be buffered, if its needs to  be  unbuffered,  use
                   the fcntl command to set it unbuffered.

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

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

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

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

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

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

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

                   APPEND - The file is  opened  for  append-only  writes.
                   All writes will be forced to the end of the file.

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

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

                   NOBUF - The file is not buffered. If set, then there no
                   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.  Note  that  SIGPIPE  is
                   set  to  be ignored by the Tcl library to support pipes
                   to processes in the exec and open commands.  If SIGPIPE
                   is  ignored,  an  error is returned on the write.  This
                   attribute is valid only on sockets.

                   The APPEND, NONBLOCK, and CLOEXEC attributes may be set
                   or cleared by specifying the attribute name and a value
                   1 to set the attribute and 0 to clear it.

              flock options fileId ?start? ?length? ?origin?
                   This command places a lock on all or part of  the  file
                   specified  by  fileId.   The lock is either advisory or
                   mandatory, depending on the mode bits of the file.  The
                   lock  is placed beginning at relative byte offset start
                   for length bytes.  If start or  length  is  omitted  or
                   empty,  zero  is  assumed.  If length is zero, then the
                   lock always extents to end of file, even  if  the  file
                   grows.   If  origin  is  "start",  then  the  offset is
                   relative to  the  beginning  of  the  file.  If  it  is
                   "current",   it  is  relative  to  the  current  access
                   position in the file.  If  it  is  "end",  then  it  is
                   relative  to  the end-of-file (a negative is before the
                   EOF, positive is after).  If origin is  omitted,  start
                   is assumed.

                   The following options are recognized:

                   -read - Place  a  read  lock  on  the  file.   Multiple
                   processes may be accessing the file with read-locks.

                   -write - Place a write lock  on  the  file.   Only  one
                   process  may  be  accessing  a file if there is a write
                   lock.

                   -nowait - If specified, then the process will not block
                   if the lock can not be obtained.  With this option, the
                   command returns 1 if the lock is obtained and 0  if  it
                   is not.

                   See your system's fcntl system call  documentation  for
                   full  details  of  the  behavior  of  file locking.  If
                   locking is being done on ranges of a file, it  is  best
                   to use unbuffered file access (see the fcntl command).

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

                   The break and continue commands work as with foreach.
                   For example, the command

                        for_file line /etc/passwd {echo $line}

                   would echo all the lines in the password file.

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

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

                   The following keys are used to identify data items:

                   o atime - The time of last access.

                   o ctime - The time of last file status change

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

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

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

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

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

                   o nlink - The number of links to the file.

                   o size - The file size in bytes.

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

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

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

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

                   If stat arrayvar is specified, then the information  is
                   returned in the array 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:

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

                   o localhost - If fileId is a TCP/IP socket  connection,
                   then  a  list  is returned with the first element being
                   the local host IP address.  If the local host name  can
                   be  found,  it is returned as the second element of the
                   list.  The local host  IP  port  number  is  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.

              lgets fileId ?varName?
                   Reads the next Tcl list from the file given  by  fileId
                   and  discards  the terminating newline character.  This
                   command differs from the gets command, in that it reads
                   Tcl  lists  rather  than lines.  If the list contains a
                   newline, then that newline will be returned as part  of
                   the  result.   Only a newline not quoted as part of the
                   list indicates the  end  of  the  list.   There  is  no
                   corresponding  command  for  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.

                   If lgets is used on a non-blocking file, blocking  will
                   be  temporarily  enabled  for the duration of the lgets
                   command.    This   is   required   by    the    current
                   implementation  of  the  underlying Tcl I/O system.  In
                   most cases, this will not cause any  problems,  as  the
                   process writing the file should be writing entire lists
                   in one write  operation.    The  only  difficulty  that
                   might  arise  is  if non-blocking I/O was being used to
                   keep two processes from  deadlocking  while  exchanging
                   large amounts of data.

              frename oldPath newPath
                   Renames oldPath to  newPath.   This  command  does  not
                   support renaming across file systems.

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

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

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

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

                   The files specified by the readFileIds list are checked
                   to   see   if   data  is  available  for  reading.  The
                   writeFileIds are checked if  the  specified  files  are
                   clear  for  writing.   The exceptFileIds are checked to
                   see  if   an   exceptional   condition   has   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 {} {}

              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 addresses host
                   host_info official_name host
                   host_info aliases host
                   Obtain information about a internet host. The  argument
                   host can be either a host name or an IP address.

                   The following subcommands are recognized:

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

                   o official_name - Return official name for host.

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

         FILE SCANNING COMMANDS
              These commands provide a facility to  scan  files,  matching
              lines  of the file against regular expressions and executing
              Tcl code on a match.  With this facility you can use Tcl  to
              do  the  sort  of file processing that is traditionally done
              with awk.  And since Tcl's  approach  is  more  declarative,
              some of the scripts that can be rather difficult to write in
              awk are simple to code in Tcl.

              File scanning in Tcl centers around the concept  of  a  scan
              context.    A  scan  context  contains  one  or  more  match
              statements, which associate regular expressions to scan  for
              with  Tcl  code  to  be  executed  when  the expressions are
              matched.

              scancontext ?option?
                   This  command  manages  file  scan  contexts.   A  scan
                   context  is  a  collection  of  regular expressions and
                   commands  to  execute  when  that  regular   expression
                   matches  a line of the file.  A context may also have a
                   single default match, to be applied against lines  that
                   do  not match any of the regular expressions.  Multiple
                   scan contexts may be defined and they may be reused  on
                   multiple  files.   A  scan  context  is identified by a
                   context handle.   The  scancontext  command  takes  the
                   following forms:

              scancontext create
                   Create a new scan context.  The  scanmatch  command  is
                   used   to   define   patterns   in   the   context.   A
                   contexthandle is returned,  which  the  Tcl  programmer
                   uses  to  refer  to  the  newly created scan context in
                   calls to the Tcl file scanning commands.

              scancontext delete contexthandle
                   Delete the scan context  identified  by  contexthandle,
                   and  free  all  of  the  match  statements and compiled
                   regular  expressions  associated  with  the   specified
                   context.

              scancontext copyfile contexthandle ?filehandle?
                   Set or return the file handle that unmatched lines  are
                   copied  to.  (See scanfile).  If filehandle is omitted,
                   the copy file handle is returned.  If no copy  file  is
                   associated with the context, {} is returned.  If a file
                   handle is specified, it becomes the copy file for  this
                   context.  If filehandle is {}, then it removes any copy
                   file specification for the context.

              scanfile ?-copyfile copyFileId? contexthandle fileId
                   Scan the file specified by fileId,  starting  from  the
                   current  file position.  Check all patterns in the scan
                   context  specified   by   contexthandle   against   it,
                   executing  the match commands corresponding to patterns
                   matched.

                   If the optional -copyfile argument  is  specified,  the
                   next  argument  is  a  file  ID  to which all lines not
                   matched by any pattern (excluding the default  pattern)
                   are  to be written.  If the copy file is specified with
                   this flag, instead of using  the  scancontext  copyfile
                   command,  the  file  is  disassociated  from  the  scan
                   context at the end of the scan.

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

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

                   The array matchInfo is available to the Tcl  code  that
                   is  executed  when an expression matches (or defaults).
                   It 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''.

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

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

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

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

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

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

                   If mode is omitted then it defaults to -glob.

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

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

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

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

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

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

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

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

              A keyed list is a list in which each element contains a  key
              and  value  pair.   These  element pairs are stored as lists
              themselves, where the key is the first element of the  list,
              and  the  value  is  the  second.   The  key-value pairs are
              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 amd 1
                   if string1 is greater than string2.

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

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

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

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

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

                       string length string

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

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

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

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

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

              ctype ?-failindex var? class string
                   ctype determines whether all characters in  string  are
                   of  the  specified class.  It returns 1 if they are all
                   of class, and 0 if they are not, or if  the  string  is
                   empty.   This  command  also  provides  another  method
                   (besides format and  scan)  of  converting  between  an
                   ASCII  character  and its numeric value.  The following
                   ctype commands are available:

                   ctype ?-failindex var? alnum string
                        Tests  that  all  characters  are  alphabetic   or
                        numeric  characters  as  defined  by the character
                        set.

                   ctype ?-failindex var? alpha string
                        Tests   that   all   characters   are   alphabetic
                        characters as defined by the character set.

                   ctype ?-failindex var? ascii string
                        Tests that all characters are an  ASCII  character
                        (a non-negative number less than 0200).

                   ctype char number
                        Converts the numeric value, string,  to  an  ASCII
                        character.   Number must be in the range 0 through
                        255.

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

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

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

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

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

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

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

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

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

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

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

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

              translit inrange outrange string
                   Translate characters  in  string,  changing  characters
                   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

                   returns "FOOBAR".

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

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

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

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

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

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

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

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

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

         EXTENDED TCL SHELL
              tcl ?-qn? ?-f? script?|?-c command? ?args?

              The tcl starts the  interactive  TclX  command  interpreter.
              The   TclX   shell  provides  an  environment  for  writing,
              debugging and executing Tcl scripts.  The  functionality  of
              the  TclX  shell  can  be easily obtained by any application
              that includes TclX.

              The tcl command, issued without any  arguments,  invokes  an
              interactive   Tcl  shell,  allowing  the  user  to  interact
              directly with Tcl, executing any Tcl commands  at  will  and
              viewing their results.

              If script is specified, then the  script  is  executed  non-
              interactively  with  any  additional  arguments, args, being
              supplied in the global Tcl variable `argv'.  If  command  is
              supplied,  then  this command (or semicolon-separated series
              of commands) is executed, with `argv' containing any args.

              The TclX shell is intended as an environment for Tcl program
              development  and execution.  While it is not a full-featured
              interactive shell, it provides a comfortable environment for
              the interactive development of Tcl code.

              The following command line flags are recognized by  the  Tcl
              shell command line parser:

              -q   Quick initialization flag.  The Tcl initiaization  file
                   is not evaluated and the auto_path variable is not set.
                   Tcl auto-load libraries will not be available.

              -n   No procedure call stack dump.  The procedure call stack
                   will  not  be  displayed when an error occurs, only the
                   error message.   Useful  in  the  #!  line  of  already
                   debugged scripts.

              -f   Takes the next argument as a script for Tcl to  source,
                   rather  than entering interactive mode.  The -f flag is
                   optional.  Normally the first argument  that  does  not
                   start  with  a  `-'  is  taken as the script to execute
                   unless the `-c' option  is  specified.   Any  following
                   arguments  are  passed to the script via argv, thus any
                   other Tcl shell command-line flags  must  precede  this
                   option.

              -c   Take the next argument as a Tcl command to execute.  It
                   may contain series of commands to execute, separated by
                   `;'.  Any following arguments are passed in argv, thus,
                   as with -f, any other Tcl shell flags must precede this
                   option.

              --   Mark the end of the arguments to  the  Tcl  shell.  All
                   arguments following this are passed in the Tcl variable
                   argv.   This  is  useful  to  pass  arguments   without
                   attempting to execute a Tcl script.

              The result string returned by a command  executed  from  the
              Tcl  shell command line is normally echoed back to the user.
              If an error occurs, then the  string  result  is  displayed,
              along  with  the  error  message.  The error message will be
              preceded by the string ``Error:''.

              The set command is a special case.  If the command is called
              to set a variable (i.e. with two arguments), then the result
              will not be echoed.  If only one argument,  the  name  of  a
              variable,  is  supplied  to  set,  then  the  result will be
              echoed.

              If an unknown Tcl command is entered from the command  line,
              then  the  Unix  command  path, specified in the environment
              variable PATH, will be searched for a command  of  the  same
              name.  If the command is found, it will be executed with any
              arguments remaining on the Tcl command line being passed  as
              arguments  to  the  command.   This  feature  is provided to
              enhance  the  interactive  environment  for  developing  Tcl
              scripts.

              Automatic execution of  programs  in  this  manner  is  only
              supported  from  the command line, not in script files or in
              procedures,  to  reduce   confusion   and   mistakes   while
              programming  in  Tcl.   Scripts  should  use the Tcl exec or
              system commands to run Unix commands.

              The following variables are  set  and/or  used  by  the  Tcl
              shell.

              argv0
                   Contains the name of the Tcl program specified  on  the
                   command line or the name that the Tcl shell was invoked
                   under if no program was  specified.   argc  Contains  a
                   count  of  the  number  of  argv arguments (0 if none).
                   argv A list containing the arguments passed in from the
                   command  line,  excluding  arguments  used  by  the Tcl
                   shell.  The first element is the first passed argument,
                   not the program name.

              tcl_interactive
                   Set to 1 if Tcl shell is invoked interactively, or 0 if
                   the Tcl shell is directly executing a script.  Normally
                   checked by scripts so  that  they  can  function  as  a
                   standalone  application  if  specified  on  the command
                   line, but merely load in  and  not  execute  if  loaded
                   during an interactive invocation of Tcl.

              auto_path
                   Path to search to locate  Tcl  scripts.   Used  by  the
                   auto_load command and the TclX unknown command handler.
                   The path is a Tcl list of directory names.

              tclx_library
                   Path to the TclX runtime library.  If your running  the
                   TclX  shell or an application based on it (like wishx).
                   The TclX initialization file normally adds this to  the
                   auto_path.

              tclx_library_env
                   Name  of  the  environment  variable  the  is  used  to
                   override  the  default  value  for  tclx_library.  This
                   value is normally not set and the  default  environment
                   variable,  TCLX_LIBRARY,  is  used.  If the variable is
                   set to an empty string, no environment override will be
                   allowed.   This  value  must be set before Tclx_Init is
                   called.

              tclx_init
                   Path to the initialization  file  that  Tclx_Init  will
                   evaluate.  This value is normally not set, resulting in
                   the standard init file being evaluated.   If  the  path
                   starts  with  a  "/", its is taken as an absolute path.
                   If it does not start with a "/", its is taken as a path
                   relative to tclx_library.

              tkx_library
                   Path to the TkX runtime library.  This is set  only  if
                   your   application  has  called  Tkx_InitfR.   The  TkX
                   initialization  file  normally   adds   this   to   the
                   auto_path.

              tkx_library_env
                   Name  of  the  environment  variable  the  is  used  to
                   override the default value for tkx_library.  This value
                   is  normally  not  set  and  the  default   environment
                   variable, TKX_LIBRARY, is used.  If the variable is set
                   to an empty string, no  environment  override  will  be
                   allowed.   This  value  must  be set before Tkx_Init is
                   called.

              tkx_init
                   Path to the  initialization  file  that  Tkx_Init  will
                   evaluate.  This value is normally not set, resulting in
                   the standard init file being evaluated.   If  the  path
                   starts  with  a  "/", its is taken as an absolute path.
                   If it does not start with a "/", its is taken as a path
                   relative to tkx_library.

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

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

              TCLXENV
                   Array that  contains  information  used  internally  by
                   various Tcl procedures that are part of the TclX shell.
                   Don't change this  array  unless  you  know  what  your
                   doing.  tclx_errorHandler message
                   The tclx_errorHandler command doesn't exist as built-in
                   part  of  TclX.   Instead,  individual  applications or
                   users  can  define  a tclx_errorHandler  command  (e.g.
                   as  a  Tcl  procedure)  if they wish to handle uncaught
                   errors.  The procedure will be passed a single argument
                   of  the  error  message,  with  errorCode and errorInfo
                   having values reflecting the error that occurred.

                   The tclx_errorHandler command is called when  an  error
                   that  is  not  caught  returns to the top level command
                   evaluation in the TclX shell or wishx.  The  difference
                   between   tclx_errorHandler   and   bgerror   is   that
                   tclx_errorHandler  is  called  during  the  synchronous
                   execution  of  a  script  while  bgerror is called as a
                   result of an uncaught error in an event handler.  In  a
                   non-event oriented Tcl script tclx_errorHandler will be
                   called on all errors that are not caught and bgerror is
                   not  used.   In a wishx script or event oriented script
                   executed with the TclX shell, tclx_errorHandler will be
                   called  on  uncaught errors during the execution of the
                   main script that set up  the  event  oriented  program.
                   Once  the event loop is entered, bgerror will be called
                   on uncaught errors.

                   This procedure is not called in  response  to  commands
                   entered  via an interactive command loop, only from the
                   evaluation of scripts or Tcl commands  passed  via  the
                   command  line.   If the procedure returns normally, the
                   program will just exit without any error  being  issued
                   by the shell.  Generally the procedure should exit with
                   a non-zero exit code once the error has been processed.
                   It  is  not  possible to continue executing the code in
                   which the error occurred.  This is useful  for  logging
                   errorInfo or e-mailing it to the maintainer.

              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.

                   This  commands  is  not  useful   in   wishx,   as   it
                   automatically  enters  an event loop after processing a
                   script.

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

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

              To run the Tk-based interactive help program:

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

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

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

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

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

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

              helppwd
                   Displays the current help subject.

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

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

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

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

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

              The start of a package is delimited by:

                   #@package: package_name proc1 ?..procN?

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

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

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

                   #@package: directory_stack pushd popd dirs

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

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

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

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

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

              auto_load ?command?
                   Attempt to load the specified command from  a  loadable
                   library.  loading the package containing the procedure.
                   If the package indexes have not  been  loaded  for  all
                   package  libraries  in  auto_path, they will be loaded.
                   Out-of-date library indexes will be rebuilt if they are
                   writable.   The  procedure returns 1 if the command was
                   successfully loaded, or 0 if it was not.

                   Duplicated package names are skipped, the first package
                   of  a  given  name found in the path is loaded.  If the
                   auto_path has changed since the last load, indexes will
                   be reloaded (duplicate packages will not be redefined).

                   If command  is  not  specified,  the  indexes  will  be
                   loaded,  if they have not already been loaded or if the
                   auto_path variable has changed, but no command will  be
                   loaded.

              This command overrides the standard  Tcl  procedure  of  the
              same name.

              loadlibindex libfile.tlib
                   Load the package library  index  of  the  library  file
                   libfile  (which  must  have the suffix .tlib).  Package
                   library  indexes  along  the   auto_path   are   loaded
                   automatically on the first demand_load; this command is
                   provided to explicitly load libraries that are  not  in
                   the path.  If the index file (with a .tndx suffix) does
                   not exists or is out of date, it will be rebuilt if the
                   user  has  directory  permissions  to  create  it. If a
                   package with the same name as a package in libfile.tlib
                   has   already  been  loaded,  its  definition  will  be
                   overridden  by  the  new  package.   However,  if   any
                   procedure  has  actually  been used from the previously
                   defined package, the procedures from libfile.tlib  will
                   not be loaded.

                   This  command  will  also  load  an  index   built   by
                   mkindex.tcl  program  supplied with standard Tcl.  This
                   file must be named "tclIndex".

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

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

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