-*-man-*- 

                       TclX Commands

       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  introduces  a  set of new commands and a user-extensible
       library of useful Tcl procedures, any of	 which	can  be	 automatically
       loaded on the first attempt to execute it.

       The command descriptions are separated into several sections:

	    ¥ General Commands

	    ¥ Debugging and Development Commands

	    ¥ Unix Access Commands

	    ¥ File Commands

	    ¥ Network Programming Support

	    ¥ File Scanning Commands

	    ¥ Math Commands

	    ¥ List Manipulation Commands

	    ¥ Keyed Lists

	    ¥ String and Character Manipulation Commands

	    ¥ XPG/3 Message Catalog Commands

	    ¥ Help Facility

	    ¥ Tcl Loadable Libraries and Packages

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

       dirs   This procedure lists the directories in the directory stack.

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

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

	      The following options are available:

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

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

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

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

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

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

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

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

       infox option

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

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

	      patchlevel
		     Return the patchlevel for Extended Tcl.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       try_eval code catch ?finally?

	      The try_eval command evaluates code in the current context.

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

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

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


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

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

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

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

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

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

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

	      command cmd

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

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

		   cmdtrace on [open cmd.log w]

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

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

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

	      evalLevel
		     The Tcl_Eval call level.

	      procLevel
		     The procedure call level.

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

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

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

       cmdtrace off
	      Turn off all tracing.

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

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

       profile ?-commands? ?-eval? on

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

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

	      The off option turns off profiling and moves the data  collected
	      to  the array arrayVar.  The array is address by a list contain-
	      ing the procedure call stack.  Element zero is the  top  of  the
	      stack,  the  procedure  that  the data is for.  The data in each
	      entry is a list consisting of the procedure call count  and  the
	      real  time  and  CPU time in milliseconds spent in the procedure
	      (but not any procedures it calls).  The  list  is	 in  the  form
	      {count real cpu}.

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

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

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

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

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

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

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

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

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

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

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

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

		  kill [id process]

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

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

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

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

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

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

       id options

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

	      id user ?name?

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

	      id convert userid uid

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

	      id group ?name?

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

	      id groups

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

	      id convert groupid gid

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

	      id effective user

	      id effective userid
		     Return the effective user name, or effective user ID num-
		     ber, respectively.

	      id effective group

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

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

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

	      id process
		     Return the process ID of the current process.

	      id process parent
		     Return the process ID of the parent of the	 current  pro-
		     cess.

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

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

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

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

       kill ?-pgroup ?signal? idlist

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

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

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

       link ?-sym? srcpath destpath

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

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

       nice ?priorityincr?

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

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

	      The new priority is returned.

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

       readdir ?-hidden? dirPath

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

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

       signal ?-restart? action siglist ?command?

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

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

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

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

	      ignore Ignore the signal.

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

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

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

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

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

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

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

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

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

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

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

       sync ?fileId?

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

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

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

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

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

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

	      If -nohang is specified, then don't block waiting on  a  process
	      to terminate.  If no process is immediately available, return an
	      empty list.  If -untraced is specified then the status of	 child
	      processes	 that  are  stopped, and whose status has not yet been
	      reported since they stopped, are also returned.  If  -pgroup  is
	      specified	 and pid is not specified, then wait on any child pro-
	      cess 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  pro-
	      cess  exited  normally,  the  second  element is `EXIT', and the
	      third contains the numeric exit code.  If the process terminated
	      due to a signal, the second element is `SIG', and the third con-
	      tains the signal name.  If the process is currently stopped  (on
	      systems that support SIGSTP), the second element is `STOP', fol-
	      lowed by the signal name.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       flock options fileId ?start? ?length? ?origin?

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

	      The following options are recognized:

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

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

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

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

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

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

	      The break and continue commands work as with foreach.

	      For example, the command

		   for_file line /etc/passwd {echo $line}

	      would echo all the lines in the password file.

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

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

       fstat fileId ?item? | ?stat arrayvar?

	      Obtain status information about an open file.

	      The following keys are used to identify data items:

	      atime  The time of last access.

	      ctime  The time of last file status change

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

	      gid    The group ID of the file's group.

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

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

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

	      nlink  The number of links to the file.

	      size   The file size in bytes.

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

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

	      uid    The user ID of the file's owner.

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

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

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

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

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

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

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

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

	      This command is not available or not  fully  functional  if  the
	      underlying  operating system support is not available.  The com-
	      mand infox have_truncate will indicate if this command may trun-
	      cate  by file path.  The command infox have_ftruncate will indi-
	      cate if this command may truncate by file id.

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

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

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

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

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

	      If lgets is currently supported on non-blocking files.

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

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

       read_file ?-nonewline? fileName

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

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

	      The  files  specified by the readFileIds list are checked to see
	      if data is available for reading. The writeFileIds  are  checked
	      if the specified files are clear for writing.  The exceptFileIds
	      are checked to see if  an	 exceptional  condition	 has  occurred
	      (typically, an error).  The write and exception checking is most
	      useful on devices, however, the read  checking  is  very	useful
	      when   communicating  with  multiple  processes  through	pipes.
	      Select considers data pending in the stdio input buffer for read
	      files  as being ready for reading, the files do.	not have to be
	      unbuffered.

	      Timeout is a floating point timeout value, in  seconds.	If  an
	      empty  list  is  supplied (or the parameter is omitted), then no
	      timeout is set.  If the value is zero, then the  select  command
	      functions	 as a poll of the files, returning immediately even if
	      none are ready.

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

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

	      could return

		      {file3 file4} {file6} {}

	      or perhaps

		      file3 {} {}

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

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

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

       host_info addresses host

       host_info official_name host

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

	      The following subcommands are recognized:

	      addresses
		     Return the list of IP addresses for host.

	      official_name
		     Return official name for host.

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

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

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

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

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

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

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

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

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

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

       scanmatch ?-nocase? contexthandle ?regexp? commands

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

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

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

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

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

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

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

	      matchInfo(context)
		     The context handle of the context that this scan is asso-
		     ciated with.

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

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

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

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

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

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

MATH COMMANDS
       Several extended math commands commands make many additional math func-
       tions available in TclX.	 In addition, a set of procedures provide com-
       mand access to the math functions supported by the expr command.


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

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

       max num1 ?..numN?

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

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

       min num1 ?..numN?

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

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

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

LIST MANIPULATION COMMANDS
       Extended Tcl provides additional list manipulation commands and	proce-
       dures.

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

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

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

	      For example,

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

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

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

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

       lmatch ?mode? list pattern

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

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

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

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

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

	      If mode is omitted then it defaults to -glob.

	      Only the -exact comparison will work on binary data.

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

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

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

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

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

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

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

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

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

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

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

		   keylset person ID 106

       would make person contain

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

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

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

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

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

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

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

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

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

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

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


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

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

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

	      This command does not work with binary or UTF data.

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

	      This command is UTF-aware.

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

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

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

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

	      This command is UTF-aware.

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

	      This command is UTF-aware.

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

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

	      This command is UTF-aware.

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

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

	      This command is UTF-aware.

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

	      This command does not work with binary data.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       To run the Tk-based interactive help program:

	   tclhelp ?addpaths?

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

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

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

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

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

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

       helppwd
	      Displays the current help subject.

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

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

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

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

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

       The start of a package is delimited by:

	      #@package: package_name proc1 ?..procN?

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

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

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

	      #@package: directory_stack pushd popd dirs

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

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

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

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

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

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

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

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

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

