TclX - Extended Tcl: Extended command set for Tcl


INTRODUCTION

       This  man  page  contains the documentation for all of the
       extensions that are added to Tcl 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 environment),  and a user-extensible
       library of useful Tcl procedures,  any  of  which  can  be
       automatically loaded on the first attempt to execute it.

       The  command  descriptions are separated into several sec­
       tions:

            · General Commands

            · Debugging and Development Commands

            · Unix Access Commands

            · File Commands

            · Network Programming Support

            · File Scanning Commands

            · Math Commands

            · List Manipulation Commands

            · Keyed Lists

            · String and Character Manipulation Commands

            · XPG/3 Message Catalog Commands


            · Help Facility

            · Tcl Loadable Libraries and Packages

       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  direc­
              tory 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 ori­
              ented.  This command is useful for Tcl scripts that
              do  not normally converse interactively with a user
              through a Tcl command interpreter, but which  some­
              times  want  to enter this mode, perhaps for debug­
              ging or user configuration.  The command loop  ter­
              minates on EOF.

              The following options are available:

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

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

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

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


              -endcommand cmd
                     If specified, cmd is evaluated when the com­
                     mand loop terminates.

                     In interactive mode, the results of set com­
                     mands 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 pro­
                     gram 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  cur­
              rent  application.   The  following  infox  command
              options are available:

              version
                     Return the version number of  Extended  Tcl.
                     The  version number for Extended Tcl is gen­
                     erated by combining the base version of  the
                     standard  Tcl code with another number indi­
                     cating the version  of  Extended  Tcl  being
                     used.

              patchlevel
                     Return the patchlevel for Extended Tcl.

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

              have_fchmod
                     Return 1 if the fchmod system call is avail­
                     able.  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  avail­
                     able and the sync command will sync individ­
                     ual files.  0 if it is not available and the
                     sync  command  will  always  sync  all  file


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

              have_msgcats
                     Return 1 if XPG message catalogs are  avail­
                     able,  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 avail­
                     able (-restart option available for the sig­
                     nal  command).  0 is returned if restartable
                     signals are not available.

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

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

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

              applongname
                     Return a natural language name for the  cur­
                     rent application. The C variable tclLongApp­
                     Name must  be  set  by  the  application  to
                     return  an  application  specific  value for
                     this variable.

              appversion
                     Return the version number  for  the  current

                     must be set by the application to return  an
                     application-specific  value  for  this vari­
                     able.

              apppatchlevel
                     Return the patchlevel for the current appli­
                     cation.   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 con­
              tinue 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 state­
              ment achieves substantially higher performance  and
              is  easier  to  code  when the beginning and ending
              values of a loop are known, and the  loop  variable
              is to be incremented by a known, fixed amount every
              time through the loop.

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

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

              The first, limit and increment are integer  expres­
              sions.   They are only evaluated once at the begin­
              ning of the loop.

              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  direc­
              tory.

       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  exe­
       cute  a  global  command.  The result of the catch command
       becomes the result of the try_eval command.  If the  error
       that  caused  the catch to be evaluate is to be continued,
       the following command should be used:
            error $errorResult $errorCode $errorInfo

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

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

       cmdtrace  level | on ?noeval? ?notruncate? ?procs?
              ?fileid? ?com­ mand 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 char­
                     acters, 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 argu­
                     ment  will  be  enclosed  inside  of  braces
                     (`{}') to allow the reader to visually sepa­
                     rate the arguments from each other.

              notruncate
                     Disables  the  truncation  of  commands  and
                     evaluated arguments.

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

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

              command cmd

                     Call  the specified command cmd on when each
                     command is executed instead of tracing to  a

                     ally below.  This option may not  be  speci­
                     fied 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  execu­
              tion  of code, so it should be removed when code is
              debugged.  The following command will enable  trac­
              ing to a file for the remainder of the program:

                   cmdtrace on [open cmd.log w]

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

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

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

              evalLevel
                     The Tcl_Eval call level.

              procLevel
                     The procedure call level.

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

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

              If an error occurs during the execution of command,
              an error message is dumped to stderr and the  trac­
              ing  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.

              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 spec­
              ified), 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 pro­
              file of a Tcl script.  It collects data at the  Tcl
              procedure  level.  The  number of calls to a proce­
              dure, and the amount of real and CPU time  is  col­
              lected.  Time is also collected for the global con­
              text.  The procedure data is collected by bucketing
              it  based  on the procedure call stack, this allows
              determination of how much time is spent in  a  par­
              ticular procedure in each of it's calling contexts.

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

              The  off  option  turns off profiling and moves the
              data collected to the array arrayVar.  The array is
              address  by  a  list  containing the procedure call
              stack.  Element zero is the top of the  stack,  the
              procedure  that  the data is for.  The data in each
              entry is a list consisting of  the  procedure  call
              count  and  the real time and CPU time in millisec­
              onds 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 evalu­
              ation (call) stack is used instead of the procedure
              scope stack.  Upleveled code  is  reported  in  the
              context of the procedure that did the uplevel.

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

              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 containing the data  returned  by  the
              profile command. SortKey indicates which data value
              to sort by.  It should be one of "calls", "cpu"  or
              "real".   OutFile  is the name of file to write the
              report to.  If omitted, stdout is assumed.  UserTi­
              tle is an optional title line to add to output.

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

       These commands provide access to many basic  Unix  facili­
       ties,  including  process handling, date and time process­
       ing, 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  float­
              ing  point number, so fractions of a section may be
              specified.  If seconds is 0.0, any  previous  alarm
              request  is canceled.  Only one alarm at a time may
              be active; the command returns the number  of  sec­
              onds  left in the previous alarm.  On systems with­
              out 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  argu­
              ments in the list arglist.

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

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

                  kill [id process]

              On  Windows  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

              sequence is going to  be  performed  on  stdout  or
              stderr,  then a flush should be issued against std­
              out, stderr and any other open output  file  before
              doing  the fork. Otherwise characters from the par­
              ent 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

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

              id effective user

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

              id effective group

              id effective groupid
                     Return the effective group name,  or  effec­
                     tive 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  pro­
                     gram is running on.

              id process
                     Return  the  process  ID of the current pro­
                     cess.

              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 pro­
                     cess 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 permitted.  Signal, if present,  is  the
              signal  number  or the symbolic name of the signal,
              see the signal system call manual page.  The  lead­
              ing   ``SIG''   is  optional  when  the  signal  is

              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 pro­
              cess 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  cre­
              ated.   (The  -sym option is only available on sys­
              tems that support symbolic links.)

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

       nice ?priorityincr?

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

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

              The new priority is returned.

              The nice command is not available on Windows 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

              call, such as  read  or  waitpid  to  be  restarted
              rather  than generate an error.  Failure to do this
              may results in  unexpected  errors  when  a  signal
              arrives  while  in one of these system calls.  When
              available, the -restart  option  can  prevent  this
              problem.

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

              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 signals, use `*' (this will not  include
              SIGKILL  and SIGSTOP, as they can not be modified).

              default
                     Perform system default action when signal is
                     received  (see signal system call documenta­
                     tion).

              ignore Ignore the signal.

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

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

                     fied signals.  A keyed list will be returned
                     were the keys are one of the specified  sig­
                     nals and the values are a list consisting of
                     the action associated with the signal,  a  0
                     if  the  signal may be delivered (not block)
                     and a 1 if it is blocked and a flag indicat­
                     ing  if restarting of system calls is speci­
                     fied.    The   actions    maybe    one    of
                     `default',`ignore',  `error'  or `trap'.  If
                     the action is trap, the third element is the
                     command  associated  with  the  action.  The
                     action `unknown' is returned  if  a  non-Tcl
                     signal  handler has been associated with the
                     signal.

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

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

              unblock
                     Allow  the  specified signal to be received.
                     Pending signals will not occur. (Posix  sys­
                     tems only).

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

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

       sleep seconds
              Sleep the Extended Tcl process for seconds seconds.

              Concatenates  cmdstr1,  cmdstr2 etc with space sep­
              arators (see the concat command) into a single com­
              mand and then evaluates the command using the stan­
              dard  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  stan­
              dard  output  as the result string, and system goes
              through the Unix shell to provide  wildcard  expan­
              sion,  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 deter­
              mine if "sync fileId" will do a sync or a fsync.

       times
              Return a list containing the process and child exe­
              cution 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

              -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  pro­
              cess.  If pid is specified with -pgroup, then it is
              take as a process group ID, waiting on any  process
              in that process group to terminate.

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

              Note that it is possible to wait  on  processes  to
              terminate  that  were create in the background with
              the exec command.  However, if any other exec  com­
              mand is executed after the process terminates, 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 functionality is avail­
              able.

       These commands provide extended file access and  manipula­
       tion.   This  includes  searching ASCII-sorted data files,
       copying files, duplicating file  descriptors,  control  of
       file access options, retrieving open file status, and cre­
       ating 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.   Alterna­
       tively, 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  speci­
              fied,  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  com­
              pare_proc is specified, then it defines the name of
              a Tcl procedure to evaluate against each line  read
              from  the  sorted  file during the execution of the
              bsearch command.  Compare_proc takes two arguments,
              the  key  and  a line extracted from the file.  The
              compare routine should return a  number  less  than
              zero  if the key is less than the line, zero if the
              key matches the line, or greater than zero  if  the
              key  is  greater  than  the line.  The file must be
              sorted in ascending order  according  to  the  same
              criteria  compare_proc uses to compare the key with
              the line, or erroneous results will occur.

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

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

              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 specified file id.  Normally this is stdin,
              stdout, or stderr.  The  dup  command  will  handle
              flushing  output  and  closing  this file.  The new
              file  will  be  buffered,  if  its  needs   to   be
              unbuffered,   use  the  fcntl  command  to  set  it
              unbuffered.

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

              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 advi­
              sory 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 rela­
              tive to the current access position  in  the  file.
              If  it is "end", then it is relative to the end-of-
              file (a negative is before  the  EOF,  positive  is
              after).  If origin is omitted, start is assumed.

              The following options are recognized:

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

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

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

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

              It is available on Windows NT.

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

              The  break and continue commands work as with fore­
              ach.

              For example, the command

                   for_file line /etc/passwd {echo $line}

              would echo all the lines in the password file.

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

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

       fstat fileId ?item? | ?stat arrayvar?

              Obtain status information about an open file.

              The following keys are used to identify data items:

              atime  The time of last access.

              ctime  The time of last file status change

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

              gid    The group ID of the file's group.

              ino    The inode number.  This field uniquely iden­
                     tifies 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 mod­
                     ified.

              nlink  The number of links to the file.

              size   The file size in bytes.

                     then 1 otherwise 0.

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

              uid    The user ID of the file's owner.

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

              If stat arrayvar is specified, then the information
              is returned in the array  arrayvar.   Each  of  the
              above keys indexes an element of the array contain­
              ing 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  ele­
                     ment  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  ele­
                     ment  being  the  local host IP address.  If
                     the local host name  can  be  found,  it  is
                     returned  as the second element of the list.
                     The local host IP port number is  the  third
                     element.

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

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

              This  command  is  not available or not fully func­
              tional if the underlying operating  system  support
              is  not available.  The command infox have_truncate
              will indicate if this command may truncate by  file

              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 discards the terminating newline charac­
              ter.   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 includ­
              ing  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 charac­
              ters except the newline, so eof may have to be used
              to determine what really happened.

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

              If  lgets  is  currently  supported on non-blocking
              files.

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

              If  the  fileId variables are not specified, then a
              list containing  the  read  and  write  fileIdw  is


       read_file ?-nonewline? fileName

       read_file fileName numBytes
              This  proecure  reads the file fileName and returns
              the contents as a string.  If -nonewline is  speci­
              fied,  then  the last character of the file is dis­
              carded if it is a newline.  The second form  speci­
              fies  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? ?time­
              out?
              This command allows an Extended Tcl program to wait
              on zero or more files being ready for for  reading,
              writing,  have an exceptional condition pending, or
              for  a  timeout  period  to  expire.   readFileIds,
              writeFileIds,   exceptFileIds  are  each  lists  of
              fileIds, as returned from open, to query.  An empty
              list  ({})  may  be  specified if a category is not
              used.

              The files specified by  the  readFileIds  list  are
              checked  to  see  if data is available for reading.
              The writeFileIds are checked if the specified files
              are  clear  for  writing.   The  exceptFileIds  are
              checked to see  if  an  exceptional  condition  has
              occurred  (typically,  an  error).   The  write and
              exception checking is most useful on devices,  how­
              ever,  the read checking is very useful when commu­
              nicating 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 sec­
              onds.  If an empty list is supplied (or the parame­
              ter  is  omitted),  then no timeout is set.  If the
              value is zero, then the select command functions as
              a  poll of the files, returning immediately even if
              none are ready.

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


              could return

                      {file3 file4} {file6} {}

              or perhaps

                      file3 {} {}

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

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

       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 argu­
              ment host can be  either  a  host  name  or  an  IP
              address.

              The following subcommands are recognized:

              addresses
                     Return the list of IP addresses for host.

              official_name
                     Return official name for host.

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

       These  commands provide a facility to scan files, matching
       lines of the file against regular expressions and  execut­
       ing  Tcl  code on a match.  With this facility you can use
       Tcl to do the sort of file processing that  is  tradition­
       ally  done  with  awk.   And  since Tcl's approach is more
       declarative, some of the scripts that can be rather diffi­
       cult 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 state­
       ments,  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  expres­
              sions.   Multiple  scan contexts may be defined and
              they may be reused on multiple files.  A scan  con­
              text  is identified by a context handle.  The scan­
              context command takes the following forms:

       scancontext create
              Create a new scan context.  The  scanmatch  command
              is  used to define patterns in the context.  A con­
              texthandle 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  contex­
              thandle,  and  free all of the match statements and
              compiled regular expressions  associated  with  the
              specified context.

       scancontext copyfile contexthandle ?filehandle?
              Set  or return the file handle that unmatched lines
              are copied to.  (See scanfile).  If  filehandle  is
              omitted,  the  copy file handle is returned.  If no
              copy file is associated with  the  context,  {}  is
              returned.   If  a  file  handle  is  specified,  it
              becomes the copy file for this context.   If  file­
              handle  is {}, then it removes any copy file speci­
              fication 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

              patterns matched.

              If the optional -copyfile  argument  is  specified,
              the  next  argument is a file ID to which all lines
              not matched by any pattern (excluding  the  default
              pattern)  are  to  be written.  If the copy file is
              specified with this  flag,  instead  of  using  the
              scancontext  copyfile command, the file is disasso­
              ciated 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  contex­
              thandle.   Any  number  of  match statements may be
              specified for a give context.  Regexp is a  regular
              expression (see the regexp command).  If -nocase is
              specified as the first  argument,  the  pattern  is
              matched regardless of alphabetic case.

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

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

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

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

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

                     The  line  number  of  the  line  that   was
                     matched.  This is relative to the first line
                     scanned, which is usually, but not necessar­
                     ily,  the first line of the file.  The first
                     line is line number one.

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

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

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

              matchInfo(submatch0)
                     Will contain  the  characters  matching  the
                     first parenthesized subexpression.  The sec­
                     ond 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 sec­
                     ond will be contained in subindex1, etc.

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

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

       Several  extended  math  commands commands make many addi­
       tional math functions available in TclX.  In  addition,  a
       set of procedures provide command access to the math func­
       tions 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  float­
              ing point value.

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

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

       Extended  Tcl  provides  additional list manipulation com­
       mands and procedures.

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

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

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

              For example,

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

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

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

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

       lmatch ?mode? list pattern

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

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

                     same string as pattern.

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

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

              If mode is omitted then it defaults to -glob.

              Only the -exact  comparison  will  work  on  binary
              data.

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

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

       lvarpop var ?indexExpr? ?string?
              The lvarpop  command  pops  (deletes)  the  element
              indexed  by  the expression indexExpr from the list
              contained in the variable var.  If index  is  omit­
              ted,  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

              with  len,  then len is replaced with the length of
              the list.  Note the a value of end means insert the
              string before the last element.

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

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

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

                  {{NAME  {Frank  Zappa}} {JOB {musician and com­
              poser}}}

       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 charac­
       ter.  Subfields are actually fields  where  the  value  is
       another  keyed  list.  Thus the following list has the top
       level fields ID and NAME,  and  subfields  NAME.FIRST  and
       NAME.LAST:

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

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

       Keyed lists are constructed and accessed via a  number  of
       commands.   All  keyed  list  management commands take the
       name of the variable containing the keyed list as an argu­
       ment  (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


              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 speci­
              fied, if desired.

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

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

              If  -local  is  specified, the strings are compared
              according to the collation environment of the  cur­
              rent 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.

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

              This command is UTF-aware.

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

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

              This command is UTF-aware.

       csubstr string firstExpr lengthExpr
              Returns  a range of characters from string starting
              at the character indexed by the  expression  first­
              Expr (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  con­
              verting  between an ASCII character and its numeric
              value.  The following ctype commands are available:

                     Tests  that all characters are alphabetic or
                     numeric characters as defined by the charac­
                     ter 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 char­
                     acter  (a  non-negative  number  less   than
                     0200).

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

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

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

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

              ctype ?-failindex var? lower string
                     Tests that all characters are lowercase let­
                     ters 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, new­
                     line, 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  charac­
                     ter'' as defined by the character set.

                     Tests that all characters are made up of any
                     of the characters other than  the  ones  for
                     which alnum, cntrl, or space is true.

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

              ctype ?-failindex var? xdigit string
                     Tests that all characters are valid hexadec­
                     imal  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 exam­
              ple:
                      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.

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

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

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

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

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

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

       catopen ?-fail | -nofail? catname
              Open  the  message  catalog catname.  This may be a
              relative path name, in which case the NLSPATH envi­
              ronment  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 han­
              dle  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.

              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  mes­
              sage  set number, and msgnum is the message number.
              If the message catalog was not opened, or the  mes­
              sage  set  or  message number cannot be found, then
              the default string, defaultstr, is returned.

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

       tcl ?-qn? ?-f? script? | ?-c command? ?args?

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

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

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

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

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

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

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

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

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

       --     Mark the end of the arguments to the Tcl shell. All

              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  dis­
       played,  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 envi­
       ronment variable PATH, will be searched for a  command  of
       the  same  name.  If the command is found, it will be exe­
       cuted 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 devel­
       oping Tcl scripts.

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

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

       argv0  Contains the name of the Tcl program  specified  on
              the command line or the name that the Tcl shell was
              invoked under if no program  was  specified.   argc
              Contains a count of the number of argv arguments (0
              if none).  argv A  list  containing  the  arguments
              passed  in  from  the command line, excluding argu­
              ments 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 func­
              tion 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.

              ing 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 initialization 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
              interactively prompting for commands.

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

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

              The tclx_errorHandler command  is  called  when  an
              error  that  is not caught returns to the top level
              command evaluation in the TclX shell or wishx.  The
              difference between tclx_errorHandler and bgerror is
              that tclx_errorHandler is called  during  the  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 program.
              Once the event loop is  entered,  bgerror  will  be
              called on uncaught errors.

              mands 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 with­
              out 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  pos­
              sible  to  continue executing the code in which the
              error occurred.  This is useful for logging  error­
              Info or e-mailing it to the maintainer.

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

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

       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  struc­
       tured  as  a  multilevel  tree of subjects and help pages.
       Help files are found by searching directories  named  help
       in  the directories listed in the auto_path variable.  All
       of the files in the list of help directories form  a  vir­
       tual  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 interac­
       tive commands in the Extended Tcl shell or as an  interac­
       tive 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 sub­
              jects and pages under the current help subject.

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

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

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

       helppwd
              Displays the current help subject.

              Displays help on the help facility at any directory
              level.

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

       Extended  Tcl supports standard Tcl tclIndex libraries and
       package libraries. A package library file can contain mul­
       tiple independent Tcl packages.  A package is a named col­
       lection 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  pack­
       ages  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 direc­
       tory as the .tlib file.  The .tndx will  be  automatically
       created  whenever  it  is out of date or missing (provided
       there is write access to the directory).

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

       The start of a package is delimited by:

              #@package: package_name proc1 ?..procN?

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

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

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

              #@package: directory_stack pushd popd dirs

       age  file  up  to  the next package line or the end of the
       file is  a  package  named  directory_stack  and  that  an
       attempt  to  execute  either  pushd, popd or dirs when the
       routine is not  already  defined  will  cause  the  direc­
       tory_stack portion of the package file to be loaded.

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

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

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

       convert_lib tclIndex packagelib ?ignore?
              Convert  a Ousterhout style tclIndex index file and
              associate source files into a package library pack­
              agelib.  If packagelib does not have a .tlib exten­
              sion, 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).   Pack­
              age  library indexes along the auto_path are loaded
              automatically on the first demand_load;  this  com­
              mand  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  permis­
              sions 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  actu­
              ally been used from the previously defined package,
              the  procedures  from  libfile.tlib  will  not   be
              loaded.

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

              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.


Man(1) output converted with man2html