DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

TclX(n)





NAME

       TclX - Extended Tcl: Extended command set for Tcl


SYNOPSIS

       package require Tclx


INTRODUCTION

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

       Extended Tcl was created by Karl Lehenbauer (karl@neosoft.com) and Mark
       Diekhans (markd@grizzly.com) and is freely redistributable for any  use
       without license or fee.

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

       Extended Tcl has three basic functional areas: A set of new commands, a
       Tcl shell (i.e. a Unix shell-style command line and  interactive  envi-
       ronment),   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?
       ?-prompt2 cmd? ?-endcommand cmd?

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

              The following options are available:

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

              -interactive on | off | tty
                     Enable  or disable interactive command mode.  In interac-
                     tive 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 std-
                     out.

              -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 ter-
                     minates.

                     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  applica-
              tion.  The following infox command options are available:

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

              patchlevel
                     Return the patchlevel for Extended Tcl.

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

              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 avail-
                     able.  If it is, the  ftruncate  command  -fileid  option
                     maybe used.

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

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

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

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

              have_waitpid
                     Return  1 if the waitpid system call is available and the
                     wait command has full functionality.  0 if the wait  com-
                     mand 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  applica-
                     tion.  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  applica-
                     tion  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  vari-
                     able.

       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 con-
              tain the loop index.  The loop index is set to the value  speci-
              fied 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  parame-
              ters 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.

       try_eval code catch ?finally?

              The try_eval command evaluates code in the current context.

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

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


DEBUGGING AND DEVELOPMENT COMMANDS

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

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

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

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

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

              notruncate
                     Disables  the  truncation of commands and evaluated argu-
                     ments.

              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 mon-
                     itored  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 descrip-
                     tion of the functionally below.  This option may  not  be
                     specified with a fileid.

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

                   cmdtrace on [open cmd.log w]

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

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

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

              evalLevel
                     The Tcl_Eval call level.

              procLevel
                     The procedure call level.

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

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

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

       cmdtrace off
              Turn off all tracing.

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

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

       profile ?-commands? ?-eval? on

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

              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  com-
              mand 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 contain-
              ing the procedure call stack.  Element zero is the  top  of  the
              stack,  the  procedure  that  the data is for.  The data in each
              entry is a list consisting of the procedure call count  and  the
              real  time  and  CPU time in milliseconds spent in the procedure
              (but not any procedures it calls).  The  list  is  in  the  form
              {count real cpu}.

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

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

              On Windows 95/NT, profile  command  only  reports  elasped  real
              time, CPU time is not available and is reported as zero.

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

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

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


UNIX ACCESS COMMANDS

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

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

              The alarm command is not available on Windows 95/NT.

       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 exe-
              cuting the Tk version of the exit command.  We suggest using the
              following command to abort Tk applications after an execl  fail-
              ure:

                  kill [id process]

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

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

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

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

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

              The fork command is not available on Windows 95/NT.

       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 num-
                     ber, respectively.

              id effective group

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

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

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

              id process
                     Return the process ID of the current process.

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

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

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

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

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

       kill ?-pgroup ?signal? idlist

              Send a signal to the each process in the list idlist, if permit-
              ted.   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.

              The kill command is not available on Windows 95/NT.

       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 avail-
              able on systems that support symbolic links.)

              The link command is not available on Windows 95/NT.

       nice ?priorityincr?

              Change or return the process priority.  If priorityincr is omit-
              ted, the current priority is returned.  If priorityincr is posi-
              tive, it is added to the current priority level, up to a  system
              defined maximum (normally 19),

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

              The new priority is returned.

              The nice command is not available on Windows 95/NT.

       readdir ?-hidden? dirPath

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

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

       signal ?-restart? action siglist ?command?

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

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

              Specify  the  action  to  take when a Unix signal is received by
              Extended Tcl, or a program that embeds it.  Siglist is a list of
              either  the  symbolic  or numeric Unix signal (the SIG prefix is
              optional).  Action is one of the following actions  to  be  per-
              formed on receipt of the signal.  To specify all modifiable sig-
              nals, 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 exe-
                     cution  if an error is not returned by command.  The com-
                     mand 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 fol-
                     low 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  consist-
                     ing  of the action associated with the signal, a 0 if the
                     signal may be delivered (not block) and  a  1  if  it  is
                     blocked  and  a  flag  indicating if restarting of system
                     calls  is  specified.    The   actions   maybe   one   of
                     `default',`ignore',  `error' or `trap'.  If the action is
                     trap, the third element is the  command  associated  with
                     the  action.   The action `unknown' is returned if a non-
                     Tcl signal handler has been associated with the signal.

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

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

              unblock
                     Allow the specified signal to be received.  Pending  sig-
                     nals 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 with-
              out  Posix  signals.  For these systems, SIGCHLD is not be auto-
              matically 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  pro-
              cesses and ignore for processes in the background).

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

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

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

       sync ?fileId?

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

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

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

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

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

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

              If -nohang is specified, then don't block waiting on  a  process
              to terminate.  If no process is immediately available, return an
              empty list.  If -untraced is specified then the status of  child
              processes  that  are  stopped, and whose status has not yet been
              reported since they stopped, are also returned.  If  -pgroup  is
              specified  and  pid  is  not  specified,  then wait on any child
              process whose process 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 con-
              tains the signal name.  If the process is currently stopped  (on
              systems that support SIGSTP), the second element is `STOP', fol-
              lowed 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  termi-
              nates,  then  the process status will be reaped by the exec com-
              mand 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  functional-
              ity is available.


FILE COMMANDS

       These  commands  provide  extended  file access and manipulation.  This
       includes searching ASCII-sorted data files, copying files,  duplicating
       file  descriptors, control of file access options, retrieving open file
       status, and creating pipes with the pipe  system  call.   Also  linking
       files, setting file, process, and user attributes and truncating files.
       An interface to the select system call is  available  on  Unix  systems
       that support it.

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

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

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

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

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

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

              The chmod command is not available on Windows 95/NT.

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

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

              The chown command is not available on Windows 95/NT.

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

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

              The chgrp command is not available on Windows 95/NT.

       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 speci-
              fied  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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

              The  APPEND  and  CLOEXEC  options  are not available on Windows
              95/NT.

       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  begin-
              ning of the file. If it is "current", it is relative to the cur-
              rent access position in the file.  If it is "end",  then  it  is
              relative to the end-of-file (a negative is before the EOF, posi-
              tive is after).  If origin is omitted, start is assumed.

              The following options are recognized:

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

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

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

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

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

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

              The break and continue commands work as with foreach.

              For example, the command

                   for_file line /etc/passwd {echo $line}

              would echo all the lines in the password file.

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

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

       fstat fileId ?item? | ?stat arrayvar?

              Obtain status information about an open file.

              The following keys are used to identify data items:

              atime  The time of last access.

              ctime  The time of last file status change

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

              gid    The group ID of the file's group.

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

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

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

              nlink  The number of links to the file.

              size   The file size in bytes.

              tty    If the file is associated with a terminal, then 1  other-
                     wise 0.

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

              uid    The user ID of the file's owner.

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

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

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

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

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

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

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

              If the option -fileid is specified, file is an open file identi-
              fier, 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 com-
              mand infox have_truncate will indicate if this command may trun-
              cate  by file path.  The command infox have_ftruncate will indi-
              cate if this command may truncate by file id.

              The -fileid option is not available on Windows 95/NT.

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

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

              If varName is not specified then the return value  will  be  the
              line (minus the newline character) or an empty string if the end
              of the file is reached before reading any characters.  An  empty
              string  will  also  be returned if a line contains no characters
              except the newline, so eof may have to be used to determine what
              really happened.

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

              If lgets is currently supported on non-blocking files.

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

              If  the fileId variables are not specified, then a list contain-
              ing 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  charac-
              ter  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 excep-
              tional 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 ele-
              ment will be the null list.  For example:

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

              could return

                      {file3 file4} {file6} {}

              or perhaps

                      file3 {} {}

              On  Windows 95/NT, only sockets can be used with the select com-
              mand.  Pipes, as returned by the  open  command,  are  not  sup-
              ported.

       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:

              addresses
                     Return the list of IP addresses for host.

              official_name
                     Return official name for host.

              aliases
                     Return the list of aliases for host.   (Note  that  these
                     are  IP number aliases, not DNS CNAME aliases. See ifcon-
                     fig(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.   Multi-
              ple  scan contexts may be defined and they may be reused on mul-
              tiple 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 con-
              text, {} 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 corre-
              sponding to patterns matched.

              If the optional -copyfile argument is specified, the next  argu-
              ment  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 scancon-
              text copyfile command, the file is disassociated from  the  scan
              context at the end of the scan.

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

       scanmatch ?-nocase? contexthandle ?regexp? commands

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

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

              The  array  matchInfo  is available to the Tcl code that is exe-
              cuted 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 asso-
                     ciated 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  -copy-
                     file option.  The element does not exist if -copyfile was
                     not specified.

              matchInfo(submatch0)
                     Will contain the characters matching the first  parenthe-
                     sized  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 func-
       tions available in TclX.  In addition, a set of procedures provide com-
       mand 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  com-
              mand  resets  the  random  number  generator to a starting point
              derived from the seedval. This allows one to  reproduce  pseudo-
              random  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  proce-
       dures.

       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  vari-
              ables  are  set to the empty string.  If there are more elements
              than variables, a list of the unassigned elements is returned.

              For example,

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

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

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

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

       lmatch ?mode? list pattern

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

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

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

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

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

              If mode is omitted then it defaults to -glob.

              Only the -exact comparison will work on binary data.

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

       lvarcat var string ?string...?
              This  command treats each string argument as a list and concate-
              nates 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 pro-
       gramming 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.   Sub-
       fields are actually fields where the value is another keyed list.  Thus
       the following list has the top level fields ID and NAME, and  subfields
       NAME.FIRST and  NAME.LAST:

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

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

       Keyed lists are constructed and accessed via a number of commands.  All
       keyed list management commands take the name of the variable containing
       the keyed list as an argument (i.e. passed by reference),  rather  than
       passing the list directly.

       keyldel listvar key
              Delete  the  field  specified  by key from the keyed list in the
              variable listvar.  This removes both the key and the value  from
              the keyed list.

       keylget listvar ?key? ?retvar | {}?
              Return  the value associated with key from the keyed list in the
              variable listvar.  If retvar is not specified,  then  the  value
              will be returned as the result of the command.  In this case, if
              key is not found in the list, an error will result.

              If retvar is specified and key is in the list, then the value is
              returned in the variable retvar and the command returns 1 if the
              key was present within the list.  If key isn't in the list,  the
              command will return 0, and retvar will be left unchanged.  If {}
              is specified for retvar, the value is not returned, allowing the
              Tcl  programmer to determine if a key is present in a keyed list
              without setting a variable as a side-effect.

              If key is omitted, then a list of all the keys in the keyed list
              is returned.

       keylkeys listvar ?key?
              Return  the a list of the keys in the keyed list in the variable
              listvar.  If keys is specified, then it is the  name  of  a  key
              field  who's subfield keys are to be retrieve.

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


STRING AND CHARACTER MANIPULATION COMMANDS

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

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

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

              This command does not work with binary or UTF data.

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

              This command is UTF-aware.

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

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

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

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

              This command is UTF-aware.

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

              This command is UTF-aware.

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

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

              This command is UTF-aware.

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

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

              This command is UTF-aware.

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

              This command does not work with binary data.

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

              ctype ?-failindex var? alnum string
                     Tests that all characters are alphabetic or numeric char-
                     acters 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  charac-
                     ter.   Number  must be in the range 0 through the maximum
                     Unicode values.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


XPG/3 MESSAGE CATALOG COMMANDS

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

       Tcl  programmers  can  use message catalogs to create applications that
       are  language-independent.   Through  the  use  of  message   catalogs,
       prompts,  messages, menus and so forth can exist for any number of lan-
       guages, and they can altered, and new languages added,  without affect-
       ing  any Tcl or C source code, greatly easing the maintenance difficul-
       ties 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 mes-
       sage 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 nor-
       mally  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  multi-
       ple 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 mes-
              sage number cannot be found, then the default  string,  default-
              str, 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 spec-
              ifies 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 semi-
       colon-separated series of commands) is executed, with `argv' containing
       any args.

       The  TclX  shell is intended as an environment for Tcl program develop-
       ment 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  com-
       mand 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.  Use-
              ful 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.   Nor-
              mally 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 con-
              tain series of commands to execute, separated by `;'.  Any  fol-
              lowing 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 con-
       fusion 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 pro-
              gram 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  exe-
              cute if loaded during an interactive invocation of Tcl.

       auto_path
              Path  to  search  to locate Tcl autoload libraries.  Used by the
              both the Tcl and TclX library autoloading facility.

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

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

       tcl_prompt1
              Contains code to run to output the  prompt  used  when  interac-
              tively prompting for commands.

       tcl_prompt2
              Contains  code  to  run  to output the prompt used when interac-
              tively 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  mes-
              sage
              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 error-
              Info 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 syn-
              chronous 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 pro-
              gram.  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-mail-
              ing it to the maintainer.

       mainloop
              This procedure sets up a top-level event loop.  Events are  pro-
              cessed  until  there  are no more active event sources, at which
              time the process exits.  It is used to build event oriented pro-
              grams  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  sub-
       jects  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 wait-
              ing 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  com-
              mand).


TCL LOADABLE LIBRARIES AND PACKAGES

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

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

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

       The start of a package is delimited by:

              #@package: package_name proc1 ?..procN?

       These lines must start in column one.  Everything between  the  #@pack-
       age: 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  direc-
       tory_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 man-
       agement 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  lib-
              filelist  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 con-
              taining each library.

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

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

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

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

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

Tcl                                                                  TclX(TCL)

Man(1) output converted with man2html