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.