
                       Tcl 8-4-0 Commands


_________________________________________________________________

NAME
       after - Execute a command after a time delay

SYNOPSIS
       after ms

       after ms ?script script script ...?

       after cancel id

       after cancel script script script ...

       after idle ?script script script ...?

       after info ?id?
_________________________________________________________________


DESCRIPTION
       This  command is used to delay execution of the program or
       to execute a command in background sometime in the future.
       It  has  several forms, depending on the first argument to
       the command:

       after ms
              Ms must be an integer giving a  time  in  millisec-
              onds.   The  command sleeps for ms milliseconds and
              then returns.  While the command  is  sleeping  the
              application does not respond to events.

       after ms ?script script script ...?
              In  this  form the command returns immediately, but
              it arranges for a Tcl command  to  be  executed  ms
              milliseconds  later  as an event handler.  The com-
              mand will be executed exactly once,  at  the  given
              time.  The delayed command is formed by concatenat-
              ing all the script arguments in the same fashion as
              the  concat  command.  The command will be executed
              at global level (outside the  context  of  any  Tcl
              procedure).  If an error occurs while executing the
              delayed command then the bgerror mechanism is  used
              to  report the error.  The after command returns an
              identifier that can be used to cancel  the  delayed
              command using after cancel.

       after cancel id
              Cancels the execution of a delayed command that was
              previously scheduled.  Id indicates  which  command
              should  be  canceled;  it must have been the return
              value from a previous after command.  If  the  com-
              mand given by id has already been executed then the
              after cancel command has no effect.


       after cancel script script ...
              This  command  also  cancels  the  execution  of  a
              delayed command.  The script arguments are concate-
              nated together with space separators  (just  as  in
              the concat command).  If there is a pending command
              that matches the string, it is cancelled  and  will
              never be executed;  if no such command is currently
              pending  then  the  after  cancel  command  has  no
              effect.

       after idle script ?script script ...?
              Concatenates  the  script  arguments  together with
              space separators (just as in the  concat  command),
              and  arranges for the resulting script to be evalu-
              ated later as an idle callback.  The script will be
              run  exactly  once, the next time the event loop is
              entered and there are no events  to  process.   The
              command  returns  an identifier that can be used to
              cancel the delayed command using after cancel.   If
              an error occurs while executing the script then the
              bgerror mechanism is used to report the error.

       after info ?id?
              This command  returns  information  about  existing
              event handlers.  If no id argument is supplied, the
              command returns a list of the identifiers  for  all
              existing  event  handlers created by the after com-
              mand for this interpreter.  If id is  supplied,  it
              specifies  an  existing  handler; id must have been
              the return value from some previous call  to  after
              and  it  must  not  have triggered yet or been can-
              celled.  In this case the command  returns  a  list
              with  two  elements.  The first element of the list
              is the script associated with id,  and  the  second
              element  is  either  idle or timer to indicate what
              kind of event handler it is.

       The after ms and after idle forms of  the  command  assume
       that  the  application  is event driven:  the delayed com-
       mands will not be executed unless the  application  enters
       the  event  loop.   In  applications that are not normally
       event-driven, such as tclsh, the event loop can be entered
       with the vwait and update commands.


KEYWORDS
       cancel, delay, idle callback, sleep, time


_________________________________________________________________

NAME
       append - Append to variable

SYNOPSIS
       append varName ?value value value ...?
_________________________________________________________________


DESCRIPTION
       Append  all of the value arguments to the current value of
       variable varName.  If varName doesn't exist, it is given a
       value  equal  to  the concatenation of all the value argu-
       ments.  This command provides an efficient way to build up
       long  variables  incrementally.   For  example, ``append a
       $b'' is much more efficient than ``set a $a$b'' if  $a  is
       long.


KEYWORDS
       append, variable


_________________________________________________________________

NAME
       array - Manipulate array variables

SYNOPSIS
       array option arrayName ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       This  command  performs  one  of several operations on the
       variable given by arrayName.  Unless  otherwise  specified
       for  individual commands below, arrayName must be the name
       of an existing array variable.  The option argument deter-
       mines  what  action  is  carried  out by the command.  The
       legal options (which may be abbreviated) are:

       array anymore arrayName searchId
              Returns 1 if there are any more elements left to be
              processed  in  an  array  search, 0 if all elements
              have already  been  returned.   SearchId  indicates
              which  search  on arrayName to check, and must have
              been the return value from a previous invocation of
              array  startsearch.   This  option  is particularly
              useful if an array has an  element  with  an  empty
              name, since the return value from array nextelement
              won't indicate whether the  search  has  been  com-
              pleted.

       array donesearch arrayName searchId
              This   command   terminates  an  array  search  and
              destroys all the state associated with that search.
              SearchId  indicates  which  search  on arrayName to
              destroy, and must have been the return value from a
              previous  invocation of array startsearch.  Returns
              an empty string.

       array exists arrayName
              Returns 1 if arrayName is an array variable,  0  if
              there  is  no  variable  by that name or if it is a
              scalar variable.

       array get arrayName ?pattern?
              Returns a list containing pairs of  elements.   The
              first  element  in each pair is the name of an ele-
              ment in arrayName and the second  element  of  each
              pair  is the value of the array element.  The order
              of the pairs is undefined.  If pattern is not spec-
              ified,  then  all  of the elements of the array are
              included in the result.  If pattern  is  specified,
              then  only those elements whose names match pattern
              (using the matching  rules  of  string  match)  are
              included.   If arrayName isn't the name of an array
              variable, or if the  array  contains  no  elements,
              then an empty list is returned.

       array names arrayName ?mode? ?pattern?
              Returns  a  list containing the names of all of the
              elements in the array that match pattern.  Mode may
              be one of -exact, -glob, or -regexp.  If specified,
              mode designates which  matching  rules  to  use  to
              match  pattern against the names of the elements in
              the array.  If  not  specified,  mode  defaults  to
              -glob.   See the documentation for string match for
              information on glob style matching, and  the  docu-
              mentation  for  regexp  for  information  on regexp
              matching.  If pattern is omitted then  the  command
              returns  all of the element names in the array.  If
              there are no (matching) elements in the  array,  or
              if  arrayName  isn't the name of an array variable,
              then an empty string is returned.

       array nextelement arrayName searchId
              Returns the name of the next element in  arrayName,
              or  an  empty  string  if all elements of arrayName
              have already been returned  in  this  search.   The
              searchId  argument  identifies the search, and must
              have been the return value of an array  startsearch
              command.   Warning:   if  elements  are added to or
              deleted from the array, then all searches are auto-
              matically  terminated  just  as if array donesearch
              had been invoked; this will cause array nextelement
              operations to fail for those searches.

       array set arrayName list
              Sets  the  values of one or more elements in array-
              Name.  list must have a form like that returned  by
              array  get,  consisting  of  an even number of ele-
              ments.   Each  odd-numbered  element  in  list   is
              treated  as  an  element name within arrayName, and
              the following element in list  is  used  as  a  new
              value  for  that  array  element.   If the variable
              arrayName does not already exist and list is empty,
              arrayName is created with an empty array value.

       array size arrayName
              Returns  a decimal string giving the number of ele-
              ments in the array.  If arrayName isn't the name of
              an array then 0 is returned.

       array startsearch arrayName
              This   command  initializes  an  element-by-element
              search through the array given by  arrayName,  such
              that  invocations  of the array nextelement command
              will return the names of the individual elements in
              the array.  When the search has been completed, the
              array donesearch command should  be  invoked.   The
              return  value  is  a search identifier that must be
              used in array nextelement and array donesearch com-
              mands;  it  allows multiple searches to be underway
              simultaneously for the same array.                  

       array statistics                                           
       arrayName                                        
              Returns  statistics  about the distribution of data 
              within the hashtable  that  represents  the  array. 
              This  information includes the number of entries in 
              the table, the number of buckets, and the  utiliza-
              tion of the buckets.                                

       array unset arrayName                                      
       ?pattern?                                   
              Unsets all of the elements in the array that  match 
              pattern (using the matching rules of string match). 
              If arrayName isn't the name of an array variable or 
              there  are  no  matching  elements in the array, no 
              error will be raised.  If pattern  is  omitted  and 
              arrayName  is  an  array variable, then the command 
              unsets  the  entire  array.   The  command   always 
              returns an empty string.


KEYWORDS
       array, element names, search


_________________________________________________________________

NAME
       bgerror - Command invoked to process background errors

SYNOPSIS
       bgerror message
_________________________________________________________________


DESCRIPTION
       The bgerror command doesn't exist as built-in part of Tcl.
       Instead, individual applications or  users  can  define  a
       bgerror  command (e.g. as a Tcl procedure) if they wish to
       handle background errors.

       A background error is one that occurs in an event  handler
       or  some  other  command  that  didn't  originate with the
       application.  For example, if an error occurs  while  exe-
       cuting a command specified with the after command, then it
       is a background error.  For a  non-background  error,  the
       error can simply be returned up through nested Tcl command
       evaluations until it reaches the  top-level  code  in  the
       application;  then the application can report the error in
       whatever way it wishes.  When a background  error  occurs,
       the  unwinding  ends  in  the  Tcl library and there is no
       obvious way for Tcl to report the error.

       When Tcl detects a background error, it saves  information
       about  the  error and invokes the bgerror command later as
       an  idle  event  handler.  Before  invoking  bgerror,  Tcl
       restores  the  errorInfo  and errorCode variables to their
       values at the time the error  occurred,  then  it  invokes
       bgerror  with the error message as its only argument.  Tcl
       assumes that the application has implemented  the  bgerror
       command,  and  that the command will report the error in a
       way that makes sense for the application.  Tcl will ignore
       any  result  returned by the bgerror command as long as no
       error is generated.

       If another Tcl error occurs  within  the  bgerror  command
       (for example, because no bgerror command has been defined)
       then Tcl reports the error itself by writing a message  to
       stderr.

       If  several background errors accumulate before bgerror is
       invoked to process them, bgerror will be invoked once  for
       each error, in the order they occurred.  However, if bger-
       ror returns with a break  exception,  then  any  remaining
       errors are skipped without calling bgerror.

       Tcl has no default implementation for bgerror. However, in
       applications using Tk there is a default bgerror procedure
       which  posts a dialog box containing the error message and
       offers the user a chance to  see  a  stack  trace  showing
       where  the  error  occurred.   In addition to allowing the
       user to view the stack trace, the dialog provides an addi-
       tional  application configurable button which may be used,
       for example, to save  the  stack  trace  to  a  file.   By
       default, this is the behavior associated with that button.
       This behavior can  be  redefined  by  setting  the  option
       database values *ErrorDialog.function.text, to specify the
       caption for the function  button,  and  *ErrorDialog.func-
       tion.command,  to specify the command to be run.  The text
       of the stack trace is appended to the command when  it  is
       evaluated.  If either of these options is set to the empty
       string, then the additional button will not  be  displayed
       in the dialog.


KEYWORDS
       background error, reporting


_________________________________________________________________

NAME
       binary - Insert and extract fields from binary strings

SYNOPSIS
       binary format formatString ?arg arg ...?
       binary scan string formatString ?varName varName ...?
_________________________________________________________________


DESCRIPTION
       This  command  provides facilities for manipulating binary
       data.  The first form, binary  format,  creates  a  binary
       string  from  normal  Tcl  values.  For example, given the
       values 16 and 22, on a 32 bit architecture, it might  pro-
       duce  an  8-byte  binary  string  consisting of two 4-byte
       integers, one for each of the numbers.  The second form of
       the  command,  binary scan, does the opposite: it extracts
       data from a binary string and returns it as  ordinary  Tcl
       string values.


BINARY FORMAT
       The  binary format command generates a binary string whose
       layout is specified by the formatString and whose contents
       come  from the additional arguments.  The resulting binary
       value is returned.

       The formatString consists of a sequence of  zero  or  more
       field  specifiers  separated by zero or more spaces.  Each
       field specifier is a single type character followed by  an
       optional numeric count.  Most field specifiers consume one
       argument to obtain the value to be  formatted.   The  type
       character specifies how the value is to be formatted.  The
       count typically indicates how many items of the  specified
       type are taken from the value.  If present, the count is a
       non-negative decimal integer or *,  which  normally  indi-
       cates  that  all of the items in the value are to be used.
       If the number of arguments does not match  the  number  of
       fields  in  the format string that consume arguments, then
       an error is generated.

       Each type-count pair moves an imaginary cursor through the
       binary  data,  storing  bytes  at the current position and
       advancing the cursor to just after the last  byte  stored.
       The  cursor is initially at position 0 at the beginning of
       the data.  The type may be any one of the following  char-
       acters:

       a    Stores a character string of length count in the out-
            put string.  If arg has fewer than count bytes,  then
            additional  zero bytes are used to pad out the field.
            If arg is longer than the specified length, the extra
            characters  will be ignored.  If count is *, then all
            of the bytes in arg will be formatted.  If  count  is
            omitted,  then  one character will be formatted.  For
            example,
                   binary format a7a*a alpha bravo charlie
            will    return     a     string     equivalent     to
            alpha\000\000bravoc.

       A    This  form  is  the  same as a except that spaces are
            used for padding instead of nulls.  For example,
                   binary format A6A*A alpha bravo charlie
            will return alpha bravoc.

       b    Stores a string of count binary digits in low-to-high
            order  within  each  byte  in the output string.  Arg
            must contain a sequence of 1 and 0  characters.   The
            resulting  bytes  are  emitted in first to last order
            with the bits being formatted  in  low-to-high  order
            within  each  byte.  If arg has fewer than count dig-
            its, then zeros will be used for the remaining  bits.
            If  arg has more than the specified number of digits,
            the extra digits will be ignored.   If  count  is  *,
            then  all of the digits in arg will be formatted.  If
            count is omitted, then one digit will  be  formatted.
            If  the  number  of  bits formatted does not end at a
            byte boundary, the remaining bits of  the  last  byte
            will be zeros.  For example,
                   binary format b5b* 11100 111000011010
            will return a string equivalent to \x07\x87\x05.

       B    This  form  is the same as b except that the bits are
            stored in high-to-low order within  each  byte.   For
            example,
                   binary format B5B* 11100 111000011010
            will return a string equivalent to \xe0\xe1\xa0.

       h    Stores  a  string of count hexadecimal digits in low-
            to-high within each byte in the output  string.   Arg
            must  contain  a  sequence  of  characters in the set
            ``0123456789abcdefABCDEF''.  The resulting bytes  are
            emitted  in  first  to last order with the hex digits
            being formatted  in  low-to-high  order  within  each
            byte.  If arg has fewer than count digits, then zeros
            will be used for the remaining digits.   If  arg  has
            more  than  the specified number of digits, the extra
            digits will be ignored.  If count is *, then  all  of
            the  digits  in  arg  will be formatted.  If count is
            omitted, then one digit will be  formatted.   If  the
            number  of  digits  formatted  does not end at a byte
            boundary, the remaining bits of the last byte will be
            zeros.  For example,
                   binary format h3h* AB def
            will  return a string equivalent to \xba\x00\xed\x0f.


       H    This form is the same as h except that the digits are
            stored  in  high-to-low  order within each byte.  For
            example,
                   binary format H3H* ab DEF
            will return a string equivalent to  \xab\x00\xde\xf0.

       c    Stores one or more 8-bit integer values in the output
            string.  If no count is specified, then arg must con-
            sist  of an integer value; otherwise arg must consist
            of a list containing at least count integer elements.
            The  low-order 8 bits of each integer are stored as a
            one-byte value at the cursor position.  If  count  is
            *,  then  all of the integers in the list are format-
            ted.  If the number of elements in the list is  fewer
            than  count, then an error is generated.  If the num-
            ber of elements in the list is  greater  than  count,
            then the extra elements are ignored.  For example,
                   binary format c3cc* {3 -3 128 1} 260 {2 5}
            will     return     a     string     equivalent    to
            \x03\xfd\x80\x04\x02\x05, whereas
                   binary format c {2 5}
            will generate an error.

       s    This form is the same as c except that it stores  one
            or  more  16-bit integers in little-endian byte order
            in the output string.  The low-order 16-bits of  each
            integer  are stored as a two-byte value at the cursor
            position  with  the  least  significant  byte  stored
            first.  For example,
                   binary format s3 {3 -3 258 1}
            will     return     a     string     equivalent    to
            \x03\x00\xfd\xff\x02\x01.

       S    This form is the same as s except that it stores  one
            or  more  16-bit integers in big-endian byte order in
            the output string.  For example,
                   binary format S3 {3 -3 258 1}
            will    return     a     string     equivalent     to
            \x00\x03\xff\xfd\x01\x02.

       i    This  form is the same as c except that it stores one
            or more 32-bit integers in little-endian  byte  order
            in  the output string.  The low-order 32-bits of each
            integer are stored as a four-byte value at the cursor
            position  with  the  least  significant  byte  stored
            first.  For example,
                   binary format i3 {3 -3 65536 1}
            will    return     a     string     equivalent     to
            \x03\x00\x00\x00\xfd\xff\xff\xff\x00\x00\x01\x00

       I    This  form is the same as i except that it stores one
            or more one or more  32-bit  integers  in  big-endian
            byte order in the output string.  For example,
                   binary format I3 {3 -3 65536 1}
            will     return     a     string     equivalent    to
            \x00\x00\x00\x03\xff\xff\xff\xfd\x00\x01\x00\x00

       w    This form is the same as w except that it stores  one 
            or  more  64-bit integers in little-endian byte order 
            in the output string.  The low-order 64-bits of  each 
            integer are stored as an eight-byte value at the cur-
            sor position with the least significant  byte  stored 
            first.  For example,                                  
                   binary format w 7810179016327718216            
            will return the string HelloTcl                       

       W                                                                 
            This form is the same as w except that it stores  one 
            or  more  one  or  more 64-bit integers in big-endian 
            byte order in the output string.  For example,        
                   binary format W 4785469626960341345            
            will return the string BigEndian

       f    This form is the same as c except that it stores  one
            or  more one or more single-precision floating in the
            machine's native representation in the output string.
            This  representation is not portable across architec-
            tures, so it should not be used to communicate float-
            ing  point numbers across the network.  The size of a
            floating point number may vary across  architectures,
            so  the  number of bytes that are generated may vary.
            If the value overflows the machine's native represen-
            tation,  then  the value of FLT_MAX as defined by the
            system will be used instead.  Because Tcl  uses  dou-
            ble-precision   floating-point   numbers  internally,
            there may be some loss of precision in the conversion
            to  single-precision.  For example, on a Windows sys-
            tem running on an Intel Pentium processor,
                   binary format f2 {1.6 3.4}
            will    return     a     string     equivalent     to
            \xcd\xcc\xcc\x3f\x9a\x99\x59\x40.

       d    This  form is the same as f except that it stores one
            or more one or more double-precision floating in  the
            machine's native representation in the output string.
            For example, on a Windows system running on an  Intel
            Pentium processor,
                   binary format d1 {1.6}
            will     return     a     string     equivalent    to
            \x9a\x99\x99\x99\x99\x99\xf9\x3f.

       x    Stores count null bytes in  the  output  string.   If
            count  is  not  specified,  stores one null byte.  If
            count is *, generates an error.  This type  does  not
            consume an argument.  For example,
                   binary format a3xa3x2a3 abc def ghi
            will     return     a     string     equivalent    to
            abc\000def\000\000ghi.


       X    Moves the cursor  back  count  bytes  in  the  output
            string.   If count is * or is larger than the current
            cursor position, then the  cursor  is  positioned  at
            location  0  so that the next byte stored will be the
            first byte in the result string.  If count is omitted
            then  the  cursor  is moved back one byte.  This type
            does not consume an argument.  For example,
                   binary format a3X*a3X2a3 abc def ghi
            will return dghi.

       @    Moves the cursor to the absolute location in the out-
            put  string specified by count.  Position 0 refers to
            the first byte in the output string.  If count refers
            to  a  position  beyond  the last byte stored so far,
            then null bytes will be placed in  the  uninitialized
            locations and the cursor will be placed at the speci-
            fied location.  If count is *,  then  the  cursor  is
            moved  to  the  current end of the output string.  If
            count is omitted, then an error  will  be  generated.
            This type does not consume an argument. For example,
                   binary format a5@2a1@*a3@10a1 abcde f ghi j
            will return abfdeghi\000\000j.


BINARY SCAN
       The  binary  scan  command  parses  fields  from  a binary
       string, returning the  number  of  conversions  performed.
       String gives the input to be parsed and formatString indi-
       cates how to parse it.  Each varName gives the name  of  a
       variable;  when  a field is scanned from string the result
       is assigned to the corresponding variable.

       As with binary format,  the  formatString  consists  of  a
       sequence  of  zero  or  more field specifiers separated by
       zero or more spaces.  Each field  specifier  is  a  single
       type  character  followed  by  an  optional numeric count.
       Most field specifiers consume one argument to  obtain  the
       variable  into  which the scanned values should be placed.
       The type character specifies how the binary data is to  be
       interpreted.  The count typically indicates how many items
       of the specified type are taken from the  data.   If  pre-
       sent,  the  count  is a non-negative decimal integer or *,
       which normally indicates that all of the  remaining  items
       in the data are to be used.  If there are not enough bytes
       left after the current cursor position to satisfy the cur-
       rent  field  specifier, then the corresponding variable is
       left untouched and binary scan  returns  immediately  with
       the  number  of variables that were set.  If there are not
       enough arguments for all  of  the  fields  in  the  format
       string that consume arguments, then an error is generated.

       It is important to note that the c, s, and S (and i and  I
       on 64bit systems) will be scanned into long data size val-
       ues.  In doing this, values that have their high  bit  set
       (0x80  for chars, 0x8000 for shorts, 0x80000000 for ints),
       will be sign extended.  Thus the following will occur:
              set signShort [binary format s1 0x8000]
              binary scan $signShort s1 val; # val == 0xFFFF8000
       If you want to produce an unsigned  value,  then  you  can
       mask  the  return value to the desired size.  For example,
       to produce an unsigned short value:
              set val [expr {$val & 0xFFFF}]; # val == 0x8000

       Each type-count pair moves an imaginary cursor through the
       binary data, reading bytes from the current position.  The
       cursor is initially at position 0 at the beginning of  the
       data.   The  type  may be any one of the following charac-
       ters:

       a    The data is a character string of length  count.   If
            count is *, then all of the remaining bytes in string
            will be scanned into the variable.  If count is omit-
            ted,  then  one character will be scanned.  For exam-
            ple,
                   binary scan abcde\000fghi a6a10 var1 var2
            will return 1 with the string equivalent to abcde\000
            stored in var1 and var2 left unmodified.

       A    This  form  is  the same as a, except trailing blanks
            and nulls are stripped from the scanned value  before
            it is stored in the variable.  For example,
                   binary scan "abc efghi  \000" A* var1
            will return 1 with abc efghi stored in var1.

       b    The data is turned into a string of count binary dig-
            its in low-to-high order represented as a sequence of
            ``1''  and  ``0''  characters.   The  data  bytes are
            scanned in first to last order with  the  bits  being
            taken  in  low-to-high  order  within each byte.  Any
            extra bits in the last byte are ignored.  If count is
            *,  then  all of the remaining bits in string will be
            scanned.  If count is omitted, then one bit  will  be
            scanned.  For example,
                   binary scan \x07\x87\x05 b5b* var1 var2
            will   return   2  with  11100  stored  in  var1  and
            1110000110100000 stored in var2.

       B    This form is the same as b, except the bits are taken
            in high-to-low order within each byte.  For example,
                   binary scan \x70\x87\x05 B5B* var1 var2
            will   return   2  with  01110  stored  in  var1  and
            1000011100000101 stored in var2.

       h    The data is turned into a string of count hexadecimal
            digits in low-to-high order represented as a sequence
            of characters in the set  ``0123456789abcdef''.   The
            data  bytes  are  scanned in first to last order with
            the hex  digits  being  taken  in  low-to-high  order
            within  each  byte.   Any extra bits in the last byte
            are ignored.  If count is *, then all of the  remain-
            ing  hex  digits in string will be scanned.  If count
            is omitted, then one hex digit will be scanned.   For
            example,
                   binary scan \x07\x86\x05 h3h* var1 var2
            will  return  2 with 706 stored in var1 and 50 stored
            in var2.

       H    This form is the same as h,  except  the  digits  are
            taken  in  high-to-low  order  within each byte.  For
            example,
                   binary scan \x07\x86\x05 H3H* var1 var2
            will return 2 with 078 stored in var1 and  05  stored
            in var2.

       c    The  data  is turned into count 8-bit signed integers
            and stored in the corresponding variable as  a  list.
            If  count  is  *,  then all of the remaining bytes in
            string will be scanned.  If count  is  omitted,  then
            one 8-bit integer will be scanned.  For example,
                   binary scan \x07\x86\x05 c2c* var1 var2
            will return 2 with 7 -122 stored in var1 and 5 stored
            in var2.  Note that the integers returned are signed,
            but  they  can be converted to unsigned 8-bit quanti-
            ties using an expression like:
                   expr ( $num + 0x100 ) % 0x100

       s    The data is interpreted as count 16-bit signed  inte-
            gers  represented  in  little-endian byte order.  The
            integers are stored in the corresponding variable  as
            a  list.   If  count  is *, then all of the remaining
            bytes in string will be scanned.  If count  is  omit-
            ted,  then  one  16-bit integer will be scanned.  For
            example,
                   binary scan \x05\x00\x07\x00\xf0\xff s2s* var1 var2
            will return 2 with 5 7 stored in var1 and -16  stored
            in var2.  Note that the integers returned are signed,
            but they can be converted to unsigned 16-bit  quanti-
            ties using an expression like:
                   expr ( $num + 0x10000 ) % 0x10000

       S    This  form  is  the same as s except that the data is
            interpreted as count 16-bit  signed  integers  repre-
            sented in big-endian byte order.  For example,
                   binary scan \x00\x05\x00\x07\xff\xf0 S2S* var1 var2
            will  return 2 with 5 7 stored in var1 and -16 stored
            in var2.

       i    The data is interpreted as count 32-bit signed  inte-
            gers  represented  in  little-endian byte order.  The
            integers are stored in the corresponding variable  as
            a  list.   If  count  is *, then all of the remaining
            bytes  in  string  will  be  scanned.   If  count  is
            omitted,  then  one  32-bit  integer will be scanned.
            For example,
                   binary scan \x05\x00\x00\x00\x07\x00\x00\x00\xf0\xff\xff\xff i2i* var1 var2
            will return 2 with 5 7 stored in var1 and -16  stored
            in  var2.  Note that the integers returned are signed
            and cannot be represented by Tcl as unsigned  values.

       I    This  form  is  the same as I except that the data is
            interpreted as count 32-bit  signed  integers  repre-
            sented in big-endian byte order.  For example,
                   binary scan \x00\x00\x00\x05\x00\x00\x00\x07\xff\xff\xff\xf0 I2I* var1 var2
            will  return 2 with 5 7 stored in var1 and -16 stored
            in var2.

       w    The data is interpreted as count 64-bit signed  inte-
            gers  represented  in  little-endian byte order.  The 
            integers are stored in the corresponding variable  as 
            a  list.   If  count  is *, then all of the remaining 
            bytes in string will be scanned.  If count  is  omit-
            ted,  then  one  64-bit integer will be scanned.  For 
            example,                                              
                   binary scan \x05\x00\x00\x00\x07\x00\x00\x00\xf0\xff\xff\xff wi* var1 var2
            will return 2 with 30064771077 stored in var1 and -16 
            stored  in var2.  Note that the integers returned are 
            signed and cannot be represented by Tcl  as  unsigned 
            values.                                               

       W                                                                 
            This form is the same as w except that  the  data  is 
            interpreted  as  count  64-bit signed integers repre-
            sented in big-endian byte order.  For example,        
                   binary scan \x00\x00\x00\x05\x00\x00\x00\x07\xff\xff\xff\xf0 WI* var1 var2
            will return 2 with 21474836487 stored in var1 and -16 
            stored in var2.

       f    The  data  is  interpreted  as count single-precision
            floating point numbers in the machine's native repre-
            sentation.   The floating point numbers are stored in
            the corresponding variable as a list.  If count is *,
            then  all  of  the  remaining bytes in string will be
            scanned.  If count is omitted, then one single-preci-
            sion floating point number will be scanned.  The size
            of a floating point number may vary across  architec-
            tures,  so  the  number of bytes that are scanned may
            vary.  If the data does not represent a valid  float-
            ing  point  number,  the resulting value is undefined
            and compiler dependent.  For example,  on  a  Windows
            system running on an Intel Pentium processor,
                   binary scan \x3f\xcc\xcc\xcd f var1
            will return 1 with 1.6000000238418579 stored in var1.

       d    This form is the same as f except that  the  data  is
            interpreted  as count double-precision floating point
            numbers in the machine's native  representation.  For
            example, on a Windows system running on an Intel Pen-
            tium processor,
                   binary scan \x9a\x99\x99\x99\x99\x99\xf9\x3f d var1
            will return 1 with 1.6000000000000001 stored in var1.

       x    Moves  the  cursor forward count bytes in string.  If
            count is * or is larger  than  the  number  of  bytes
            after  the  current  cursor cursor position, then the
            cursor is positioned after the last byte  in  string.
            If count is omitted, then the cursor is moved forward
            one byte.  Note that this type does  not  consume  an
            argument.  For example,
                   binary scan \x01\x02\x03\x04 x2H* var1
            will return 1 with 0304 stored in var1.

       X    Moves  the  cursor  back  count  bytes in string.  If
            count is * or is larger than the current cursor posi-
            tion,  then the cursor is positioned at location 0 so
            that the next byte scanned will be the first byte  in
            string.  If count is omitted then the cursor is moved
            back one byte.  Note that this type does not  consume
            an argument.  For example,
                   binary scan \x01\x02\x03\x04 c2XH* var1 var2
            will  return  2  with  1  2 stored in var1 and 020304
            stored in var2.

       @    Moves the cursor to the absolute location in the data
            string  specified  by  count.   Note  that position 0
            refers to the first byte in string.  If count  refers
            to a position beyond the end of string, then the cur-
            sor is positioned after the last byte.  If  count  is
            omitted,  then an error will be generated.  For exam-
            ple,
                   binary scan \x01\x02\x03\x04 c2@1H* var1 var2
            will return 2 with 1 2  stored  in  var1  and  020304
            stored in var2.


PLATFORM ISSUES
       Sometimes it is desirable to format or scan integer values
       in the native byte order for the machine.   Refer  to  the
       byteOrder  element  of  the  tcl_platform  array to decide
       which type character to use when  formatting  or  scanning
       integers.


KEYWORDS
       binary, format, scan


_________________________________________________________________

NAME
       break - Abort looping command

SYNOPSIS
       break
_________________________________________________________________


DESCRIPTION
       This  command  is  typically  invoked inside the body of a
       looping command such as  for  or  foreach  or  while.   It
       returns  a  TCL_BREAK code, which causes a break exception
       to occur.  The exception causes the current script  to  be
       aborted  out  to  the  innermost  containing loop command,
       which then aborts  its  execution  and  returns  normally.
       Break  exceptions  are  also handled in a few other situa-
       tions, such as the catch command, Tk event  bindings,  and
       the outermost scripts of procedure bodies.


KEYWORDS
       abort, break, loop


_________________________________________________________________

NAME
       catch - Evaluate script and trap exceptional returns

SYNOPSIS
       catch script ?varName?
_________________________________________________________________


DESCRIPTION
       The  catch  command  may  be  used  to prevent errors from
       aborting command  interpretation.   Catch  calls  the  Tcl
       interpreter  recursively  to  execute  script,  and always
       returns without raising an error, regardless of any errors
       that might occur while executing script.

       If  script  raises  an error, catch will return a non-zero
       integer value corresponding  to  one  of  the  exceptional
       return  codes  (see tcl.h for the definitions of code val-
       ues).  If the varName argument is given, then the variable
       it  names  is  set  to the error message from interpreting
       script.

       If script does not raise an error,  catch  will  return  0
       (TCL_OK)  and  set the variable to the value returned from
       script.

       Note that catch catches all  exceptions,  including  those
       generated  by  break  and continue as well as errors.  The
       only errors that are not caught are  syntax  errors  found
       when  the  script  is compiled.  This is because the catch
       command only catches  errors  during  runtime.   When  the
       catch  statement  is  compiled,  the script is compiled as
       well and any syntax errors will generate a Tcl error.


EXAMPLES
       The catch command may be used in an if to branch based  on
       the success of a script.

              if { [catch {open $someFile w} fid] } {
                  puts stderr "Could not open $someFile for writing\n$fid"
                  exit 1
              }
       The  catch  command will not catch compiled syntax errors.
       The first time proc foo is called, the body will  be  com-
       piled and a Tcl error will be generated.

              proc foo {} {
                  catch {expr {1 +- }}
              }


KEYWORDS
       catch, error


_________________________________________________________________

NAME
       cd - Change working directory

SYNOPSIS
       cd ?dirName?
_________________________________________________________________


DESCRIPTION
       Change the current working directory to dirName, or to the
       home directory (as specified in the HOME environment vari-
       able) if dirName is not given.  Returns an empty string.


KEYWORDS
       working directory


_________________________________________________________________

NAME
       clock - Obtain and manipulate time

SYNOPSIS
       clock option ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       This  command  performs one of several operations that may
       obtain or manipulate strings or values that represent some
       notion  of  time.   The  option  argument  determines what
       action is carried out by the command.  The  legal  options
       (which may be abbreviated) are:

       clock clicks                                               
       ?-milliseconds?                                      
              Return a high-resolution time value  as  a  system- 
              dependent  integer value.  The unit of the value is 
              system-dependent but should be the highest  resolu-
              tion  clock  available  on the system such as a CPU 
              cycle counter. If -milliseconds is specified,  then 
              the value is guaranteed to be of millisecond granu-
              larity.  This value should only  be  used  for  the 
              relative measurement of elapsed time.

       clock format clockValue ?-format string? ?-gmt boolean?
              Converts  an integer time value, typically returned
              by clock seconds, clock scan, or the atime,  mtime,
              or  ctime  options  of  the file command, to human-
              readable form.  If the -format argument is  present
              the  next  argument  is a string that describes how
              the date and  time  are  to  be  formatted.   Field
              descriptors  consist  of  a  %  followed by a field
              descriptor character.   All  other  characters  are
              copied  into  the  result.  Valid field descriptors
              are:

              %%     Insert a %.

              %a     Abbreviated weekday name (Mon, Tue, etc.).

              %A     Full weekday name (Monday, Tuesday, etc.).

              %b     Abbreviated month name (Jan, Feb, etc.).

              %B     Full month name.                             

              %c                                                                
                     Locale  specific  date and time.  The format 
                     for date and time in the default "C"  locale 
                     on  Unix/Mac  is "%a %b %d %H:%M:%S %Y".  On 
                     Windows, this value is the  locale  specific 
                     long  date  and  time,  as  specified in the 
                     Regional Options control panel settings.     

              %C                                                                
                     First  two digits of the four-digit year (19 
                     or 20).

              %d     Day of month (01 - 31).                      

              %D                                                                
                     Date as %m/%d/%y.                            

              %e                                                                
                     Day of month (1 - 31), no leading zeros.     

              %h                                                                
                     Abbreviated month name.

              %H     Hour in 24-hour format (00 - 23).            

              %I                                                                
                     Hour in 12-hour format (01 - 12).

              %j     Day of year (001 - 366).                     

              %k                                                                
                     Hour  in  24-hour  format,  without  leading 
                     zeros (0 - 23).                              

              %l                                                                
                     Hour  in  12-hour  format,  without  leading 
                     zeros (1 - 12).

              %m     Month number (01 - 12).

              %M     Minute (00 - 59).                            

              %n                                                                
                     Insert a newline.

              %p     AM/PM indicator.                             

              %r                                                                
                     Time in a locale-specific "meridian" format. 
                     The  "meridian"  format  in  the default "C" 
                     locale is "%I:%M:%S %p".                     

              %R                                                                
                     Time as %H:%M.                               

              %s                                                                
                     Count of seconds since the epoch,  expressed 
                     as a decimal integer.


              %S     Seconds (00 - 59).                           

              %t                                                                
                     Insert a tab.                                

              %T                                                                
                     Time as %H:%M:%S.                            

              %u                                                                
                     Weekday number (Monday = 1, Sunday = 7).

              %U     Week of year (00 - 52), Sunday is the  first
                     day of the week.                             

              %V                                                                
                     Week of year according  to  ISO-8601  rules. 
                     Week  1 of a given year is the week contain-
                     ing 4 January.                               

              %w                                                                
                     Weekday number (Sunday = 0, Saturday = 6).

              %W     Week  of year (00 - 52), Monday is the first
                     day of the week.                             

              %x                                                                
                     Locale specific date format.  The format for 
                     a  date  in  the  default  "C"  locale   for 
                     Unix/Mac  is  "%m/%d/%y".   On Windows, this 
                     value is the locale specific short date for-
                     mat,  as  specified  in the Regional Options 
                     control panel settings.                      

              %X                                                                
                     Locale  specific  24-hour  time format.  The 
                     format for a 24-hour time in the default "C" 
                     locale  for Unix/Mac is "%H:%M:%S".  On Win-
                     dows, this value is the locale specific time 
                     format, as specified in the Regional Options 
                     control panel settings.

              %y     Year without century (00 - 99).

              %Y     Year with century (e.g. 1990)

              %Z     Time zone name.

              If the -format argument is not specified, the  for-
              mat  string  "%a %b %d %H:%M:%S %Z %Y" is used.  If
              the -gmt argument is present the next argument must
              be  a boolean which if true specifies that the time
              will be formatted as Greenwich Mean Time. If  false
              then  the local timezone will be used as defined by
              the operating environment.


       clock scan dateString ?-base clockVal? ?-gmt boolean?
              Convert dateString to an integer clock  value  (see
              clock seconds).  This command can parse and convert
              virtually any standard  date  and/or  time  string,
              which can include standard time zone mnemonics.  If
              only a time  is  specified,  the  current  date  is
              assumed.   If  the  string  does not contain a time
              zone mnemonic, the  local  time  zone  is  assumed,
              unless the -gmt argument is true, in which case the
              clock value is calculated assuming that the  speci-
              fied  time  is  relative  to  Greenwich  Mean Time.
              -gmt, if specified, affects only the computed  time
              value;  it  does  not  impact the interpretation of
              -base.

              If the -base flag is specified, the  next  argument
              should  contain  an  integer clock value.  Only the
              date in this value is used, not the time.  This  is
              useful  for  determining the time on a specific day
              or doing other date-relative conversions.

              The dateString consists of zero or more  specifica-
              tions of the following form:

              time   A  time  of  day,  which  is  of  the  form:
                     hh?:mm?:ss??   ?meridian?  ?zone?  or   hhmm
                     ?meridian?  ?zone?. If no meridian is speci-
                     fied, hh is interpreted on a 24-hour  clock.

              date   A specific month and day with optional year.
                     The acceptable formats are mm/dd?/yy?,  mon-
                     thname dd ?, yy?, dd monthname ?yy?, day, dd
                     monthname yy, ?CC?yymmdd, ?CC?yy-mm-dd,  dd-
                     monthname-?CC?yy.   The  default year is the
                     current year.  If the year is less than 100, 
                     we  treat  the  years 00-68 as 2000-2068 and 
                     the years 69-99 as 1969-1999.  Not all plat-
                     forms  can  represent the years 38-70, so an 
                     error may result if these years are used.

              ISO 8601 point-in-time
                     An  ISO  8601  point-in-time  specification,
                     such as CCyymmddThhmmss, where T is the lit-
                     eral  T,  CCyymmdd   hhmmss,   or   CCyymmd-
                     dThh:mm:ss.

              relative time
                     A  specification  relative  to  the  current
                     time.  The format is number unit  acceptable
                     units are year, fortnight, month, week, day,
                     hour, minute (or min), and second (or  sec).
                     The  unit  can be specified as a singular or
                     plural, as in 3 weeks.  These modifiers  may
                     also   be  specified:  tomorrow,  yesterday,


                     today, now, last, this, next, ago.

              The actual date is calculated according to the fol-
              lowing steps.  First, any absolute date and/or time
              is processed and converted.  Using that time as the
              base,  day-of-week specifications are added.  Next,
              relative specifications are used.  If a date or day
              is  specified,  and no absolute or relative time is
              given, midnight is used.  Finally, a correction  is
              applied so that the correct hour of the day is pro-
              duced after allowing for daylight savings time dif-
              ferences  and  the correct date is given when going
              from the end of a long month to a short month.

              Daylight savings time correction  is  applied  only
              when  the  relative  time  is specified in units of
              days or more, ie, days, weeks,  fortnights,  months
              or  years.   This means that when crossing the day-
              light savings time boundary, different results will
              be  given for clock scan "1 day" and clock scan "24
              hours":
                     % clock scan "1 day" -base [clock scan 1999-10-31]
                     941443200
                     % clock scan "24 hours" -base [clock scan 1999-10-31]
                     941439600

       clock seconds
              Return the current date and time as a system-depen-
              dent  integer value.  The unit of the value is sec-
              onds, allowing it to be used for relative time cal-
              culations.   The  value is usually defined as total
              elapsed time  from  an  ``epoch''.   You  shouldn't
              assume the value of the epoch.


KEYWORDS
       clock, date, time


_________________________________________________________________

NAME
       close - Close an open channel.

SYNOPSIS
       close channelId
_________________________________________________________________


DESCRIPTION
       Closes the channel given by channelId.

       ChannelId  must  be an identifier for an open channel such 
       as a Tcl standard channel (stdin, stdout, or stderr),  the 
       return  value from an invocation of open or socket, or the 
       result of a channel creation command  provided  by  a  Tcl 
       extension.

       All  buffered  output  is  flushed to the channel's output
       device, any buffered input is  discarded,  the  underlying
       file  or  device is closed, and channelId becomes unavail-
       able for use.

       If the channel is blocking, the command  does  not  return 
       until  all output is flushed.  If the channel is nonblock-
       ing and there is unflushed  output,  the  channel  remains 
       open  and  the command returns immediately; output will be 
       flushed in the background and the channel will  be  closed 
       when all the flushing is complete.

       If  channelId is a blocking channel for a command pipeline
       then close waits for the child processes to complete.

       If the channel is shared between interpreters, then  close 
       makes  channelId  unavailable  in the invoking interpreter 
       but has no other effect until all of  the  sharing  inter-
       preters  have  closed  the  channel.  When the last inter-
       preter in which the channel is registered  invokes  close, 
       the  cleanup actions described above occur. See the interp 
       command for a description of channel sharing.              

       Channels are automatically closed when an  interpreter  is 
       destroyed  and  when  the  process  exits.   Channels  are 
       switched to blocking mode, to ensure that  all  output  is 
       correctly flushed before the process exits.

       The  command  returns an empty string, and may generate an
       error if an error occurs while flushing output.



KEYWORDS
       blocking, channel, close, nonblocking


_________________________________________________________________

NAME
       concat - Join lists together

SYNOPSIS
       concat ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       This  command  joins  each  of its arguments together with
       spaces after trimming leading  and  trailing  spaces  from
       each  of  them.   If all the arguments are lists, this has
       the same effect as concatenating them into a single  list.
       It permits any number of arguments.  For example, the com-
       mand
              concat a b {c d e} {f {g h}}
       will return
              a b c d e f {g h}
       as its result, and
              concat " a b {c   " d "  e} f"
       will return
              a b {c d e} f
       as its result.

       If no args are supplied, the result is an empty string.


KEYWORDS
       concatenate, join, lists


_________________________________________________________________

NAME
       continue - Skip to the next iteration of a loop

SYNOPSIS
       continue
_________________________________________________________________


DESCRIPTION
       This  command  is  typically  invoked inside the body of a
       looping command such as  for  or  foreach  or  while.   It
       returns  a  TCL_CONTINUE  code,  which  causes  a continue
       exception to occur.   The  exception  causes  the  current
       script  to be aborted out to the innermost containing loop
       command, which then continues with the next  iteration  of
       the  loop.   Catch  exceptions  are  also handled in a few
       other situations, such as the catch command and the outer-
       most scripts of procedure bodies.


KEYWORDS
       continue, iteration, loop


_________________________________________________________________

NAME
       encoding - Manipulate encodings

SYNOPSIS
       encoding option ?arg arg ...?
_________________________________________________________________


INTRODUCTION
       Strings  in  Tcl  are encoded using 16-bit Unicode charac-
       ters.  Different operating system interfaces  or  applica-
       tions  may  generate  strings  in  other encodings such as
       Shift-JIS.  The encoding command helps to bridge  the  gap
       between Unicode and these other formats.


DESCRIPTION
       Performs  one  of  several  encoding  related  operations,
       depending on option.  The legal options are:

       encoding convertfrom ?encoding? data
              Convert data to Unicode from the  specified  encod-
              ing.   The characters in data are treated as binary
              data where the lower 8-bits of  each  character  is
              taken  as a single byte.  The resulting sequence of
              bytes is treated  as  a  string  in  the  specified
              encoding.   If  encoding is not specified, the cur-
              rent system encoding is used.

       encoding convertto ?encoding? string
              Convert string from Unicode to the specified encod-
              ing.  The result is a sequence of bytes that repre-
              sents the converted string.  Each byte is stored in
              the lower 8-bits of a Unicode character.  If encod-
              ing is not specified, the current  system  encoding
              is used.

       encoding names
              Returns  a  list containing the names of all of the
              encodings that are currently available.

       encoding system ?encoding?
              Set the system encoding to encoding. If encoding is
              omitted then the command returns the current system
              encoding.  The system encoding is used whenever Tcl
              passes strings to system calls.


EXAMPLE
       It  is  common practice to write script files using a text
       editor that produces output in the euc-jp encoding,  which
       represents   the  ASCII  characters  as  singe  bytes  and
       Japanese characters as two bytes.  This makes it  easy  to
       embed literal strings that correspond to non-ASCII charac-
       ters by simply typing the strings in place in the  script.
       However,  because  the  source  command always reads files
       using the ISO8859-1 encoding, Tcl will treat each byte  in
       the  file as a separate character that maps to the 00 page
       in Unicode.  The resulting Tcl strings  will  not  contain
       the expected Japanese characters.  Instead, they will con-
       tain a sequence of Latin-1 characters that  correspond  to
       the  bytes  of  the original string.  The encoding command
       can be  used  to  convert  this  string  to  the  expected
       Japanese Unicode characters.  For example,
                set s [encoding convertfrom euc-jp "\xA4\xCF"]
       would  return  the  Unicode  string "\u306F", which is the
       Hiragana letter HA.


KEYWORDS
       encoding


_________________________________________________________________

NAME
       eof - Check for end of file condition on channel

SYNOPSIS
       eof channelId
_________________________________________________________________


DESCRIPTION
       Returns  1 if an end of file condition occurred during the
       most recent input operation on channelId (such as gets), 0
       otherwise.

       ChannelId  must  be an identifier for an open channel such 
       as a Tcl standard channel (stdin, stdout, or stderr),  the 
       return  value from an invocation of open or socket, or the 
       result of a channel creation command  provided  by  a  Tcl 
       extension.
  

KEYWORDS
       channel, end of file


_________________________________________________________________

NAME
       error - Generate an error

SYNOPSIS
       error message ?info? ?code?
_________________________________________________________________


DESCRIPTION
       Returns a TCL_ERROR code, which causes command interpreta-
       tion to be unwound.  Message is a string that is  returned
       to the application to indicate what went wrong.

       If  the  info argument is provided and is non-empty, it is
       used to initialize the global variable errorInfo.   error-
       Info  is  used  to accumulate a stack trace of what was in
       progress  when  an  error  occurred;  as  nested  commands
       unwind, the Tcl interpreter adds information to errorInfo.
       If the info argument is present, it is used to  initialize
       errorInfo  and  the  first increment of unwind information
       will not be added by the Tcl interpreter.  In other words,
       the  command  containing the error command will not appear
       in errorInfo; in its place will be info.  This feature  is
       most  useful  in  conjunction with the catch command: if a
       caught error cannot be handled successfully, info  can  be
       used to return a stack trace reflecting the original point
       of occurrence of the error:
              catch {...} errMsg
              set savedInfo $errorInfo
              ...
              error $errMsg $savedInfo

       If the code argument is present, then its value is  stored
       in  the  errorCode  global  variable.   This  variable  is
       intended to hold a  machine-readable  description  of  the
       error  in  cases  where such information is available; see
       the tclvars manual page for information on the proper for-
       mat  for  the  variable.  If the code argument is not pre-
       sent, then errorCode is automatically reset to ``NONE'' by
       the Tcl interpreter as part of processing the error gener-
       ated by the command.


KEYWORDS
       error, errorCode, errorInfo


_________________________________________________________________

NAME
       eval - Evaluate a Tcl script

SYNOPSIS
       eval arg ?arg ...?
_________________________________________________________________


DESCRIPTION
       Eval  takes one or more arguments, which together comprise
       a Tcl script containing one or more commands.   Eval  con-
       catenates  all  its  arguments  in the same fashion as the
       concat command, passes the concatenated string to the  Tcl
       interpreter  recursively,  and  returns the result of that
       evaluation (or any error generated by it).  Note that  the
       list  command quotes sequences of words in such a way that
       they are not further expanded by the eval command.


KEYWORDS
       concatenate, evaluate, script




_________________________________________________________________

NAME
       exec - Invoke subprocess(es)

SYNOPSIS
       exec ?switches? arg ?arg ...?
_________________________________________________________________


DESCRIPTION
       This  command treats its arguments as the specification of
       one or more subprocesses to execute.  The  arguments  take
       the  form  of  a  standard  shell  pipeline where each arg
       becomes one word of a command, and each  distinct  command
       becomes a subprocess.

       If  the  initial  arguments to exec start with - then they
       are treated as command-line switches and are not  part  of
       the  pipeline  specification.   The following switches are
       currently supported:

       -keepnewline Retains a trailing newline in the  pipeline's
                    output.   Normally a trailing newline will be
                    deleted.

       --           Marks the end of switches.  The argument fol-
                    lowing  this one will be treated as the first
                    arg even if it starts with a -.

       If an arg  (or  pair  of  arg's)  has  one  of  the  forms
       described  below  then  it  is used by exec to control the
       flow of input and output among the  subprocess(es).   Such
       arguments  will  not  be passed to the subprocess(es).  In
       forms such as ``< fileName'' fileName may either be  in  a
       separate  argument from ``<'' or in the same argument with
       no intervening space (i.e. ``<fileName'').

       |              Separates   distinct   commands   in    the
                      pipeline.   The standard output of the pre-
                      ceding command will be piped into the stan-
                      dard input of the next command.

       |&             Separates    distinct   commands   in   the
                      pipeline.  Both standard output  and  stan-
                      dard error of the preceding command will be
                      piped into the standard input of  the  next
                      command.   This  form  of redirection over-
                      rides forms such as 2> and >&.

       < fileName     The file named by fileName  is  opened  and
                      used  as  the  standard input for the first
                      command in the pipeline.


       <@ fileId      FileId must be the identifier for  an  open
                      file,  such as the return value from a pre-
                      vious call to open.   It  is  used  as  the
                      standard input for the first command in the
                      pipeline.  FileId must have been opened for
                      reading.

       << value       Value is passed to the first command as its
                      standard input.

       > fileName     Standard output from the  last  command  is
                      redirected  to  the  file  named  fileName,
                      overwriting its previous contents.

       2> fileName    Standard error from  all  commands  in  the
                      pipeline  is  redirected  to the file named
                      fileName,  overwriting  its  previous  con-
                      tents.

       >& fileName    Both  standard output from the last command
                      and standard error from  all  commands  are
                      redirected  to  the  file  named  fileName,
                      overwriting its previous contents.

       >> fileName    Standard output from the  last  command  is
                      redirected  to  the  file  named  fileName,
                      appending to it rather than overwriting it.

       2>> fileName   Standard  error  from  all  commands in the
                      pipeline is redirected to  the  file  named
                      fileName, appending to it rather than over-
                      writing it.

       >>& fileName   Both standard output from the last  command
                      and  standard  error  from all commands are
                      redirected  to  the  file  named  fileName,
                      appending to it rather than overwriting it.

       >@ fileId      FileId must be the identifier for  an  open
                      file,  such as the return value from a pre-
                      vious call to open.  Standard  output  from
                      the  last command is redirected to fileId's
                      file, which must have been opened for writ-
                      ing.

       2>@ fileId     FileId  must  be the identifier for an open
                      file, such as the return value from a  pre-
                      vious  call  to  open.  Standard error from
                      all commands in the pipeline is  redirected
                      to  fileId's file.  The file must have been
                      opened for writing.

       >&@ fileId     FileId must be the identifier for  an  open
                      file,  such  as  the  return  value  from a


                      previous call to open.  Both standard  out-
                      put  from  the  last  command  and standard
                      error from all commands are  redirected  to
                      fileId's  file.   The  file  must have been
                      opened for writing.

       If standard output has not been redirected then  the  exec
       command  returns the standard output from the last command
       in the pipeline.  If any of the commands in  the  pipeline
       exit abnormally or are killed or suspended, then exec will
       return an error and the error  message  will  include  the
       pipeline's  output  followed  by error messages describing
       the abnormal terminations;  the  errorCode  variable  will
       contain  additional  information  about  the last abnormal
       termination encountered.  If any of the commands writes to
       its  standard  error  file  and  that standard error isn't
       redirected, then exec will return  an  error;   the  error
       message  will include the pipeline's standard output, fol-
       lowed by messages about abnormal  terminations  (if  any),
       followed by the standard error output.

       If  the last character of the result or error message is a
       newline then that character is normally deleted  from  the
       result  or  error  message.  This is consistent with other
       Tcl return values, which don't normally end with newlines.
       However,  if  -keepnewline  is specified then the trailing
       newline is retained.

       If standard input isn't redirected with ``<'' or ``<<'' or
       ``<@''  then  the  standard input for the first command in
       the pipeline is taken from the application's current stan-
       dard input.

       If  the  last  arg is ``&'' then the pipeline will be exe-
       cuted in background.  In this case the exec  command  will
       return  a  list whose elements are the process identifiers
       for all of the subprocesses in the pipeline.  The standard
       output  from  the  last command in the pipeline will go to
       the application's standard output if it hasn't been  redi-
       rected,  and  error output from all of the commands in the
       pipeline will go to the application's standard error  file
       unless redirected.

       The  first  word  in  each command is taken as the command
       name; tilde-substitution is performed on it,  and  if  the
       result  contains  no  slashes  then the directories in the
       PATH environment variable are searched for  an  executable
       by  the  given name.  If the name contains a slash then it
       must refer to an executable  reachable  from  the  current
       directory.  No ``glob'' expansion or other shell-like sub-
       stitutions are performed on the arguments to commands.


PORTABILITY ISSUES                                                
       Windows (all versions)                                            
              Reading  from  or  writing  to  a socket, using the 
              ``@ fileId'' notation, does not work.  When reading 
              from  a  socket, a 16-bit DOS application will hang 
              and a 32-bit application  will  return  immediately 
              with  end-of-file.  When either type of application 
              writes to a socket, the information is instead sent 
              to the console, if one is present, or is discarded. 

              The Tk console text widget does  not  provide  real 
              standard IO capabilities.  Under Tk, when redirect-
              ing from standard input, all applications will  see 
              an immediate end-of-file; information redirected to 
              standard output or  standard  error  will  be  dis-
              carded.                                             

              Either  forward or backward slashes are accepted as 
              path separators  for  arguments  to  Tcl  commands. 
              When executing an application, the path name speci-
              fied for the application may also  contain  forward 
              or  backward  slashes  as path separators.  Bear in 
              mind,  however,  that  most  Windows   applications 
              accept  arguments  with  forward  slashes  only  as 
              option delimiters and backslashes  only  in  paths. 
              Any arguments to an application that specify a path 
              name with forward slashes will not automatically be 
              converted  to  use  the backslash character.  If an 
              argument contains forward slashes as the path sepa-
              rator,  it  may  or may not be recognized as a path 
              name, depending on the program.                     

              Additionally, when calling a 16-bit DOS or  Windows 
              3.X application, all path names must use the short, 
              cryptic, path format (e.g., using  ``applba~1.def'' 
              instead  of  ``applbakery.default''),  which can be 
              obtained with the file attributes $fileName -short-
              name command.                                       

              Two or more forward or backward slashes in a row in 
              a path refer to a network  path.   For  example,  a 
              simple concatenation of the root directory c:/ with 
              a subdirectory /windows/system will yield  c://win-
              dows/system (two slashes together), which refers to 
              the mount point called system on the machine called 
              windows (and the c:/ is ignored), and is not equiv-
              alent  to  c:/windows/system,  which  describes   a 
              directory  on  the current computer.  The file join 
              command should be used to concatenate  path  compo-
              nents.                                              

              Note that there are two general types of Win32 con-
              sole applications:                                  
                     1)  CLI  --  CommandLine  Interface,  simple 
                     stdio exchange. netstat.exe for example.     
                     2)  TUI  --  Textmode  User  Interface,  any 
                     application that accesses  the  console  API 
                     for  doing  such  things as cursor movement, 
                     setting text color,  detecting  key  presses 
                     and mouse movement, etc...  An example would 
                     be  telnet.exe  from  Windows  2000.   These 
                     types  of  applications  are not common in a 
                     windows environment, but do exist.           
              exec will not work well with TUI applications  when 
              a console is not present, as is done when launching 
              applications under wish.  It is desirable  to  have 
              console  applications hidden and detached.  This is 
              a designed-in limitation as exec wants to  communi-
              cate  over  pipes.   The Expect extension addresses 
              this issue when communication between a TUI  appli-
              cation is desired.                                  


       Windows NT                                                        
              When  attempting  to  execute  an application, exec 
              first searches for the name as  it  was  specified. 
              Then,  in  order,  .com,  .exe,  and for the longer 
              name.  If a directory name  was  not  specified  as 
              part  of the application name, the following direc-
              tories are automatically  searched  in  order  when 
              attempting to locate the application:               

                     The  directory from which the Tcl executable 
                     was loaded.                                  
                     The current directory.                       
                     The Windows NT 32-bit system directory.      
                     The Windows NT 16-bit system directory.      
                     The Windows NT home directory.               
                     The directories listed in the path.          

              In order to execute the shell builtin commands like 
              dir  and  copy,  the  caller must prepend ``cmd.exe 
              /c '' to the desired command.                       


       Windows 95                                                        
              When attempting to  execute  an  application,  exec 
              first  searches  for  the name as it was specified. 
              Then, in order, .com,  .exe,  and  for  the  longer 
              name.   If  a  directory  name was not specified as 
              part of the application name, the following  direc-
              tories  are  automatically  searched  in order when 
              attempting to locate the application:               

                     The directory from which the Tcl  executable 
                     was loaded.                                  
                     The current directory.                       
                     The Windows 95 system directory.             
                     The Windows 95 home directory.               
                     The directories listed in the path.          

              In order to execute the shell builtin commands like 
              dir and copy, the caller must prepend ``command.com 
              /c '' to the desired command.                       

              Once  a  16-bit  DOS  application has read standard 
              input from a console  and  then  quit,  all  subse-
              quently  run  16-bit  DOS applications will see the 
              standard input as already closed.  32-bit  applica-
              tions  do  not  have this problem and will run cor-
              rectly, even after a 16-bit DOS application  thinks 
              that  standard  input is closed.  There is no known 
              workaround for this bug at this time.               

              Redirection between the NUL: device  and  a  16-bit 
              application does not always work.  When redirecting 
              from NUL:, some applications may hang, others  will 
              get  an infinite stream of ``0x01'' bytes, and some 
              will actually correctly get  an  immediate  end-of- 
              file;  the  behavior seems to depend upon something 
              compiled into the application itself.   When  redi-
              recting  greater than 4K or so to NUL:, some appli-
              cations will hang.  The above problems do not  hap-
              pen with 32-bit applications.                       

              All  DOS 16-bit applications are run synchronously. 
              All standard input from a  pipe  to  a  16-bit  DOS 
              application is collected into a temporary file; the 
              other end of the pipe must  be  closed  before  the 
              16-bit DOS application begins executing.  All stan-
              dard output or error from a 16-bit DOS  application 
              to  a  pipe  is collected into temporary files; the 
              application must  terminate  before  the  temporary 
              files  are  redirected  to  the  next  stage of the 
              pipeline.  This is due to a workaround for  a  Win-
              dows  95 bug in the implementation of pipes, and is 
              how the standard Windows 95 DOS shell handles pipes 
              itself.                                             

              Certain  applications,  such as command.com, should 
              not be executed interactively.  Applications  which 
              directly  access  the  console  window, rather than 
              reading from their standard input  and  writing  to 
              their  standard  output may fail, hang Tcl, or even 
              hang the system if their own private console window 
              is not available to them.                           

       Macintosh                                                         
              The exec command is not implemented  and  does  not 
              exist under Macintosh.                              

       Unix                                                              
              The exec command is fully functional and  works  as 
              described.                                          



KEYWORDS                                                          
       execute, pipeline, redirection, subprocess                 


_________________________________________________________________

NAME
       exit - End the application

SYNOPSIS
       exit ?returnCode?
_________________________________________________________________


DESCRIPTION
       Terminate  the process, returning returnCode to the system
       as the exit status.  If returnCode isn't specified then it
       defaults to 0.


KEYWORDS
       exit, process


_________________________________________________________________

NAME
       expr - Evaluate an expression

SYNOPSIS
       expr arg ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       Concatenates arg's (adding separator spaces between them),
       evaluates the result as a Tcl expression, and returns  the
       value.   The  operators permitted in Tcl expressions are a
       subset of the operators permitted in  C  expressions,  and
       they  have  the  same meaning and precedence as the corre-
       sponding C operators.   Expressions  almost  always  yield
       numeric  results  (integer or floating-point values).  For
       example, the expression
              expr 8.2 + 6
       evaluates to 14.2.  Tcl expressions differ from C  expres-
       sions  in  the way that operands are specified.  Also, Tcl
       expressions support non-numeric operands and  string  com-
       parisons.

OPERANDS
       A  Tcl  expression  consists of a combination of operands,
       operators, and  parentheses.   White  space  may  be  used
       between  the operands and operators and parentheses; it is
       ignored by the expression's instructions.  Where possible,
       operands  are interpreted as integer values.  Integer val-
       ues may be specified in  decimal  (the  normal  case),  in
       octal  (if the first character of the operand is 0), or in
       hexadecimal (if the first two characters  of  the  operand
       are  0x).   If an operand does not have one of the integer
       formats given above, then it is  treated  as  a  floating-
       point  number if that is possible.  Floating-point numbers
       may be specified in any of the ways accepted by  an  ANSI-
       compliant  C compiler (except that the f, F, l, and L suf-
       fixes will not be permitted in most  installations).   For
       example,  all  of  the  following are valid floating-point
       numbers:  2.1, 3., 6e4, 7.91e+16.  If no numeric interpre-
       tation  is  possible,  then an operand is left as a string
       (and only a limited set of operators  may  be  applied  to
       it).

       On 32-bit systems, integer values MAX_INT (0x7FFFFFFF) and 
       MIN_INT (-0x80000000) will be represented as  32-bit  val-
       ues,  and integer values outside that range will be repre-
       sented as 64-bit values (if that is possible at all.)

       Operands may be specified in any of the following ways:

       [1]    As an numeric value, either  integer  or  floating-
              point.

       [2]    As  a Tcl variable, using standard $ notation.  The
              variable's value will be used as the operand.

       [3]    As a string enclosed in double-quotes.  The expres-
              sion  parser  will perform backslash, variable, and
              command substitutions on  the  information  between
              the  quotes,  and  use  the  resulting value as the
              operand

       [4]    As a string enclosed  in  braces.   The  characters
              between  the  open  brace  and matching close brace
              will be used as the operand without  any  substitu-
              tions.

       [5]    As a Tcl command enclosed in brackets.  The command
              will be executed and its result will be used as the
              operand.

       [6]    As a mathematical function whose arguments have any
              of the above forms for operands, such  as  sin($x).
              See below for a list of defined functions.

       Where   substitutions  occur  above  (e.g.  inside  quoted
       strings), they are performed by the expression's  instruc-
       tions.   However,  an additional layer of substitution may
       already have been performed by the command  parser  before
       the  expression processor was called.  As discussed below,
       it is usually best to enclose  expressions  in  braces  to
       prevent  the  command parser from performing substitutions
       on the contents.

       For some examples of simple expressions, suppose the vari-
       able a has the value 3 and the variable b has the value 6.
       Then the command on the left side of  each  of  the  lines
       below  will  produce  the  value  on the right side of the
       line:
              expr 3.1 + $a           6.1
              expr 2 + "$a.$b"        5.6
              expr 4*[llength "6 2"]  8
              expr {{word one} < "word $a"}0

OPERATORS
       The valid operators are listed below, grouped in  decreas-
       ing order of precedence:

       -  +  ~  !          Unary minus, unary plus, bit-wise NOT,
                           logical NOT.  None of  these  operands
                           may be applied to string operands, and
                           bit-wise NOT may be  applied  only  to
                           integers.

       *  /  %             Multiply,  divide, remainder.  None of


                           these  operands  may  be  applied   to
                           string  operands, and remainder may be
                           applied only to integers.  The remain-
                           der  will always have the same sign as
                           the  divisor  and  an  absolute  value
                           smaller than the divisor.

       +  -                Add   and  subtract.   Valid  for  any
                           numeric operands.

       <<  >>              Left and right shift.  Valid for inte-
                           ger  operands  only.   A  right  shift
                           always propagates the sign bit.

       <  >  <=  >=        Boolean less, greater,  less  than  or
                           equal,  and  greater  than  or  equal.
                           Each operator produces 1 if the condi-
                           tion  is  true,  0  otherwise.   These
                           operators may be applied to strings as
                           well  as  numeric  operands,  in which
                           case string comparison is used.

       ==  !=              Boolean equal  and  not  equal.   Each
                           operator  produces  a zero/one result.
                           Valid for all operand types.           

       eq  ne                                                            
                           Boolean  string  equal  and string not 
                           equal.   Each  operator   produces   a 
                           zero/one  result.   The  operand types 
                           are interpreted only as strings.

       &                   Bit-wise  AND.   Valid   for   integer
                           operands only.

       ^                   Bit-wise   exclusive  OR.   Valid  for
                           integer operands only.

       |                   Bit-wise  OR.    Valid   for   integer
                           operands only.

       &&                  Logical  AND.   Produces a 1 result if
                           both operands are non-zero,  0  other-
                           wise.   Valid  for boolean and numeric
                           (integers or floating-point)  operands
                           only.

       ||                  Logical  OR.   Produces  a 0 result if
                           both operands are zero,  1  otherwise.
                           Valid  for  boolean and numeric (inte-
                           gers or floating-point) operands only.

       x?y:z               If-then-else, as in C.  If x evaluates
                           to non-zero, then the  result  is  the


                           value  of  y.  Otherwise the result is
                           the value of z.  The  x  operand  must
                           have a numeric value.

       See  the C manual for more details on the results produced
       by each operator.  All of the binary operators group left-
       to-right  within  the same precedence level.  For example,
       the command
              expr 4*2 < 7
       returns 0.

       The &&, ||, and ?:  operators  have  ``lazy  evaluation'',
       just  as in C, which means that operands are not evaluated
       if they are not needed  to  determine  the  outcome.   For
       example, in the command
              expr {$v ? [a] : [b]}
       only one of [a] or [b] will actually be evaluated, depend-
       ing on the value of $v.  Note, however, that this is  only
       true if the entire expression is enclosed in braces;  oth-
       erwise the Tcl parser  will  evaluate  both  [a]  and  [b]
       before invoking the expr command.

MATH FUNCTIONS
       Tcl  supports  the  following  mathematical  functions  in
       expressions:

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


       abs(arg)
              Returns the absolute value  of  arg.   Arg  may  be
              either integer or floating-point, and the result is
              returned in the same form.

       acos(arg)
              Returns the arc cosine of arg, in the range  [0,pi]
              radians. Arg should be in the range [-1,1].

       asin(arg)
              Returns   the   arc  sine  of  arg,  in  the  range
              [-pi/2,pi/2] radians.  Arg should be in  the  range
              [-1,1].

       atan(arg)
              Returns  the  arc  tangent  of  arg,  in  the range
              [-pi/2,pi/2] radians.


       atan2(y, x)
              Returns the  arc  tangent  of  y/x,  in  the  range
              [-pi,pi]  radians.  x and y cannot both be 0.  If x
              is greater than 0, this is equivalent to atan(y/x).

       ceil(arg)
              Returns  the smallest integral floating point value
              (i.e. with a zero fractional part)  not  less  than
              arg.

       cos(arg)
              Returns the cosine of arg, measured in radians.

       cosh(arg)
              Returns  the  hyperbolic  cosine  of  arg.   If the
              result  would  cause  an  overflow,  an  error   is
              returned.

       double(arg)
              If  arg is a floating value, returns arg, otherwise
              converts arg to floating and returns the  converted
              value.

       exp(arg)
              Returns  the exponential of arg, defined as e**arg.
              If the result would cause an overflow, an error  is
              returned.

       floor(arg)
              Returns  the  largest integral floating point value
              (i.e. with a zero fractional part) not greater than
              arg.

       fmod(x, y)
              Returns  the  floating-point remainder of the divi-
              sion of x by y.  If y is 0, an error is returned.

       hypot(x, y)
              Computes the length of the hypotenuse of  a  right-
              angled triangle sqrt(x*x+y*y).

       int(arg)
              If  arg is an integer value, returns arg, otherwise 
              converts arg to an integer (of the same size  as  a 
              machine  word,  i.e. 32-bits on 32-bit systems, and 
              64-bits  on  64-bit  systems)  by  truncation   and 
              returns the converted value.

       log(arg)
              Returns  the natural logarithm of arg.  Arg must be
              a positive value.

       log10(arg)
              Returns the base 10 logarithm of arg.  Arg must  be
              a positive value.

       pow(x, y)
              Computes  the value of x raised to the power y.  If
              x is negative, y must be an integer value.

       rand() Returns a floating point number from zero  to  just
              less  than one or, in mathematical terms, the range
              [0,1).  The seed comes from the internal  clock  of
              the  machine  or  may  be set manual with the srand
              function.

       round(arg)
              If arg is an integer value, returns arg,  otherwise
              converts arg to integer by rounding and returns the
              converted value.

       sin(arg)
              Returns the sine of arg, measured in radians.

       sinh(arg)
              Returns the hyperbolic sine of arg.  If the  result
              would cause an overflow, an error is returned.

       sqrt(arg)
              Returns  the  square root of arg.  Arg must be non-
              negative.

       srand(arg)
              The arg, which must be an integer, is used to reset
              the  seed for the random number generator.  Returns
              the first  random  number  from  that  seed.   Each
              interpreter has its own seed.

       tan(arg)
              Returns the tangent of arg, measured in radians.

       tanh(arg)
              Returns the hyperbolic tangent of arg.

       wide(arg)
              Converts  arg  to a value at least 64-bits wide (by 
              sign-extension if arg is a 32-bit number.)

       In addition to these  predefined  functions,  applications
       may  define  additional  functions  using  Tcl_CreateMath-
       Func().

TYPES, OVERFLOW, AND PRECISION
       All internal computations involving integers are done with
       the  C  type long, and all internal computations involving
       floating-point are done with the C type double.  When con-
       verting  a  string to floating-point, exponent overflow is
       detected and results in a Tcl error.   For  conversion  to
       integer  from string, detection of overflow depends on the
       behavior of some routines in the local C  library,  so  it
       should  be  regarded  as unreliable.  In any case, integer
       overflow and underflow are generally not detected reliably
       for  intermediate  results.   Floating-point  overflow and
       underflow are detected to  the  degree  supported  by  the
       hardware, which is generally pretty reliable.

       Conversion  among  internal  representations  for integer,
       floating-point, and string operands is done  automatically
       as needed.  For arithmetic computations, integers are used
       until some  floating-point  number  is  introduced,  after
       which floating-point is used.  For example,
              expr 5 / 4
       returns 1, while
              expr 5 / 4.0
              expr 5 / ( [string length "abcd"] + 0.0 )
       both   return  1.25.   Floating-point  values  are  always
       returned with a ``.''  or an e so that they will not  look
       like integer values.  For example,
              expr 20.0/5.0
       returns 4.0, not 4.


STRING OPERATIONS
       String  values  may  be used as operands of the comparison
       operators, although the expression evaluator tries  to  do
       comparisons  as  integer  or  floating-point  when it can, 
       except in the case of the eq and ne operators.  If one  of
       the operands of a comparison is a string and the other has
       a numeric value, the numeric operand is converted back  to
       a string using the C sprintf format specifier %d for inte-
       gers and %g for floating-point values.  For  example,  the
       commands
              expr {"0x03" > "2"}
              expr {"0y" < "0x12"}
       both return 1.  The first comparison is done using integer
       comparison, and the second is done using string comparison
       after  the  second  operand is converted to the string 18.
       Because of Tcl's tendency to treat values as numbers when-
       ever possible, it isn't generally a good idea to use oper-
       ators like == when you really want string  comparison  and
       the  values of the operands could be arbitrary;  it's bet-
       ter in these cases to use the eq or ne operators,  or  the 
       string command instead.


PERFORMANCE CONSIDERATIONS
       Enclose  expressions  in braces for the best speed and the
       smallest storage requirements.  This allows the Tcl  byte-
       code compiler to generate the best code.

       As  mentioned  above,  expressions  are substituted twice:
       once by the Tcl parser and once by the expr command.   For
       example, the commands
              set a 3
              set b {$a + 2}
              expr $b*4
       return  11,  not a multiple of 4.  This is because the Tcl
       parser will first substitute $a + 2 for  the  variable  b,
       then  the  expr  command will evaluate the expression $a +
       2*4.

       Most expressions do not require a second round of  substi-
       tutions.   Either  they are enclosed in braces or, if not,
       their variable and command substitutions yield numbers  or
       strings that don't themselves require substitutions.  How-
       ever, because a few unbraced expressions need  two  rounds
       of  substitutions,  the  bytecode compiler must emit addi-
       tional instructions to handle this  situation.   The  most
       expensive  code  is required for unbraced expressions that
       contain command substitutions.  These expressions must  be
       implemented  by  generating new code each time the expres-
       sion is executed.


KEYWORDS
       arithmetic, boolean, compare, expression, fuzzy comparison


_________________________________________________________________

NAME
       fblocked - Test whether the last input operation exhausted
       all available input

SYNOPSIS
       fblocked channelId
_________________________________________________________________


DESCRIPTION
       The fblocked command returns 1 if the  most  recent  input
       operation  on  channelId  returned  less  information than
       requested because all available input was exhausted.   For
       example,  if  gets  is  invoked  when there are only three
       characters  available  for  input   and   no   end-of-line
       sequence,  gets  returns  an empty string and a subsequent
       call to fblocked will return 1.

       ChannelId must be an identifier for an open  channel  such 
       as  a Tcl standard channel (stdin, stdout, or stderr), the 
       return value from an invocation of open or socket, or  the 
       result  of  a  channel  creation command provided by a Tcl 
       extension.


KEYWORDS
       blocking, nonblocking


_________________________________________________________________

NAME
       fconfigure - Set and get options on a channel

SYNOPSIS
       fconfigure channelId
       fconfigure channelId name
       fconfigure channelId name value ?name value ...?
_________________________________________________________________

DESCRIPTION
       The  fconfigure  command  sets  and  retrieves options for
       channels.

       ChannelId identifies the channel for which to set or query
       an  option and must refer to an open channel such as a Tcl
       standard channel (stdin, stdout, or  stderr),  the  return
       value  from an invocation of open or socket, or the result
       of a channel creation command provided by a Tcl extension.

       If  no  name  or value arguments are supplied, the command
       returns a list containing  alternating  option  names  and
       values  for the channel.  If name is supplied but no value
       then the command returns the current value  of  the  given
       option.   If  one or more pairs of name and value are sup-
       plied, the command sets each of the named options  to  the
       corresponding  value;  in this case the return value is an
       empty string.

       The options described below are supported  for  all  chan-
       nels.  In addition, each channel type may add options that
       only it supports. See the manual  entry  for  the  command
       that  creates  each  type of channels for the options that
       that specific type of channel supports. For  example,  see
       the manual entry for the socket command for its additional
       options.

       -blocking boolean
              The -blocking option determines whether I/O  opera-
              tions on the channel can cause the process to block
              indefinitely.  The value of the option  must  be  a
              proper  boolean  value.   Channels  are normally in
              blocking mode;  if a channel is  placed  into  non-
              blocking  mode  it will affect the operation of the
              gets, read, puts, flush, and  close  commands;  see
              the  documentation  for those commands for details.
              For nonblocking mode to work correctly, the  appli-
              cation  must  be  using the Tcl event loop (e.g. by
              calling Tcl_DoOneEvent or invoking the  vwait  com-
              mand).

       -buffering newValue
              If newValue is full then the I/O system will buffer
              output until its internal buffer is full  or  until
              the  flush command is invoked. If newValue is line,
              then the I/O system will automatically flush output
              for  the  channel  whenever  a newline character is
              output. If newValue is none, the  I/O  system  will
              flush  automatically  after every output operation.
              The default is for -buffering to  be  set  to  full
              except  for  channels that connect to terminal-like
              devices; for these channels the initial setting  is
              line.  Additionally, stdin and stdout are initially
              set to line, and stderr is set to none.

       -buffersize newSize
              Newvalue must be an integer; its value is  used  to
              set  the  size  of  buffers, in bytes, subsequently
              allocated for this channel to store input  or  out-
              put.  Newvalue must be between ten and one million,
              allowing buffers of ten to  one  million  bytes  in
              size.

       -encoding name
              This  option is used to specify the encoding of the
              channel, so that the data can be converted  to  and
              from  Unicode  for  use  in  Tcl.  For instance, in
              order for Tcl to read characters  from  a  Japanese
              file  in  shiftjis and properly process and display
              the  contents,  the  encoding  would  be   set   to
              shiftjis.   Thereafter, when reading from the chan-
              nel, the bytes in the Japanese file would  be  con-
              verted  to  Unicode  as  they are read.  Writing is
              also supported - as Tcl strings are written to  the
              channel they will automatically be converted to the
              specified encoding on output.

              If a file contains pure binary data (for  instance,
              a  JPEG image), the encoding for the channel should
              be configured to be binary.  Tcl will  then  assign
              no  interpretation to the data in the file and sim-
              ply read or write raw bytes.  The Tcl  binary  com-
              mand  can  be used to manipulate this byte-oriented
              data.

              The default encoding for newly opened  channels  is
              the  same  platform-  and  locale-dependent  system
              encoding used for interfacing  with  the  operating
              system.

       -eofchar char

       -eofchar {inChar outChar}
              This option supports DOS file systems that use Con-
              trol-z (\x1a) as an end of file marker.  If char is
              not  an  empty  string, then this character signals
              end-of-file when it is  encountered  during  input.
              For  output,  the  end-of-file  character is output
              when the channel is closed.  If char is  the  empty
              string,  then there is no special end of file char-
              acter marker.  For read-write channels, a  two-ele-
              ment  list  specifies  the  end  of file marker for
              input and output, respectively.  As a  convenience,
              when  setting the end-of-file character for a read-
              write channel you can specify a single  value  that
              will  apply  to  both  reading  and  writing.  When
              querying the end-of-file character of a  read-write
              channel,   a   two-element   list  will  always  be
              returned.  The default value for  -eofchar  is  the
              empty  string  in  all cases except for files under
              Windows.  In that case the  -eofchar  is  Control-z
              (\x1a)  for  reading and the empty string for writ-
              ing.

       -translation mode

       -translation {inMode outMode}
              In Tcl scripts the end of a line is  always  repre-
              sented using a single newline character (\n).  How-
              ever, in actual files and devices the end of a line
              may  be  represented differently on different plat-
              forms, or even for different devices  on  the  same
              platform.   For  example,  under  UNIX newlines are
              used  in  files,  whereas  carriage-return-linefeed
              sequences are normally used in network connections.
              On input (i.e., with gets and  read)  the  Tcl  I/O
              system  automatically  translates the external end-
              of-line  representation  into  newline  characters.
              Upon  output  (i.e.,  with  puts),  the  I/O system
              translates newlines  to  the  external  end-of-line
              representation.    The  default  translation  mode,
              auto, handles all the common  cases  automatically,
              but  the -translation option provides explicit con-
              trol over the end of line translations.

              The value associated with -translation is a  single
              item  for  read-only  and write-only channels.  The
              value is a two-element list  for  read-write  chan-
              nels;  the  read translation mode is the first ele-
              ment of the list, and the write translation mode is
              the second element.  As a convenience, when setting
              the translation mode for a read-write  channel  you
              can  specify a single value that will apply to both
              reading and writing.  When querying the translation
              mode  of  a  read-write channel, a two-element list
              will always be returned.  The following values  are
              currently supported:

              auto   As  the  input translation mode, auto treats
                     any of newline (lf), carriage  return  (cr),
                     or  carriage  return  followed  by a newline
                     (crlf) as the end  of  line  representation.
                     The  end  of  line  representation  can even
                     change from line-to-line, and all cases  are
                     translated  to  a  newline.   As  the output
                     translation mode, auto  chooses  a  platform
                     specific  representation; for sockets on all
                     platforms Tcl chooses  crlf,  for  all  Unix
                     flavors,  it  chooses  lf, for the Macintosh
                     platform it chooses cr and for  the  various
                     flavors  of  Windows  it  chooses crlf.  The
                     default setting for -translation is auto for
                     both input and output.

              binary No  end-of-line  translations are performed.
                     This is nearly identical to lf mode,  except
                     that  in  addition binary mode also sets the
                     end-of-file character to  the  empty  string
                     (which disables it) and sets the encoding to
                     binary (which disables encoding  filtering).
                     See  the description of -eofchar and -encod-
                     ing for more information.

              cr     The end of a line in the underlying file  or
                     device  is  represented by a single carriage
                     return character.  As the input  translation
                     mode,  cr  mode converts carriage returns to
                     newline characters.  As the output  transla-
                     tion  mode, cr mode translates newline char-
                     acters to carriage returns.   This  mode  is
                     typically used on Macintosh platforms.

              crlf   The  end of a line in the underlying file or
                     device is represented by a  carriage  return
                     character  followed by a linefeed character.
                     As the input  translation  mode,  crlf  mode
                     converts  carriage-return-linefeed sequences
                     to newline characters.  As the output trans-
                     lation  mode,  crlf  mode translates newline
                     characters    to    carriage-return-linefeed
                     sequences.   This  mode is typically used on
                     Windows platforms and  for  network  connec-
                     tions.

              lf     The  end of a line in the underlying file or
                     device is represented by  a  single  newline
                     (linefeed)   character.   In  this  mode  no
                     translations occur during  either  input  or
                     output.  This mode is typically used on UNIX
                     platforms.


STANDARD CHANNELS
       The Tcl standard channels (stdin, stdout, and stderr)  can
       be  configured through this command like every other chan-
       nel opened by the Tcl library. Beyond the standard options
       described  above they will also support any special option
       according to their current type.  If, for example,  a  Tcl
       application  is started by the inet super-server common on
       Unix system its Tcl standard channels will be sockets  and
       thus support the socket options.


SERIAL PORT CONFIGURATION OPTIONS                                 
       If  channelId  refers to a serial port, then the following 
       additional configuration options are available on  Windows 
       and Unix systems with a POSIX serial interface:            


       -mode baud,parity,data,stop                                       
              This  option  is a set of 4 comma-separated values: 
              the baud rate, parity, number  of  data  bits,  and 
              number of stop bits for this serial port.  The baud 
              rate is a simple integer that specifies the connec-
              tion  speed.   Parity  is one of the following let-
              ters: n, o, e, m, s;  respectively  signifying  the 
              parity  options  of  ``none'',  ``odd'',  ``even'', 
              ``mark'', or ``space''.  Data is the number of data 
              bits  and  should  be an integer from 5 to 8, while 
              stop is the number of stop bits and should  be  the 
              integer 1 or 2.                                     


       -handshake type                                                   
              (Windows and Unix). This option is  used  to  setup 
              automatic  handshake  control.  Note  that  not all 
              handshake types maybe supported by  your  operating 
              system. The type parameter is case-independent.     

              If type is none then any handshake is switched off. 
              rtscts activates hardware handshake. Hardware hand-
              shake  signals  are  described below.  For software 
              handshake xonxoff the handshake characters  can  be 
              redefined  with  -xchar.   An  additional  hardware 
              handshake dtrdsr is available only  under  Windows. 
              There  is  no  default handshake configuration, the 
              initial value depends on your operating system set-
              tings.  The -handshake option cannot be queried.    


       -queue                                                            
              (Windows and Unix). The -queue option can  only  be 
              queried.   It returns a list of two integers repre-
              senting the current number of bytes  in  the  input 
              and output queue respectively.                      


       -timeout msec                                                     
              (Windows  and Unix). This option is used to set the 
              timeout for blocking read operations. It  specifies 
              the  maximum  interval between the reception of two 
              bytes in milliseconds.  For Unix systems the granu-
              larity  is  100  milliseconds.  The -timeout option 
              does not affect  write  operations  or  nonblocking 
              reads.  This option cannot be queried.              


       -ttycontrol {signal boolean signal boolean ...}                   
              (Windows and Unix). This option is  used  to  setup 
              the  handshake output lines (see below) permanently 
              or to send a BREAK over the serial line.  The  sig-
              nal names are case-independent.  {RTS 1 DTR 0} sets 
              the RTS output to high and the DTR output  to  low. 
              The BREAK condition (see below) is enabled and dis-
              abled with {BREAK 1} and  {BREAK  0}  respectively. 
              It's  not  a  good  idea to change the RTS (or DTR) 
              signal with active hardware  handshake  rtscts  (or 
              dtrdsr).   The  result is unpredictable.  The -tty-
              control option cannot be queried.                   


       -ttystatus                                                        
              (Windows  and Unix). The -ttystatus option can only 
              be queried.  It returns the  current  modem  status 
              and  handshake  input  signals  (see  below).   The 
              result is a list of signal,value pairs with a fixed 
              order, e.g. {CTS 1 DSR 0 RING 1 DCD 0}.  The signal 
              names are returned upper case.                      


       -xchar {xonChar xoffChar}                                         
              (Windows and Unix). This option is used to query or 
              change the software handshake characters.  Normally 
              the  operating  system default should be DC1 (0x11) 
              and DC3 (0x13) representing the ASCII standard  XON 
              and XOFF characters.                                


       -pollinterval msec                                                
              (Windows only). This option is used to set the max-
              imum  time  between  polling  for fileevents.  This 
              affects the  time  interval  between  checking  for 
              events throughout the Tcl interpreter (the smallest 
              value always wins).  Use this option  only  if  you 
              want  to  poll  the  serial port more or less often 
              than 10 msec (the default).                         


       -sysbuffer inSize                                                 
       -sysbuffer {inSize outSize}                                       
              (Windows only). This option is used to  change  the 
              size  of  Windows system buffers for a serial chan-
              nel. Especially at higher communication  rates  the 
              default input buffer size of 4096 bytes can overrun 
              for latent systems. The first  form  specifies  the 
              input  buffer  size,  in the second form both input 
              and output buffers are defined.                     


       -lasterror                                                        
              (Windows only). This option is query only.  In case 
              of a  serial  communication  error,  read  or  puts 
              returns  a  general Tcl file I/O error.  fconfigure 
              -lasterror can be called to get  a  list  of  error 
              details.  See below for an explanation of the vari-
              ous error codes.                                    


SERIAL PORT SIGNALS                                               
       RS-232 is  the  most  commonly  used  standard  electrical 
       interface  for  serial  communications. A negative voltage 
       (-3V..-12V) define a mark (on=1) bit and a positive  volt-
       age  (+3..+12V) define a space (off=0) bit (RS-232C).  The 
       following signals are specified for incoming and  outgoing 
       data,  status lines and handshaking. Here we are using the 
       terms workstation for your  computer  and  modem  for  the 
       external  device, because some signal names (DCD, RI) come 
       from modems. Of course your external device may use  these 
       signal lines for other purposes.                           

              TXD(output)                                                       
                     Transmitted Data: Outgoing serial data.      

              RXD(input)                                                        
                     Received Data:Incoming serial data.          

              RTS(output)                                                       
                     Request To  Send:  This  hardware  handshake 
                     line informs the modem that your workstation 
                     is ready to receive data.  Your  workstation 
                     may automatically reset this signal to indi-
                     cate that the input buffer is full.          

              CTS(input)                                                        
                     Clear  To Send: The complement to RTS. Indi-
                     cates that the modem  is  ready  to  receive 
                     data.                                        

              DTR(output)                                                       
                     Data Terminal Ready: This signal  tells  the 
                     modem  that  the  workstation  is  ready  to 
                     establish a link. DTR is often enabled auto-
                     matically  whenever a serial port is opened. 

              DSR(input)                                                        
                     Data Set Ready: The complement to DTR. Tells 
                     the workstation that the modem is  ready  to 
                     establish a link.                            

              DCD(input)                                                        
                     Data  Carrier  Detect:  This  line   becomes 
                     active when a modem detects a "Carrier" sig-
                     nal.                                         

              RI(input)                                                         
                     Ring  Indicator:  Goes active when the modem 
                     detects an incoming call.                    

              BREAK                                                             
                     A  BREAK  condition is not a hardware signal 
                     line, but a logical zero on the TXD  or  RXD 
                     lines for a long period of time, usually 250 
                     to 500 milliseconds.  Normally a receive  or 
                     transmit  data  signal  stays  at  the  mark 
                     (on=1) voltage until the next  character  is 
                     transferred.  A  BREAK  is sometimes used to 
                     reset the communications line or change  the 
                     operating mode of communications hardware.   


ERROR CODES (Windows only)                                        
       A  lot  of  different  errors may occur during serial read 
       operations or during  event  polling  in  background.  The 
       external device may have been switched off, the data lines 
       may be noisy, system buffers may overrun or your mode set-
       tings may be wrong.  That's why a reliable software should 
       always catch serial read operations.  In cases of an error 
       Tcl  returns  a  general  file I/O error.  Then fconfigure 
       -lasterror may help to locate the problem.  The  following 
       error codes may be returned.                               

              RXOVER:                                                           
                     Windows input buffer overrun. The data comes 
                     faster  than  your  scripts reads it or your 
                     system is overloaded. Use  fconfigure  -sys-
                     buffer   to  avoid  a  temporary  bottleneck 
                     and/or make your script faster.              

              TXFULL                                                            
                     Windows output buffer overrun. Complement to 
                     RXOVER. This error  should  practically  not 
                     happen,  because  Tcl cares about the output 
                     buffer status.                               

              OVERRUN                                                           
                     UART  buffer  overrun  (hardware)  with data 
                     lost.  The data comes faster than the system 
                     driver  receives  it.   Check  your advanced 
                     serial port  settings  to  enable  the  FIFO 
                     (16550)   buffer  and/or  setup  a  lower(1) 
                     interrupt threshold value.                   

              RXPARITY                                                          
                     A  parity  error  has  been detected by your 
                     UART.  Wrong parity settings with fconfigure 
                     -mode  or  a noisy data line (RXD) may cause 
                     this error.                                  

              FRAME                                                             
                     A  stop-bit  error has been detected by your 
                     UART.  Wrong mode settings  with  fconfigure 
                     -mode  or  a noisy data line (RXD) may cause 
                     this error.                                  

              BREAK                                                             
                     A  BREAK condition has been detected by your 
                     UART (see above).                            



KEYWORDS
       blocking,  buffering, carriage return, end of line, flush-
       ing, linemode, newline,  nonblocking,  platform,  transla-
       tion, encoding, filter, byte array, binary


_________________________________________________________________

NAME
       fcopy - Copy data from one channel to another.

SYNOPSIS
       fcopy inchan outchan ?-size size? ?-command callback?
_________________________________________________________________


DESCRIPTION
       The fcopy command copies data from one I/O channel, inchan
       to another I/O channel, outchan.  The fcopy command lever-
       ages  the  buffering  in the Tcl I/O system to avoid extra
       copies and to avoid buffering too much data in main memory
       when copying large files to slow destinations like network
       sockets.

       The fcopy command transfers data from inchan until end  of
       file  or  size  bytes  have  been transferred. If no -size
       argument is given, then the copy goes until end  of  file.
       All the data read from inchan is copied to outchan.  With-
       out the -command option, fcopy blocks until  the  copy  is
       complete  and  returns  the  number  of  bytes  written to
       outchan.

       The -command argument makes fcopy work in the  background.
       In  this  case  it returns immediately and the callback is
       invoked later when the copy completes.   The  callback  is
       called with one or two additional arguments that indicates
       how many bytes were  written  to  outchan.   If  an  error
       occurred  during  the background copy, the second argument
       is the error string associated with  the  error.   With  a
       background  copy,  it  is  not  necessary to put inchan or
       outchan into non-blocking mode; the  fcopy  command  takes
       care  of  that automatically.  However, it is necessary to
       enter the event loop by using  the  vwait  command  or  by
       using Tk.

       You are not allowed to do other I/O operations with inchan
       or outchan during a background fcopy.  If either inchan or
       outchan get closed while the copy is in progress, the cur-
       rent copy is stopped and the command callback is not made.
       If  inchan  is  closed,  then  all data already queued for
       outchan is written out.

       Note that inchan can become readable during  a  background
       copy.  You should turn off any fileevent handlers during a
       background copy so those handlers do  not  interfere  with
       the  copy.   Any I/O attempted by a fileevent handler will
       get a "channel busy" error.

       Fcopy  translates  end-of-line  sequences  in  inchan  and
       outchan  according  to  the  -translation option for these
       channels.  See the manual entry for fconfigure for details
       on  the  -translation  option.  The translations mean that
       the number of bytes read from inchan can be different than
       the  number  of bytes written to outchan.  Only the number
       of bytes written to outchan is  reported,  either  as  the
       return  value of a synchronous fcopy or as the argument to
       the callback for an asynchronous fcopy.

       Fcopy obeys the encodings  configured  for  the  channels.
       This  means  that  the  incoming  characters are converted
       internally first UTF-8 and then into the encoding  of  the
       channel fcopy writes to. See the manual entry for fconfig-
       ure for details on the -encoding option. No conversion  is
       done  if  both  channels  are set to encoding "binary". If
       only the output channel is set to  encoding  "binary"  the
       system will write the internal UTF-8 representation of the
       incoming characters. If only the input channel is  set  to
       encoding "binary" the system will assume that the incoming
       bytes are valid UTF-8 characters and convert them  accord-
       ing  to  the  output encoding. The behaviour of the system
       for bytes which are not valid UTF-8  characters  is  unde-
       fined in this case.


EXAMPLE
       This  first example shows how the callback gets passed the
       number of bytes transferred.  It also uses  vwait  to  put
       the application into the event loop.  Of course, this sim-
       plified example could be done without  the  command  call-
       back.

              proc Cleanup {in out bytes {error {}}} {
                  global total
                  set total $bytes
                  close $in
                  close $out
                  if {[string length $error] != 0} {
                   # error occurred during the copy
                  }
              }
              set in [open $file1]
              set out [socket $server $port]
              fcopy $in $out -command [list Cleanup $in $out]
              vwait total


       The  second  example copies in chunks and tests for end of
       file in the command callback

              proc CopyMore {in out chunk bytes {error {}}} {
                  global total done
                  incr total $bytes
                  if {([string length $error] != 0) || [eof $in] {


                   set done $total
                   close $in
                   close $out
                  } else {
                   fcopy $in $out -command [list CopyMore $in $out $chunk] \
                       -size $chunk
                  }
              }
              set in [open $file1]
              set out [socket $server $port]
              set chunk 1024
              set total 0
              fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk
              vwait done


KEYWORDS
       blocking, channel, end of line, end of file,  nonblocking,
       read, translation


_________________________________________________________________

NAME
       file - Manipulate file names and attributes

SYNOPSIS
       file option name ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       This  command provides several operations on a file's name
       or attributes.  Name is the name of a file; if  it  starts
       with  a tilde, then tilde substitution is done before exe-
       cuting the command (see the manual entry for filename  for
       details).  Option indicates what to do with the file name.
       Any unique abbreviation for  option  is  acceptable.   The
       valid options are:

       file atime name ?time?
              Returns  a  decimal string giving the time at which
              file name was last accessed.  If time is specified,
              it is an access time to set for the file.  The time
              is measured in the standard POSIX fashion  as  sec-
              onds  from  a fixed starting time (often January 1,
              1970).  If the file doesn't  exist  or  its  access
              time cannot be queried or set then an error is gen-
              erated.  On Windows, FAT file systems do  not  sup-
              port access time.

       file attributes name

       file attributes name ?option?

       file attributes name ?option value option value...?
              This  subcommand  returns or sets platform specific
              values associated  with  a  file.  The  first  form
              returns  a  list of the platform specific flags and
              their values. The second form returns the value for
              the  specific  option.  The  third form sets one or
              more of the values. The values are as follows:

              On Unix, -group gets or sets the group name for the
              file.  A  group id can be given to the command, but
              it returns a group name. -owner gets  or  sets  the
              user  name  of  the  owner of the file. The command
              returns the owner name, but the numerical id can be
              passed when setting the owner. -permissions sets or
              retrieves the octal code that chmod(1) uses.   This
              command  does  also has limited support for setting
              using the symbolic attributes for chmod(1), of  the
              form   [ugo]?[[+-=][rwxst],[...]],  where  multiple
              symbolic attributes  can  be  separated  by  commas
              (example: u+s,go-rw add sticky bit for user, remove
              read and write permissions for group and other).  A
              simplified  ls  style string, of the form rwxrwxrwx
              (must be 9 characters), is also supported (example:
              rwxr-xr-t is equivalent to 01755).

              On  Windows,  -archive  gives  the value or sets or
              clears the archive attribute of the  file.  -hidden
              gives  the  value  or  sets  or  clears  the hidden
              attribute of the file. -longname will  expand  each
              path  element  to  its long version. This attribute
              cannot be set. -readonly gives the value or sets or
              clears  the readonly attribute of the file. -short-
              name gives a string where  every  path  element  is
              replaced  with its short (8.3) version of the name.
              This attribute cannot be set. -system gives or sets
              or  clears the value of the system attribute of the
              file.

              On Macintosh, -creator gives  or  sets  the  Finder
              creator  type of the file. -hidden gives or sets or
              clears the hidden attribute of the file.  -readonly
              gives  or  sets or clears the readonly attribute of
              the file. Note that directories can only be  locked
              if  File  Sharing is turned on. -type gives or sets
              the Finder file type for the file.

       file channels                                              
       ?pattern?                                           
              If pattern isn't specified, returns a list of names 
              of all registered  open  channels  in  this  inter-
              preter.   If pattern is specified, only those names 
              matching pattern are returned.  Matching is  deter-
              mined using the same rules as for string match.

       file copy ?-force? ?--? source target

       file copy ?-force? ?--? source ?source ...? targetDir
              The  first  form makes a copy of the file or direc-
              tory source under the pathname target. If target is
              an  existing  directory,  then  the  second form is
              used.  The second form makes a copy inside  target-
              Dir  of each source file listed.  If a directory is
              specified as a source, then  the  contents  of  the
              directory  will  be recursively copied into target-
              Dir. Existing files will not be overwritten  unless
              the  -force  option  is  specified.   When  copying
              within a single filesystem,  file  copy  will  copy
              soft  links (i.e.  the links themselves are copied,
              not the things they point to).  Trying to overwrite
              a non-empty directory, overwrite a directory with a
              file, or a file with a directory will all result in
              errors even if -force was specified.  Arguments are
              processed in the order specified,  halting  at  the
              first  error,  if  any.   A  --  marks  the  end of
              switches; the argument following  the  --  will  be
              treated as a source even if it starts with a -.

       file delete ?-force? ?--? pathname ?pathname ... ?
              Removes  the  file  or  directory specified by each
              pathname argument.  Non-empty directories  will  be
              removed  only  if  the  -force option is specified.
              When operating on symbolic links, the  links  them-
              selves  will be deleted, not the objects they point
              to.  Trying to delete a non-existent  file  is  not
              considered  an error.  Trying to delete a read-only
              file will cause the file to be deleted, even if the
              -force  flags  is  not  specified.   If  the -force
              option  is  specified  on  a  directory,  Tcl  will
              attempt  both  to  change  permissions and move the
              current directory 'pwd' out of the  given  path  if
              that is necessary to allow the deletion to proceed.
              Arguments are processed  in  the  order  specified,
              halting at the first error, if any.  A -- marks the
              end of switches; the argument following the -- will
              be  treated  as a pathname even if it starts with a
              -.

       file dirname name
              Returns a name comprised of all of the path  compo-
              nents  in name excluding the last element.  If name
              is a relative file name and only contains one  path
              element, then returns ``.'' (or ``:'' on the Macin-
              tosh).  If name refers to a  root  directory,  then
              the root directory is returned.  For example,
                     file dirname c:/
              returns c:/.

              Note that tilde substitution will only be performed
              if it is necessary to  complete  the  command.  For
              example,
                     file dirname ~/src/foo.c
              returns ~/src, whereas
                     file dirname ~
              returns /home (or something similar).

       file executable name
              Returns 1 if file name is executable by the current
              user, 0 otherwise.

       file exists name
              Returns 1 if file name exists and the current  user
              has  search  privileges for the directories leading
              to it, 0 otherwise.

       file extension name
              Returns all of the characters  in  name  after  and
              including the last dot in the last element of name.
              If there is no dot in the last element of name then
              returns the empty string.

       file isdirectory name
              Returns 1 if file name is a directory, 0 otherwise.

       file isfile name
              Returns 1 if file name is a regular file, 0  other-
              wise.

       file join name ?name ...?
              Takes  one  or  more  file names and combines them,
              using the correct path separator  for  the  current
              platform.   If  a particular name is relative, then
              it will be joined to the previous file  name  argu-
              ment.   Otherwise,  any  earlier  arguments will be
              discarded, and joining will proceed from  the  cur-
              rent argument.  For example,
                     file join a b /foo bar
              returns /foo/bar.

              Note  that any of the names can contain separators,
              and that the result is  always  canonical  for  the
              current platform: / for Unix and Windows, and : for
              Macintosh.

       file link ?-linktype? linkName ?target?
              If only one argument is  given,  that  argument  is
              assumed  to  be  linkName, and this command returns
              the value of the link given by linkName  (i.e.  the
              name  of the file it points to).  If linkName isn't
              a link or its value cannot be read (as,  for  exam-
              ple,  seems  to  be the case with hard links, which
              look just like ordinary files), then  an  error  is
              returned.  If 2 arguments are given, then these are
              assumed to be  linkName  and  target.  If  linkName
              already  exists,  or  if  target  doesn't exist, an
              error will be returned.  Otherwise, Tcl  creates  a
              new link called linkName which points to the exist-
              ing filesystem object at target, where the type  of
              the  link  is platform-specific (on Unix a symbolic
              link will be the default).  This is useful for  the
              case  where  the  user wishes to create a link in a
              cross-platform way, and doesn't care what  type  of
              link is created.  If the user wishes to make a link
              of a specific type only, (and signal  an  error  if
              for  some  reason  that  is not possible), then the
              optional  -linktype  argument  should   be   given.
              Accepted  values  for -linktype are "-symbolic" and
              "-hard".  When creating links on  filesystems  that
              either  do not support any links, or do not support
              the specific type requested, an error message  will
              be  returned.   In particular Windows 95, 98 and ME
              do not support any links at present, but most  Unix
              platforms support both symbolic and hard links (the
              latter for files  only),  MacOS  supports  symbolic
              links  and Windows NT/2000/XP (on NTFS drives) sup-
              port symbolic directory links and hard file  links.

       file lstat name varName
              Same  as  stat  option  (see below) except uses the
              lstat kernel call instead of stat.  This means that
              if  name  refers to a symbolic link the information
              returned in varName is for the link rather than the
              file  it  refers to.  On systems that don't support
              symbolic links this option behaves exactly the same
              as the stat option.

       file mkdir dir ?dir ...?
              Creates  each  directory specified.  For each path-
              name dir specified, this command  will  create  all
              non-existing  parent  directories  as  well  as dir
              itself.  If an  existing  directory  is  specified,
              then  no  action is taken and no error is returned.
              Trying to overwrite an existing file with a  direc-
              tory  will  result in an error.  Arguments are pro-
              cessed in the order specified, halting at the first
              error, if any.

       file mtime name ?time?
              Returns  a  decimal string giving the time at which
              file name was last modified.  If time is specified,
              it  is  a  modification  time  to  set for the file
              (equivalent to Unix touch).  The time  is  measured
              in  the  standard  POSIX  fashion as seconds from a
              fixed starting time (often January  1,  1970).   If
              the  file doesn't exist or its modified time cannot
              be queried or set then an error is generated.

       file nativename name
              Returns the platform-specific  name  of  the  file.
              This is useful if the filename is needed to pass to
              a platform-specific call, such as exec  under  Win-
              dows or AppleScript on the Macintosh.

       file normalize name
              Returns a unique normalised path representation for
              the  file-system  object  (file,  directory,  link,
              etc),  whose  string  value can be used as a unique
              identifier for it.  A normalized path is  an  abso-
              lute  path which has all '../', './' removed.  Also
              it is one which is in the ``standard''  format  for
              the  native  platform.   On MacOS, Unix, this means
              the segments leading up to the path must be free of
              symbolic links/aliases (but the very last path com-
              ponent may be a symbolic link), and on  Windows  it
              also  means  means  we want the long form with that
              form's case-dependence (which gives  us  a  unique,
              case-dependent path).  The one exception concerning
              the last link in the path is necessary, because Tcl
              or  the user may wish to operate on the actual sym-
              bolic link itself (for example 'file delete', 'file
              rename', 'file copy' are defined to operate on sym-
              bolic links, not on the things that they point to).

       file owned name
              Returns  1  if  file  name  is owned by the current
              user, 0 otherwise.

       file pathtype name
              Returns one of absolute, relative,  volumerelative.
              If  name  refers  to  a specific file on a specific
              volume, the path type will be  absolute.   If  name
              refers  to  a  file relative to the current working
              directory, then the path type will be relative.  If
              name refers to a file relative to the current work-
              ing directory on a specified volume, or to  a  spe-
              cific  file on the current working volume, then the
              file type is volumerelative.

       file readable name
              Returns 1 if file name is readable by  the  current
              user, 0 otherwise.

       file readlink name
              Returns  the  value  of  the symbolic link given by
              name (i.e. the name of the file it points to).   If
              name  isn't  a symbolic link or its value cannot be
              read, then an error is returned.  On  systems  that
              don't  support  symbolic links this option is unde-
              fined.

       file rename ?-force? ?--? source target

       file rename ?-force? ?--? source ?source ...? targetDir
              The first form takes the file or  directory  speci-
              fied  by  pathname source and renames it to target,
              moving the file if the pathname target specifies  a
              name  in  a  different  directory.  If target is an
              existing directory, then the second form  is  used.
              The second form moves each source file or directory
              into the directory targetDir. Existing  files  will
              not  be  overwritten  unless  the  -force option is
              specified.  When operating inside a single filesys-
              tem, Tcl will rename symbolic links rather than the
              things that they point to.  Trying to  overwrite  a
              non-empty  directory,  overwrite a directory with a
              file, or a file with a directory will all result in
              errors.  Arguments are processed in the order spec-
              ified, halting at the first error, if  any.   A  --
              marks  the  end of switches; the argument following
              the -- will be treated  as  a  source  even  if  it
              starts with a -.


       file rootname name
              Returns all of the characters in name up to but not
              including the last ``.'' character in the last com-
              ponent  of  name.   If  the  last component of name
              doesn't contain a dot, then returns name.

       file separator ?name?
              If no argument  is  given,  returns  the  character
              which  is used to separate path segments for native
              files on this platform.  If a path  is  given,  the
              filesystem  responsible  for  that path is asked to
              return its separator character.  If no file  system
              accepts name, an error is generated.

       file size name
              Returns  a  decimal  string giving the size of file
              name in bytes.  If the file doesn't  exist  or  its
              size  cannot be queried then an error is generated.

       file split name
              Returns a list whose elements are the  path  compo-
              nents  in name.  The first element of the list will
              have the same path type as name.   All  other  ele-
              ments  will  be  relative.  Path separators will be
              discarded unless they are  needed  ensure  that  an
              element  is  unambiguously  relative.  For example,
              under Unix
                     file split /foo/~bar/baz
              returns /  foo  ./~bar  baz to  ensure  that  later
              commands  that  use  the  third  component  do  not
              attempt to perform tilde substitution.

       file stat  name varName
              Invokes the stat kernel call on name, and uses  the
              variable  given  by  varName  to  hold  information
              returned from the kernel call.  VarName is  treated
              as an array variable, and the following elements of
              that variable are set: atime, ctime, dev, gid, ino,
              mode,  mtime, nlink, size, type, uid.  Each element
              except type is a decimal string with the  value  of
              the corresponding field from the stat return struc-
              ture; see the manual entry for stat for details  on
              the meanings of the values.  The type element gives
              the type of the file in the same form  returned  by
              the  command  file  type.   This command returns an
              empty string.

       file system name
              Returns a list of two elements, the first of  which
              is  the name of the filesystem to use for the file,
              and the second an arbitrary string representing the
              filesystem-specific  nature or type of the location
              within that filesystem.  If a filesystem only  sup-
              ports  one  type of file, the second element may be
              null.  For example the native files  have  a  first
              element  'native',  and a second element which is a
              platform-specific type name for the  file's  system
              (e.g.  'NTFS',  'FAT',  etc), or possibly the empty
              string if no further information is available or if
              this  is  not  implemented.  A generic virtual file
              system might return the list 'vfs ftp' to represent
              a  file  on  a remote ftp site mounted as a virtual
              filesystem through an extension called  'vfs'.   If
              the  file  does  not  belong  to any filesystem, an
              error is generated.

       file tail name
              Returns all of the characters  in  name  after  the
              last directory separator.  If name contains no sep-
              arators then returns name.

       file type name
              Returns a string giving  the  type  of  file  name,
              which will be one of file, directory, characterSpe-
              cial, blockSpecial, fifo, link, or socket.

       file volume
              Returns the absolute paths to the  volumes  mounted
              on the system, as a proper Tcl list.  On the Macin-
              tosh, this will be a list of  the  mounted  drives,
              both  local  and  network.  N.B. if two drives have
              the same name, they will both appear on the  volume
              list,  but  there is currently no way, from Tcl, to
              access any but the first of these drives.  On UNIX,
              the  command  will  always  return  "/",  since all
              filesystems are locally mounted.   On  Windows,  it
              will  return  a  list of the available local drives
              (e.g. {a:/ c:/}).

       file writable name
              Returns 1 if file name is writable by  the  current
              user, 0 otherwise.

PORTABILITY ISSUES
       Unix
              These  commands  always operate using the real user
              and group identifiers, not the effective ones.



KEYWORDS
       attributes,  copy  files,  delete  files, directory, file,
       move files, name, rename files, stat


_________________________________________________________________

NAME
       fileevent  - Execute a script when a channel becomes read-
       able or writable

SYNOPSIS
       fileevent channelId readable ?script?

       fileevent channelId writable ?script?
_________________________________________________________________


DESCRIPTION
       This command is used to create  file  event  handlers.   A
       file  event  handler  is a binding between a channel and a
       script, such that the script  is  evaluated  whenever  the
       channel becomes readable or writable.  File event handlers
       are most commonly used to allow data to be  received  from
       another  process  on  an  event-driven  basis, so that the
       receiver can continue to  interact  with  the  user  while
       waiting for the data to arrive.  If an application invokes
       gets or read on a blocking channel when there is no  input
       data  available,  the  process will block; until the input
       data arrives, it will not be able to service other events,
       so  it  will  appear  to  the user to ``freeze up''.  With
       fileevent, the process can tell when data is  present  and
       only invoke gets or read when they won't block.

       The  channelId  argument  to  fileevent  refers to an open 
       channel such as a Tcl standard channel (stdin, stdout,  or 
       stderr),  the  return  value from an invocation of open or 
       socket, or the result of a channel creation  command  pro-
       vided by a Tcl extension.

       If  the  script argument is specified, then fileevent cre-
       ates a new event handler:  script will be evaluated  when-
       ever  the  channel becomes readable or writable (depending
       on the  second  argument  to  fileevent).   In  this  case
       fileevent  returns  an  empty  string.   The  readable and
       writable event handlers for a file  are  independent,  and
       may be created and deleted separately.  However, there may
       be at most one readable and one  writable  handler  for  a
       file at a given time in a given interpreter.  If fileevent
       is called when the specified handler already exists in the
       invoking interpreter, the new script replaces the old one.

       If the script argument is not specified, fileevent returns
       the  current  script  for channelId, or an empty string if
       there is none.  If the script argument is specified as  an
       empty string then the event handler is deleted, so that no
       script will be invoked.  A  file  event  handler  is  also
       deleted  automatically  whenever  its channel is closed or
       its interpreter is deleted.


       A channel is considered to be readable if there is  unread
       data  available  on  the  underlying device.  A channel is
       also considered to be readable if there is unread data  in
       an input buffer, except in the special case where the most
       recent attempt to read from the channel was  a  gets  call
       that  could  not find a complete line in the input buffer.
       This feature allows a file to be read a line at a time  in
       nonblocking  mode using events.  A channel is also consid-
       ered to be readable if an end of file or  error  condition
       is present on the underlying file or device.  It is impor-
       tant for script to check for these conditions  and  handle
       them  appropriately;   for example, if there is no special
       check for end of file, an infinite loop  may  occur  where
       script  reads no data, returns, and is immediately invoked
       again.

       A channel is considered to be writable  if  at  least  one
       byte  of  data  can  be  written to the underlying file or
       device without blocking, or if an error condition is  pre-
       sent on the underlying file or device.

       Event-driven  I/O  works  best for channels that have been
       placed into nonblocking mode with the fconfigure  command.
       In  blocking mode, a puts command may block if you give it
       more data than the underlying file or device  can  accept,
       and  a  gets  or read command will block if you attempt to
       read more data than is ready;  no events will be processed
       while the commands block.  In nonblocking mode puts, read,
       and gets never block.  See the documentation for the indi-
       vidual  commands for information on how they handle block-
       ing and nonblocking channels.

       The script for a file event is executed  at  global  level
       (outside  the  context of any Tcl procedure) in the inter-
       preter in which the fileevent command was invoked.  If  an
       error  occurs  while executing the script then the bgerror
       mechanism is used to report the error.  In  addition,  the
       file event handler is deleted if it ever returns an error;
       this is done in order to prevent  infinite  loops  due  to
       buggy handlers.


EXAMPLE
               proc GetData {chan} {
                  if {![eof $chan]} {
                      puts [gets $chan]
                  }
               }

               fileevent $chan readable [list GetData $chan]

       In  this  setup GetData will be called with the channel as
       an argument whenever $chan becomes readable.


CREDITS
       fileevent is based on the addinput command created by Mark
       Diekhans.


KEYWORDS
       asynchronous I/O, blocking, channel, event  handler,  non-
       blocking, readable, script, writable.


_________________________________________________________________

NAME
       filename - File name conventions supported by Tcl commands
_________________________________________________________________

INTRODUCTION
       All Tcl commands and C procedures that take file names  as
       arguments  expect  the  file  names  to be in one of three
       forms, depending on the current platform.  On  each  plat-
       form, Tcl supports file names in the standard forms(s) for
       that platform.  In addition, on all  platforms,  Tcl  sup-
       ports  a Unix-like syntax intended to provide a convenient
       way of constructing simple file names.   However,  scripts
       that  are intended to be portable should not assume a par-
       ticular form for file names.   Instead,  portable  scripts
       must  use the file split and file join commands to manipu-
       late file names  (see  the  file  manual  entry  for  more
       details).


PATH TYPES
       File  names  are grouped into three general types based on
       the starting point for the path used to specify the  file:
       absolute,  relative,  and volume-relative.  Absolute names
       are completely qualified, giving a path to the file  rela-
       tive to a particular volume and the root directory on that
       volume.  Relative names are unqualified, giving a path  to
       the  file relative to the current working directory.  Vol-
       ume-relative names are partially qualified, either  giving
       the  path  relative  to  the root directory on the current
       volume, or relative to the current directory of the speci-
       fied  volume.   The  file  pathtype command can be used to
       determine the type of a given path.


PATH SYNTAX
       The rules for native names depend on the value reported in
       the Tcl array element tcl_platform(platform):

       mac       On  Apple  Macintosh  systems,  Tcl supports two
                 forms of path names.  The normal Mac style names
                 use  colons  as  path  separators.  Paths may be
                 relative or absolute, and file names may contain
                 any character other than colon.  A leading colon
                 causes the rest of the path  to  be  interpreted
                 relative  to  the  current directory.  If a path
                 contains a colon that is not at  the  beginning,
                 then  the  path  is  interpreted  as an absolute
                 path.  Sequences of two or more colons  anywhere
                 in the path are used to construct relative paths
                 where :: refers to the  parent  of  the  current
                 directory,  ::: refers to the parent of the par-
                 ent, and so forth.


                 In addition to Macintosh style names,  Tcl  also
                 supports a subset of Unix-like names.  If a path
                 contains no colons, then it is interpreted  like
                 a  Unix path.  Slash is used as the path separa-
                 tor.  The file name  .  refers  to  the  current
                 directory,  and  ..  refers to the parent of the
                 current directory.  However, some names  like  /
                 or  /..  have no mapping, and are interpreted as
                 Macintosh names.  In general, commands that gen-
                 erate  file  names  will  return Macintosh style
                 names, but commands that accept file names  will
                 take both Macintosh and Unix-style names.

                 The  following examples illustrate various forms
                 of path names:

                 :              Relative  path  to  the   current
                                folder.

                 MyFile         Relative  path  to  a  file named
                                MyFile in the current folder.

                 MyDisk:MyFile  Absolute path  to  a  file  named
                                MyFile   on   the   device  named
                                MyDisk.

                 :MyDir:MyFile  Relative  path  to  a  file  name
                                MyFile in a folder named MyDir in
                                the current folder.

                 ::MyFile       Relative path  to  a  file  named
                                MyFile  in  the  folder above the
                                current folder.

                 :::MyFile      Relative path  to  a  file  named
                                MyFile  in  the folder two levels
                                above the current folder.

                 /MyDisk/MyFile Absolute path  to  a  file  named
                                MyFile   on   the   device  named
                                MyDisk.

                 ../MyFile      Relative path  to  a  file  named
                                MyFile  in  the  folder above the
                                current folder.

       unix      On Unix platforms, Tcl uses path names where the
                 components are separated by slashes.  Path names
                 may be relative or absolute, and file names  may
                 contain  any  character  other  than slash.  The
                 file names . and .. are special and refer to the
                 current  directory and the parent of the current
                 directory respectively.  Multiple adjacent slash
                 characters   are   interpreted   as   a   single
                separator.  The  following  examples  illustrate
                 various forms of path names:

                 /              Absolute  path to the root direc-
                                tory.

                 /etc/passwd    Absolute path to the  file  named
                                passwd  in  the  directory etc in
                                the root directory.

                 .              Relative  path  to  the   current
                                directory.

                 foo            Relative  path to the file foo in
                                the current directory.

                 foo/bar        Relative path to the file bar  in
                                the  directory foo in the current
                                directory.

                 ../foo         Relative path to the file foo  in
                                the  directory  above the current
                                directory.

       windows   On Microsoft  Windows  platforms,  Tcl  supports
                 both drive-relative and UNC style names.  Both /
                 and \ may be used  as  directory  separators  in
                 either  type of name.  Drive-relative names con-
                 sist of an optional drive specifier followed  by
                 an  absolute or relative path.  UNC paths follow
                 the     general     form     \\servername\share-
                 name\path\file,  but must at the very least con-
                 tain  the  server  and  share  components,  i.e.
                 \\servername\sharename.  In both forms, the file
                 names . and .. are special and refer to the cur-
                 rent  directory  and  the  parent of the current
                 directory respectively.  The following  examples
                 illustrate various forms of path names:

                 \\Host\share/file
                                Absolute   UNC  path  to  a  file
                                called file in the root directory
                                of  the export point share on the
                                host Host.   Note  that  repeated
                                use  of file dirname on this path
                                will give //Host/share, and  will
                                never give just /fB//Host/fR.

                 c:foo          Volume-relative  path  to  a file
                                foo in the current  directory  on
                                drive c.

                 c:/foo         Absolute  path  to  a file foo in
                                the root directory of drive c.


                 foo\bar        Relative path to a  file  bar  in
                                the  foo directory in the current
                                directory on the current  volume.

                 \foo           Volume-relative  path  to  a file
                                foo in the root directory of  the
                                current volume.

                 \\foo          Volume-relative  path  to  a file
                                foo in the root directory of  the
                                current  volume.   This  is not a
                                valid UNC path, so the assumption
                                is that the extra backslashes are
                                superfluous.


TILDE SUBSTITUTION
       In addition to the file name rules  described  above,  Tcl
       also  supports  csh-style  tilde  substitution.  If a file
       name starts with a tilde,  then  the  file  name  will  be
       interpreted  as  if the first element is replaced with the
       location of the home directory for the given user.  If the
       tilde  is  followed  immediately  by a separator, then the
       $HOME environment variable is substituted.  Otherwise  the
       characters  between  the  tilde and the next separator are
       taken as a user name, which is used to retrieve the user's
       home directory for substitution.

       The  Macintosh  and Windows platforms do not support tilde
       substitution when a user name follows the tilde.  On these
       platforms, attempts to use a tilde followed by a user name
       will generate an error that the user does not  exist  when
       Tcl  attempts to interpret that part of the path or other-
       wise access the file.  The behaviour of these  paths  when
       not trying to interpret them is the same as on Unix.  File
       names that have a tilde without a user name will  be  cor-
       rectly  substituted  using the $HOME environment variable,
       just like for Unix.


PORTABILITY ISSUES
       Not all file systems are case sensitive, so scripts should
       avoid  code  that  depends  on the case of characters in a
       file name.  In addition, the  character  sets  allowed  on
       different  devices  may  differ,  so scripts should choose
       file names that do not contain  special  characters  like:
       <>:"/\|.   The  safest approach is to use names consisting
       of alphanumeric characters only.  Also  Windows  3.1  only
       supports  file names with a root of no more than 8 charac-
       ters and an extension of no more than 3 characters.

       On Windows  platforms  there  are  file  and  path  length
       restrictions.   Complete  paths  or  filenames longer than
       about 260 characters will lead  to  errors  in  most  file
       operations.


KEYWORDS
       current directory, absolute file name, relative file name,
       volume-relative file name, portability


_________________________________________________________________

NAME
       flush - Flush buffered output for a channel

SYNOPSIS
       flush channelId
_________________________________________________________________


DESCRIPTION
       Flushes any output that has been buffered for channelId.

       ChannelId  must  be an identifier for an open channel such 
       as a Tcl standard channel (stdout or stderr),  the  return 
       value  from an invocation of open or socket, or the result 
       of a channel creation command provided by a Tcl extension. 
       The channel must have been opened for writing.

       If  the  channel  is in blocking mode the command does not
       return until all the buffered output has been  flushed  to
       the  channel.  If  the channel is in nonblocking mode, the
       command may return before all  buffered  output  has  been
       flushed;  the  remainder will be flushed in the background
       as fast as the underlying file or device is able to absorb
       it.


KEYWORDS
       blocking, buffer, channel, flush, nonblocking, output


_________________________________________________________________

NAME
       for - ``For'' loop

SYNOPSIS
       for start test next body
_________________________________________________________________


DESCRIPTION
       For  is  a  looping command, similar in structure to the C
       for statement.  The start, next, and body  arguments  must
       be  Tcl command strings, and test is an expression string.
       The for command first invokes the Tcl interpreter to  exe-
       cute  start.   Then  it  repeatedly  evaluates  test as an
       expression; if the result is non-zero it invokes  the  Tcl
       interpreter  on  body, then invokes the Tcl interpreter on
       next, then repeats the loop.  The command terminates  when
       test  evaluates  to  0.   If a continue command is invoked
       within body then any remaining  commands  in  the  current
       execution  of  body  are  skipped; processing continues by
       invoking the Tcl  interpreter  on  next,  then  evaluating
       test,  and  so  on.   If a break command is invoked within
       body or next, then the for  command  will  return  immedi-
       ately.  The operation of break and continue are similar to
       the corresponding statements in C.  For returns  an  empty
       string.

       Note: test should almost always be enclosed in braces.  If
       not, variable substitutions will be made  before  the  for
       command   starts  executing,  which  means  that  variable
       changes made by the loop body will not  be  considered  in
       the  expression.   This is likely to result in an infinite
       loop.  If test is enclosed in braces,  variable  substitu-
       tions  are  delayed  until  the  expression  is  evaluated
       (before each loop iteration), so changes in the  variables
       will be visible.  For an example, try the following script
       with and without the braces around $x<10:
              for {set x 0} {$x<10} {incr x} {
                puts "x is $x"
              }


KEYWORDS
       for, iteration, looping


_________________________________________________________________

NAME
       foreach - Iterate over all elements in one or more lists

SYNOPSIS
       foreach varname list body
       foreach varlist1 list1 ?varlist2 list2 ...? body
_________________________________________________________________


DESCRIPTION
       The foreach command implements a loop where the loop vari-
       able(s) take on values from one or  more  lists.   In  the
       simplest case there is one loop variable, varname, and one
       list, list, that is a list of values to assign to varname.
       The  body  argument  is a Tcl script.  For each element of
       list (in order from first to last),  foreach  assigns  the
       contents  of  the element to varname as if the lindex com-
       mand had been used to extract the element, then calls  the
       Tcl interpreter to execute body.

       In  the general case there can be more than one value list
       (e.g., list1 and list2), and each value list can be  asso-
       ciated  with  a list of loop variables (e.g., varlist1 and
       varlist2).  During each iteration of the  loop  the  vari-
       ables of each varlist are assigned consecutive values from
       the corresponding list.  Values in each list are  used  in
       order  from  first to last, and each value is used exactly
       once.  The total number of loop iterations is large enough
       to  use  up all the values from all the value lists.  If a
       value list does not contain enough elements  for  each  of
       its  loop  variables  in  each iteration, empty values are
       used for the missing elements.

       The break and continue statements may  be  invoked  inside
       body, with the same effect as in the for command.  Foreach
       returns an empty string.

EXAMPLES
       The following loop uses i and j as loop variables to iter-
       ate over pairs of elements of a single list.

              set x {}
              foreach {i j} {a b c d e f} {
                  lappend x $j $i
              }
              # The value of x is "b a d c f e"
              # There are 3 iterations of the loop.


       The  next  loop  uses i and j to iterate over two lists in
       parallel.


              set x {}
              foreach i {a b c} j {d e f g} {
                  lappend x $i $j
              }
              # The value of x is "a d b e c f {} g"
              # There are 4 iterations of the loop.


       The two forms are combined in the following example.

              set x {}
              foreach i {a b c} {j k} {d e f g} {
                  lappend x $i $j $k
              }
              # The value of x is "a d e b f g c {} {}"
              # There are 3 iterations of the loop.


KEYWORDS
       foreach, iteration, list, looping


_________________________________________________________________

NAME
       format - Format a string in the style of sprintf

SYNOPSIS
       format formatString ?arg arg ...?
_________________________________________________________________


INTRODUCTION
       This  command generates a formatted string in the same way
       as the ANSI C sprintf procedure (it uses  sprintf  in  its
       implementation).  FormatString indicates how to format the
       result, using % conversion specifiers as in  sprintf,  and
       the  additional  arguments,  if  any, provide values to be
       substituted into the result.  The return value from format
       is the formatted string.


DETAILS ON FORMATTING
       The command operates by scanning formatString from left to
       right.  Each character from the format string is  appended
       to  the result string unless it is a percent sign.  If the
       character is a % then it  is  not  copied  to  the  result
       string.  Instead, the characters following the % character
       are treated as a  conversion  specifier.   The  conversion
       specifier  controls  the conversion of the next successive
       arg to a particular format and the result is  appended  to
       the  result  string  in place of the conversion specifier.
       If there are multiple conversion specifiers in the  format
       string, then each one controls the conversion of one addi-
       tional arg.  The format command must be given enough  args
       to  meet  the needs of all of the conversion specifiers in
       formatString.

       Each conversion specifier may contain up to six  different
       parts: an XPG3 position specifier, a set of flags, a mini-
       mum field width, a precision, a  length  modifier,  and  a
       conversion  character.  Any of these fields may be omitted
       except for the conversion character.  The fields that  are
       present  must  appear in the order given above.  The para-
       graphs below discuss each of these fields in turn.

       If the % is followed by a decimal number and a  $,  as  in
       ``%2$d'',  then the value to convert is not taken from the
       next sequential argument.  Instead, it is taken  from  the
       argument  indicated  by the number, where 1 corresponds to
       the first arg.  If the conversion specifier requires  mul-
       tiple  arguments  because of * characters in the specifier
       then successive arguments  are  used,  starting  with  the
       argument  given by the number.  This follows the XPG3 con-
       ventions for positional  specifiers.   If  there  are  any
       positional  specifiers  in  formatString  then  all of the
       specifiers must be positional.

       The second portion of a conversion specifier  may  contain
       any of the following flag characters, in any order:

       -         Specifies  that the converted argument should be
                 left-justified in its field  (numbers  are  nor-
                 mally  right-justified  with  leading  spaces if
                 needed).

       +         Specifies that a number should always be printed
                 with a sign, even if positive.

       space     Specifies  that  a  space should be added to the
                 beginning of the number if the  first  character
                 isn't a sign.

       0         Specifies  that  the  number should be padded on
                 the left with zeroes instead of spaces.

       #         Requests an alternate output form. For o  and  O
                 conversions  it  guarantees that the first digit
                 is always 0.  For x or X conversions, 0x  or  0X
                 (respectively) will be added to the beginning of
                 the result unless it is zero.  For all floating-
                 point conversions (e, E, f, g, and G) it guaran-
                 tees that the result always has a decimal point.
                 For g and G conversions it specifies that trail-
                 ing zeroes should not be removed.

       The third portion of a conversion specifier  is  a  number
       giving  a  minimum field width for this conversion.  It is
       typically used to make columns line up in  tabular  print-
       outs.  If the converted argument contains fewer characters
       than the minimum field width then it  will  be  padded  so
       that  it  is  as wide as the minimum field width.  Padding
       normally occurs by adding extra spaces on the left of  the
       converted  argument,  but the 0 and - flags may be used to
       specify padding with zeroes on the left or with spaces  on
       the  right,  respectively.   If the minimum field width is
       specified as * rather than a number, then the  next  argu-
       ment  to  the  format command determines the minimum field
       width; it must be a numeric string.

       The fourth portion of a conversion specifier is  a  preci-
       sion,  which  consists  of  a period followed by a number.
       The number is used in different ways for different conver-
       sions.   For e, E, and f conversions it specifies the num-
       ber of digits to appear to the right of the decimal point.
       For  g  and G conversions it specifies the total number of
       digits to appear, including those on  both  sides  of  the
       decimal  point (however, trailing zeroes after the decimal
       point will still be omitted unless the  #  flag  has  been
       specified).   For  integer  conversions,  it  specifies  a
       minimum number of digits to print (leading zeroes will  be
       added  if  necessary).  For s conversions it specifies the
       maximum number of characters to be printed; if the  string
       is  longer  than this then the trailing characters will be
       dropped.  If the precision is specified with * rather than
       a  number  then  the  next  argument to the format command
       determines the precision; it must be a numeric string.

       The fifth part of a conversion specifier is a length modi-
       fier,  which must be h or l.  If it is h it specifies that
       the numeric value should be truncated to  a  16-bit  value
       before  converting.   This option is rarely useful.  If it 
       is l it specifies that the numeric  value  should  be  (at 
       least)  a  64-bit  value.   If neither h or l are present, 
       numeric values are interpreted  as  being  values  of  the 
       width   of  the  native  machine  word,  as  described  by 
       tcl_platform(wordSize).

       The last thing in a conversion specifier is an  alphabetic
       character  that determines what kind of conversion to per-
       form.  The following conversion characters  are  currently
       supported:

       d         Convert integer to signed decimal string.

       u         Convert integer to unsigned decimal string.

       i         Convert  integer  to signed decimal string;  the
                 integer may either be in decimal, in octal (with
                 a  leading  0) or in hexadecimal (with a leading
                 0x).

       o         Convert integer to unsigned octal string.

       x or X    Convert integer to unsigned hexadecimal  string,
                 using  digits  ``0123456789abcdef''  for  x  and
                 ``0123456789ABCDEF'' for X).                     

       c                                                                 
                 Convert integer to the Unicode character it rep-
                 resents.

       s         No conversion; just insert string.

       f         Convert floating-point number to signed  decimal
                 string  of  the form xx.yyy, where the number of
                 y's is determined by the precision (default: 6).
                 If  the  precision is 0 then no decimal point is
                 output.

       e or e    Convert  floating-point  number  to   scientific
                 notation in the form x.yyye±±zz, where the number
                 of y's is determined by the precision  (default:
                 6).  If the precision is 0 then no decimal point


                 is output.  If the E form  is  used  then  E  is
                 printed instead of e.

       g or G    If  the exponent is less than -4 or greater than
                 or equal to the precision, then  convert  float-
                 ing-point  number  as  for  %e or %E.  Otherwise
                 convert as for %f.  Trailing zeroes and a trail-
                 ing decimal point are omitted.

       %         No conversion: just insert %.

       For the numerical conversions the argument being converted
       must be an integer or floating-point string;  format  con-
       verts  the argument to binary and then converts it back to
       a string according to the conversion specifier.


DIFFERENCES FROM ANSI SPRINTF
       The behavior of the format command is the same as the ANSI
       C sprintf procedure except for the following differences:

       [1]    %p and %n specifiers are not currently supported.

       [2]    For  %c  conversions the argument must be a decimal
              string, which will then be converted to the  corre-
              sponding character value.

       [3]    The  l  modifier  is ignored for real values and on 
              64-bit platforms, which are always converted as  if 
              the  l modifier were present (i.e. the types double 
              and long are used for the  internal  representation 
              of  real and integer values, respectively).  If the
              h modifier is specified  then  integer  values  are
              truncated to short before conversion.  Both h and l
              modifiers are ignored on all other conversions.


KEYWORDS
       conversion specifier, format, sprintf,  string,  substitu-
       tion


_________________________________________________________________

NAME
       gets - Read a line from a channel

SYNOPSIS
       gets channelId ?varName?
_________________________________________________________________


DESCRIPTION
       This  command  reads the next line from channelId, returns
       everything in the line up to (but not including) the  end-
       of-line character(s), and discards the end-of-line charac-
       ter(s).

       ChannelId must be an identifier for an open  channel  such 
       as  the  Tcl  standard  input  channel (stdin), the return 
       value from an invocation of open or socket, or the  result 
       of a channel creation command provided by a Tcl extension. 
       The channel must have been opened for input.

       If varName is omitted the line is returned as  the  result
       of  the command.  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 returned.

       If  end  of file occurs while scanning for an end of line,
       the command returns whatever input is available up to  the
       end  of  file.   If  channelId  is in nonblocking mode and
       there is not a full line of input available,  the  command
       returns  an  empty  string and does not consume any input.
       If varName is specified and an empty string is returned in
       varName  because of end-of-file or because of insufficient
       data in nonblocking mode, then the  return  count  is  -1.
       Note that if varName is not specified then the end-of-file
       and no-full-line-available  cases  can  produce  the  same
       results  as if there were an input line consisting only of
       the end-of-line character(s).  The eof and  fblocked  com-
       mands can be used to distinguish these three cases.


KEYWORDS
       blocking,  channel,  end  of file, end of line, line, non-
       blocking, read


_________________________________________________________________

NAME
       glob - Return names of files that match patterns

SYNOPSIS
       glob ?switches? pattern ?pattern ...?
_________________________________________________________________


DESCRIPTION
       This  command performs file name ``globbing'' in a fashion
       similar to the csh shell.  It returns a list of the  files
       whose names match any of the pattern arguments.

       If  the  initial  arguments to glob start with - then they
       are treated as switches.  The following switches are  cur-
       rently supported:                                          

       -directory                                                 
       directory                                              
              Search for files which  match  the  given  patterns 
              starting  in  the  given  directory.   This  allows 
              searching of directories whose name contains  glob- 
              sensitive characters without the need to quote such 
              characters explicitly.  This option may not be used 
              in  conjunction  with -path, which is used to allow 
              searching for complete file paths whose  names  may 
              contain glob-sensitive characters.                  

       -join                                                             
              The remaining pattern arguments are  treated  as  a 
              single  pattern  obtained  by joining the arguments 
              with directory separators.

       -nocomplain
              Allows an empty list to be returned without  error;
              without  this  switch  an  error is returned if the
              result list would be empty.                         

       -path pathPrefix                                                  
              Search for files with the  given  pathPrefix  where 
              the  rest  of  the name matches the given patterns. 
              This allows searching for files with names  similar 
              to  a  given  file (as opposed to a directory) even 
              when the names contain  glob-sensitive  characters. 
              This  option  may  not  be used in conjunction with 
              -directory.  For example, to find  all  files  with 
              the  same  root name as $path, but differing exten-
              sions, you should use  glob  -path  [file  rootname 
              $path]  .*  which  will work even if $path contains 
              numerous glob-sensitive characters.                 

       -tails                                                            
              Only  return the part of each file found which fol-
              lows the last directory named in any -directory  or 
              -path path specification.  Thus glob -tails -direc-
              tory $dir * is equivalent to set  pwd  [pwd]  ;  cd 
              $dir  ; glob *; cd $pwd.  For -path specifications, 
              the returned names will include the last path  seg-
              ment,   so   glob   -tails   -path  [file  rootname 
              ~/foo.tex]  .*   will  return  paths  like  foo.aux 
              foo.bib foo.tex etc.                                

       -types typeList                                                   
              Only  list  files  or directories which match type-
              List, where the items in the list have  two  forms. 
              The first form is like the -type option of the Unix 
              find command: b (block special file), c  (character 
              special  file),  d  (directory),  f (plain file), l 
              (symbolic link), p (named  pipe),  or  s  (socket), 
              where  multiple types may be specified in the list. 
              Glob will return all files which match at least one 
              of the types given.                                 

              The second form specifies types where all the types 
              given must match.  These are r, w, x as  file  per-
              missions,  and  readonly, hidden as special permis-
              sion cases.  On the Macintosh, MacOS types and cre-
              ators  are  also supported, where any item which is 
              four characters long is assumed to be a MacOS  type 
              (e.g.  TEXT).   Items which are of the form {macin-
              tosh type XXXX} or {macintosh  creator  XXXX}  will 
              match types or creators respectively.  Unrecognized 
              types,  or   specifications   of   multiple   MacOS 
              types/creators will signal an error.                

              The  two  forms  may  be mixed, so -types {d f r w} 
              will find all regular  files  OR  directories  that 
              have  both read AND write permissions.  The follow-
              ing are equivalent:                                 
                             glob -type d *                       
                             glob */                              
              except that  the  first  case  doesn't  return  the 
              trailing ``/'' and is more platform independent.    

       --     Marks  the end of switches.  The argument following
              this one will be treated as a pattern  even  if  it
              starts with a -.

       The  pattern  arguments  may  contain any of the following
       special characters:

       ?         Matches any single character.

       *         Matches any sequence of zero or more characters.


       [chars]   Matches any single character in chars.  If chars
                 contains a sequence of the  form  a-b  then  any
                 character  between  a  and  b  (inclusive)  will
                 match.

       \x        Matches the character x.

       {a,b,...} Matches any of the strings a, b, etc.

       On Unix, as with csh, a ``.'' at the beginning of a file's
       name  or  just after a ``/'' must be matched explicitly or
       with a {} construct, unless the ``-types hidden'' flag  is
       given (since ``.'' at the beginning of a file's name indi-
       cates that it  is  hidden).   On  other  platforms,  files
       beginning  with  a ``.'' are handled no differently to any
       others, except the special directories  ``.''  and  ``..''
       which  must  be  matched  explicitly  (this  is to avoid a
       recursive pattern like ``glob -join * * * *'' from recurs-
       ing up the directory hierarchy as well as down).  In addi-
       tion, all ``/'' characters must be matched explicitly.

       If the first character in  a  pattern  is  ``~''  then  it
       refers  to the home directory for the user whose name fol-
       lows the ``~''.  If the ``~'' is followed  immediately  by
       ``/''  then  the value of the HOME environment variable is
       used.

       The glob command differs from csh globbing  in  two  ways.
       First,  it  does  not  sort its result list (use the lsort
       command if you want the list sorted).  Second,  glob  only
       returns the names of files that actually exist;  in csh no
       check for existence is made unless a pattern contains a ?,
       *, or [] construct.


PORTABILITY ISSUES
       Unlike  other  Tcl  commands that will accept both network
       and native style names (see the filename manual entry  for
       details  on  how  native and network names are specified),
       the glob command only accepts native names.

       Windows
              For Windows UNC names, the servername and sharename
              components  of the path may not contain ?, *, or []
              constructs.  On Windows NT, if pattern  is  of  the
              form  ``~username@domain''  it  refers  to the home
              directory of the  user  whose  account  information
              resides  on the specified NT domain server.  Other-
              wise, user account information is obtained from the
              local computer.  On Windows 95 and 98, glob accepts
              patterns like ``.../'' and  ``..../''  for  succes-
              sively higher up parent directories.

              Since the backslash character has a special meaning
              to the glob command, glob patterns containing  Win-
              dows  style  path separators need special care. The
              pattern C:\\foo\\* is interpreted as C:\foo\* where
              \f  will  match  the single character f and \* will
              match the single character * and will not be inter-
              preted  as  a  wildcard  character. One solution to
              this problem is to use the Unix style forward slash
              as  a  path  separator.  Windows style paths can be
              converted to Unix style paths with the command file
              join $path (or file normalize $path in Tcl 8.4).

       Macintosh
              When using the options, -directory, -join or -path,
              glob assumes the directory separator for the entire
              pattern  is  the  standard  ``:''.   When not using
              these options, glob examines each pattern  argument
              and uses ``/'' unless the pattern contains a ``:''.


KEYWORDS
       exist, file, glob, pattern


_________________________________________________________________

NAME
       global - Access global variables

SYNOPSIS
       global varname ?varname ...?
_________________________________________________________________


DESCRIPTION
       This  command  is  ignored unless a Tcl procedure is being
       interpreted.  If so then it declares the  given  varname's
       to  be  global  variables  rather than local ones.  Global
       variables are variables in the global namespace.  For  the
       duration  of the current procedure (and only while execut-
       ing in the current procedure), any reference to any of the
       varnames  will  refer  to  the global variable by the same
       name.


KEYWORDS
       global, namespace, procedure, variable


_________________________________________________________________

NAME
       history - Manipulate the history list

SYNOPSIS
       history ?option? ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       The  history  command  performs  one of several operations
       related to recently-executed commands recorded in  a  his-
       tory list.  Each of these recorded commands is referred to
       as an ``event''.  When specifying an event to the  history
       command, the following forms may be used:

       [1]    A number:  if positive, it refers to the event with
              that number (all events are  numbered  starting  at
              1).  If the number is negative, it selects an event
              relative to the current event  (-1  refers  to  the
              previous  event,  -2 to the one before that, and so
              on).  Event 0 refers to the current event.

       [2]    A string:   selects  the  most  recent  event  that
              matches  the  string.   An  event  is considered to
              match the string either if the string is  the  same
              as  the  first  characters  of the event, or if the
              string matches the event in the sense of the string
              match command.

       The history command can take any of the following forms:

       history
              Same as history info, described below.

       history add command ?exec?
              Adds  the command argument to the history list as a
              new event.  If exec is specified  (or  abbreviated)
              then the command is also executed and its result is
              returned.  If exec isn't specified  then  an  empty
              string is returned as result.

       history change newValue ?event?
              Replaces  the value recorded for an event with new-
              Value.  Event specifies the event to  replace,  and
              defaults to the current event (not event -1).  This
              command is intended for use in commands that imple-
              ment  new forms of history substitution and wish to
              replace the current event (which invokes  the  sub-
              stitution) with the command created through substi-
              tution.  The return value is an empty string.

       history clear
              Erase the history list.  The current keep limit  is
              retained.  The history event numbers are reset.

       history event ?event?
              Returns  the  value  of  the  event given by event.
              Event defaults to -1.

       history info ?count?
              Returns a formatted string (intended for humans  to
              read) giving the event number and contents for each
              of the events in the history list except  the  cur-
              rent  event.   If  count is specified then only the
              most recent count events are returned.

       history keep ?count?
              This command may be used to change the size of  the
              history list to count events.  Initially, 20 events
              are retained in the history list.  If count is  not
              specified, the current keep limit is returned.

       history nextid
              Returns the number of the next event to be recorded
              in the history list.  It is useful for things  like
              printing  the event number in command-line prompts.

       history redo ?event?
              Re-executes the  command  indicated  by  event  and
              return  its  result.   Event  defaults to -1.  This
              command results in history revision:  see below for
              details.

HISTORY REVISION
       Pre-8.0 Tcl had a complex history revision mechanism.  The
       current mechanism is more limited,  and  the  old  history
       operations  substitute and words have been removed.  (As a
       consolation, the clear operation was added.)

       The history option redo results in much simpler  ``history
       revision''.   When  this  option  is invoked then the most
       recent event is modified to eliminate the history  command
       and replace it with the result of the history command.  If
       you want to redo an event without modifying history,  then
       use  the  event  operation to retrieve some event, and the
       add operation to add it to history and execute it.


KEYWORDS
       event, history, record


_________________________________________________________________

NAME
       http  -  Client-side implementation of the HTTP/1.0 proto-
       col.

SYNOPSIS
       package require http ?2.4?

       ::http::config ?options?

       ::http::geturl url ?options?

       ::http::formatQuery list

       ::http::reset token

       ::http::wait token

       ::http::status token

       ::http::size token

       ::http::code token

       ::http::ncode token

       ::http::data token

       ::http::error token

       ::http::cleanup token

       ::http::register proto port command

       ::http::unregister proto
_________________________________________________________________


DESCRIPTION
       The http package provides the client side of the  HTTP/1.0
       protocol.   The package implements the GET, POST, and HEAD
       operations of HTTP/1.0.   It  allows  configuration  of  a
       proxy  host to get through firewalls.  The package is com-
       patible with the Safesock security policy, so  it  can  be
       used  by  untrusted  applets  to  do  URL  fetching from a
       restricted set of hosts. This package can be  extended  to
       support  additional  HTTP  transport  protocols,  such  as
       HTTPS,  by  providing  a  custom   socket   command,   via
       http::register.

       The ::http::geturl procedure does a HTTP transaction.  Its
       options  determine whether a GET, POST, or  HEAD  transac-
       tion  is performed.  The return value of ::http::geturl is


       a token for the transaction.  The value is also  the  name
       of  an  array  in the ::http namespace that contains state
       information about the transaction.  The elements  of  this
       array are described in the STATE ARRAY section.

       If  the -command option is specified, then the HTTP opera-
       tion is done in the  background.   ::http::geturl  returns
       immediately  after  generating  the  HTTP  request and the
       callback is invoked when the transaction  completes.   For
       this  to  work,  the Tcl event loop must be active.  In Tk
       applications this is always true.  For  pure-Tcl  applica-
       tions,  the  caller  can  use  ::http::wait  after calling
       ::http::geturl to start the event loop.

COMMANDS
       ::http::config ?options?
              The ::http::config command is used to set and query
              the  name  of  the  proxy  server and port, and the
              User-Agent name used in the HTTP requests.   If  no
              options  are specified, then the current configura-
              tion is returned.  If a single argument  is  speci-
              fied,  then it should be one of the flags described
              below.  In this case the current value of that set-
              ting is returned.  Otherwise, the options should be
              a set of flags and values that define the  configu-
              ration:

              -accept mimetypes
                     The  Accept  header  of  the  request.   The
                     default is */*, which means that  all  types
                     of  documents  are  accepted.  Otherwise you
                     can supply a comma separated  list  of  mime
                     type   patterns  that  you  are  willing  to
                     receive.     For    example,     "image/gif,
                     image/jpeg, text/*".

              -proxyhost hostname
                     The name of the proxy host, if any.  If this
                     value is the empty string, the URL  host  is
                     contacted directly.

              -proxyport number
                     The proxy port number.

              -proxyfilter command
                     The  command is a callback that is made dur-
                     ing ::http::geturl to determine if  a  proxy
                     is required for a given host.  One argument,
                     a host name, is added to command when it  is
                     invoked.   If a proxy is required, the call-
                     back should return a two element  list  con-
                     taining  the  proxy  server  and proxy port.
                     Otherwise the filter should return an  empty
                     list.  The default filter returns the values
                     of the -proxyhost and -proxyport settings if
                     they are non-empty.

              -useragent string
                     The  value  of  the User-Agent header in the
                     HTTP request.   The  default  is  "Tcl  http
                     client package 2.4."

       ::http::geturl url ?options?
              The ::http::geturl command is the main procedure in
              the package.  The -query option causes a POST oper-
              ation and the -validate option causes a HEAD opera-
              tion; otherwise, a GET operation is performed.  The
              ::http::geturl  command  returns a token value that
              can be used to get information about  the  transac-
              tion.   See  the STATE ARRAY and ERRORS section for
              details.  The ::http::geturl command  blocks  until
              the operation completes, unless the -command option
              specifies a callback that is invoked when the  HTTP
              transaction  completes.   ::http::geturl takes sev-
              eral options:

              -binary boolean
                     Specifies whether to force interpreting  the
                     url  data as binary.  Normally this is auto-
                     detected (anything not beginning with a text
                     content  type  or  whose content encoding is
                     gzip or compress is considered binary data).

              -blocksize size
                     The blocksize used when reading the URL.  At
                     most size bytes are  read  at  once.   After
                     each block, a call to the -progress callback
                     is made (if that option is specified).

              -channel name
                     Copy  the  URL  contents  to  channel   name
                     instead of saving it in state(body).

              -command callback
                     Invoke  callback  after the HTTP transaction
                     completes.      This      option      causes
                     ::http::geturl  to  return immediately.  The
                     callback gets an additional argument that is
                     the token returned from ::http::geturl. This
                     token is  the  name  of  an  array  that  is
                     described  in the STATE ARRAY section.  Here
                     is a template for the callback:
                             proc httpCallback {token} {
                                 upvar #0 $token state
                                 # Access state as a Tcl array
                             }


              -handler callback
                     Invoke callback whenever HTTP data is avail-
                     able;  if present, nothing else will be done
                     with the HTTP data.  This procedure gets two
                     additional  arguments:  the  socket  for the
                     HTTP  data  and  the  token  returned   from
                     ::http::geturl.   The token is the name of a
                     global array that is described in the  STATE
                     ARRAY section.  The procedure is expected to
                     return the number of  bytes  read  from  the
                     socket.   Here  is  a template for the call-
                     back:
                             proc httpHandlerCallback {socket token} {
                                 upvar #0 $token state
                                 # Access socket, and state as a Tcl array
                                 ...
                                 (example: set data [read $socket 1000];set nbytes [string length $data])
                                 ...
                                 return nbytes
                             }

              -headers keyvaluelist
                     This option is used to add extra headers  to
                     the HTTP request.  The keyvaluelist argument
                     must be a list with an even number  of  ele-
                     ments  that  alternate between keys and val-
                     ues.  The keys become  header  field  names.
                     Newlines are stripped from the values so the
                     header cannot be corrupted.  For example, if
                     keyvaluelist  is  Pragma  no-cache  then the
                     following header is  included  in  the  HTTP
                     request:
                     Pragma: no-cache

              -progress callback
                     The  callback is made after each transfer of
                     data from the URL.  The callback gets  three
                     additional   arguments:   the   token   from
                     ::http::geturl, the expected total  size  of
                     the  contents  from the Content-Length meta-
                     data, and the current number of bytes trans-
                     ferred  so far.  The expected total size may
                     be unknown, in which case zero is passed  to
                     the  callback.   Here  is a template for the
                     progress callback:
                             proc httpProgress {token total current} {
                                 upvar #0 $token state
                             }

              -query query
                     This flag causes ::http::geturl to do a POST
                     request that passes the query to the server.
                     The query must be a x-url-encoding formatted
                     query.   The  ::http::formatQuery  procedure
                     can be used to do the formatting.

              -queryblocksize size
                     The blocksize used when posting  query  data
                     to  the URL.  At most size bytes are written
                     at once.  After each block, a  call  to  the
                     -queryprogress  callback  is  made  (if that
                     option is specified).

              -querychannel channelID
                     This flag causes ::http::geturl to do a POST
                     request  that  passes  the data contained in
                     channelID to the server. The data  contained
                     in  channelID  must be a x-url-encoding for-
                     matted query unless the -type  option  below
                     is  used.  If a Content-Length header is not
                     specified   via   the   -headers    options,
                     ::http::geturl  attempts  to  determine  the
                     size of the post data  in  order  to  create
                     that  header.   If it is unable to determine
                     the size, it returns an error.

              -queryprogress callback
                     The callback is made after each transfer  of
                     data to the URL (i.e. POST) and acts exactly
                     like the -progress option (the callback for-
                     mat is the same).

              -timeout milliseconds
                     If    milliseconds    is    non-zero,   then
                     ::http::geturl sets up a  timeout  to  occur
                     after  the specified number of milliseconds.
                     A timeout results in a call to ::http::reset
                     and  to the -command callback, if specified.
                     The return value of ::http::status is  time-
                     out after a timeout has occurred.

              -type mime-type
                     Use  mime-type  as  the  Content-Type value,
                     instead of the default value (application/x-
                     www-form-urlencoded)  during  a  POST opera-
                     tion.

              -validate boolean
                     If boolean is non-zero, then  ::http::geturl
                     does  an  HTTP  HEAD  request.  This request
                     returns meta information about the URL,  but
                     the  contents  are  not  returned.  The meta
                     information is available in the  state(meta)
                     variable  after  the  transaction.   See the
                     STATE ARRAY section for details.

       ::http::formatQuery key value ?key value ...?
              This procedure does x-url-encoding of  query  data.
              It  takes  an even number of arguments that are the
              keys and values of the query.  It encodes the  keys
              and  values,  and generates one string that has the
              proper & and = separators.  The result is  suitable
              for the -query value passed to ::http::geturl.

       ::http::reset token ?why?
              This command resets the HTTP transaction identified
              by token, if  any.   This  sets  the  state(status)
              value  to  why,  which  defaults to reset, and then
              calls the registered -command callback.

       ::http::wait token
              This is a convenience  procedure  that  blocks  and
              waits  for  the transaction to complete.  This only
              works in trusted code because it uses vwait.  Also,
              it's  not  useful for the case where ::http::geturl
              is called without the -command  option  because  in
              this  case  the  ::http::geturl call doesn't return
              until the HTTP transaction is  complete,  and  thus
              there's nothing to wait for.

       ::http::data token
              This  is  a  convenience procedure that returns the
              body element (i.e., the  URL  data)  of  the  state
              array.

       ::http::error token
              This  is  a  convenience procedure that returns the
              error element of the state array.

       ::http::status token
              This is a convenience procedure  that  returns  the
              status element of the state array.

       ::http::code token
              This  is  a  convenience procedure that returns the
              http element of the state array.

       ::http::ncode token
              This is a convenience procedure that  returns  just
              the  numeric  return code (200, 404, etc.) from the
              http element of the state array.

       ::http::size token
              This is a convenience procedure  that  returns  the
              currentsize  element of the state array, which rep-
              resents the number of bytes received from  the  URL
              in the ::http::geturl call.

       ::http::cleanup token
              This  procedure cleans up the state associated with
              the connection identified  by  token.   After  this
              call,  the  procedures  like ::http::data cannot be
              used to get information about the operation.  It is
              strongly  recommended  that  you call this function
              after you're done with a given HTTP  request.   Not
              doing so will result in memory not being freed, and
              if your app calls ::http::geturl enough times,  the
              memory  leak  could  cause  a  performance hit...or
              worse.

       ::http::register proto port command
              This procedure allows one to  provide  custom  HTTP
              transport  types  such  as  HTTPS, by registering a
              prefix, the default port, and the command  to  exe-
              cute to create the Tcl channel. E.g.:
                     package require http
                     package require tls

                     http::register https 443 ::tls::socket

                     set token [http::geturl https://my.secure.site/]

       ::http::unregister proto
              This  procedure unregisters a protocol handler that
              was previously registered via http::register.


ERRORS
       The http::geturl procedure will raise errors in  the  fol-
       lowing  cases:  invalid  command  line options, an invalid
       URL, a URL on a non-existent host, or a URL at a bad  port
       on  an  existing  host.   These errors mean that it cannot
       even start the network transaction.  It will also raise an
       error  if  it gets an I/O error while writing out the HTTP
       request  header.   For  synchronous  ::http::geturl  calls
       (where  -command is not specified), it will raise an error
       if it gets an I/O error while reading the HTTP reply head-
       ers  or  data.   Because  ::http::geturl  doesn't return a
       token in these cases, it does all the required cleanup and
       there's   no   issue   of   your   app   having   to  call
       ::http::cleanup.

       For asynchronous ::http::geturl calls, all  of  the  above
       error  situations  apply, except that if there's any error
       while reading the HTTP reply headers or data, no exception
       is  thrown.   This is because after writing the HTTP head-
       ers, ::http::geturl returns, and  the  rest  of  the  HTTP
       transaction  occurs  in the background.  The command call-
       back can check if any error occurred during  the  read  by
       calling  ::http::status  to  check  the  status and if its
       error, calling ::http::error to get the error message.

       Alternatively, if the main program flow  reaches  a  point
       where it needs to know the result of the asynchronous HTTP
       request, it can call ::http::wait and  then  check  status
       and error, just as the callback does.
       In  any  case, you must still call http::cleanup to delete
       the state array when you're done.

       There are other possible results of the  HTTP  transaction
       determined  by  examining  the  status  from http::status.
       These are described below.

       ok     If the HTTP transaction  completes  entirely,  then
              status will be ok.  However, you should still check
              the http::code value to get the HTTP  status.   The
              http::ncode  procedure  provides  just  the numeric
              error (e.g., 200, 404 or 500) while the  http::code
              procedure  returns  a value like "HTTP 404 File not
              found".

       eof    If the server closes the socket  without  replying,
              then  no  error  is  raised,  but the status of the
              transaction will be eof.

       error  The error message will also be stored in the  error
              status array element, accessible via ::http::error.

       Another error possibility is that http::geturl  is  unable
       to  write all the post query data to the server before the
       server responds and closes the socket.  The error  message
       is  saved  in  the posterror status array element and then
       http::geturl attempts to complete the transaction.  If  it
       can  read  the server's response it will end up with an ok
       status, otherwise it will have an eof status.


STATE ARRAY
       The ::http::geturl procedure returns a token that  can  be
       used  to  get  to the state of the HTTP transaction in the
       form of a Tcl array.  Use  this  construct  to  create  an
       easy-to-use array variable:
              upvar #0 $token state
       Once the data associated with the url is no longer needed,
       the state array should be unset to free up  storage.   The
       http::cleanup procedure is provided for that purpose.  The
       following elements of the array are supported:

              body   The contents of the URL.  This will be empty
                     if  the  -channel option has been specified.
                     This value is returned by  the  ::http::data
                     command.

              charset
                     The  value of the charset attribute from the
                     Content-Type meta-data value.  If  none  was
                     specified, this defaults to the RFC standard
                     iso8859-1, or the value of $::http::default-
                     Charset.   Incoming  text data will be auto-
                     matically converted  from  this  charset  to
                     utf-8.

              coding A  copy  of  the  Content-Encoding meta-data
                     value.

              currentsize
                     The current number of bytes fetched from the
                     URL.    This   value   is  returned  by  the
                     ::http::size command.

              error  If defined, this is the  error  string  seen
                     when the HTTP transaction was aborted.

              http   The HTTP status reply from the server.  This
                     value is returned by the  ::http::code  com-
                     mand.  The format of this value is:
                             HTTP/1.0 code string
                     The  code is a three-digit number defined in
                     the HTTP standard.  A code  of  200  is  OK.
                     Codes beginning with 4 or 5 indicate errors.
                     Codes  beginning  with  3  are   redirection
                     errors.  In this case the Location meta-data
                     specifies  a  new  URL  that  contains   the
                     requested information.

              meta   The  HTTP  protocol  returns  meta-data that
                     describes the URL contents.  The  meta  ele-
                     ment  of  the  state  array is a list of the
                     keys and values of the meta-data.   This  is
                     in a format useful for initializing an array
                     that just contains the meta-data:
                             array set meta $state(meta)
                     Some of the meta-data keys are listed below,
                     but  the  HTTP  standard  defines  more, and
                     servers are free to add their own.

                     Content-Type
                             The type of the URL contents.  Exam-
                             ples  include  text/html, image/gif,
                             application/postscript and  applica-
                             tion/x-tcl.

                     Content-Length
                             The advertised size of the contents.
                             The   actual   size   obtained    by
                             ::http::geturl   is   available   as
                             state(size).

                     Location
                             An alternate URL that  contains  the
                             requested data.

              posterror
                     The  error,  if  any,  that  occurred  while
                   writing the post query data to the server.

              status Either ok, for successful completion,  reset
                     for   user-reset,   timeout   if  a  timeout
                     occurred before the transaction  could  com-
                     plete,  or  error  for  an  error condition.
                     During the transaction  this  value  is  the
                     empty string.

              totalsize
                     A   copy  of  the  Content-Length  meta-data
                     value.

              type   A copy of the Content-Type meta-data  value.

              url    The requested URL.

EXAMPLE
              # Copy a URL to a file and print meta-data
              proc ::http::copy { url file {chunk 4096} } {
                  set out [open $file w]
                  set token [geturl $url -channel $out -progress ::http::Progress \
                -blocksize $chunk]
                  close $out
                  # This ends the line started by http::Progress
                  puts stderr ""
                  upvar #0 $token state
                  set max 0
                  foreach {name value} $state(meta) {
                if {[string length $name] > $max} {
                    set max [string length $name]
                }
                if {[regexp -nocase ^location$ $name]} {
                    # Handle URL redirects
                    puts stderr "Location:$value"
                    return [copy [string trim $value] $file $chunk]
                }
                  }
                  incr max
                  foreach {name value} $state(meta) {
                puts [format "%-*s %s" $max $name: $value]
                  }

                  return $token
              }
              proc ::http::Progress {args} {
                  puts -nonewline stderr . ; flush stderr
              }


KEYWORDS
       security policy, socket


_________________________________________________________________

NAME
       if - Execute scripts conditionally

SYNOPSIS
       if expr1 ?then? body1 elseif expr2 ?then? body2 elseif ...
       ?else? ?bodyN?
_________________________________________________________________


DESCRIPTION
       The if command evaluates expr1 as an  expression  (in  the
       same  way that expr evaluates its argument).  The value of
       the expression must be a boolean (a numeric value, where 0
       is  false  and anything is true, or a string value such as
       true or yes for true and false or no for false); if it  is
       true  then  body1  is  executed  by  passing it to the Tcl
       interpreter.  Otherwise expr2 is evaluated as  an  expres-
       sion  and if it is true then body2 is executed, and so on.
       If none of the expressions evaluates to true then bodyN is
       executed.   The  then  and  else  arguments  are  optional
       ``noise words'' to make the command easier to read.  There
       may  be  any  number  of  elseif  clauses, including zero.
       BodyN may also be omitted as long as else is omitted  too.
       The  return  value  from  the command is the result of the
       body script that was executed, or an empty string if  none
       of the expressions was non-zero and there was no bodyN.


KEYWORDS
       boolean, conditional, else, false, if, true


_________________________________________________________________

NAME
       incr - Increment the value of a variable

SYNOPSIS
       incr varName ?increment?
_________________________________________________________________


DESCRIPTION
       Increments  the value stored in the variable whose name is
       varName.  The value of the variable must  be  an  integer.
       If  increment is supplied then its value (which must be an
       integer) is added to the value of variable varName;   oth-
       erwise  1 is added to varName.  The new value is stored as
       a decimal string in variable varName and also returned  as
       result.


KEYWORDS
       add, increment, variable, value


_________________________________________________________________

NAME
       info  -  Return  information  about  the  state of the Tcl
       interpreter

SYNOPSIS
       info option ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       This command provides information about various  internals
       of  the Tcl interpreter.  The legal option's (which may be
       abbreviated) are:

       info args procname
              Returns a list containing the names  of  the  argu-
              ments  to  procedure  procname, in order.  Procname
              must be the name of a Tcl command procedure.

       info body procname
              Returns the body of procedure  procname.   Procname
              must be the name of a Tcl command procedure.

       info cmdcount
              Returns  a  count  of  the total number of commands
              that have been invoked in this interpreter.

       info commands ?pattern?
              If pattern isn't specified, returns a list of names
              of  all  the Tcl commands in the current namespace,
              including both the built-in commands written  in  C
              and  the  command procedures defined using the proc
              command.  If pattern is specified, only those names
              matching  pattern are returned.  Matching is deter-
              mined using the same rules  as  for  string  match.
              pattern  can  be a qualified name like Foo::print*.
              That is, it  may  specify  a  particular  namespace
              using  a  sequence  of namespace names separated by
              ::s, and may have pattern matching special  charac-
              ters  at  the  end  to specify a set of commands in
              that namespace.  If pattern is  a  qualified  name,
              the  resulting  list  of command names has each one
              qualified with the name of the specified namespace.

       info complete command
              Returns  1  if command is a complete Tcl command in
              the sense of having  no  unclosed  quotes,  braces,
              brackets  or  array  element  names, If the command
              doesn't appear to be complete then 0  is  returned.
              This  command  is  typically  used in line-oriented
              input environments to allow users to type  in  com-
              mands  that  span  multiple  lines;  if the command
              isn't complete, the script can delay evaluating  it
              until  additional lines have been typed to complete
              the command.

       info default procname arg varname
              Procname must be the name of a Tcl  command  proce-
              dure  and  arg  must  be the name of an argument to
              that procedure.  If  arg  doesn't  have  a  default
              value  then  the  command  returns 0.  Otherwise it
              returns 1 and places the default value of arg  into
              variable varname.

       info exists varName
              Returns  1  if the variable named varName exists in
              the current context (either as a  global  or  local
              variable)  and  has  been  defined by being given a
              value, returns 0 otherwise.                         

       info functions                                             
       ?pattern?                                          
              If  pattern  isn't specified, returns a list of all 
              the math functions currently defined.   If  pattern 
              is  specified,  only  those  functions  whose  name 
              matches pattern are returned.  Matching  is  deter-
              mined using the same rules as for string match.

       info globals ?pattern?
              If  pattern  isn't specified, returns a list of all
              the names of  currently-defined  global  variables.
              Global variables are variables in the global names-
              pace.  If pattern is specified,  only  those  names
              matching  pattern are returned.  Matching is deter-
              mined using the same rules as for string match.

       info hostname
              Returns the name of  the  computer  on  which  this
              invocation  is being executed.  Note that this name 
              is not guaranteed to be the fully qualified  domain 
              name of the host.  Where machines have several dif-
              ferent names (as is common  on  systems  with  both 
              TCP/IP    (DNS)    and   NetBIOS-based   networking 
              installed,) it is the name  that  is  suitable  for 
              TCP/IP networking that is returned.

       info level ?number?
              If  number is not specified, this command returns a
              number giving the stack level of the invoking  pro-
              cedure,  or  0  if  the  command is invoked at top-
              level.  If number is specified, then the result  is
              a list consisting of the name and arguments for the
              procedure call at level number on  the  stack.   If
              number  is  positive  then  it selects a particular
              stack level (1 refers to the top-most active proce-
              dure,  2  to  the  procedure it called, and so on);
              otherwise it gives a level relative to the  current
              level (0 refers to the current procedure, -1 to its
              caller, and so on).  See the  uplevel  command  for
              more information on what stack levels mean.

       info library
              Returns  the name of the library directory in which
              standard Tcl scripts are stored.  This is  actually
              the  value  of  the tcl_library variable and may be
              changed by setting tcl_library.   See  the  tclvars
              manual entry for more information.

       info loaded ?interp?
              Returns  a list describing all of the packages that
              have been loaded into interp with the load command.
              Each  list  element is a sub-list with two elements
              consisting of the name of the file from  which  the
              package  was  loaded  and  the name of the package.
              For statically-loaded packages the file  name  will
              be  an  empty  string.   If  interp is omitted then
              information is returned for all packages loaded  in
              any  interpreter  in the process.  To get a list of
              just the packages in the current interpreter, spec-
              ify an empty string for the interp argument.

       info locals ?pattern?
              If  pattern  isn't specified, returns a list of all
              the names  of  currently-defined  local  variables,
              including  arguments  to  the current procedure, if
              any.  Variables defined with the global, upvar  and
              variable commands will not be returned.  If pattern
              is specified, only those names matching pattern are
              returned.   Matching  is  determined using the same
              rules as for string match.

       info nameofexecutable
              Returns the full path name of the binary file  from
              which  the  application  was  invoked.   If Tcl was
              unable to identify the file, then an  empty  string
              is returned.

       info patchlevel
              Returns the value of the global variable tcl_patch-
              Level; see the tclvars manual entry for more infor-
              mation.

       info procs ?pattern?
              If  pattern  isn't specified, returns a list of all
              the names of Tcl command procedures in the  current
              namespace.   If  pattern  is  specified, only those
              procedure names in the current  namespace  matching
              pattern are returned.  Matching is determined using
              the same rules as for string match.


       info script ?filename?
              If a Tcl script file is currently  being  evaluated
              (i.e.  there  is  a  call to Tcl_EvalFile active or
              there is an active invocation of  the  source  com-
              mand),  then  this  command returns the name of the
              innermost file being  processed.   If  filename  is
              specified,  then  the  return value of this command
              will be modified for the  duration  of  the  active
              invocation  to return that name.  This is useful in
              virtual file system  applications.   Otherwise  the
              command returns an empty string.

       info sharedlibextension
              Returns the extension used on this platform for the
              names of files  containing  shared  libraries  (for
              example,  .so  under Solaris).  If shared libraries
              aren't supported on this  platform  then  an  empty
              string is returned.

       info tclversion
              Returns  the  value of the global variable tcl_ver-
              sion; see the tclvars manual entry for more  infor-
              mation.

       info vars ?pattern?
              If  pattern  isn't specified, returns a list of all
              the names  of  currently-visible  variables.   This
              includes  locals and currently-visible globals.  If
              pattern is specified,  only  those  names  matching
              pattern are returned.  Matching is determined using
              the same rules as for string match.  pattern can be
              a  qualified  name  like Foo::option*.  That is, it
              may specify a particular namespace using a sequence
              of  namespace  names separated by ::s, and may have
              pattern matching special characters at the  end  to
              specify  a  set of variables in that namespace.  If
              pattern is a qualified name, the resulting list  of
              variable names has each matching namespace variable
              qualified with the name of its namespace.


KEYWORDS
       command, information, interpreter, level, namespace,  pro-
       cedure, variable


_________________________________________________________________

NAME
       interp - Create and manipulate Tcl interpreters

SYNOPSIS
       interp option ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       This  command  makes it possible to create one or more new
       Tcl interpreters that co-exist with  the  creating  inter-
       preter  in the same application.  The creating interpreter
       is called the master and the new interpreter is  called  a
       slave.  A master can create any number of slaves, and each
       slave can itself create additional slaves for which it  is
       master, resulting in a hierarchy of interpreters.

       Each  interpreter  is  independent from the others: it has
       its own name space for commands,  procedures,  and  global
       variables.   A  master  interpreter may create connections
       between its slaves and itself using a mechanism called  an
       alias.   An  alias  is  a  command  in a slave interpreter
       which, when invoked, causes a command to be invoked in its
       master  interpreter  or in another slave interpreter.  The
       only other connections between  interpreters  are  through
       environment  variables  (the env variable), which are nor-
       mally shared among all interpreters  in  the  application.
       Note  that  the  name  space  for files (such as the names
       returned by the open command) is no longer shared  between
       interpreters.  Explicit  commands  are  provided  to share
       files and to transfer references to open  files  from  one
       interpreter to another.

       The  interp  command also provides support for safe inter-
       preters.  A safe interpreter is a  slave  whose  functions
       have  been  greatly restricted, so that it is safe to exe-
       cute untrusted scripts without fear of them damaging other
       interpreters  or  the application's environment. For exam-
       ple, all IO channel creation commands and subprocess  cre-
       ation commands are made inaccessible to safe interpreters. 
       See SAFE INTERPRETERS below for more information  on  what 
       features are present in a safe interpreter.  The dangerous 
       functionality is not removed from  the  safe  interpreter; 
       instead,  it  is hidden, so that only trusted interpreters 
       can obtain access to it. For  a  detailed  explanation  of 
       hidden  commands,  see  HIDDEN COMMANDS, below.  The alias 
       mechanism can be used for protected communication  (analo-
       gous to a kernel call) between a slave interpreter and its 
       master. See ALIAS INVOCATION, below, for more  details  on 
       how the alias mechanism works.

       A  qualified  interpreter  name  is  a  proper  Tcl  lists
       containing a subset of its ancestors  in  the  interpreter
       hierarchy, terminated by the string naming the interpreter
       in its immediate master. Interpreter names are relative to
       the  interpreter in which they are used. For example, if a
       is a slave of the current interpreter and it has  a  slave
       a1,  which  in turn has a slave a11, the qualified name of
       a11 in a is the list a1 a11.

       The interp command,  described  below,  accepts  qualified
       interpreter  names  as arguments; the interpreter in which
       the command is being evaluated can always be  referred  to
       as {} (the empty list or string). Note that it is impossi-
       ble to refer to a master (ancestor) interpreter by name in
       a slave interpreter except through aliases. Also, there is
       no global name by which one can refer to the first  inter-
       preter  created  in an application.  Both restrictions are
       motivated by safety concerns.


THE INTERP COMMAND                                                
       The interp command is used to create, delete, and  manipu-
       late slave interpreters, and to share or transfer channels
       between interpreters.  It can have any of  several  forms,
       depending on the option argument:

       interp alias srcPath srcCmd
              Returns a Tcl list whose elements are the targetCmd
              and args associated with  the  alias  named  srcCmd
              (all  of  these  are  the values specified when the
              alias was created; it is possible that  the  actual
              source  command in the slave is different from src-
              Cmd if it was renamed).

       interp alias srcPath srcCmd {}
              Deletes the alias for srcCmd in  the  slave  inter-
              preter identified by srcPath.  srcCmd refers to the
              name under which the alias  was  created;   if  the
              source  command  has been renamed, the renamed com-
              mand will be deleted.

       interp alias srcPath srcCmd targetPath targetCmd ?arg arg...?
              This command creates an alias between one slave and
              another (see the alias slave command below for cre-
              ating  aliases between a slave and its master).  In
              this command, either of the slave interpreters  may
              be  anywhere in the hierarchy of interpreters under
              the interpreter invoking the command.  SrcPath  and
              srcCmd  identify  the source of the alias.  SrcPath
              is a Tcl list whose elements  select  a  particular
              interpreter.   For  example,  ``a b'' identifies an
              interpreter b, which is a slave of  interpreter  a,
              which  is  a slave of the invoking interpreter.  An
              empty list specifies the interpreter  invoking  the
              command.   srcCmd  gives the name of a new command,
              which will be created in  the  source  interpreter.
              TargetPath  and  targetCmd  specify a target inter-
              preter and command, and the arg arguments, if  any,
              specify additional arguments to targetCmd which are
              prepended to any arguments specified in the invoca-
              tion  of srcCmd.  TargetCmd may be undefined at the
              time of this call, or it may already exist;  it  is
              not  created  by  this command.  The alias arranges
              for the given target command to be invoked  in  the
              target  interpreter  whenever the given source com-
              mand is invoked in  the  source  interpreter.   See
              ALIAS INVOCATION below for more details.

       interp aliases ?path?
              This command returns a Tcl list of the names of all
              the source commands  for  aliases  defined  in  the
              interpreter identified by path.

       interp create ?-safe? ?--? ?path?
              Creates  a slave interpreter identified by path and
              a new command, called a slave command. The name  of
              the  slave  command  is the last component of path.
              The new slave interpreter and the slave command are
              created  in  the interpreter identified by the path
              obtained by removing the last component from  path.
              For  example,  if  path  is  a b c then a new slave
              interpreter and slave command named c  are  created
              in the interpreter identified by the path a b.  The
              slave command may be used  to  manipulate  the  new
              interpreter as described below. If path is omitted,
              Tcl creates a unique  name  of  the  form  interpx,
              where  x  is an integer, and uses it for the inter-
              preter and the slave command. If the  -safe  switch
              is  specified  (or  if  the master interpreter is a
              safe interpreter), the new slave  interpreter  will
              be created as a safe interpreter with limited func-
              tionality; otherwise the  slave  will  include  the

              The -- switch can  be  used  to  mark  the  end  of
              switches;   it  may be needed if path is an unusual
              value such as -safe. The result of the  command  is
              the  name  of  the  new  interpreter. The name of a
              slave interpreter must  be  unique  among  all  the
              slaves  for its master;  an error occurs if a slave
              interpreter by the given  name  already  exists  in
              this  master.   The  initial recursion limit of the
              slave interpreter is set to the  current  recursion
              limit of its parent interpreter.

       interp delete ?path ...?
              Deletes  zero  or  more  interpreters  given by the
              optional path arguments, and for each  interpreter,
              it  also  deletes  its  slaves.  The  command  also
              deletes the  slave  command  for  each  interpreter
              deleted.  For each path argument, if no interpreter
              by that name exists, the command raises an error.

       interp eval path arg ?arg ...?
              This command concatenates all of the arg  arguments
              in  the  same  fashion  as the concat command, then
              evaluates the resulting string as a Tcl  script  in
              the  slave  interpreter  identified  by  path.  The
              result of this evaluation (including error informa-
              tion such as the errorInfo and errorCode variables,
              if an error occurs) is  returned  to  the  invoking
              interpreter.

       interp exists path
              Returns   1 if a slave interpreter by the specified
              path exists in this master, 0 otherwise. If path is
              omitted, the invoking interpreter is used.

       interp expose path hiddenName ?exposedCmdName?                    
              Makes the hidden command hiddenName exposed,  even-
              tually  bringing it back under a new exposedCmdName 
              name (this name is currently accepted only if it is 
              a  valid global name space name without any ::), in 
              the interpreter denoted by  path.   If  an  exposed 
              command with the targeted name already exists, this 
              command fails.  Hidden commands  are  explained  in 
              more detail in HIDDEN COMMANDS, below.              

       interp hide path exposedCmdName ?hiddenCmdName?                   
              Makes the exposed  command  exposedCmdName  hidden, 
              renaming it to the hidden command hiddenCmdName, or 
              keeping the  same  name  if  hiddenCmdName  is  not 
              given,  in  the  interpreter denoted by path.  If a 
              hidden  command  with  the  targeted  name  already 
              exists,   this   command   fails.   Currently  both 
              exposedCmdName and hiddenCmdName  can  not  contain 
              namespace  qualifiers, or an error is raised.  Com-
              mands to be hidden by interp hide are looked up  in 
              the  global namespace even if the current namespace 
              is not the global one. This  prevents  slaves  from 
              fooling  a master interpreter into hiding the wrong 
              command, by making the current namespace be differ-
              ent  from  the  global  one.   Hidden  commands are 
              explained in more detail in HIDDEN COMMANDS, below. 

       interp hidden path                                                
              Returns a list of the names of all hidden  commands 
              in the interpreter identified by path.              


       interp invokehidden path ?-global? hiddenCmdName ?arg...?        
              Invokes the hidden command hiddenCmdName  with  the 
              arguments  supplied  in  the interpreter denoted by 
              path. No substitutions or evaluation are applied to 
              the arguments.  If the -global flag is present, the 
              hidden command is invoked at the  global  level  in 
              the  target interpreter; otherwise it is invoked at 
              the current call frame and can access  local  vari-
              ables  in  that and outer call frames.  Hidden com-
              mands are explained in more detail in  HIDDEN  COM-
              MANDS, below.

       interp issafe ?path?
              Returns  1  if  the  interpreter  identified by the
              specified path is safe, 0 otherwise.

       interp marktrusted path                                           
              Marks   the   interpreter  identified  by  path  as 
              trusted. Does not expose the hidden commands.  This 
              command  can  only be invoked from a trusted inter-
              preter.  The command has no effect  if  the  inter-
              preter identified by path is already trusted.

       interp recursionlimit path ?newlimit?
              Returns the maximum allowable nesting depth for the
              interpreter specified  by  path.   If  newlimit  is
              specified,  the interpreter recursion limit will be
              set so that nesting of more than newlimit calls  to
              Tcl_Eval()  and  related  procedures in that inter-
              preter will return an error.  The newlimit value is
              also  returned.  The newlimit value must be a posi-
              tive integer between 1 and the maximum value  of  a
              non-long integer on the platform.

              The  command  sets the maximum size of the Tcl call
              stack only. It cannot by itself prevent stack over-
              flows on the C stack being used by the application.
              If your machine has a limit on the size  of  the  C
              stack,  you may get stack overflows before reaching
              the limit set by the command. If this happens,  see
              if there is a mechanism in your system for increas-
              ing the maximum size of the C stack.

       interp share srcPath channelId destPath
              Causes the IO channel identified  by  channelId  to
              become shared between the interpreter identified by
              srcPath and the interpreter identified by destPath.
              Both  interpreters have the same permissions on the
              IO channel.  Both interpreters  must  close  it  to
              close the underlying IO channel; IO channels acces-
              sible in an interpreter  are  automatically  closed
              when an interpreter is destroyed.


       interp slaves ?path?
              Returns  a  Tcl  list of the names of all the slave
              interpreters associated with the interpreter  iden-
              tified  by  path.  If path is omitted, the invoking
              interpreter is used.

       interp target path alias
              Returns a Tcl list  describing  the  target  inter-
              preter for an alias. The alias is specified with an
              interpreter path and source command name,  just  as
              in  interp  alias  above.  The  name  of the target
              interpreter is returned  as  an  interpreter  path,
              relative  to the invoking interpreter.  If the tar-
              get interpreter  for  the  alias  is  the  invoking
              interpreter  then an empty list is returned. If the
              target interpreter for the alias is not the  invok-
              ing  interpreter  or one of its descendants then an
              error is generated.  The target  command  does  not
              have  to be defined at the time of this invocation.

       interp transfer srcPath channelId destPath
              Causes the IO channel identified  by  channelId  to
              become  available  in the interpreter identified by
              destPath and unavailable in the interpreter identi-
              fied by srcPath.


SLAVE COMMAND
       For  each  slave  interpreter created with the interp com-
       mand, a new Tcl command is created in  the  master  inter-
       preter  with  the  same  name as the new interpreter. This
       command may be used to invoke various  operations  on  the
       interpreter.  It has the following general form:
              slave command ?arg arg ...?
       Slave  is the name of the interpreter, and command and the
       args determine the exact behavior  of  the  command.   The
       valid forms of this command are:

       slave aliases
              Returns  a Tcl list whose elements are the names of
              all the aliases in slave.  The names  returned  are
              the  srcCmd  values used when the aliases were cre-
              ated (which may not be  the  same  as  the  current
              names  of the commands, if they have been renamed).

       slave alias srcCmd
              Returns a Tcl list whose elements are the targetCmd
              and  args  associated  with  the alias named srcCmd
              (all of these are the  values  specified  when  the
              alias  was  created; it is possible that the actual
              source command in the slave is different from  src-
              Cmd if it was renamed).


       slave alias srcCmd {}
              Deletes  the  alias  for srcCmd in the slave inter-
              preter.  srcCmd refers to the name under which  the
              alias  was created;  if the source command has been
              renamed, the renamed command will be deleted.

       slave alias srcCmd targetCmd ?arg ..?
              Creates an  alias  such  that  whenever  srcCmd  is
              invoked  in slave, targetCmd is invoked in the mas-
              ter.  The arg arguments will be passed to targetCmd
              as additional arguments, prepended before any argu-
              ments passed in  the  invocation  of  srcCmd.   See
              ALIAS INVOCATION below for details.

       slave eval arg ?arg ..?
              This  command concatenates all of the arg arguments
              in the same fashion as  the  concat  command,  then
              evaluates  the  resulting string as a Tcl script in
              slave.  The result of  this  evaluation  (including
              error  information such as the errorInfo and error-
              Code variables, if an error occurs) is returned  to
              the invoking interpreter.

       slave expose hiddenName ?exposedCmdName?                          
              This command exposes the hidden command hiddenName, 
              eventually bringing it back under a new exposedCmd-
              Name name (this name is currently accepted only  if 
              it  is  a  valid global name space name without any 
              ::), in slave.  If an exposed command with the tar-
              geted name already exists, this command fails.  For 
              more details on hidden commands,  see  HIDDEN  COM-
              MANDS, below.                                       

       slave hide exposedCmdName ?hiddenCmdName?                         
              This command hides the exposed command  exposedCmd-
              Name,  renaming it to the hidden command hiddenCmd-
              Name, or keeping the same name if the the  argument 
              is  not given, in the slave interpreter.  If a hid-
              den command with the targeted name already  exists, 
              this  command fails.  Currently both exposedCmdName 
              and hiddenCmdName can not contain namespace  quali-
              fiers,  or an error is raised.  Commands to be hid-
              den are looked up in the global namespace  even  if 
              the  current  namespace is not the global one. This 
              prevents slaves from fooling a  master  interpreter 
              into  hiding  the wrong command, by making the cur-
              rent namespace be different from  the  global  one. 
              For  more  details  on  hidden commands, see HIDDEN 
              COMMANDS, below.                                    

       slave hidden                                                      
              Returns a list of the names of all hidden  commands 
              in slave.                                           

       slave invokehidden ?-global hiddenName ?arg...?                   
              This command invokes the hidden command  hiddenName 
              with the supplied arguments, in slave. No substitu-
              tions or evaluations are applied to the  arguments. 
              If  the  -global  flag  is  given,  the  command is 
              invoked at the global level in the slave; otherwise 
              it  is  invoked  at  the current call frame and can 
              access  local  variables  in  that  or  outer  call 
              frames.   For  more details on hidden commands, see 
              HIDDEN COMMANDS, below.

       slave issafe
              Returns  1 if the slave interpreter is safe, 0 oth-
              erwise.

       slave                                                      
       marktrusted                                                 
              Marks the slave interpreter as trusted. Can only be 
              invoked by a trusted interpreter. This command does 
              not  expose any hidden commands in the slave inter-
              preter. The command has no effect if the  slave  is 
              already trusted.

       slave recursionlimit ?newlimit?
              Returns the maximum allowable nesting depth for the
              slave interpreter.  If newlimit is  specified,  the
              recursion  limit in slave will be set so that nest-
              ing of more than newlimit calls to  Tcl_Eval()  and
              related  procedures  in slave will return an error.
              The newlimit value is also returned.  The  newlimit
              value  must be a positive integer between 1 and the
              maximum value of a non-long integer  on  the  plat-
              form.

              The  command  sets the maximum size of the Tcl call
              stack only. It cannot by itself prevent stack over-
              flows on the C stack being used by the application.
              If your machine has a limit on the size  of  the  C
              stack,  you may get stack overflows before reaching
              the limit set by the command. If this happens,  see
              if there is a mechanism in your system for increas-
              ing the maximum size of the C stack.

SAFE INTERPRETERS
       A safe interpreter is one with  restricted  functionality,
       so  that  is safe to execute an arbitrary script from your
       worst enemy without  fear  of  that  script  damaging  the
       enclosing  application or the rest of your computing envi-
       ronment.  In order to make an  interpreter  safe,  certain
       commands  and  variables are removed from the interpreter.

       For example, commands to create files on disk are removed,
       and the exec command is removed, since it could be used to
       cause damage  through  subprocesses.   Limited  access  to
       these  facilities  can be provided, by creating aliases to
       the master interpreter which check their  arguments  care-
       fully  and  provide  restricted access to a safe subset of
       facilities.  For example, file creation might  be  allowed
       in  a  particular  subdirectory  and subprocess invocation
       might be allowed for a carefully selected and fixed set of
       programs.

       A  safe  interpreter  is  created  by specifying the -safe
       switch to the interp  create  command.   Furthermore,  any
       slave created by a safe interpreter will also be safe.

       A  safe  interpreter is created with exactly the following
       set of built-in commands:

              after       append      array       binary
              break       case        catch       clock
              close       concat      continue    eof
              error       eval        expr        fblocked
              fcopy       fileevent   flush       for
              foreach     format      gets        global
              if          incr        info        interp
              join        lappend     lindex      linsert
              list        llength     lrange      lreplace
              lsearch     lsort       namespace   package
              pid         proc        puts        read
              regexp      regsub      rename      return
              scan        seek        set         split
              string      subst       switch      tell
              time        trace       unset       update
              uplevel     upvar       variable    vwait
              while

       The following commands are hidden by interp create when it 
       creates a safe interpreter:                                

              cd          encoding    exec        exit            
              fconfigure file         glob        load            
              open        pwd         socket      source          

       These commands can be recreated later as Tcl procedures or 
       aliases, or re-exposed by interp expose.                   

       The following commands from Tcl's library of support  pro-
       cedures are not present in a safe interpreter:             

              auto_exec_ok    auto_import     auto_load           
              auto_load_index auto_qualify    unknown             

       Note  in particular that safe interpreters have no default 
       unknown command, so Tcl's default  autoloading  facilities 
       are not available.  Autoload access to Tcl's commands that 
       are normally autoloaded:                                   
              auto_mkindex         auto_mkindex_old               
              auto_reset           history                        
              parray               pkg_mkIndex                    
              ::pkg::create        ::safe::interpAddToAccessPath  
              ::safe::interpCreate ::safe::interpConfigure        
              ::safe::interpDelete ::safe::interpFindInAccessPath 
              ::safe::interpInit   ::safe::setLogCmd              
              tcl_endOfWord        tcl_findLibrary                
              tcl_startOfNextWord  tcl_startOfPreviousWord        
              tcl_wordBreakAfter   tcl_wordBreakBefore            

       can only be provided by explicit definition of an  unknown 
       command in the safe interpreter.  This will involve expos-
       ing the source command.  This is most easily  accomplished 
       by creating the safe interpreter with Tcl's Safe-Tcl mech-
       anism.  Safe-Tcl provides safe versions of  source,  load, 
       and  other  Tcl  commands needed to support autoloading of 
       commands and the loading of packages.

       In addition, the env variable is not  present  in  a  safe
       interpreter, so it cannot share environment variables with
       other interpreters. The  env  variable  poses  a  security
       risk,  because users can store sensitive information in an
       environment variable. For example, the PGP  manual  recom-
       mends  storing  the PGP private key protection password in
       the environment variable  PGPPASS.  Making  this  variable
       available  to  untrusted  code  executing in a safe inter-
       preter would incur a security risk.

       If extensions are loaded into a safe interpreter, they may
       also  restrict their own functionality to eliminate unsafe
       commands. For a discussion of management of extensions for
       safety  see  the  manual entries for Safe-Tcl and the load
       Tcl command.

       A safe interpreter may not alter the  recursion  limit  of
       any interpreter, including itself.


ALIAS INVOCATION
       The alias mechanism has been carefully designed so that it
       can be used safely when an untrusted script  is  executing
       in  a  safe slave and the target of the alias is a trusted
       master.  The most important thing in  guaranteeing  safety
       is to ensure that information passed from the slave to the
       master is never evaluated or substituted  in  the  master;
       if  this  were to occur, it would enable an evil script in
       the slave to invoke arbitrary  functions  in  the  master,
       which would compromise security.


       When  the  source  for  an  alias  is invoked in the slave
       interpreter, the usual  Tcl  substitutions  are  performed
       when  parsing  that command.  These substitutions are car-
       ried out in the source interpreter just as they  would  be
       for  any  other  command invoked in that interpreter.  The
       command procedure for the source command takes  its  argu-
       ments  and merges them with the targetCmd and args for the
       alias to create a new array of arguments.  If the words of
       srcCmd  were ``srcCmd arg1 arg2 ... argN'', the new set of
       words will be ``targetCmd arg arg ... arg  arg1  arg2  ...
       argN'',  where  targetCmd and args are the values supplied
       when the alias was created.  TargetCmd  is  then  used  to
       locate  a command procedure in the target interpreter, and
       that command procedure is invoked  with  the  new  set  of
       arguments.   An  error occurs if there is no command named
       targetCmd in the target interpreter.  No  additional  sub-
       stitutions are performed on the words:  the target command
       procedure is invoked directly, without going  through  the
       normal  Tcl  evaluation mechanism.  Substitutions are thus
       performed on each word exactly once:  targetCmd  and  args
       were substituted when parsing the command that created the
       alias, and arg1 - argN are substituted  when  the  alias's
       source command is parsed in the source interpreter.

       When  writing  the  targetCmds  for aliases in safe inter-
       preters, it is very important that the arguments  to  that
       command  never  be  evaluated  or  substituted, since this
       would provide an escape mechanism whereby the slave inter-
       preter  could  execute arbitrary code in the master.  This
       in turn would compromise the security of the system.


HIDDEN COMMANDS                                                   
       Safe  interpreters  greatly  restrict  the   functionality 
       available to Tcl programs executing within them.  Allowing 
       the untrusted Tcl program to have direct  access  to  this 
       functionality  is  unsafe,  because  it  can be used for a 
       variety of attacks on the environment.  However, there are 
       times when there is a legitimate need to use the dangerous 
       functionality in the context of the safe interpreter.  For 
       example,  sometimes  a  program  must  be sourced into the 
       interpreter.  Another example is  Tk,  where  windows  are 
       bound  to  the  hierarchy of windows for a specific inter-
       preter; some potentially dangerous functions, e.g.  window 
       management,  must be performed on these windows within the 
       interpreter context.                                       

       The interp command provides a solution to this problem  in 
       the  form of hidden commands. Instead of removing the dan-
       gerous commands entirely from a  safe  interpreter,  these 
       commands  are  hidden  so  they  become unavailable to Tcl 
       scripts executing in the interpreter. However, such hidden 
       commands  can  be  invoked  by any trusted ancestor of the 
       safe interpreter, in the context of the safe  interpreter, 
       using  interp invoke. Hidden commands and exposed commands 
       reside in separate name spaces. It is possible to define a 
       hidden  command  and  an  exposed command by the same name 
       within one interpreter.                                    

       Hidden commands in a slave interpreter can be  invoked  in 
       the  body  of procedures called in the master during alias 
       invocation. For example, an alias for source could be cre-
       ated  in  a  slave  interpreter. When it is invoked in the 
       slave interpreter, a procedure is  called  in  the  master 
       interpreter to check that the operation is allowable (e.g. 
       it asks to source a file that  the  slave  interpreter  is 
       allowed to access). The procedure then it invokes the hid-
       den source command in the slave  interpreter  to  actually 
       source in the contents of the file. Note that two commands 
       named source exist in the slave  interpreter:  the  alias, 
       and the hidden command.                                    

       Because  a  master interpreter may invoke a hidden command 
       as part of handling an alias invocation, great  care  must 
       be  taken  to  avoid  evaluating  any  arguments passed in 
       through the alias invocation.  Otherwise, malicious  slave 
       interpreters  could  cause a trusted master interpreter to 
       execute dangerous commands on their behalf. See  the  sec-
       tion on ALIAS INVOCATION for a more complete discussion of 
       this topic.  To help avoid this problem, no  substitutions 
       or  evaluations are applied to arguments of interp invoke-
       hidden.                                                    

       Safe interpreters are not allowed to  invoke  hidden  com-
       mands in themselves or in their descendants. This prevents 
       safe slaves from gaining access to hidden functionality in 
       themselves or their descendants.                           

       The set of hidden commands in an interpreter can be manip-
       ulated by a trusted interpreter using  interp  expose  and 
       interp hide. The interp expose command moves a hidden com-
       mand to the set of exposed  commands  in  the  interpreter 
       identified  by  path,  potentially renaming the command in 
       the process. If an exposed command by  the  targeted  name 
       already  exists,  the  operation  fails. Similarly, interp 
       hide moves an exposed command to the set  of  hidden  com-
       mands  in  that  interpreter.  Safe  interpreters  are not 
       allowed to move commands between the  set  of  hidden  and 
       exposed  commands,  in  either themselves or their descen-
       dants.                                                     

       Currently, the names of  hidden  commands  cannot  contain 
       namespace  qualifiers, and you must first rename a command 
       in a namespace to the global namespace before you can hide 
       it.  Commands to be hidden by interp hide are looked up in 
       the global namespace even if the current namespace is  not 
       the global one. This prevents slaves from fooling a master 
       interpreter into hiding the wrong command, by  making  the 
       current namespace be different from the global one.

CREDITS
       This  mechanism  is based on the Safe-Tcl prototype imple-
       mented by Nathaniel Borenstein and Marshall Rose.


KEYWORDS
       alias, master interpreter, safe interpreter, slave  inter-
       preter


_________________________________________________________________

NAME
       join - Create a string by joining together list elements

SYNOPSIS
       join list ?joinString?
_________________________________________________________________


DESCRIPTION
       The  list argument must be a valid Tcl list.  This command
       returns the string formed by joining all of  the  elements
       of  list together with joinString separating each adjacent
       pair of elements.  The joinString argument defaults  to  a
       space character.


KEYWORDS
       element, join, list, separator


_________________________________________________________________

NAME
       lappend - Append list elements onto a variable

SYNOPSIS
       lappend varName ?value value value ...?
_________________________________________________________________


DESCRIPTION
       This  command  treats  the  variable given by varName as a
       list and appends each of the value arguments to that  list
       as  a  separate element, with spaces between elements.  If
       varName doesn't exist, it is created as a list  with  ele-
       ments given by the value arguments.  Lappend is similar to
       append except that the values are appended  as  list  ele-
       ments rather than raw text.  This command provides a rela-
       tively efficient way to build up large lists.   For  exam-
       ple,  ``lappend a $b'' is much more efficient than ``set a
       [concat $a [list $b]]'' when $a is long.


       lsort(n), lrange(n)


KEYWORDS
       append, element, list, variable


_________________________________________________________________

NAME
       lindex - Retrieve an element from a list

SYNOPSIS
       lindex list ?index...?
_________________________________________________________________

DESCRIPTION
       The  lindex  command  accepts  a parameter, list, which it 
       treats as a Tcl list. It also accepts zero or more indices 
       into  the  list.  The indices may be presented either con-
       secutively on the command line, or grouped in a  Tcl  list 
       and presented as a single argument.                        

       If no indices are presented, the command takes the form:   
              lindex list                                         
       or                                                         
              lindex list {}                                      
       In  this  case,  the  return value of lindex is simply the 
       value of the list parameter.                               

       When presented with a single  index,  the  lindex  command 
       treats list as a Tcl list and returns the index'th element
       from it (0 refers to the first element of the  list).   In
       extracting  the  element,  lindex  observes the same rules
       concerning braces and quotes and backslashes  as  the  Tcl
       command  interpreter;  however,  variable substitution and
       command substitution do not occur.  If index  is  negative
       or  greater  than  or  equal  to the number of elements in
       value, then an empty string is returned.  If index has the
       value  end, it refers to the last element in the list, and
       end-integer refers to the last element in the  list  minus
       the specified integer offset.

       If  additional  index  arguments  are  supplied, then each 
       argument is used in turn to select  an  element  from  the 
       previous indexing operation, allowing the script to select 
       elements from sublists.  The command,                      
              lindex $a 1 2 3                                     
       or                                                         
              lindex $a {1 2 3}                                   
       is synonymous with                                         
              lindex [lindex [lindex $a 1] 2] 3                   

EXAMPLES                                                          
              lindex {a b c}  => a b c                            
              lindex {a b c} {} => a b c                          
              lindex {a b c} 0 => a                               
              lindex {a b c} 2 => c                               
              lindex {a b c} end => c                             
              lindex {a b c} end-1 => b                           
              lindex {{a b c} {d e f} {g h i}} 2 1 => h           


              lindex {{a b c} {d e f} {g h i}} {2 1} => h         
              lindex {{{a b} {c d}} {{e f} {g h}}} 1 1 0 => g     
              lindex {{{a b} {c d}} {{e f} {g h}}} {1 1 0} => g   


       lset(n), lsort(n), lrange(n), lreplace(n)


KEYWORDS
       element, index, list


_________________________________________________________________

NAME
       linsert - Insert elements into a list

SYNOPSIS
       linsert list index element ?element element ...?
_________________________________________________________________


DESCRIPTION
       This  command  produces  a new list from list by inserting
       all of the element arguments just before the indexth  ele-
       ment  of  list.  Each element argument will become a sepa-
       rate element of the new list.  If index is  less  than  or
       equal  to  zero, then the new elements are inserted at the
       beginning of the list.  If index has the value end, or  if
       it  is  greater than or equal to the number of elements in
       the list, then the new elements are appended to the  list.
       end-integer  refers  to the last element in the list minus
       the specified integer offset.


KEYWORDS
       element, insert, list


_________________________________________________________________

NAME
       list - Create a list

SYNOPSIS
       list ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       This  command returns a list comprised of all the args, or
       an empty string if no  args  are  specified.   Braces  and
       backslashes  get  added  as  necessary, so that the lindex
       command may be used on the result to re-extract the origi-
       nal  arguments,  and also so that eval may be used to exe-
       cute the resulting list, with  arg1  comprising  the  com-
       mand's  name  and the other args comprising its arguments.
       List produces  slightly  different  results  than  concat:
       concat  removes  one  level of grouping before forming the
       list, while list works directly from  the  original  argu-
       ments.  For example, the command
              list a b {c d e} {f {g h}}
       will return
              a b {c d e} {f {g h}}
       while concat with the same arguments will return
              a b c d e f {g h}


       lset(n), lsort(n), lrange(n), lreplace(n)


KEYWORDS
       element, list


_________________________________________________________________

NAME
       llength - Count the number of elements in a list

SYNOPSIS
       llength list
_________________________________________________________________


DESCRIPTION
       Treats  list as a list and returns a decimal string giving
       the number of elements in it.


KEYWORDS
       element, list, length


_________________________________________________________________

NAME
       load - Load machine code and initialize new commands.

SYNOPSIS
       load fileName
       load fileName packageName
       load fileName packageName interp
_________________________________________________________________


DESCRIPTION
       This command loads binary code from a file into the appli-
       cation's address space and calls an initialization  proce-
       dure in the package to incorporate it into an interpreter.
       fileName is the name of the file containing the code;  its
       exact  form  varies from system to system but on most sys-
       tems it is a shared library, such  as  a  .so  file  under
       Solaris  or  a DLL under Windows.  packageName is the name
       of the package, and is used to compute the name of an ini-
       tialization  procedure.   interp  is  the path name of the
       interpreter into which to load the package (see the interp
       manual  entry  for  details);  if  interp  is  omitted, it
       defaults to the interpreter in which the load command  was
       invoked.

       Once  the  file  has  been  loaded  into the application's
       address space, one of two initialization  procedures  will
       be  invoked in the new code.  Typically the initialization
       procedure will add new commands to a Tcl interpreter.  The
       name  of  the  initialization  procedure  is determined by
       packageName and whether or not the target interpreter is a
       safe  one.   For  normal interpreters the name of the ini-
       tialization procedure will have the form  pkg_Init,  where
       pkg  is the same as packageName except that the first let-
       ter is converted to upper case and all other  letters  are
       converted  to  lower case.  For example, if packageName is
       foo or FOo, the initialization procedure's  name  will  be
       Foo_Init.

       If  the target interpreter is a safe interpreter, then the
       name of the initialization procedure will be  pkg_SafeInit
       instead  of pkg_Init.  The pkg_SafeInit function should be
       written carefully, so that it initializes the safe  inter-
       preter  only  with  partial  functionality provided by the
       package that is safe for use by untrusted code.  For  more
       information on Safe-Tcl, see the safe manual entry.

       The initialization procedure must match the following pro-
       totype:
              typedef int Tcl_PackageInitProc(Tcl_Interp *interp);
       The interp argument identifies the  interpreter  in  which
       the package is to be loaded.  The initialization procedure
       must return TCL_OK or TCL_ERROR to indicate whether or not
       it  completed  successfully;   in the event of an error it
       should set the interpreter's result to point to  an  error
       message.   The  result  of  the  load  command will be the
       result returned by the initialization procedure.

       The actual loading of a file will only be  done  once  for
       each  fileName  in an application.  If a given fileName is
       loaded into multiple interpreters,  then  the  first  load
       will  load the code and call the initialization procedure;
       subsequent loads will call  the  initialization  procedure
       without  loading  the  code  again.  It is not possible to
       unload or reload a package.

       The load command also supports packages  that  are  stati-
       cally  linked with the application, if those packages have
       been registered by calling  the  Tcl_StaticPackage  proce-
       dure.   If  fileName  is an empty string, then packageName
       must be specified.

       If packageName is omitted or specified as an empty string,
       Tcl  tries  to guess the name of the package.  This may be
       done differently  on  different  platforms.   The  default
       guess,  which  is  used on most UNIX platforms, is to take
       the last element of fileName, strip off  the  first  three
       characters  if  they are lib, and use any following alpha-
       betic and underline characters as the  module  name.   For
       example,  the  command  load  libxyz4.2.so uses the module
       name xyz and the command load bin/last.so {} uses the mod-
       ule name last.

       If  fileName  is an empty string, then packageName must be 
       specified.  The load command first searches for  a  stati-
       cally  loaded  package  (one  that  has been registered by 
       calling the Tcl_StaticPackage procedure) by that name;  if 
       one  is  found,  it  is used.  Otherwise, the load command 
       searches for a dynamically loaded package  by  that  name, 
       and  uses  it  if it is found.  If several different files 
       have been loaded with different versions of  the  package, 
       Tcl picks the file that was loaded first.


PORTABILITY ISSUES
       Windows
              When  a  load fails with "library not found" error,
              it is also possible that a  dependent  library  was
              not  found.   To  see the dependent libraries, type
              ``dumpbin -imports <dllname>'' in a DOS console  to
              see  what  the library must import.  When loading a
              DLL in the current directory, Windows  will  ignore
              ``./'' as a path specifier and use a search heuris-
              tic to find the DLL instead.  To avoid  this,  load
              the DLL with
                  load [file join [pwd] mylib.DLL]


BUGS
       If the same file is loaded by different fileNames, it will
       be loaded into the process's address space multiple times.
       The  behavior  of  this varies from system to system (some
       systems may detect the redundant loads, others may not).


KEYWORDS
       binary code, loading, safe interpreter, shared library


_________________________________________________________________

NAME
       lrange - Return one or more adjacent elements from a list

SYNOPSIS
       lrange list first last
_________________________________________________________________


DESCRIPTION
       List must be a valid Tcl list.  This command will return a
       new list consisting of elements first through last, inclu-
       sive.   First  or  last may be end (or any abbreviation of
       it) to refer to the last element of the list.  If first is
       less than zero, it is treated as if it were zero.  If last
       is greater than or equal to the number of elements in  the
       list,  then  it is treated as if it were end.  If first is
       greater than last then an empty string is returned.  Note:
       ``lrange  list  first  first'' does not always produce the
       same result as ``lindex list first''  (although  it  often
       does for simple fields that aren't enclosed in braces); it
       does, however, produce exactly the same results as  ``list
       [lindex list first]''


KEYWORDS
       element, list, range, sublist


_________________________________________________________________

NAME
       lreplace - Replace elements in a list with new elements

SYNOPSIS
       lreplace list first last ?element element ...?
_________________________________________________________________


DESCRIPTION
       lreplace  returns  a  new  list formed by replacing one or
       more elements of list with the element  arguments.   first
       and  last specify the first and last index of the range of
       elements to replace.  0 refers to the first element of the
       list,  and  end (or any abbreviation of it) may be used to
       refer to the last element of the list.  If list is  empty,
       then first and last are ignored.

       If  first  is less than zero, it is considered to refer to
       the first element of the list.  For non-empty  lists,  the
       element indicated by first must exist.

       If last is less than zero but greater than first, then any
       specified elements will be prepended to the list.  If last
       is  less  than first then no elements are deleted; the new
       elements are simply inserted before first.

       The element arguments specify zero or more  new  arguments
       to  be  added  to  the  list  in  place of those that were
       deleted.  Each element argument  will  become  a  separate
       element  of  the list.  If no element arguments are speci-
       fied, then the elements between first and last are  simply
       deleted.   If  list  is  empty,  any element arguments are
       added to the end of the list.



KEYWORDS
       element, list, replace


_________________________________________________________________

NAME
       lsearch - See if a list contains a particular element

SYNOPSIS
       lsearch ?options? list pattern
_________________________________________________________________


DESCRIPTION
       This  command  searches the elements of list to see if one
       of them matches pattern.  If so, the command  returns  the
       index  of  the  first matching element (unless the options 
       -all or -inline  are  specified.)   If  not,  the  command
       returns  -1.   The option arguments indicates how the ele-
       ments of the list are to be matched against pattern and it
       must have one of the following values:

       -all   Changes  the  result to be the list of all matching 
              indices (or all matching values if -inline is spec-
              ified as well.)

       -ascii The  list  elements  are  to  be  examined as ASCII
              strings.  This option is only meaningful when  used
              with -exact or -sorted.

       -decreasing
              The  list  elements are sorted in decreasing order.
              This option  is  only  meaningful  when  used  with
              -sorted.

       -dictionary
              The  list elements are to be compared using dictio-
              nary-style comparisons.  This option is only  mean-
              ingful when used with -exact or -sorted.

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

       -increasing
              The list elements are sorted in  increasing  order.
              This  option  is  only  meaningful  when  used with
              -sorted.

       -inline
              The matching value is returned instead of its index 
              (or  an empty string if no value matches.)  If -all 
              is also specified, then the result of  the  command 
              is the list of all values that matched.

       -integer
              The  list  elements are to be compared as integers.
              This option  is  only  meaningful  when  used  with
              -exact or -sorted.

       -not   This  negates the sense of the match, returning the 
              index of the first non-matching value in the  list.

       -real  The  list  elements are to be compared as floating-
              point values.  This option is only meaningful  when
              used with -exact or -sorted.

       -regexp
              Pattern  is  treated  as  a  regular expression and
              matched against each list element using  the  rules
              described in the re_syntax reference page.

       -sorted
              The  list  elements  are  in sorted order.  If this
              option is specified, lsearch will use a more  effi-
              cient  searching  algorithm  to search list.  If no
              other options are specified, list is assumed to  be
              sorted  in  increasing  order, and to contain ASCII
              strings.  This option cannot  be  used  with  -all,
              -glob, -not or -regexp.

       -start index
              The  list  is  searched starting at position index. 
              If index has the value end, it refers to  the  last 
              element  in the list, and end-integer refers to the 
              last element in the list minus the specified  inte-
              ger offset.

       If  option  is omitted then it defaults to -glob.  If more
       than one of -exact, -glob, -regexp, and -sorted is  speci-
       fied, whichever option is specified last takes precedence.
       If more than one  of  -ascii,  -dictionary,  -integer  and
       -real is specified, the option specified last takes prece-
       dence.  If more than one of -increasing and -decreasing is
       specified, the option specified last takes precedence.


EXAMPLES                                                          
              lsearch {a b c d e} c => 2                          
              lsearch -all {a b c a b c} c => 2 5                 
              lsearch -inline {a20 b35 c47} b* => b35             
              lsearch -inline -not {a20 b35 c47} b* => a20        
              lsearch -all -inline -not {a20 b35 c47} b* => a20 c47
              lsearch -all -not {a20 b35 c47} b* => 0 2           
              lsearch -start 3 {a b c a b c} c => 5               


KEYWORDS
       list, match, pattern, regular expression, search, string


_________________________________________________________________

NAME
       lset - Change an element in a list

SYNOPSIS
       lset list ?index...? newValue
_________________________________________________________________

DESCRIPTION
       The  lset  command  accepts  a  parameter,  list, which it
       interprets as the name of  a  variable  containing  a  Tcl
       list.  It also accepts zero or more indices into the list.
       The indices may be presented either consecutively  on  the
       command  line, or grouped in a Tcl list and presented as a
       single argument.  Finally, it accepts a new value  for  an
       element of list.

       If no indices are presented, the command takes the form:
              lset list newValue
       or
              lset list {} newValue
       In this case, newValue replaces the old value of the vari­
       able list.

       When presented with  a  single  index,  the  lset  command
       treats the content of the list variable as a Tcl list.  It
       addresses the index'th element in  it  (0  refers  to  the
       first  element  of the list).  When interpreting the list,
       lset observes the same rules concerning braces and  quotes
       and  backslashes  as the Tcl command interpreter; however,
       variable substitution  and  command  substitution  do  not
       occur.   The  command  constructs  a new list in which the
       designated element is replaced with  newValue.   This  new
       list  is  stored  in  the  variable  list, and is also the
       return value from the lset command.

       If index is negative or greater than or equal to the  num­
       ber of elements in $list, then an error occurs.

       If  index has the value end, it refers to the last element
       in the list, and end-integer refers to the last element in
       the list minus the specified integer offset.

       If  additional  index  arguments  are  supplied, then each
       argument is used in turn to address an  element  within  a
       sublist  designated  by  the  previous indexing operation,
       allowing the script to alter elements  in  sublists.   The
       command,
              lset a 1 2 newValue
       or
              lset a {1 2} newValue
       replaces element 2 of sublist 1 with newValue.

       The  integer  appearing  in  each  index  argument must be
       greater than or equal to zero.  The integer  appearing  in
       each  index argument must be strictly less than the length
       of the corresponding list.  In other words, the lset  com­
       mand  cannot  change  the  size of a list.  If an index is
       outside the permitted range, an error is reported.

EXAMPLES
       In each of these examples, the initial value of x is:
              set x [list [list a b c] [list d e f] [list g h i]]
                => {a b c} {d e f} {g h i}
       The indicated return value also becomes the new  value  of
       x.
              lset x {j k l} => j k l
              lset x {} {j k l} => j k l
              lset x 0 j => j {d e f} {g h i}
              lset x 2 j => {a b c} {d e f} j
              lset x end j => {a b c} {d e f} j
              lset x end-1 j => {a b c} j {d e f}
              lset x 2 1 j => {a b c} {d e f} {g j i}
              lset x {2 1} j => {a b c} {d e f} {g j i}
              lset x {2 3} j
       In the following examples, the initial value of x is:
              set x [list [list [list a b] [list c d]] \
                          [list [list e f] [list g h]]]
               => {{a b} {c d}} {{e f} {g h}}
       The  indicated  return value also becomes the new value of
       x.
              lset x 1 1 0 j => {{a b} {c d}} {{e f} {j h}}
              lset x {1 1 0} j => {{a b} {c d}} {{e f} {j h}}


KEYWORDS
       element, index, list, replace, set



_________________________________________________________________

NAME
       lsort - Sort the elements of a list

SYNOPSIS
       lsort ?options? list
_________________________________________________________________


DESCRIPTION
       This  command  sorts the elements of list, returning a new
       list in sorted order.  The  implementation  of  the  lsort
       command  uses  the  merge-sort algorithm which is a stable
       sort that has O(n log n) performance characteristics.

       By default ASCII sorting is used with the result  returned
       in  increasing  order.   However,  any  of  the  following
       options may be specified before list to control the  sort-
       ing process (unique abbreviations are accepted):

       -ascii              Use  string comparison with ASCII col-
                           lation order.  This is the default.

       -dictionary         Use dictionary-style comparison.  This
                           is  the same as -ascii except (a) case
                           is ignored except as a tie-breaker and
                           (b)  if  two  strings contain embedded
                           numbers, the numbers compare as  inte-
                           gers, not characters.  For example, in
                           -dictionary mode, bigBoy sorts between
                           bigbang  and  bigboy,  and  x10y sorts
                           between x9y and x11y.

       -integer            Convert list elements to integers  and
                           use integer comparison.

       -real               Convert  list  elements  to  floating-
                           point values and use floating compari-
                           son.

       -command command    Use  command  as a comparison command.
                           To compare two  elements,  evaluate  a
                           Tcl  script consisting of command with
                           the two  elements  appended  as  addi-
                           tional  arguments.   The script should
                           return an integer less than, equal to,
                           or greater than zero if the first ele-
                           ment is to be  considered  less  than,
                           equal  to, or greater than the second,
                           respectively.

       -increasing         Sort  the  list  in  increasing  order
                           (``smallest''  items  first).  This is
                           the default.

       -decreasing         Sort  the  list  in  decreasing  order
                           (``largest'' items first).

       -index index        If  this  option is specified, each of
                           the elements of list must itself be  a
                           proper  Tcl sublist.  Instead of sort-
                           ing based  on  whole  sublists,  lsort
                           will extract the index'th element from
                           each sublist and  sort  based  on  the
                           given  element.   The  keyword  end is
                           allowed for the index to sort  on  the
                           last  sublist  element,  and end-index 
                           sorts on a sublist element offset from 
                           the end.  For example,
                                  lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
                           returns  {Second 18} {First 24} {Third
                           30}, and                               
                                  lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
                           returns {c 4 5 6 d h} {a 1 e i} {b 2 3 
                           f  g}.  This option is much more effi-
                           cient than using -command  to  achieve
                           the same effect.

       -unique             If this option is specified, then only
                           the last  set  of  duplicate  elements
                           found  in  the  list will be retained.
                           Note that  duplicates  are  determined
                           relative to the comparison used in the
                           sort.  Thus if -index 0 is used, {1 a}
                           and  {1  b} would be considered dupli-
                           cates and only the second element,  {1
                           b}, would be retained.


NOTES
       The  options to lsort only control what sort of comparison
       is used, and do not necessarily constrain what the  values
       themselves actually are.  This distinction is only notice-
       able when the list to be sorted has fewer  than  two  ele-
       ments.

       The  lsort command is reentrant, meaning it is safe to use
       as part of the implementation of a  command  used  in  the
       -command option.


EXAMPLES
       Sorting a list using ASCII sorting:
              % lsort {a10 B2 b1 a1 a2}
              B2 a1 a10 a2 b1


       Sorting a list using Dictionary sorting:
              % lsort -dictionary {a10 B2 b1 a1 a2}
              a1 a2 a10 b1 B2


       Sorting lists of integers:
              % lsort -integer {5 3 1 2 11 4}
              1 2 3 4 5 11
              % lsort -integer {1 2 0x5 7 0 4 -1}
              -1 0 1 2 4 0x5 7


       Sorting lists of floating-point numbers:
              % lsort -real {5 3 1 2 11 4}
              1 2 3 4 5 11
              % lsort -real {.5 0.07e1 0.4 6e-1}
              0.4 .5 6e-1 0.07e1


       Sorting using indices:
              % # Note the space character before the c
              % lsort {{a 5} { c 3} {b 4} {e 1} {d 2}}
              { c 3} {a 5} {b 4} {d 2} {e 1}
              % lsort -index 0 {{a 5} { c 3} {b 4} {e 1} {d 2}}
              {a 5} {b 4} { c 3} {d 2} {e 1}
              % lsort -index 1 {{a 5} { c 3} {b 4} {e 1} {d 2}}
              {e 1} {d 2} { c 3} {b 4} {a 5}


       Stripping duplicate values using sorting:
              % lsort -unique {a b c a b c a b c}
              a b c


       More complex sorting using a comparison function:
              % proc compare {a b} {
                  set a0 [lindex $a 0]
                  set b0 [lindex $b 0]
                  if {$a0 < $b0} {
                      return -1
                  } elseif {$a0 > $b0} {
                      return 1
                  }
                  return [string compare [lindex $a 1] [lindex $b 1]]
              }
              % lsort -command compare \
                      {{3 apple} {0x2 carrot} {1 dingo} {2 banana}}
              {1 dingo} {2 banana} {0x2 carrot} {3 apple}


       lsearch(n), lset(n), lrange(n), lreplace(n)


KEYWORDS
       element, list, order, sort


_________________________________________________________________

NAME
       msgcat - Tcl message catalog

SYNOPSIS
       package require Tcl 8.2

       package require msgcat 1.3

       ::msgcat::mc src-string ?arg arg ...?

       ::msgcat::mcmax ?src-string src-string ...?

       ::msgcat::mclocale ?newLocale?

       ::msgcat::mcpreferences

       ::msgcat::mcload dirname

       ::msgcat::mcset locale src-string ?translate-string?

       ::msgcat::mcmset locale src-trans-list

       ::msgcat::mcunknown locale src-string
_________________________________________________________________


DESCRIPTION
       The msgcat package provides a set of functions that can be
       used  to  manage  multi-lingual  user  interfaces.    Text
       strings  are  defined  in  a  ``message catalog'' which is
       independent from the application, and which can be  edited
       or  localized  without  modifying  the  application source
       code.  New languages or locales are provided by  adding  a
       new file to the message catalog.

       Use  of the message catalog is optional by any application
       or package, but is encouraged if the application or  pack-
       age wishes to be enabled for multi-lingual applications.


COMMANDS
       ::msgcat::mc src-string ?arg arg ...?
              Returns  a  translation  of src-string according to
              the user's current locale.  If additional arguments
              past  src-string  are  given, the format command is
              used to substitute the additional arguments in  the
              translation of src-string.

              ::msgcat::mc  will  search  the messages defined in
              the current namespace for  a  translation  of  src-
              string;  if  none  is  found, it will search in the
              parent of the current namespace, and so on until it
              reaches  the  global  namespace.  If no translation
              string exists, ::msgcat::mcunknown  is  called  and
              the  string  returned  from  ::msgcat::mcunknown is
              returned.

       ::msgcat::mc is the main  function  used  to  localize  an
       application.  Instead of using an English string directly,
       an application can pass the English string through  ::msg-
       cat::mc  and use the result.  If an application is written
       for a single language in this fashion, then it is easy  to
       add  support  for  additional  languages  later  simply by
       defining new message catalog entries.

       ::msgcat::mcmax ?src-string src-string ...?
              Given  several  source   strings,   ::msgcat::mcmax
              returns   the  length  of  the  longest  translated
              string.  This is useful  when  designing  localized
              GUIs, which may require that all buttons, for exam-
              ple, be a fixed width (which will be the  width  of
              the widest button).

       ::msgcat::mclocale ?newLocale?
              This  function  sets  the  locale to newLocale.  If
              newLocale  is  omitted,  the  current   locale   is
              returned,  otherwise  the  current locale is set to
              newLocale.  msgcat stores and compares  the  locale
              in  a  case-insensitive manner, and returns locales
              in lowercase.  The initial locale is determined  by
              the  locale  specified  in  the user's environment.
              See LOCALE SPECIFICATION below for a description of
              the locale string format.

       ::msgcat::mcpreferences
              Returns an ordered list of the locales preferred by
              the user, based on the user's  language  specifica-
              tion.   The  list  is ordered from most specific to
              least preference.  The list  is  derived  from  the
              current  locale  set in msgcat by msgcat::mclocale,
              and cannot be set independently.  For  example,  if
              the   current  locale  is  en_US_funky,  then  msg-
              cat::mcpreferences returns {en_US_funky en_US  en}.

       ::msgcat::mcload dirname
              Searches  the  specified  directory  for files that
              match  the  language  specifications  returned   by
              ::msgcat::mcpreferences  (note  that  these are all
              lowercase),  extended   by   the   file   extension
              ``.msg''.   Each  matching  file  is read in order,
              assuming a UTF-8 encoding.  The file  contents  are
              then  evaluated  as  a Tcl script.  This means that
              non-Latin characters may be present in the  message
              file  either  directly in their UTF-8 encoded form,
              or by use of the backslash-u quoting recognized  by
              Tcl  evaluation.  The number of message files which
              matched  the  specification  and  were  loaded   is
              returned.

       ::msgcat::mcset locale src-string ?translate-string?
              Sets  the  translation for src-string to translate-
              string in the  specified  locale  and  the  current
              namespace.   If  translate-string is not specified,
              src-string is used for both.  The function  returns
              translate-string.

       ::msgcat::mcmset locale src-trans-list
              Sets the translation for multiple source strings in
              src-trans-list in the specified locale and the cur-
              rent  namespace.   src-trans-list must have an even
              number of elements and is in the  form  {src-string
              translate-string ?src-string translate-string ...?}
              msgcat::mcmset can  be  significantly  faster  than
              multiple invocations of msgcat::mcset. The function
              returns the number of translations set.

       ::msgcat::mcunknown locale src-string
              This routine is called by ::msgcat::mc in the  case
              when a translation for src-string is not defined in
              the current  locale.   The  default  action  is  to
              return src-string.  This procedure can be redefined
              by the application, for example to log  error  mes-
              sages for each unknown string.  The ::msgcat::mcun-
              known procedure is invoked at the same  stack  con-
              text as the call to ::msgcat::mc.  The return value
              of ::msgcat::mcunknown is used as the return  value
              for the call to ::msgcat::mc.


LOCALE SPECIFICATION
       The  locale  is  specified  to  msgcat  by a locale string
       passed to ::msgcat::mclocale.  The locale string  consists
       of  a  language  code,  an  optional  country code, and an
       optional system-specific code, each  separated  by  ``_''.
       The  country and language codes are specified in standards
       ISO-639 and ISO-3166.   For  example,  the  locale  ``en''
       specifies English and ``en_US'' specifies U.S. English.

       When  the  msgcat  package  is first loaded, the locale is
       initialized according  to  the  user's  environment.   The
       variables env(LC_ALL), env(LC_MESSAGES), and env(LANG) are
       examined in order.  The first of them to have a  non-empty
       value  is used to determine the initial locale.  The value
       is parsed according to the XPG4 pattern
              language[_country][.codeset][@modifier]
       to extract its parts.  The initial locale is then  set  by
       calling msgcat::mclocale with the argument
              language[_country][_modifier]
       On Windows, if none of those environment variables is set,
       msgcat will attempt to extract locale information from the
       registry.   If  all  these attempts to discover an initial
       locale from the user's environment fail,  msgcat  defaults
       to an initial locale of ``C''.

       When  a  locale is specified by the user, a ``best match''
       search is performed during string translation.  For  exam-
       ple,   if   a  user  specifies  en_GB_Funky,  the  locales
       ``en_GB_Funky'', ``en_GB'', and  ``en''  are  searched  in
       order until a matching translation string is found.  If no
       translation string is available, then ::msgcat::unknown is
       called.


NAMESPACES AND MESSAGE CATALOGS
       Strings  stored in the message catalog are stored relative
       to the namespace from which they were added.  This  allows
       multiple  packages to use the same strings without fear of
       collisions with other packages.  It also allows the source
       string  to  be  shorter  and  less  prone to typographical
       error.

       For example, executing the code
              mcset en hello "hello from ::"
              namespace eval foo {mcset en hello "hello from ::foo"}
              puts [mc hello]
              namespace eval foo {puts [mc hello]}
       will print
              hello from ::
              hello from ::foo

       When searching for a translation of a message, the message
       catalog  will search first the current namespace, then the
       parent of the current  namespace,  and  so  on  until  the
       global namespace is reached.  This allows child namespaces
       to "inherit" messages from their parent namespace.

       For example, executing (in the ``en'' locale) the code
              mcset en m1 ":: message1"
              mcset en m2 ":: message2"
              mcset en m3 ":: message3"
              namespace eval ::foo {
                  mcset en m2 "::foo message2"
                  mcset en m3 "::foo message3"
              }
              namespace eval ::foo::bar {
                  mcset en m3 "::foo::bar message3"
              }
              puts "[mc m1]; [mc m2]; [mc m3]"
              namespace eval ::foo {puts "[mc m1]; [mc m2]; [mc m3]"}
              namespace eval ::foo::bar {puts "[mc m1]; [mc m2]; [mc m3]"}
       will print
              :: message1; :: message2; :: message3
              :: message1; ::foo message2; ::foo message3
              :: message1; ::foo message2; ::foo::bar message3


LOCATION AND FORMAT OF MESSAGE FILES
       Message files can be located in any directory, subject  to
       the following conditions:

       [1]    All  message  files  for  a package are in the same
              directory.

       [2]    The message file name is a msgcat locale  specifier
              (all lowercase) followed by ``.msg''.  For example:
              es.msg    -- spanish
              en_gb.msg -- United Kingdom English

       [3]    The file contains a series of calls  to  mcset  and
              mcmset,  setting  the necessary translation strings
              for the language, likely enclosed  in  a  namespace
              eval  so  that  all  source strings are tied to the
              namespace of the  package.  For  example,  a  short
              es.msg might contain:
              namespace eval ::mypackage {
                  ::msgcat::mcset es "Free Beer!" "Cerveza Gracias!"
              }


RECOMMENDED MESSAGE SETUP FOR PACKAGES
       If  a  package  is  installed  into  a subdirectory of the
       tcl_pkgPath and loaded via package require, the  following
       procedure is recommended.

       [1]    During  package installation, create a subdirectory
              msgs under your package directory.

       [2]    Copy your *.msg files into that directory.

       [3]     Add the following command to your package initial-
              ization script:
              # load language files, stored in msgs subdirectory
              ::msgcat::mcload [file join [file dirname [info script]] msgs]


POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS
       It  is  possible that a message string used as an argument
       to format might  have  positionally  dependent  parameters
       that might need to be repositioned.  For example, it might
       be  syntactically  desirable  to  rearrange  the  sentence
       structure while translating.
              format "We produced %d units in location %s" $num $city
              format "In location %s we produced %d units" $city $num

       This can be handled by using the positional parameters:
              format "We produced %1\$d units in location %2\$s" $num $city
              format "In location %2\$s we produced %1\$d units" $num $city

       Similarly,  positional parameters can be used with scan to
       extract values from internationalized strings.


CREDITS
       The message catalog code was developed by Mark Harrison.


KEYWORDS
       internationalization, i18n, localization,  l10n,  message,
       text, translation


_________________________________________________________________

NAME
       namespace  -  create  and manipulate contexts for commands
       and variables

SYNOPSIS
       namespace ?option? ?arg ...?
_________________________________________________________________


DESCRIPTION
       The namespace command lets you create, access, and destroy
       separate  contexts  for  commands  and variables.  See the
       section WHAT IS A NAMESPACE? below for a brief overview of
       namespaces.   The  legal  option's are listed below.  Note
       that you can abbreviate the option's.

       namespace children ?namespace? ?pattern?
              Returns a list of all child namespaces that  belong
              to  the  namespace  namespace.  If namespace is not
              specified, then the children are returned  for  the
              current  namespace.   This  command  returns fully-
              qualified names,  which  start  with  ::.   If  the
              optional   pattern  is  given,  then  this  command
              returns only the names that  match  the  glob-style
              pattern.   The actual pattern used is determined as
              follows: a pattern that  starts  with  ::  is  used
              directly, otherwise the namespace namespace (or the
              fully-qualified name of the current  namespace)  is
              prepended onto the the pattern.

       namespace code script
              Captures  the  current  namespace context for later
              execution of the script script.  It returns  a  new
              script in which script has been wrapped in a names-
              pace code command.  The new script has  two  impor-
              tant properties.  First, it can be evaluated in any
              namespace and will cause script to be evaluated  in
              the  current namespace (the one where the namespace
              code  command  was  invoked).   Second,  additional
              arguments  can  be appended to the resulting script
              and they will be passed  to  script  as  additional
              arguments.   For  example,  suppose the command set
              script [namespace code {foo  bar}]  is  invoked  in
              namespace  ::a::b.   Then eval "$script x y" can be
              executed in any namespace (assuming  the  value  of
              script  has  been passed in properly) and will have
              the same effect as  the  command  ::namespace  eval
              ::a::b  {foo  bar  x  y}.   This  command is needed
              because extensions like Tk normally  execute  call-
              back  scripts  in  the  global namespace.  A scoped
              command captures a command together with its names-
              pace context in a way that allows it to be executed
              properly later.  See the section SCOPED VALUES  for
              some  examples  of how this is used to create call-
              back scripts.

       namespace current
              Returns the fully-qualified name  for  the  current
              namespace.  The actual name of the global namespace
              is ``'' (i.e., an empty string), but  this  command
              returns  ::  for  the  global namespace as a conve-
              nience to programmers.

       namespace delete ?namespace namespace ...?
              Each namespace namespace is deleted and  all  vari-
              ables,  procedures,  and child namespaces contained
              in the namespace are deleted.  If  a  procedure  is
              currently   executing  inside  the  namespace,  the
              namespace will be kept alive  until  the  procedure
              returns;  however,  the namespace is marked to pre-
              vent other code from looking it up by name.   If  a
              namespace  doesn't  exist,  this command returns an
              error.  If no namespace names are given, this  com-
              mand does nothing.

       namespace eval namespace arg ?arg ...?
              Activates  a  namespace called namespace and evalu-
              ates some code in that context.  If  the  namespace
              does  not  already  exist,  it is created.  If more
              than one arg argument is specified,  the  arguments
              are concatenated together with a space between each
              one in the same fashion as the  eval  command,  and
              the result is evaluated.

              If  namespace  has leading namespace qualifiers and
              any leading namespaces do not exist, they are auto-
              matically created.

       namespace exists namespace
              Returns  1 if namespace is a valid namespace in the
              current context, returns 0 otherwise.

       namespace export ?-clear? ?pattern pattern ...?
              Specifies which commands are exported from a names-
              pace.   The exported commands are those that can be
              later  imported  into  another  namespace  using  a
              namespace import command.  Both commands defined in
              a namespace and commands the namespace  has  previ-
              ously imported can be exported by a namespace.  The
              commands do not have to be defined at the time  the
              namespace export command is executed.  Each pattern
              may contain glob-style special characters,  but  it
              may not include any namespace qualifiers.  That is,
              the pattern can only specify commands in  the  cur-
              rent   (exporting)   namespace.   Each  pattern  is
              appended  onto  the  namespace's  list  of   export
              patterns.   If the -clear flag is given, the names-
              pace's export pattern list is reset to empty before
              any pattern arguments are appended.  If no patterns
              are given and the -clear  flag  isn't  given,  this
              command  returns  the  namespace's  current  export
              list.

       namespace forget ?pattern pattern ...?
              Removes previously imported commands from a  names-
              pace.   Each  pattern is a simple or qualified name
              such as x, foo::x  or  a::b::p*.   Qualified  names
              contain ::s and qualify a name with the name of one
              or more  namespaces.   Each  qualified  pattern  is
              qualified  with  the name of an exporting namespace
              and may have glob-style special characters  in  the
              command  name  at  the  end  of the qualified name.
              Glob characters may not appear in a namespace name.
              For  each  simple  pattern this command deletes the
              matching commands of  the  current  namespace  that
              were  imported  from  a  different  namespace.  For
              qualified patterns, this command  first  finds  the
              matching exported commands.  It then checks whether
              any of those commands were previously  imported  by
              the current namespace.  If so, this command deletes
              the corresponding imported  commands.   In  effect,
              this  un-does the action of a namespace import com-
              mand.

       namespace import ?-force? ?pattern pattern ...?
              Imports commands into a namespace.  Each pattern is
              a qualified name like foo::x or a::p*.  That is, it
              includes the name of an exporting namespace and may
              have  glob-style  special characters in the command
              name at the end of the qualified name.  Glob  char-
              acters may not appear in a namespace name.  All the
              commands that match a pattern string and which  are
              currently  exported  from their namespace are added
              to the current namespace.  This is done by creating
              a  new command in the current namespace that points
              to the exported command in its original  namespace;
              when the new imported command is called, it invokes
              the  exported  command.   This   command   normally
              returns  an  error if an imported command conflicts
              with an existing command.  However, if  the  -force
              option  is  given,  imported commands will silently
              replace existing commands.   The  namespace  import
              command  has  snapshot  semantics:  that  is,  only
              requested commands that are  currently  defined  in
              the  exporting  namespace  are  imported.  In other
              words, you can import only the commands that are in
              a  namespace  at the time when the namespace import
              command is executed.  If another command is defined
              and  exported  in  this namespace later on, it will
              not be imported.


       namespace inscope namespace arg ?arg ...?
              Executes a script in the context  of  a  particular
              namespace.  This command is not expected to be used
              directly by programmers; calls to it are  generated
              implicitly  when  applications  use  namespace code
              commands to create callback scripts that the appli-
              cations  then register with, e.g., Tk widgets.  The
              namespace inscope command is much like  the  names-
              pace eval command except that it has lappend seman-
              tics and the  namespace  must  already  exist.   It
              treats  the  first  argument as a list, and appends
              any arguments after  the  first  onto  the  end  as
              proper  list elements.  namespace inscope ::foo a x
              y z is equivalent to namespace eval ::foo [concat a
              [list  x  y z]] This lappend semantics is important
              because many callback  scripts  are  actually  pre-
              fixes.

       namespace origin command
              Returns  the  fully-qualified  name of the original
              command  to  which  the  imported  command  command
              refers.   When  a command is imported into a names-
              pace, a new command is created  in  that  namespace
              that  points to the actual command in the exporting
              namespace.   If  a  command  is  imported  into   a
              sequence  of  namespaces a, b,...,n where each suc-
              cessive namespace just imports the command from the
              previous namespace, this command returns the fully-
              qualified name of the original command in the first
              namespace,  a.   If  command  does  not refer to an
              imported command, the command's own fully-qualified
              name is returned.

       namespace parent ?namespace?
              Returns  the  fully-qualified  name  of  the parent
              namespace for namespace namespace.  If namespace is
              not specified, the fully-qualified name of the cur-
              rent namespace's parent is returned.

       namespace qualifiers string
              Returns  any  leading  namespace   qualifiers   for
              string.   Qualifiers  are namespace names separated
              by ::s.  For the string ::foo::bar::x, this command
              returns  ::foo::bar, and for :: it returns an empty
              string.  This command  is  the  complement  of  the
              namespace  tail  command.   Note  that  it does not
              check whether the namespace names are, in fact, the
              names of currently defined namespaces.

       namespace tail string
              Returns  the  simple name at the end of a qualified
              string.  Qualifiers are namespace  names  separated
              by ::s.  For the string ::foo::bar::x, this command
              returns x, and for :: it returns an  empty  string.
              This  command  is  the  complement of the namespace
              qualifiers command.  It does not check whether  the
              namespace  names  are,  in  fact, the names of cur-
              rently defined namespaces.

       namespace which ?-command? ?-variable? name
              Looks up name as either a command or  variable  and
              returns  its fully-qualified name.  For example, if
              name does not exist in the  current  namespace  but
              does  exist  in  the global namespace, this command
              returns a fully-qualified name in the global names-
              pace.   If  the command or variable does not exist,
              this command returns an empty string.  If the vari-
              able has been created but not defined, such as with
              the variable command or  through  a  trace  on  the
              variable, this command will return the fully-quali-
              fied name of the variable.  If no  flag  is  given,
              name is treated as a command name.  See the section
              NAME RESOLUTION below for  an  explanation  of  the
              rules regarding name resolution.


WHAT IS A NAMESPACE?
       A namespace is a collection of commands and variables.  It
       encapsulates the commands and  variables  to  ensure  that
       they  won't  interfere  with the commands and variables of
       other namespaces.  Tcl has always had one such collection,
       which  we  refer  to  as the global namespace.  The global
       namespace holds all global variables  and  commands.   The
       namespace  eval  command  lets  you create new namespaces.
       For example,
              namespace eval Counter {
                  namespace export bump
                  variable num 0

                  proc bump {} {
                      variable num
                      incr num
                  }
              }
       creates a new namespace containing the  variable  num  and
       the  procedure  bump.   The commands and variables in this
       namespace are separate from other commands  and  variables
       in  the same program.  If there is a command named bump in
       the global namespace, for example, it  will  be  different
       from the command bump in the Counter namespace.

       Namespace  variables  resemble  global  variables  in Tcl.
       They exist outside of the procedures in  a  namespace  but
       can  be  accessed in a procedure via the variable command,
       as shown in the example above.

       Namespaces are dynamic.  You can add and  delete  commands
       and  variables  at  any  time,  so  you  can  build up the
       contents of a namespace over time using a series of names-
       pace  eval commands.  For example, the following series of
       commands has the same effect as the  namespace  definition
       shown above:
              namespace eval Counter {
                  variable num 0
                  proc bump {} {
                      variable num
                      return [incr num]
                  }
              }
              namespace eval Counter {
                  proc test {args} {
                      return $args
                  }
              }
              namespace eval Counter {
                  rename test ""
              }
       Note  that  the  test  procedure  is  added to the Counter
       namespace, and later removed via the rename command.

       Namespaces can have other namespaces within them, so  they
       nest  hierarchically.   A nested namespace is encapsulated
       inside its parent namespace and  can  not  interfere  with
       other namespaces.


QUALIFIED NAMES
       Each  namespace  has  a  textual  name  such as history or
       ::safe::interp.   Since  namespaces  may  nest,  qualified
       names  are used to refer to commands, variables, and child
       namespaces contained inside namespaces.   Qualified  names
       are  similar to the hierarchical path names for Unix files
       or Tk widgets, except that :: is  used  as  the  separator
       instead  of  /  or ..  The topmost or global namespace has
       the name ``'' (i.e., an empty string), although  ::  is  a
       synonym.   As  an example, the name ::safe::interp::create
       refers to the command create in the namespace interp  that
       is  a  child  of  of  namespace ::safe, which in turn is a
       child of the global namespace ::.

       If you want to access commands and variables from  another
       namespace,  you must use some extra syntax.  Names must be
       qualified by the namespace that contains them.   From  the
       global  namespace,  we might access the Counter procedures
       like this:
              Counter::bump 5
              Counter::Reset
       We could access the current count like this:
              puts "count = $Counter::num"
       When one namespace contains another,  you  may  need  more
       than  one  qualifier  to  reach its elements.  If we had a
       namespace Foo that contained the  namespace  Counter,  you


       could  invoke its bump procedure from the global namespace
       like this:
              Foo::Counter::bump 3

       You can also use  qualified  names  when  you  create  and
       rename  commands.   For example, you could add a procedure
       to the Foo namespace like this:
              proc Foo::Test {args} {return $args}
       And you could move the same procedure to another namespace
       like this:
              rename Foo::Test Bar::Test

       There  are  a  few  remaining points about qualified names
       that we should  cover.   Namespaces  have  nonempty  names
       except for the global namespace.  :: is disallowed in sim-
       ple command, variable, and namespace  names  except  as  a
       namespace  separator.   Extra  :s  in a qualified name are
       ignored; that is, two or more :s are treated as  a  names-
       pace  separator.  A trailing :: in a qualified variable or
       command name refers to the variable or command  named  {}.
       However,  a  trailing  :: in a qualified namespace name is
       ignored.


NAME RESOLUTION
       In general, all Tcl commands that take variable  and  com-
       mand  names  support  qualified names.  This means you can
       give qualified  names  to  such  commands  as  set,  proc,
       rename,  and  interp alias.  If you provide a fully-quali-
       fied name that starts with a  ::,  there  is  no  question
       about what command, variable, or namespace you mean.  How-
       ever, if the name does not start with a :: (i.e., is rela-
       tive), Tcl follows a fixed rule for looking it up: Command
       and variable names are always resolved by looking first in
       the  current  namespace, and then in the global namespace.
       Namespace names, on the other hand, are always resolved by
       looking in only the current namespace.

       In the following example,
              set traceLevel 0
              namespace eval Debug {
                  printTrace $traceLevel
              }
       Tcl  looks  for traceLevel in the namespace Debug and then
       in the global namespace.  It looks up the  command  print-
       Trace  in  the same way.  If a variable or command name is
       not found in either context, the name  is  undefined.   To
       make  this  point absolutely clear, consider the following
       example:
              set traceLevel 0
              namespace eval Foo {
                  variable traceLevel 3

                  namespace eval Debug {


                      printTrace $traceLevel
                  }
              }
       Here Tcl looks  for  traceLevel  first  in  the  namespace
       Foo::Debug.   Since  it is not found there, Tcl then looks
       for  it   in   the   global   namespace.    The   variable
       Foo::traceLevel is completely ignored during the name res-
       olution process.

       You can use the namespace which command to  clear  up  any
       question about name resolution.  For example, the command:
              namespace eval Foo::Debug {namespace which -variable traceLevel}
       returns ::traceLevel.  On the other hand, the command,
              namespace eval Foo {namespace which -variable traceLevel}
       returns ::Foo::traceLevel.

       As mentioned above, namespace names are looked up  differ-
       ently than the names of variables and commands.  Namespace
       names are always resolved in the current namespace.   This
       means,  for  example,  that  a namespace eval command that
       creates a new namespace always creates a child of the cur-
       rent namespace unless the new namespace name begins with a
       ::.

       Tcl has no access control to limit  what  variables,  com-
       mands,  or namespaces you can reference.  If you provide a
       qualified name that resolves to an  element  by  the  name
       resolution rule above, you can access the element.

       You  can  access  a namespace variable from a procedure in
       the same namespace by using the  variable  command.   Much
       like  the global command, this creates a local link to the
       namespace variable.  If necessary,  it  also  creates  the
       variable  in  the  current  namespace  and initializes it.
       Note that the global command only creates links  to  vari-
       ables in the global namespace.  It is not necessary to use
       a variable command if you always refer  to  the  namespace
       variable using an appropriate qualified name.


IMPORTING COMMANDS
       Namespaces  are  often  used to represent libraries.  Some
       library commands are used so frequently that it is a  nui-
       sance to type their qualified names.  For example, suppose
       that all of the commands in a package like  BLT  are  con-
       tained  in  a namespace called Blt.  Then you might access
       these commands like this:
              Blt::graph .g -background red
              Blt::table . .g 0,0
       If you use the graph and table  commands  frequently,  you
       may want to access them without the Blt:: prefix.  You can
       do this by importing the commands into the current  names-
       pace, like this:
              namespace import Blt::*


       This  adds  all  exported  commands from the Blt namespace
       into the current namespace context, so you can write  code
       like this:
              graph .g -background red
              table . .g 0,0
       The  namespace import command only imports commands from a
       namespace that that namespace exported  with  a  namespace
       export command.

       Importing  every  command  from a namespace is generally a
       bad idea since you don't know what you will  get.   It  is
       better to import just the specific commands you need.  For
       example, the command
              namespace import Blt::graph Blt::table
       imports only the graph and table commands into the current
       context.

       If  you  try  to import a command that already exists, you
       will get an error.  This prevents you from  importing  the
       same  command  from two different packages.  But from time
       to time (perhaps when debugging),  you  may  want  to  get
       around  this  restriction.   You  may  want to reissue the
       namespace import command to pick up new commands that have
       appeared  in  a  namespace.  In that case, you can use the
       -force option, and  existing  commands  will  be  silently
       overwritten:
              namespace import -force Blt::graph Blt::table
       If  for  some  reason, you want to stop using the imported
       commands, you can remove them  with  an  namespace  forget
       command, like this:
              namespace forget Blt::*
       This  searches  the  current  namespace  for  any commands
       imported from Blt.  If it  finds  any,  it  removes  them.
       Otherwise,  it does nothing.  After this, the Blt commands
       must be accessed with the Blt:: prefix.

       When you delete a command  from  the  exporting  namespace
       like this:
              rename Blt::graph ""
       the  command  is automatically removed from all namespaces
       that import it.


EXPORTING COMMANDS
       You can export commands from a namespace like this:
              namespace eval Counter {
                  namespace export bump reset
                  variable Num 0
                  variable Max 100

                  proc bump {{by 1}} {
                      variable Num
                      incr Num $by
                      Check


                      return $Num
                  }
                  proc reset {} {
                      variable Num
                      set Num 0
                  }
                  proc Check {} {
                      variable Num
                      variable Max
                      if {$Num > $Max} {
                          error "too high!"
                      }
                  }
              }
       The procedures bump and reset are exported,  so  they  are
       included  when you import from the Counter namespace, like
       this:
              namespace import Counter::*
       However, the Check procedure is not  exported,  so  it  is
       ignored by the import operation.

       The  namespace  import  command only imports commands that
       were declared as exported by their namespace.  The  names-
       pace   export  command  specifies  what  commands  may  be
       imported by other namespaces.  If a namespace import  com-
       mand specifies a command that is not exported, the command
       is not imported.


KEYWORDS
       exported, internal, variable


_________________________________________________________________

NAME
       open - Open a file-based or command pipeline channel

SYNOPSIS
       open fileName
       open fileName access
       open fileName access permissions
_________________________________________________________________


DESCRIPTION
       This  command  opens  a  file,  serial  port,  or  command
       pipeline and returns a channel identifier that may be used
       in  future  invocations  of  commands like read, puts, and
       close.  If the first character of fileName is not  |  then
       the  command  opens a file: fileName gives the name of the
       file to open, and  it  must  conform  to  the  conventions
       described in the filename manual entry.

       The  access  argument,  if  present,  indicates the way in
       which the file (or command pipeline) is  to  be  accessed.
       In  the  first  form  access may have any of the following
       values:

       r              Open the file for reading  only;  the  file
                      must  already  exist.  This  is the default
                      value if access is not specified.

       r+             Open the file for both reading and writing;
                      the file must already exist.

       w              Open  the  file for writing only.  Truncate
                      it if it exists.  If it doesn't exist, cre-
                      ate a new file.

       w+             Open  the  file  for  reading  and writing.
                      Truncate it if it exists.   If  it  doesn't
                      exist, create a new file.

       a              Open  the  file  for  writing only.  If the
                      file doesn't  exist,  create  a  new  empty
                      file.   Set the initial access position  to
                      the end of the file.

       a+             Open the file for reading and writing.   If
                      the  file doesn't exist, create a new empty
                      file.  Set the initial access position   to
                      the end of the file.

       In  the  second  form, access consists of a list of any of
       the following flags, all of which have the standard  POSIX
       meanings.   One of the flags must be either RDONLY, WRONLY
       or RDWR.

       RDONLY         Open the file for reading only.

       WRONLY         Open the file for writing only.

       RDWR           Open the file for both reading and writing.

       APPEND         Set the file pointer to the end of the file
                      prior to each write.

       CREAT          Create the file if it doesn't already exist
                      (without  this  flag it is an error for the
                      file not to exist).

       EXCL           If CREAT is also  specified,  an  error  is
                      returned if the file already exists.

       NOCTTY         If the file is a terminal device, this flag
                      prevents the file from  becoming  the  con-
                      trolling terminal of the process.

       NONBLOCK       Prevents  the  process  from blocking while
                      opening the file, and  possibly  in  subse-
                      quent  I/O  operations.  The exact behavior
                      of this flag is system-  and  device-depen-
                      dent;  its use is discouraged (it is better
                      to use the fconfigure command to put a file
                      in nonblocking mode).  For details refer to
                      your system documentation on the open  sys-
                      tem call's O_NONBLOCK flag.

       TRUNC          If  the file exists it is truncated to zero
                      length.

       If a new file is created as part of  opening  it,  permis-
       sions  (an integer) is used to set the permissions for the
       new file in conjunction with the process's file mode  cre-
       ation mask.  Permissions defaults to 0666.

       Note that if you are going to be reading or writing binary
       data from the channel created by this command, you  should
       use  the  fconfigure  command  to  change the -translation
       option of the channel to binary  before  transferring  any
       binary  data.   This is in contrast to the ``b'' character
       passed as part of the equivalent of the  access  parameter
       to some versions of the C library fopen() function.


COMMAND PIPELINES
       If  the  first  character  of  fileName  is ``|'' then the
       remaining characters of fileName are treated as a list  of
       arguments  that  describe a command pipeline to invoke, in
       the same style as the arguments for exec.  In  this  case,
       the  channel  identifier  returned  by open may be used to
       write to the command's input pipe or read from its  output
       pipe,  depending  on  the  value of access.  If write-only
       access is used (e.g. access is w),  then  standard  output
       for  the pipeline is directed to the current standard out-
       put unless overridden by the command.  If read-only access
       is  used  (e.g.  access  is  r),  standard  input  for the
       pipeline is taken from the current standard  input  unless
       overridden  by the command.  The id of the spawned process
       is accessible through the pid command, using  the  channel
       id returned by open as argument.


SERIAL COMMUNICATIONS                                             
       If  fileName  refers  to a serial port, then the specified 
       serial port is opened and initialized in a platform-depen-
       dent manner.  Acceptable values for the fileName to use to 
       open a serial port are described in the PORTABILITY ISSUES 
       section.                                                   

       The  fconfigure command can be used to query and set addi-
       tional configuration options specific to serial ports.


PORTABILITY ISSUES
       Windows (all versions)
              Valid values for fileName to open a serial port are
              of  the  form comX:, where X is a number, generally
              from 1 to 4.  This notation only works  for  serial
              ports  from  1  to 9, if the system happens to have
              more than four.  An attempt to open a  serial  port
              that  does not exist or has a number greater than 9
              will fail.  An alternate  form  of  opening  serial
              ports  is  to use the filename \\.\comX, where X is
              any number  that  corresponds  to  a  serial  port;
              please note that this method is considerably slower
              on Windows 95 and Windows 98.

       Windows NT
              When running Tcl interactively, there may  be  some
              strange  interactions  between the real console, if
              one is present, and a command  pipeline  that  uses
              standard input or output.  If a command pipeline is
              opened for reading, some of the  lines  entered  at
              the  console  will  be sent to the command pipeline
              and some will be sent to the Tcl evaluator.   If  a
              command  pipeline is opened for writing, keystrokes
              entered into the console are not visible until  the
              the  pipe  is closed.  This behavior occurs whether
              the command pipeline is executing 16-bit or  32-bit
              applications.   These  problems  only occur because
              both Tcl and the child  application  are  competing
              for  the  console at the same time.  If the command
              pipeline is started from a script, so that  Tcl  is
              not  accessing  the  console,  or  if  the  command
              pipeline does not use standard input or output, but
              is  redirected  from  or  to a file, then the above
              problems do not occur.

       Windows 95
              A command  pipeline  that  executes  a  16-bit  DOS
              application  cannot  be opened for both reading and
              writing, since 16-bit DOS applications that receive
              standard input from a pipe and send standard output
              to a pipe  run  synchronously.   Command  pipelines
              that  do  not  execute  16-bit DOS applications run
              asynchronously and can be opened for  both  reading
              and writing.

              When  running  Tcl interactively, there may be some
              strange interactions between the real  console,  if
              one  is  present,  and a command pipeline that uses
              standard input or output.  If a command pipeline is
              opened  for reading from a 32-bit application, some
              of the keystrokes entered at the  console  will  be
              sent  to the command pipeline and some will be sent
              to the Tcl evaluator.  If  a  command  pipeline  is
              opened for writing to a 32-bit application, no out-
              put is visible on the console until the pipe is
              closed.  These problems only occur because both Tcl
              and the child application  are  competing  for  the
              console  at the same time.  If the command pipeline
              is started from  a  script,  so  that  Tcl  is  not
              accessing  the  console, or if the command pipeline
              does not use standard input or output, but is redi-
              rected  from  or to a file, then the above problems
              do not occur.

              Whether or not Tcl is running interactively,  if  a
              command  pipeline  is  opened  for  reading  from a
              16-bit DOS application, the call to open  will  not
              return until end-of-file has been received from the
              command pipeline's standard output.  If  a  command
              pipeline  is  opened  for  writing  to a 16-bit DOS
              application, no data will be sent  to  the  command
              pipeline's  standard output until the pipe is actu-
              ally closed.  This problem  occurs  because  16-bit
              DOS   applications   are   run   synchronously,  as
              described above.

       Macintosh
              Opening a serial port is not currently  implemented
              under Macintosh.

              Opening  a  command pipeline is not supported under
              Macintosh, since applications do  not  support  the
              concept of standard input or output.


       Unix
              Valid values for fileName to open a serial port are
              generally of the form /dev/ttyX, where X is a or b,
              but  the  name  of  any  pseudo-file that maps to a
              serial port may be used.

              When running Tcl interactively, there may  be  some
              strange interactions between the console, if one is
              present, and a command pipeline that uses  standard
              input.   If  a command pipeline is opened for read-
              ing, some of the lines entered at the console  will
              be  sent  to  the command pipeline and some will be
              sent to  the  Tcl  evaluator.   This  problem  only
              occurs  because  both Tcl and the child application
              are competing for the console at the same time.  If
              the  command  pipeline is started from a script, so
              that Tcl is not accessing the console,  or  if  the
              command  pipeline  does not use standard input, but
              is redirected from a file, then the  above  problem
              does not occur.

       See the PORTABILITY ISSUES section of the exec command for
       additional information not specific to  command  pipelines
       about executing applications on the various platforms


       read(n), puts(n), exec(n), pid(n), fopen(3)


KEYWORDS
       access mode, append,  create,  file,  non-blocking,  open,
       permissions, pipeline, process, serial


_________________________________________________________________

NAME
       package  - Facilities for package loading and version con-
       trol

SYNOPSIS
       package forget ?package package ...?
       package ifneeded package version ?script?
       package names
       package present ?-exact? package ?version?
       package provide package ?version?
       package require ?-exact? package ?version?
       package unknown ?command?
       package vcompare version1 version2
       package versions package
       package vsatisfies version1 version2
_________________________________________________________________


DESCRIPTION
       This command keeps  a  simple  database  of  the  packages
       available  for  use  by the current interpreter and how to
       load them into the interpreter.  It supports multiple ver-
       sions of each package and arranges for the correct version
       of a package to be loaded based on what is needed  by  the
       application.   This  command also detects and reports ver-
       sion clashes.  Typically, only  the  package  require  and
       package   provide  commands  are  invoked  in  normal  Tcl
       scripts;  the other commands are used primarily by  system
       scripts that maintain the package database.

       The  behavior  of the package command is determined by its
       first argument.  The following forms are permitted:

       package forget ?package package ...?
              Removes all information about each specified  pack-
              age  from  this  interpreter, including information
              provided by both package ifneeded and package  pro-
              vide.

       package ifneeded package version ?script?
              This  command typically appears only in system con-
              figuration scripts to set up the package  database.
              It indicates that a particular version of a partic-
              ular package is available if needed, and  that  the
              package  can be added to the interpreter by execut-
              ing script.  The script is saved in a database  for
              use  by subsequent package require commands;  typi-
              cally, script sets up auto-loading for the commands
              in   the  package  (or  calls  load  and/or  source
              directly), then invokes package provide to indicate
              that the package is present.  There may be informa-
              tion in the database for several different versions
              of  a single package.  If the database already con-
              tains information for package and version, the  new
              script  replaces  the  existing one.  If the script
              argument is omitted, the current script for version
              version of package package is returned, or an empty
              string if no  package  ifneeded  command  has  been
              invoked for this package and version.

       package names
              Returns  a list of the names of all packages in the
              interpreter for which a version has  been  provided
              (via  package  provide)  or  for  which  a  package
              ifneeded script is available.  The  order  of  ele-
              ments in the list is arbitrary.

       package present ?-exact? package ?version?
              This  command  is  equivalent  to  package  require
              except that it does not try and load the package if
              it is not already loaded.

       package provide package ?version?
              This  command  is  invoked to indicate that version
              version of package package is now  present  in  the
              interpreter.   It is typically invoked once as part
              of an ifneeded script, and  again  by  the  package
              itself  when it is finally loaded.  An error occurs
              if a different version of package has been provided
              by a previous package provide command.  If the ver-
              sion argument is omitted, then the command  returns
              the  version  number that is currently provided, or
              an empty string if no package provide  command  has
              been invoked for package in this interpreter.

       package require ?-exact? package ?version?
              This  command is typically invoked by Tcl code that
              wishes to use a particular version of a  particular
              package.   The  arguments indicate which package is
              wanted, and the command  ensures  that  a  suitable
              version  of  the  package is loaded into the inter-
              preter.  If the command succeeds,  it  returns  the
              version number that is loaded;  otherwise it gener-
              ates an error.  If both the -exact switch  and  the
              version  argument are specified then only the given
              version is acceptable.  If -exact  is  omitted  but
              version is specified, then versions later than ver-
              sion are also acceptable as long as they  have  the
              same  major  version  number  as  version.  If both
              -exact and version are  omitted  then  any  version
              whatsoever  is acceptable.  If a version of package
              has already been provided (by invoking the  package
              provide command), then its version number must sat-
              isfy the criteria given by -exact and  version  and
              the  command  returns  immediately.  Otherwise, the
              command  searches  the  database   of   information
              provided  by  previous package ifneeded commands to
              see if an acceptable  version  of  the  package  is
              available.   If  so,  the  script  for  the highest
              acceptable  version  number  is  evaluated  in  the
              global  namespace; it must do whatever is necessary
              to load the package, including calling package pro-
              vide  for  the  package.   If  the package ifneeded
              database does not contain an acceptable version  of
              the  package and a package unknown command has been
              specified for the interpreter then that command  is
              evaluated  in  the  global namespace;  when it com-
              pletes, Tcl checks again to see if the  package  is
              now  provided  or  if  there  is a package ifneeded
              script for it.  If all of these steps fail to  pro-
              vide an acceptable version of the package, then the
              command returns an error.

       package unknown ?command?
              This command supplies a ``last resort'' command  to
              invoke  during  package require if no suitable ver-
              sion of a package  can  be  found  in  the  package
              ifneeded database.  If the command argument is sup-
              plied, it contains the first  part  of  a  command;
              when  the  command  is  invoked  during  a  package
              require command, Tcl appends two  additional  argu-
              ments  giving the desired package name and version.
              For example, if command is foo bar  and  later  the
              command  package  require test 2.4 is invoked, then
              Tcl will execute the command foo bar  test  2.4  to
              load the package.  If no version number is supplied
              to the package require command,  then  the  version
              argument  for  the invoked command will be an empty
              string.  If the package unknown command is  invoked
              without  a command argument, then the current pack-
              age unknown script is returned, or an empty  string
              if  there  is  none.  If command is specified as an
              empty string,  then  the  current  package  unknown
              script is removed, if there is one.

       package vcompare version1 version2
              Compares  the two version numbers given by version1
              and version2.  Returns -1 if version1 is an earlier
              version  than  version2, 0 if they are equal, and 1
              if version1 is later than version2.

       package versions package
              Returns a list of all the version numbers of  pack-
              age  for  which  information  has  been provided by
              package ifneeded commands.

       package vsatisfies version1 version2
              Returns 1 if scripts written for version2 will work
              unchanged  with version1 (i.e. version1 is equal to
              or greater than version2 and  they  both  have  the
              same major version number), 0 otherwise.


VERSION NUMBERS
       Version  numbers  consist  of  one or more decimal numbers
       separated by dots, such as 2 or 1.162  or  3.1.13.1.   The
       first  number  is called the major version number.  Larger
       numbers correspond to later versions of  a  package,  with
       leftmost  numbers  having greater significance.  For exam-
       ple, version 2.1 is later than 1.3 and  version  3.4.6  is
       later  than  3.3.5.   Missing  fields  are  equivalent  to
       zeroes:  version 1.3 is the  same  as  version  1.3.0  and
       1.3.0.0,  so it is earlier than 1.3.1 or 1.3.0.2.  A later
       version number is assumed to be upwards compatible with an
       earlier  version  number as long as both versions have the
       same major version number.  For example, Tcl scripts writ-
       ten  for  version  2.3  of a package should work unchanged
       under versions 2.3.2, 2.4,  and  2.5.1.   Changes  in  the
       major version number signify incompatible changes: if code
       is written to use version 2.1 of  a  package,  it  is  not
       guaranteed to work unmodified with either version 1.7.3 or
       version 3.1.


PACKAGE INDICES
       The recommended way to use packages in Tcl  is  to  invoke
       package  require  and package provide commands in scripts,
       and use the procedure pkg_mkIndex to create package  index
       files.   Once  you've  done  this, packages will be loaded
       automatically in response  to  package  require  commands.
       See the documentation for pkg_mkIndex for details.


KEYWORDS
       package, version


_________________________________________________________________

NAME
       pid - Retrieve process id(s)

SYNOPSIS
       pid ?fileId?
_________________________________________________________________


DESCRIPTION
       If  the  fileId  argument is given then it should normally
       refer to a process pipeline created with the open command.
       In this case the pid command will return a list whose ele-
       ments are the process identifiers of all the processes  in
       the  pipeline, in order.  The list will be empty if fileId
       refers to an open file that isn't a process pipeline.   If
       no  fileId  argument is given then pid returns the process
       identifier of the current process.   All  process  identi-
       fiers are returned as decimal strings.


KEYWORDS
       file, pipeline, process identifier



_________________________________________________________________

NAME
       pkg_mkIndex  -  Build  an  index  for automatic loading of
       packages

SYNOPSIS
       pkg_mkIndex ?-direct?  ?-lazy?  ?-load pkgPat? ?-verbose? dir ?pattern pattern ...?
_________________________________________________________________


DESCRIPTION
       Pkg_mkIndex is a utility procedure that  is  part  of  the
       standard  Tcl  library.   It is used to create index files
       that allow packages to be loaded automatically when  pack-
       age  require  commands  are executed.  To use pkg_mkIndex,
       follow these steps:

       [1]    Create the package(s).  Each package may consist of
              one  or  more  Tcl  script  files  or binary files.
              Binary files must be suitable for loading with  the
              load  command with a single argument;  for example,
              if the file is test.so it must be possible to  load
              this  file  with  the  command  load test.so.  Each
              script file must contain a package provide  command
              to declare the package and version number, and each
              binary file must contain a call to  Tcl_PkgProvide.

       [2]    Create  the index by invoking pkg_mkIndex.  The dir
              argument gives the name of  a  directory  and  each
              pattern  argument  is  a  glob-style  pattern  that
              selects script or binary files in dir.  The default 
              pattern is *.tcl and *.[info sharedlibextension].
              Pkg_mkIndex  will create a file pkgIndex.tcl in dir
              with package information about all the files  given
              by  the pattern arguments.  It does this by loading
              each file into a slave interpreter and seeing  what
              packages and new commands appear (this is why it is
              essential  to  have  package  provide  commands  or
              Tcl_PkgProvide  calls  in  the  files, as described
              above).  If you have a package split among  scripts
              and binary files, or if you have dependencies among
              files, you may have to  use  the  -load  option  or
              adjust the order in which pkg_mkIndex processes the
              files.  See COMPLEX CASES below.


       [3]    Install the package as a subdirectory of one of the
              directories  given by the tcl_pkgPath variable.  If
              $tcl_pkgPath  contains  more  than  one  directory,
              machine-dependent  packages  (e.g., those that con-
              tain binary shared libraries)  should  normally  be
              installed  under  the  first directory and machine-
              independent packages (e.g., those that contain only
              Tcl  scripts)  should be installed under the second
              directory.  The  subdirectory  should  include  the
              package's script and/or binary files as well as the
              pkgIndex.tcl file.   As  long  as  the  package  is
              installed  as  a  subdirectory  of  a  directory in
              $tcl_pkgPath it will automatically be found  during
              package require commands.
              If  you install the package anywhere else, then you
              must ensure that the directory containing the pack-
              age is in the auto_path global variable or an imme-
              diate subdirectory of one  of  the  directories  in
              auto_path.   Auto_path  contains a list of directo-
              ries that are searched by both the auto-loader  and
              the   package   loader;   by  default  it  includes
              $tcl_pkgPath.  The package loader also  checks  all
              of   the   subdirectories  of  the  directories  in
              auto_path.  You can add a  directory  to  auto_path
              explicitly  in your application, or you can add the
              directory to your TCLLIBPATH environment  variable:
              if  this  environment variable is present, Tcl ini-
              tializes  auto_path  from  it  during   application
              startup.

       [4]    Once  the above steps have been taken, all you need
              to do  to  use  a  package  is  to  invoke  package
              require.   For  example,  if versions 2.1, 2.3, and
              3.1  of  package  Test   have   been   indexed   by
              pkg_mkIndex,  the command package require Test will
              make version 3.1 available and the command  package
              require  -exact  Test  2.1  will  make  version 2.1
              available.  There may be many versions of a package
              in  the  various index files in auto_path, but only
              one will actually be loaded in a given interpreter,
              based  on  the first call to package require.  Dif-
              ferent versions of a package may be loaded in  dif-
              ferent interpreters.


OPTIONS
       The optional switches are:

       -direct        The  generated  index will implement direct
                      loading  of  the   package   upon   package
                      require.  This is the default.

       -lazy          The  generated  index  will manage to delay
                      loading the package until the use of one of
                      the   commands  provided  by  the  package,
                      instead  of  loading  it  immediately  upon
                      package require.

       -load pkgPat   The  index  process will pre-load any pack-
                      ages that exist in the current  interpreter
                      and match pkgPat into the slave interpreter
                      used to generate the  index.   The  pattern
                      match uses string match rules.  See COMPLEX
                      CASES below.

       -verbose       Generate output during  the  indexing  pro-
                      cess.   Output is via the tclLog procedure,
                      which by default prints to stderr.

       --             End of the flags, in case dir begins with a
                      dash.


PACKAGES AND THE AUTO-LOADER
       The  package  management  facilities overlap somewhat with
       the auto-loader, in that both  arrange  for  files  to  be
       loaded   on-demand.   However,  package  management  is  a
       higher-level mechanism that uses the auto-loader  for  the
       last  step in the loading process.  It is generally better
       to  index  a  package   with   pkg_mkIndex   rather   than
       auto_mkindex  because  the package mechanism provides ver-
       sion control:  several versions of a package can  be  made
       available  in the index files, with different applications
       using different versions based  on  package  require  com-
       mands.  In contrast, auto_mkindex does not understand ver-
       sions so it can only handle a single version of each pack-
       age.   It  is  probably  not  a good idea to index a given
       package with both pkg_mkIndex and  auto_mkindex.   If  you
       use pkg_mkIndex to index a package, its commands cannot be
       invoked until package require has been used  to  select  a
       version;   in contrast, packages indexed with auto_mkindex
       can be used immediately since there is no version control.


HOW IT WORKS
       Pkg_mkIndex  depends  on  the package unknown command, the
       package ifneeded command, and the auto-loader.  The  first
       time  a  package  require  command is invoked, the package
       unknown script is invoked.  This is set by Tcl initializa-
       tion  to  a  script that evaluates all of the pkgIndex.tcl
       files in the auto_path.  The  pkgIndex.tcl  files  contain
       package  ifneeded commands for each version of each avail-
       able package;  these commands invoke package provide  com-
       mands  to  announce  the  availability of the package, and
       they setup auto-loader information to load  the  files  of
       the  package.   If  the  -lazy  flag was provided when the 
       pkgIndex.tcl was generated, a given file of a  given  ver-
       sion  of  a  given package isn't actually loaded until the
       first time one of its commands is  invoked.   Thus,  after
       invoking  package  require  you  may not see the package's
       commands in the interpreter,  but  you  will  be  able  to
       invoke the commands and they will be auto-loaded.

DIRECT LOADING                                                    
       Some  packages, for instance packages which use namespaces 
       and export commands or those which  require  special  ini-
       tialization,  might  select  that  their  package files be 
       loaded immediately upon package require instead of  delay-
       ing  the  actual  loading  to  the first use of one of the 
       package's command. This is the default mode when  generat-
       ing the package index.  It can be overridden by specifying 
       the -lazy argument.


COMPLEX CASES
       Most complex  cases  of  dependencies  among  scripts  and
       binary  files,  and packages being split among scripts and
       binary files are handled OK.  However,  you  may  have  to
       adjust   the   order  in  which  files  are  processed  by
       pkg_mkIndex.  These issues are described in detail  below.

       If  each script or file contains one package, and packages
       are only contained in one file, then things are easy.  You
       simply  specify  all files to be indexed in any order with
       some glob patterns.

       In general, it is OK for scripts to have  dependencies  on
       other  packages.   If scripts contain package require com-
       mands, these are stubbed out in the  interpreter  used  to
       process  the  scripts, so these do not cause problems.  If
       scripts call into other packages  in  global  code,  these
       calls  are handled by a stub unknown command.  However, if
       scripts make variable references to other package's  vari-
       ables  in  global  code, these will cause errors.  That is
       also bad coding style.

       If binary  files  have  dependencies  on  other  packages,
       things  can  become  tricky  because it is not possible to
       stub out C-level APIs  such  as  Tcl_PkgRequire  API  when
       loading a binary file.  For example, suppose the BLT pack-
       age requires  Tk,  and  expresses  this  with  a  call  to
       Tcl_PkgRequire  in its Blt_Init routine.  To support this,
       you must run pkg_mkIndex in an  interpreter  that  has  Tk
       loaded.   You  can  achieve  this  with  the  -load pkgPat
       option.  If you specify this option, pkg_mkIndex will load
       any  packages  listed by info loaded and that match pkgPat
       into the interpreter used to process files.  In most cases
       this  will satisfy the Tcl_PkgRequire calls made by binary
       files.

       If you are indexing two binary files and  one  depends  on
       the  other,  you should specify the one that has dependen-
       cies last.  This way the one without dependencies will get
       loaded  and indexed, and then the package it provides will
       be available when the second file is processed.   You  may
       also  need  to  load  the first package into the temporary
       interpreter used to create the index by  using  the  -load
       flag;  it  won't hurt to specify package patterns that are
       not yet loaded.

       If you have a package that is split across scripts  and  a
       binary  file,  then  you  should avoid the -load flag. The
       problem is that if you load a package before computing the
       index  it  masks  any other files that provide part of the
       same package.  If you must use -load, then you must  spec-
       ify  the  scripts first; otherwise the package loaded from
       the binary file  may  mask  the  package  defined  by  the
       scripts.


KEYWORDS
       auto-load, index, package, version


_________________________________________________________________

NAME
       proc - Create a Tcl procedure

SYNOPSIS
       proc name args body
_________________________________________________________________


DESCRIPTION
       The  proc  command creates a new Tcl procedure named name,
       replacing any existing command or procedure there may have
       been  by  that name.  Whenever the new command is invoked,
       the contents of body will be executed by  the  Tcl  inter-
       preter.   Normally,  name is unqualified (does not include
       the names of any containing namespaces), and the new  pro-
       cedure  is  created  in  the  current  namespace.  If name
       includes any namespace qualifiers, the procedure  is  cre-
       ated  in the specified namespace.  Args specifies the for-
       mal arguments to the procedure.  It consists  of  a  list,
       possibly empty, each of whose elements specifies one argu-
       ment.  Each argument specifier is also a list with  either
       one or two fields.  If there is only a single field in the
       specifier then it is the name of the  argument;  if  there
       are  two  fields,  then the first is the argument name and
       the second is its default value.

       When name is invoked a local variable will be created  for
       each  of  the formal arguments to the procedure; its value
       will be the value of corresponding argument in the  invok-
       ing  command  or  the argument's default value.  Arguments
       with default values need not be specified in  a  procedure
       invocation.   However,  there  must be enough actual argu-
       ments  for  all  the  formal  arguments  that  don't  have
       defaults,  and  there  must  not be any extra actual argu-
       ments.  There is one special  case  to  permit  procedures
       with  variable  numbers  of arguments.  If the last formal
       argument has the name args, then a call to  the  procedure
       may  contain  more actual arguments than the procedure has
       formals.  In this case, all of the actual arguments start-
       ing at the one that would be assigned to args are combined
       into a list (as if the list command had been  used);  this
       combined value is assigned to the local variable args.

       When body is being executed, variable names normally refer
       to local variables, which are created  automatically  when
       referenced  and  deleted  when the procedure returns.  One
       local variable is automatically created for  each  of  the
       procedure's  arguments.   Global  variables  can  only  be
       accessed by invoking the global command or the upvar  com-
       mand.   Namespace variables can only be accessed by invok-
       ing the variable command or the upvar command.


       The proc command returns an empty string.  When  a  proce-
       dure is invoked, the procedure's return value is the value
       specified in a return command.  If the  procedure  doesn't
       execute  an  explicit return, then its return value is the
       value of the last  command  executed  in  the  procedure's
       body.   If  an  error occurs while executing the procedure
       body, then the procedure-as-a-whole will return that  same
       error.


KEYWORDS
       argument, procedure


_________________________________________________________________

NAME
       puts - Write to a channel

SYNOPSIS
       puts ?-nonewline? ?channelId? string
_________________________________________________________________


DESCRIPTION
       Writes the characters given by string to the channel given
       by channelId.

       ChannelId must be an identifier for an open  channel  such 
       as  a  Tcl standard channel (stdout or stderr), the return 
       value from an invocation of open or socket, or the  result 
       of a channel creation command provided by a Tcl extension. 
       The channel must have been opened for output.

       If no channelId is specified then it defaults  to  stdout.
       Puts  normally  outputs  a newline character after string,
       but this feature  may  be  suppressed  by  specifying  the
       -nonewline switch.

       Newline characters in the output are translated by puts to
       platform-specific end-of-line sequences according  to  the
       current  value  of the -translation option for the channel
       (for example, on PCs newlines are normally  replaced  with
       carriage-return-linefeed  sequences;   on Macintoshes new-
       lines are normally replaced with  carriage-returns).   See
       the  fconfigure  manual  entry for a discussion on ways in
       which fconfigure will alter output.

       Tcl buffers output internally, so characters written  with
       puts  may  not  appear  immediately  on the output file or
       device;  Tcl will normally delay output until  the  buffer
       is full or the channel is closed.  You can force output to
       appear immediately with the flush command.

       When the output buffer fills up,  the  puts  command  will
       normally  block  until  all  the  buffered  data  has been
       accepted for output by the operating system.  If channelId
       is  in  nonblocking  mode  then  the puts command will not
       block even if the operating system cannot accept the data.
       Instead, Tcl continues to buffer the data and writes it in
       the background as fast as the underlying  file  or  device
       can  accept  it.   The  application must use the Tcl event
       loop for nonblocking output to work;  otherwise Tcl  never
       finds out that the file or device is ready for more output
       data.  It is possible for an arbitrarily large  amount  of
       data  to  be  buffered  for a channel in nonblocking mode,
       which could consume a large amount of  memory.   To  avoid
       wasting memory, nonblocking I/O should normally be used in
       an event-driven fashion with the fileevent command  (don't
       invoke  puts  unless you have recently been notified via a
       file event that the  channel  is  ready  for  more  output
       data).


KEYWORDS
       channel, newline, output, write


_________________________________________________________________

NAME
       pwd - Return the current working directory

SYNOPSIS
       pwd
_________________________________________________________________


DESCRIPTION
       Returns the path name of the current working directory.


KEYWORDS
       working directory


_________________________________________________________________

NAME
       re_syntax - Syntax of Tcl regular expressions.
_________________________________________________________________


DESCRIPTION
       A  regular  expression  describes  strings  of characters.
       It's a pattern that matches certain  strings  and  doesn't
       match others.


DIFFERENT FLAVORS OF REs
       Regular  expressions  (``RE''s), as defined by POSIX, come
       in two flavors: extended  REs  (``EREs'')  and  basic  REs
       (``BREs'').   EREs  are  roughly  those of the traditional
       egrep, while BREs are roughly those of the traditional ed.
       This  implementation  adds  a  third  flavor, advanced REs
       (``AREs''), basically EREs with  some  significant  exten-
       sions.

       This  manual  page  primarily describes AREs.  BREs mostly
       exist for backward compatibility  in  some  old  programs;
       they  will be discussed at the end.  POSIX EREs are almost
       an exact subset of AREs.  Features of AREs  that  are  not
       present in EREs will be indicated.


REGULAR EXPRESSION SYNTAX
       Tcl  regular expressions are implemented using the package
       written by Henry Spencer, based on  the  1003.2  spec  and
       some  (not  quite  all)  of  the Perl5 extensions (thanks,
       Henry!).  Much of the description of  regular  expressions
       below is copied verbatim from his manual entry.

       An ARE is one or more branches, separated by `|', matching
       anything that matches any of the branches.

       A branch is zero or more constraints or quantified  atoms,
       concatenated.   It matches a match for the first, followed
       by a match for the second, etc; an  empty  branch  matches
       the empty string.

       A quantified atom is an atom possibly followed by a single
       quantifier.  Without a quantifier, it matches a match  for
       the  atom.  The quantifiers, and what a so-quantified atom
       matches, are:

         *     a sequence of 0 or more matches of the atom

         +     a sequence of 1 or more matches of the atom

         ?     a sequence of 0 or 1 matches of the atom


         {m}   a sequence of exactly m matches of the atom

         {m,}  a sequence of m or more matches of the atom

         {m,n} a sequence of m through n (inclusive)  matches  of
               the atom; m may not exceed n

         *?  +?  ??  {m}?  {m,}?  {m,n}?
               non-greedy  quantifiers, which match the same pos-
               sibilities, but prefer the smallest number  rather
               than the largest number of matches (see MATCHING)

       The  forms using { and } are known as bounds.  The numbers
       m and n are unsigned  decimal  integers  with  permissible
       values from 0 to 255 inclusive.

       An atom is one of:

         (re)  (where  re  is  any  regular expression) matches a
               match for re, with the match  noted  for  possible
               reporting

         (?:re)
               as  previous,  but does no reporting (a ``non-cap-
               turing'' set of parentheses)

         ()    matches  an  empty  string,  noted  for   possible
               reporting

         (?:)  matches an empty string, without reporting

         [chars]
               a  bracket  expression,  matching  any  one of the
               chars (see BRACKET EXPRESSIONS for more detail)

          .    matches any single character

         \k    (where k is a non-alphanumeric character)  matches
               that  character  taken  as  an ordinary character,
               e.g. \\ matches a backslash character

         \c    where c  is  alphanumeric  (possibly  followed  by
               other  characters),  an  escape  (AREs  only), see
               ESCAPES below

         {     when followed by a character other than  a  digit,
               matches  the  left-brace  character `{'; when fol-
               lowed by a digit, it is the beginning of  a  bound
               (see above)

         x     where  x  is a single character with no other sig-
               nificance, matches that character.

       A  constraint  matches  an  empty  string  when   specific
       conditions are met.  A constraint may not be followed by a
       quantifier.  The simple constraints are as  follows;  some
       more constraints are described later, under ESCAPES.

         ^       matches at the beginning of a line

         $       matches at the end of a line

         (?=re)  positive  lookahead  (AREs only), matches at any
                 point where a substring matching re begins

         (?!re)  negative lookahead (AREs only), matches  at  any
                 point where no substring matching re begins

       The  lookahead constraints may not contain back references
       (see later), and all parentheses within them  are  consid-
       ered non-capturing.

       An RE may not end with `\'.


BRACKET EXPRESSIONS
       A  bracket  expression is a list of characters enclosed in
       `[]'.  It normally matches any single character  from  the
       list  (but  see  below).   If the list begins with `^', it
       matches any single character (but see below) not from  the
       rest of the list.

       If  two  characters in the list are separated by `-', this
       is shorthand for the  full  range  of  characters  between
       those  two  (inclusive)  in  the  collating sequence, e.g.
       [0-9] in ASCII matches any decimal digit.  Two ranges  may
       not  share an endpoint, so e.g.  a-c-e is illegal.  Ranges
       are very collating-sequence-dependent, and  portable  pro-
       grams should avoid relying on them.

       To  include  a  literal  ]  or - in the list, the simplest
       method is to enclose it in [. and .]  to make it a collat-
       ing element (see below).  Alternatively, make it the first
       character (following a possible `^'), or (AREs only)  pre-
       cede  it  with  `\'.   Alternatively, for `-', make it the
       last character, or the second endpoint of a range.  To use
       a  literal  -  as the first endpoint of a range, make it a
       collating element or (AREs  only)  precede  it  with  `\'.
       With  the  exception  of  these, some combinations using [
       (see next paragraphs),  and  escapes,  all  other  special
       characters   lose  their  special  significance  within  a
       bracket expression.

       Within a bracket expression, a collating element (a  char-
       acter,  a  multi-character sequence that collates as if it
       were a single character, or a collating-sequence name  for
       either)  enclosed in [. and .]  stands for the sequence of
       characters of that collating element.  The sequence  is  a
       single  element  of  the  bracket  expression's  list.   A
       bracket expression in a locale  that  has  multi-character
       collating elements can thus match more than one character. 
       So (insidiously), a bracket expression that starts with  ^ 
       can  match multi-character collating elements even if none 
       of them appear in the bracket expression!  (Note: Tcl cur-
       rently  has  no  multi-character collating elements.  This 
       information is only for illustration.)                     

       For example, assume the collating sequence includes  a  ch 
       multi-character collating element.  Then the RE [[.ch.]]*c 
       (zero or more ch's followed by c) matches the  first  five 
       characters of `chchcc'.  Also, the RE [^c]b matches all of 
       `chb' (because [^c] matches the multi-character ch).

       Within a bracket expression, a collating element  enclosed
       in  [=  and  =]  is an equivalence class, standing for the
       sequences of characters of all collating elements  equiva-
       lent  to  that  one,  including  itself.  (If there are no
       other equivalent collating elements, the treatment  is  as
       if  the  enclosing  delimiters  were  `[.' and `.]'.)  For
       example, if o and ™ are  the  members  of  an  equivalence
       class,  then `[[=o=]]', `[[=™=]]', and `[o™]' are all syn-
       onymous.  An equivalence class may not be an endpoint of a
       range.   (Note:  Tcl currently implements only the Unicode 
       locale.  It doesn't define any equivalence  classes.   The 
       examples above are just illustrations.)

       Within a bracket expression, the name of a character class
       enclosed in [: and :] stands for the list of  all  charac-
       ters  (not  all  collating  elements!)   belonging to that
       class.  Standard character classes are:

              alpha       A letter.
              upper       An upper-case letter.
              lower       A lower-case letter.
              digit       A decimal digit.
              xdigit      A hexadecimal digit.
              alnum       An alphanumeric (letter or digit).
              print       An alphanumeric (same as alnum).
              blank       A space or tab character.
              space       A character producing white space in displayed text.
              punct       A punctuation character.
              graph       A character with a visible representation.
              cntrl       A control character.

       A locale may provide others.  (Note that the  current  Tcl 
       implementation  has  only one locale: the Unicode locale.)
       A character class may not be used  as  an  endpoint  of  a
       range.

       There  are  two  special cases of bracket expressions: the
       bracket expressions [[:<:]] and [[:>:]]  are  constraints,
       matching  empty strings at the beginning and end of a word
       respectively.  A word is defined as  a  sequence  of  word
       characters  that  is neither preceded nor followed by word
       characters.  A word character is an alnum character or  an
       underscore  (_).   These  special  bracket expressions are
       deprecated; users of AREs should  use  constraint  escapes
       instead (see below).

ESCAPES
       Escapes  (AREs  only), which begin with a \ followed by an
       alphanumeric character, come in several varieties: charac-
       ter  entry, class shorthands, constraint escapes, and back
       references.  A \ followed by an alphanumeric character but
       not  constituting  a  valid escape is illegal in AREs.  In
       EREs, there are no escapes: outside a bracket  expression,
       a  \  followed  by an alphanumeric character merely stands
       for that character as an ordinary character, and inside  a
       bracket expression, \ is an ordinary character.  (The lat-
       ter is the one actual  incompatibility  between  EREs  and
       AREs.)

       Character-entry  escapes (AREs only) exist to make it eas-
       ier to specify  non-printing  and  otherwise  inconvenient
       characters in REs:

         \a   alert (bell) character, as in C

         \b   backspace, as in C

         \B   synonym  for \ to help reduce backslash doubling in
              some applications where there are  multiple  levels
              of backslash processing

         \cX  (where X is any character) the character whose low-
              order 5 bits are the same as those of X, and  whose
              other bits are all zero

         \e   the  character  whose  collating-sequence  name  is
              `ESC', or failing that, the  character  with  octal
              value 033

         \f   formfeed, as in C

         \n   newline, as in C

         \r   carriage return, as in C

         \t   horizontal tab, as in C

         \uwxyz
              (where wxyz is exactly four hexadecimal digits) the
              Unicode character U+wxyz in the local byte ordering

         \Ustuvwxyz
              (where   stuvwxyz   is  exactly  eight  hexadecimal
              digits) reserved for a  somewhat-hypothetical  Uni-
              code extension to 32 bits

         \v   vertical tab, as in C are all available.

         \xhhh
              (where  hhh  is any sequence of hexadecimal digits)
              the character whose hexadecimal value is  0xhhh  (a
              single  character  no  matter  how many hexadecimal
              digits are used).

         \0   the character whose value is 0

         \xy  (where xy is exactly two octal digits, and is not a
              back  reference  (see  below))  the character whose
              octal value is 0xy

         \xyz (where xyz is exactly three octal  digits,  and  is
              not  a  back  reference  (see below)) the character
              whose octal value is 0xyz

       Hexadecimal digits  are  `0'-`9',  `a'-`f',  and  `A'-`F'.
       Octal digits are `0'-`7'.

       The  character-entry  escapes are always taken as ordinary
       characters.  For example, \135 is ]  in  ASCII,  but  \135
       does not terminate a bracket expression.  Beware, however,
       that some applications (e.g., C compilers) interpret  such
       sequences themselves before the regular-expression package
       gets to see them, which may require doubling (quadrupling,
       etc.) the `\'.

       Class-shorthand escapes (AREs only) provide shorthands for
       certain commonly-used character classes:

         \d        [[:digit:]]

         \s        [[:space:]]

         \w        [[:alnum:]_] (note underscore)

         \D        [^[:digit:]]

         \S        [^[:space:]]

         \W        [^[:alnum:]_] (note underscore)

       Within bracket expressions,  `\d',  `\s',  and  `\w'  lose
       their  outer  brackets, and `\D', `\S', and `\W' are ille-
       gal.  (So, for  example,  [a-c\d]  is  equivalent  to  [a- 
       c[:digit:]].   Also,  [a-c\D],  which is equivalent to [a- 
       c^[:digit:]], is illegal.)

       A constraint escape (AREs only) is a constraint,  matching
       the  empty  string if specific conditions are met, written
       as an escape:

         \A    matches only at the beginning of the  string  (see
               MATCHING, below, for how this differs from `^')

         \m    matches only at the beginning of a word

         \M    matches only at the end of a word

         \y    matches only at the beginning or end of a word

         \Y    matches  only at a point that is not the beginning
               or end of a word

         \Z    matches only at the end of the string (see  MATCH-
               ING, below, for how this differs from `$')

         \m    (where m is a nonzero digit) a back reference, see
               below

         \mnn  (where m is a nonzero digit, and nn is  some  more
               digits,  and  the decimal value mnn is not greater
               than the number of closing  capturing  parentheses
               seen so far) a back reference, see below

       A  word  is defined as in the specification of [[:<:]] and
       [[:>:]] above.   Constraint  escapes  are  illegal  within
       bracket expressions.

       A  back  reference  (AREs  only)  matches  the same string
       matched by the parenthesized  subexpression  specified  by
       the  number, so that (e.g.)  ([bc])\1 matches bb or cc but
       not `bc'.  The subexpression  must  entirely  precede  the
       back  reference in the RE.  Subexpressions are numbered in
       the order of  their  leading  parentheses.   Non-capturing
       parentheses do not define subexpressions.

       There  is  an  inherent historical ambiguity between octal
       character-entry escapes  and  back  references,  which  is
       resolved  by  heuristics,  as  hinted at above.  A leading
       zero always indicates an octal escape.  A single  non-zero
       digit, not followed by another digit, is always taken as a
       back reference.  A multi-digit sequence not starting  with
       a  zero  is  taken as a back reference if it comes after a
       suitable subexpression (i.e. the number is  in  the  legal
       range  for  a  back  reference), and otherwise is taken as
       octal.

METASYNTAX
       In addition to the main syntax described above, there  are
       some  special forms and miscellaneous syntactic facilities
       available.
       Normally the flavor of  RE  being  used  is  specified  by
       application-dependent  means.   However, this can be over-
       ridden by a director.  If an RE of any flavor begins  with
       `***:',  the  rest  of  the RE is an ARE.  If an RE of any
       flavor begins with `***=', the rest of the RE is taken  to
       be  a literal string, with all characters considered ordi-
       nary characters.

       An ARE may begin with embedded options: a sequence  (?xyz)
       (where xyz is one or more alphabetic characters) specifies
       options affecting the rest of the RE.   These  supplement,
       and  can  override,  any options specified by the applica-
       tion.  The available option letters are:

         b  rest of RE is a BRE

         c  case-sensitive matching (usual default)

         e  rest of RE is an ERE

         i  case-insensitive matching (see MATCHING, below)

         m  historical synonym for n

         n  newline-sensitive matching (see MATCHING, below)

         p  partial  newline-sensitive  matching  (see  MATCHING,
            below)

         q  rest  of  RE  is  a  literal (``quoted'') string, all
            ordinary characters

         s  non-newline-sensitive matching (usual default)

         t  tight syntax (usual default; see below)

         w  inverse partial newline-sensitive (``weird'')  match-
            ing (see MATCHING, below)

         x  expanded syntax (see below)

       Embedded  options  take  effect  at  the ) terminating the
       sequence.  They are available only at the start of an ARE,
       and may not be used later within it.

       In  addition  to the usual (tight) RE syntax, in which all
       characters are significant, there is an  expanded  syntax,
       available  in all flavors of RE with the -expanded switch,
       or in AREs with the embedded x option.   In  the  expanded
       syntax, white-space characters are ignored and all charac-
       ters between a # and the following newline (or the end  of
       the  RE) are ignored, permitting paragraphing and comment-
       ing a complex RE.  There  are  three  exceptions  to  that
       basic rule:
         a  white-space  character  or  `#'  preceded  by  `\' is
         retained

         white space  or  `#'  within  a  bracket  expression  is
         retained

         white  space and comments are illegal within multi-char-
         acter symbols like the ARE `(?:' or the BRE `\('

       Expanded-syntax white-space  characters  are  blank,  tab,
       newline, and any character that belongs to the space char-
       acter class.

       Finally, in  an  ARE,  outside  bracket  expressions,  the
       sequence `(?#ttt)' (where ttt is any text not containing a
       `)') is a comment, completely ignored.  Again, this is not
       allowed  between the characters of multi-character symbols
       like `(?:'.  Such comments are more a historical  artifact
       than  a  useful facility, and their use is deprecated; use
       the expanded syntax instead.

       None of these metasyntax extensions is  available  if  the
       application  (or  an  initial ***= director) has specified
       that the user's input  be  treated  as  a  literal  string
       rather than as an RE.

MATCHING
       In  the  event  that  an RE could match more than one sub-
       string of a given string, the RE matches the one  starting
       earliest  in  the string.  If the RE could match more than
       one substring starting at that point, its choice is deter-
       mined  by its preference: either the longest substring, or
       the shortest.

       Most atoms, and all constraints, have  no  preference.   A
       parenthesized  RE  has the same preference (possibly none)
       as the RE.  A quantified atom with quantifier {m} or  {m}?
       has  the  same  preference  (possibly  none)  as  the atom
       itself.  A quantified atom with other  normal  quantifiers
       (including {m,n} with m equal to n) prefers longest match.
       A  quantified  atom  with  other  non-greedy   quantifiers
       (including  {m,n}?   with  m  equal to n) prefers shortest
       match.  A branch has the  same  preference  as  the  first
       quantified  atom in it which has a preference.  An RE con-
       sisting of two or more branches connected by the |  opera-
       tor prefers longest match.

       Subject to the constraints imposed by the rules for match-
       ing the whole RE, subexpressions also match the longest or
       shortest  possible substrings, based on their preferences,
       with subexpressions starting earlier in the RE taking pri-
       ority  over  ones  starting later.  Note that outer subex-
       pressions thus take priority over their  component  subex-
       pressions.
       Note that the quantifiers {1,1} and {1,1}?  can be used to
       force longest and shortest preference, respectively, on  a
       subexpression or a whole RE.

       Match  lengths  are  measured in characters, not collating
       elements.  An empty string is considered  longer  than  no
       match  at  all.  For example, bb* matches the three middle
       characters of `abbbc',  (week|wee)(night|knights)  matches
       all  ten  characters  of  `weeknights',  when  (.*).*   is
       matched  against  abc  the   parenthesized   subexpression
       matches  all  three  characters, and when (a*)* is matched
       against bc both the whole RE and the parenthesized  subex-
       pression match an empty string.

       If  case-independent  matching is specified, the effect is
       much as if all case distinctions  had  vanished  from  the
       alphabet.   When  an  alphabetic  that  exists in multiple
       cases appears as an ordinary character outside  a  bracket
       expression,  it  is effectively transformed into a bracket
       expression  containing  both  cases,  so  that  x  becomes
       `[xX]'.   When it appears inside a bracket expression, all
       case counterparts of it are added to the  bracket  expres-
       sion, so that [x] becomes [xX] and [^x] becomes `[^xX]'.

       If newline-sensitive matching is specified, .  and bracket
       expressions using ^ will never match the newline character
       (so  that  matches will never cross newlines unless the RE
       explicitly arranges it) and ^ and $ will match  the  empty
       string  after  and before a newline respectively, in addi-
       tion to matching at beginning and end  of  string  respec-
       tively.   ARE \A and \Z continue to match beginning or end
       of string only.

       If partial newline-sensitive matching is  specified,  this
       affects  .  and bracket expressions as with newline-sensi-
       tive matching, but not ^ and `$'.

       If inverse partial newline-sensitive  matching  is  speci-
       fied,  this  affects  ^  and  $  as with newline-sensitive
       matching, but not .  and bracket expressions.  This  isn't
       very useful but is provided for symmetry.

LIMITS AND COMPATIBILITY
       No particular limit is imposed on the length of REs.  Pro-
       grams intended to be highly portable should not employ REs
       longer than 256 bytes, as a POSIX-compliant implementation
       can refuse to accept such REs.

       The only feature of AREs  that  is  actually  incompatible
       with  POSIX  EREs is that \ does not lose its special sig-
       nificance inside bracket expressions.  All other ARE  fea-
       tures  use  syntax  which  is  illegal or has undefined or
       unspecified effects in  POSIX  EREs;  the  ***  syntax  of
       directors  likewise  is  outside the POSIX syntax for both
       BREs and EREs.

       Many of the ARE extensions are  borrowed  from  Perl,  but
       some  have  been  changed to clean them up, and a few Perl
       extensions are not  present.   Incompatibilities  of  note
       include  `\b',  `\B',  the lack of special treatment for a
       trailing newline, the  addition  of  complemented  bracket
       expressions  to  the  things affected by newline-sensitive
       matching, the restrictions on parentheses and back  refer-
       ences  in lookahead constraints, and the longest/shortest-
       match (rather than first-match) matching semantics.

       The matching rules for REs containing both normal and non-
       greedy quantifiers have changed since early beta-test ver-
       sions of this package.  (The new rules  are  much  simpler
       and cleaner, but don't work as hard at guessing the user's
       real intentions.)

       Henry Spencer's original 1986  regexp  package,  still  in
       widespread  use (e.g., in pre-8.1 releases of Tcl), imple-
       mented an early version of today's EREs.  There  are  four
       incompatibilities  between  regexp's near-EREs (`RREs' for
       short) and AREs.  In roughly increasing order of  signifi-
       cance:

              In AREs, \ followed by an alphanumeric character is
              either an escape or an error, while in RREs, it was
              just another way of writing the alphanumeric.  This
              should not be a problem because there was no reason
              to write such a sequence in RREs.

              { followed by a digit in an ARE is the beginning of
              a bound, while in RREs, { was  always  an  ordinary
              character.  Such sequences should be rare, and will
              often result in an error because following  charac-
              ters will not look like a valid bound.

              In AREs, \ remains a special character within `[]',
              so a literal \ within [] must be written `\\'.   \\
              also  gives a literal \ within [] in RREs, but only
              truly paranoid programmers  routinely  doubled  the
              backslash.

              AREs  report the longest/shortest match for the RE,
              rather than the first found in a  specified  search
              order.   This may affect some RREs which were writ-
              ten in the expectation that the first  match  would
              be  reported.   (The  careful  crafting  of RREs to
              optimize the search  order  for  fast  matching  is
              obsolete (AREs examine all possible matches in par-
              allel, and their performance is largely insensitive
              to  their  complexity)  but  cases where the search
              order was exploited to deliberately  find  a  match
              which   was  not  the  longest/shortest  will  need
              rewriting.)


BASIC REGULAR EXPRESSIONS
       BREs differ from EREs in several respects.  `|', `+',  and
       ?   are ordinary characters and there is no equivalent for
       their functionality.  The delimiters for bounds are \{ and
       `\}', with { and } by themselves ordinary characters.  The
       parentheses for nested subexpressions  are  \(  and  `\)',
       with  (  and ) by themselves ordinary characters.  ^ is an
       ordinary character except at the beginning of  the  RE  or
       the  beginning  of  a parenthesized subexpression, $ is an
       ordinary character except at the end of the RE or the  end
       of  a  parenthesized  subexpression,  and * is an ordinary
       character if it appears at the beginning of the RE or  the
       beginning of a parenthesized subexpression (after a possi-
       ble leading `^').  Finally, single-digit  back  references
       are  available, and \< and \> are synonyms for [[:<:]] and
       [[:>:]] respectively; no other escapes are available.


KEYWORDS
       match, regular expression, string


_________________________________________________________________

NAME
       read - Read from a channel

SYNOPSIS
       read ?-nonewline? channelId

       read channelId numChars
_________________________________________________________________


DESCRIPTION
       In  the first form, the read command reads all of the data
       from channelId up to the end of the file.  If the  -nonew-
       line  switch  is  specified then the last character of the
       file is discarded if it is a newline.  In the second form,
       the  extra argument specifies how many characters to read.
       Exactly that many characters will be  read  and  returned,
       unless  there are fewer than numChars left in the file; in
       this case all the remaining characters are  returned.   If
       the  channel  is  configured to use a multi-byte encoding,
       then the number of characters read may not be the same  as
       the number of bytes read.

       ChannelId  must  be an identifier for an open channel such 
       as the Tcl standard  input  channel  (stdin),  the  return 
       value  from an invocation of open or socket, or the result 
       of a channel creation command provided by a Tcl extension. 
       The channel must have been opened for input.

       If  channelId  is in nonblocking mode, the command may not
       read as many characters as requested: once  all  available
       input has been read, the command will return the data that
       is available rather than blocking for more input.  If  the
       channel  is  configured to use a multi-byte encoding, then
       there may actually be some bytes remaining in the internal
       buffers  that  do  not  form  a complete character.  These
       bytes will not be returned until a complete  character  is
       available  or  end-of-file  is  reached.   The  -nonewline
       switch is ignored if the command returns  before  reaching
       the end of the file.

       Read  translates  end-of-line  sequences in the input into
       newline characters according to  the  -translation  option
       for  the  channel.   See the fconfigure manual entry for a
       discussion on ways in which fconfigure will alter input.


USE WITH SERIAL PORTS
       For most applications a channel connected to a serial port
       should  be  configured to be nonblocking: fconfigure chan-
       nelId -blocking 0.  Then read behaves much like  described
       above.   Care  must  be  taken when using read on blocking
       serial ports:

       read channelId numChars
              In this form read blocks until numChars  have  been
              received from the serial port.

       read channelId
              In this form read blocks until the reception of the
              end-of-file character, see fconfigure -eofchar.  If
              there  no end-of-file character has been configured
              for the channel, then read will block forever.

KEYWORDS
       blocking,  channel, end of line, end of file, nonblocking,
       read, translation, encoding


_________________________________________________________________

NAME
       regexp - Match a regular expression against a string


SYNOPSIS
       regexp  ?switches? exp string ?matchVar? ?subMatchVar sub-
       MatchVar ...?
_________________________________________________________________


DESCRIPTION
       Determines whether the regular expression exp matches part
       or  all  of  string  and  returns  1  if  it does, 0 if it
       doesn't, unless -inline is specified (see below).   (Regu-
       lar expression matching is described in the re_syntax ref-
       erence page.)

       If additional arguments are specified  after  string  then
       they  are  treated  as  the names of variables in which to
       return information about which part(s) of  string  matched
       exp.   MatchVar  will  be  set to the range of string that
       matched all of exp.  The first  subMatchVar  will  contain
       the  characters in string that matched the leftmost paren-
       thesized subexpression within exp,  the  next  subMatchVar
       will  contain  the characters that matched the next paren-
       thesized subexpression to the right in exp, and so on.

       If the initial arguments to regexp start with - then  they
       are  treated as switches.  The following switches are cur-
       rently supported:

       -about         Instead of attempting to match the  regular
                      expression,   returns   a  list  containing
                      information about the  regular  expression.
                      The  first  element of the list is a subex-
                      pression count.  The second  element  is  a
                      list  of property names that describe vari-
                      ous attributes of the  regular  expression.
                      This   switch  is  primarily  intended  for
                      debugging purposes.

       -expanded      Enables use of the expanded regular expres-
                      sion  syntax  where whitespace and comments
                      are ignored.  This is the same as  specify-
                      ing  the  (?x)  embedded  option  (see  the
                      re_syntax manual page).

       -indices       Changes what is stored in the subMatchVars.
                      Instead  of storing the matching characters
                      from string, each variable will  contain  a
                      list  of  two  decimal  strings  giving the
                      indices in string of  the  first  and  last
                      characters in the matching range of charac-
                      ters.

       -line          Enables  newline-sensitive  matching.    By
                      default,  newline  is a completely ordinary
                      character with no  special  meaning.   With
                      this flag, `[^' bracket expressions and `.'
                      never match newline, `^' matches  an  empty
                      string after any newline in addition to its
                      normal function, and `$' matches  an  empty
                      string  before  any  newline in addition to
                      its normal function.  This flag is  equiva-
                      lent to specifying both -linestop and -lin-
                      eanchor, or the (?n) embedded  option  (see
                      the re_syntax manual page).

       -linestop      Changes   the   behavior  of  `[^'  bracket
                      expressions and `.' so that  they  stop  at
                      newlines.   This  is the same as specifying
                      the (?p) embedded option (see the re_syntax
                      manual page).

       -lineanchor    Changes  the  behavior  of `^' and `$' (the
                      ``anchors'') so they  match  the  beginning
                      and  end  of  a line respectively.  This is
                      the same as specifying  the  (?w)  embedded
                      option (see the re_syntax manual page).

       -nocase        Causes  upper-case  characters in string to
                      be treated as lower case during the  match-
                      ing process.                                

       -all                                                              
                      Causes the regular expression to be matched 
                      as  many  times  as possible in the string, 
                      returning  the  total  number  of   matches 
                      found.   If  this  is  specified with match 
                      variables, they will  continue  information 
                      for the last match only.                    

       -inline                                                           
                      Causes the command to return,  as  a  list, 
                      the  data that would otherwise be placed in 
                      match variables.  When using -inline, match 
                      variables  may  not  be specified.  If used 
                      with -all, the list will be concatenated at 
                      each  iteration,  such  that a flat list is 
                      always returned.  For each match iteration, 
                      the  command  will append the overall match 
                      data, plus one element for each  subexpres-
                      sion  in  the regular expression.  Examples 
                      are:                                        
                          regexp -inline -- {\w(\w)} " inlined "  
                       => {in n}                                  

                          regexp -all -inline -- {\w(\w)} " inlined "
                       => {in n li i ne e}                        

       -start                                                     
       index                                                      
                      Specifies a character index offset into the 
                      string   to   start  matching  the  regular 
                      expression at.  When using this switch, `^' 
                      will  not  match the beginning of the line, 
                      and \A will still match the  start  of  the 
                      string at index.  If -indices is specified, 
                      the indices will be indexed  starting  from 
                      the absolute beginning of the input string. 
                      index will be constrained to the bounds  of 
                      the input string.

       --             Marks  the  end  of switches.  The argument
                      following this one will be treated  as  exp
                      even if it starts with a -.

       If  there are more subMatchVar's than parenthesized subex-
       pressions within exp, or if a particular subexpression  in
       exp  doesn't  match  the  string (e.g. because it was in a
       portion of the expression that wasn't matched),  then  the
       corresponding  subMatchVar  will  be  set  to ``-1 -1'' if
       -indices has been specified or to an empty  string  other-
       wise.


KEYWORDS
       match, regular expression, string



_________________________________________________________________

NAME
       registry - Manipulate the Windows registry

SYNOPSIS
       package require registry 1.0

       registry option keyName ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       The  registry package provides a general set of operations
       for manipulating the Windows registry.  The package imple-
       ments the registry Tcl command.  This command is only sup-
       ported on the Windows  platform.   Warning:  this  command
       should  be  used  with caution as a corrupted registry can
       leave your system in an unusable state.

       KeyName is the name of a registry key.  Registry keys must
       be one of the following forms:

              \\hostname\rootname\keypath

              rootname\keypath

              rootname

       Hostname specifies the name of any valid Windows host that
       exports its registry.  The rootname component must be  one
       of   HKEY_LOCAL_MACHINE,   HKEY_USERS,  HKEY_CLASSES_ROOT, 
       HKEY_CURRENT_USER,    HKEY_CURRENT_CONFIG,    HKEY_PERFOR-
       MANCE_DATA,  or  HKEY_DYN_DATA.  The keypath can be one or 
       more registry key names separated by backslash (\) charac-
       ters.

       Option  indicates  what  to do with the registry key name.
       Any unique abbreviation for  option  is  acceptable.   The
       valid options are:

       registry delete keyName ?valueName?
              If  the optional valueName argument is present, the
              specified value under keyName will be deleted  from
              the  registry.   If the optional valueName is omit-
              ted, the specified key and any  subkeys  or  values
              beneath  it  in  the  registry  hierarchy  will  be
              deleted.  If the key could not be deleted  then  an
              error  is generated.  If the key did not exist, the
              command has no effect.

       registry get keyName valueName
              Returns the data associated with the  value  value-
              Name  under  the key keyName.  If either the key or
              the value does not exist, then an error  is  gener-
              ated.   For  more  details  on  the  format  of the
              returned data, see SUPPORTED TYPES, below.

       registry keys keyName ?pattern?
              If pattern isn't specified, returns a list of names
              of all the subkeys of keyName.  If pattern is spec-
              ified,  only  those  names  matching  pattern   are
              returned.   Matching  is  determined using the same
              rules as for string match.  If the  specified  key-
              Name does not exist, then an error is generated.

       registry set keyName ?valueName data ?type??
              If  valueName isn't specified, creates the key key-
              Name if it doesn't already exist.  If valueName  is
              specified, creates the key keyName and value value-
              Name if necessary.  The contents of  valueName  are
              set  to  data  with the type indicated by type.  If
              type isn't specified, the type sz is assumed.   For
              more  details  on  the data and type arguments, see
              SUPPORTED TYPES below.

       registry type keyName valueName
              Returns the type of the value valueName in the  key
              keyName.   For  more  information  on  the possible
              types, see SUPPORTED TYPES, below.

       registry values keyName ?pattern?
              If pattern isn't specified, returns a list of names
              of all the values of keyName.  If pattern is speci-
              fied,  only  those  names  matching   pattern   are
              returned.   Matching  is  determined using the same
              rules as for string match.


SUPPORTED TYPES
       Each value under a key in the registry contains some  data
       of  a  particular  type in a type-specific representation.
       The registry command converts between this internal repre-
       sentation  and one that can be manipulated by Tcl scripts.
       In most cases, the  data  is  simply  returned  as  a  Tcl
       string.  The type indicates the intended use for the data,
       but does not actually change the representation.  For some
       types,  the registry command returns the data in a differ-
       ent form to make it easier to manipulate.   The  following
       types are recognized by the registry command:

       binary           The  registry  value  contains  arbitrary
                        binary data.   The  data  is  represented
                        exactly  in  Tcl,  including any embedded
                        nulls.

       none             The  registry  value  contains  arbitrary
                        binary  data  with  no defined type.  The
                        data  is  represented  exactly  in   Tcl,
                        including any embedded nulls.

       sz               The registry value contains a null-termi-
                        nated string.  The data is represented in
                        Tcl as a string.

       expand_sz        The registry value contains a null-termi-
                        nated  string  that  contains  unexpanded
                        references  to  environment  variables in
                        the normal Windows  style  (for  example,
                        "%PATH%").   The  data  is represented in
                        Tcl as a string.

       dword            The registry  value  contains  a  little-
                        endian 32-bit number.  The data is repre-
                        sented in Tcl as a decimal string.

       dword_big_endian The registry value contains a  big-endian
                        32-bit  number.   The data is represented
                        in Tcl as a decimal string.

       link             The registry value  contains  a  symbolic
                        link.  The data is represented exactly in
                        Tcl, including any embedded nulls.

       multi_sz         The registry value contains an  array  of
                        null-terminated  strings.   The  data  is
                        represented in Tcl as a list of  strings.

       resource_list    The  registry  value  contains  a device-
                        driver resource list.  The data is repre-
                        sented  exactly  in  Tcl,  including  any
                        embedded nulls.

       In addition to the symbolically named types listed  above,
       unknown  types  are identified using a 32-bit integer that
       corresponds to the type code returned by the system inter-
       faces.   In  this case, the data is represented exactly in
       Tcl, including any embedded nulls.


PORTABILITY ISSUES
       The registry command is only available on Windows.


KEYWORDS
       registry



_________________________________________________________________

NAME
       regsub - Perform substitutions based on regular expression
       pattern matching

SYNOPSIS
       regsub ?switches? exp string subSpec ?varName?             
_________________________________________________________________


DESCRIPTION
       This command matches the regular  expression  exp  against
       string,  and  either  copies  string to the variable whose 
       name is given by varName or returns string if  varName  is 
       not present.  (Regular expression matching is described in
       the re_syntax reference page.)  If there is a match,  then
       while  copying string to varName (or to the result of this 
       command if varName is not present) the portion  of  string
       that  matched  exp  is  replaced with subSpec.  If subSpec
       contains a ``&'' or ``\0'', then it  is  replaced  in  the
       substitution  with the portion of string that matched exp.
       If subSpec contains a ``\n'', where n is a digit between 1
       and  9,  then  it is replaced in the substitution with the
       portion of string  that  matched  the  n-th  parenthesized
       subexpression  of exp.  Additional backslashes may be used
       in subSpec to prevent special interpretation of  ``&''  or
       ``\0''  or ``\n'' or backslash.  The use of backslashes in
       subSpec tends to interact badly with the Tcl parser's  use
       of  backslashes,  so it's generally safest to enclose sub-
       Spec in braces if it includes backslashes.

       If the initial arguments to regexp start with - then  they
       are  treated as switches.  The following switches are cur-
       rently supported:

       -all      All ranges in string that match  exp  are  found
                 and  substitution is performed for each of these
                 ranges.  Without  this  switch  only  the  first
                 matching  range  is  found  and substituted.  If
                 -all  is  specified,  then  ``&''   and   ``\n''
                 sequences  are  handled  for  each  substitution
                 using the  information  from  the  corresponding
                 match.

       -expanded      Enables use of the expanded regular expres-
                      sion syntax where whitespace  and  comments
                      are  ignored.  This is the same as specify-
                      ing  the  (?x)  embedded  option  (see  the
                      re_syntax manual page).

       -line          Enables   newline-sensitive  matching.   By
                      default, newline is a  completely  ordinary
                      character  with  no  special meaning.  With
                      this flag, `[^' bracket expressions and `.'
                      never  match  newline, `^' matches an empty
                      string after any newline in addition to its
                      normal  function,  and `$' matches an empty
                      string before any newline  in  addition  to
                      its  normal function.  This flag is equiva-
                      lent to specifying both -linestop and -lin-
                      eanchor,  or  the (?n) embedded option (see
                      the re_syntax manual page).

       -linestop      Changes  the  behavior  of   `[^'   bracket
                      expressions  and  `.'  so that they stop at
                      newlines.  This is the same  as  specifying
                      the (?p) embedded option (see the re_syntax
                      manual page).

       -lineanchor    Changes the behavior of `^'  and  `$'  (the
                      ``anchors'')  so  they  match the beginning
                      and end of a line  respectively.   This  is
                      the  same  as  specifying the (?w) embedded
                      option (see the re_syntax manual page).

       -nocase   Upper-case characters in  string  will  be  con-
                 verted  to  lower-case  before  matching against
                 exp;  however, substitutions specified  by  sub-
                 Spec   use  the  original  unconverted  form  of
                 string.

       -start index
                 Specifies a  character  index  offset  into  the
                 string  to start matching the regular expression
                 at.  When using this switch, `^' will not  match
                 the  beginning  of  the  line, and \A will still
                 match the start of the string at  index.   index
                 will  be  constrained to the bounds of the input
                 string.

       --        Marks the end of switches.  The argument follow-
                 ing  this  one will be treated as exp even if it
                 starts with a -.

       If varName is supplied, the command returns a count of the 
       number  of  matching  ranges that were found and replaced, 
       otherwise the string after replacement is  returned.   See
       the manual entry for regexp for details on the interpreta-
       tion of regular expressions.


KEYWORDS
       match, pattern, regular expression, substitute


_________________________________________________________________

NAME
       rename - Rename or delete a command

SYNOPSIS
       rename oldName newName
_________________________________________________________________


DESCRIPTION
       Rename  the command that used to be called oldName so that
       it is now called newName.  If newName is an  empty  string
       then  oldName is deleted.  oldName and newName may include
       namespace qualifiers (names of containing namespaces).  If
       a  command  is  renamed into a different namespace, future
       invocations of it will execute in the new namespace.   The
       rename command returns an empty string as result.


KEYWORDS
       command, delete, namespace, rename


_________________________________________________________________

NAME
       resource - Manipulate Macintosh resources

SYNOPSIS
       resource option ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       The  resource command provides some generic operations for
       dealing with Macintosh resources.  This  command  is  only
       supported  on the Macintosh platform.  Each Macintosh file
       consists of two forks: a data fork and  a  resource  fork.
       You  use  the  normal  open, puts, close, etc. commands to
       manipulate the data fork.  You must use this command, how-
       ever,  to  interact  with the resource fork.  Option indi-
       cates what resource command to perform.  Any unique abbre-
       viation for option is acceptable.  The valid options are:

       resource close rsrcRef
              Closes  the given resource reference (obtained from
              resource open).  Resources from that resource  file
              will no longer be available.

       resource delete ?options? resourceType
              This  command will delete the resource specified by
              options and type resourceType (see  RESOURCE  TYPES
              below).  The options give you several ways to spec-
              ify the resource to be deleted.

              -id resourceId
                     If the -id option is given the id resourceId
                     (see  RESOURCE IDS below) is used to specify
                     the resource to be deleted.  The id must  be
                     a  number  - to specify a name use the -name
                     option.

              -name resourceName
                     If -name is specified,  the  resource  named
                     resourceName will be deleted.  If the -id is
                     also provided, then there must be a resource
                     with BOTH this name and this id.  If no name
                     is  provided,  then  the  id  will  be  used
                     regardless   of   the  name  of  the  actual
                     resource.

              -file resourceRef
                     If the -file option is  specified  then  the
                     resource  will  be  deleted  from  the  file
                     pointed to by  resourceRef.   Otherwise  the
                     first  resource  with the given resourceName
                     and or resourceId  which  is  found  on  the
                     resource  file  path  will  be  deleted.  To
                     inspect the  file  path,  use  the  resource
                     files command.

       resource files ?resourceRef?
              If resourceRefis not provided, this command returns
              a Tcl list of the resource references for  all  the
              currently  open resource files.  The list is in the
              normal Macintosh search order  for  resources.   If
              resourceRef  is  specified, the command will return
              the path to the file whose resource fork is  repre-
              sented by that token.

       resource list resourceType ?resourceRef?
              List  all of the resources ids of type resourceType
              (see RESOURCE  TYPES  below).   If  resourceRef  is
              specified then the command will limit the search to
              that  particular  resource  file.   Otherwise,  all
              resource  files currently opened by the application
              will  be  searched.   A  Tcl  list  of  either  the
              resource  name's  or  resource  id's  of  the found
              resources will be returned.  See the  RESOURCE  IDS
              section   below  for  more  details  about  what  a
              resource id is.

       resource open fileName ?access?
              Open the resource for the file fileName.   Standard
              file  access permissions may also be specified (see
              the manual entry for open for details).  A resource
              reference  (resourceRef)  is  returned  that can be
              used by the other resource commands.  An error  can
              occur  if  the  file doesn't exist or the file does
              not have a resource fork.  However, if you open the
              file   with   write  permissions  the  file  and/or
              resource fork will be created instead of generating
              an error.

       resource read resourceType resourceId ?resourceRef?
              Read  the entire resource of type resourceType (see
              RESOURCE TYPES below) and the name or id of resour-
              ceId  (see  RESOURCE  IDS  below)  into  memory and
              return the result.  If resourceRef is specified  we
              limit  our  search to that resource file, otherwise
              we search all open resource forks in  the  applica-
              tion.   It is important to note that most Macintosh
              resource use a binary format and the data  returned
              from  this command may have embedded NULLs or other
              non-ASCII data.

       resource types ?resourceRef?
              This command returns a Tcl  list  of  all  resource
              types  (see  RESOURCE  TYPES  below)  found  in the
              resource  file  pointed  to  by  resourceRef.    If
              resourceRef is not specified it will return all the
              resource types found in every  resource  file  cur-
              rently opened by the application.

       resource write ?options? resourceType data
              This command will write the passed in data as a new
              resource of type resourceType (see  RESOURCE  TYPES
              below).    Several   options   are  available  that
              describe where and how the resource is stored.

              -id resourceId
                     If the -id option is given the id resourceId
                     (see RESOURCE IDS below) is used for the new
                     resource, otherwise a unique id will be gen-
                     erated  that  will  not  conflict  with  any
                     existing resource.  However, the id must  be
                     a  number  - to specify a name use the -name
                     option.

              -name resourceName
                     If -name is specified the resource  will  be
                     named  resourceName,  otherwise it will have
                     the empty string as the name.

              -file resourceRef
                     If the -file option is  specified  then  the
                     resource will be written in the file pointed
                     to  by  resourceRef,  otherwise   the   most
                     recently open resource will be used.

              -force If  the target resource already exists, then
                     by default Tcl will not  overwrite  it,  but
                     raise an error instead.  Use the -force flag
                     to force overwriting the extant resource.


RESOURCE TYPES
       Resource types are defined as a four character string that
       is  then  mapped  to  an underlying id.  For example, TEXT
       refers to the Macintosh resource type for text.  The  type
       STR#   is  a  list  of  counted  strings.   All  Macintosh
       resources must be of some type.  See Macintosh  documenta-
       tion  for  a more complete list of resource types that are
       commonly used.


RESOURCE IDS
       For this command the notion  of  a  resource  id  actually
       refers  to  two ideas in Macintosh resources.  Every place
       you can use a resource Id you can use either the  resource
       name  or  a resource number.  Names are always searched or
       returned in  preference  to  numbers.   For  example,  the
       resource  list  command will return names if they exist or
       numbers if the name is NULL.


PORTABILITY ISSUES
       The resource command is only available on Macintosh.


KEYWORDS
       open, resource


_________________________________________________________________

NAME
       return - Return from a procedure

SYNOPSIS
       return  ?-code  code?  ?-errorinfo info? ?-errorcode code?
       ?string?
_________________________________________________________________


DESCRIPTION
       Return immediately from the  current  procedure  (or  top-
       level  command  or  source  command),  with  string as the
       return value.  If string is not specified  then  an  empty
       string will be returned as result.


EXCEPTIONAL RETURNS
       In  the  usual case where the -code option isn't specified
       the procedure will return normally  (its  completion  code
       will be TCL_OK).  However, the -code option may be used to
       generate an exceptional return from the  procedure.   Code
       may have any of the following values:

       ok        Normal  return:   same as if the option is omit-
                 ted.

       error     Error return: same as if the error command  were
                 used to terminate the procedure, except for han-
                 dling of errorInfo and errorCode variables  (see
                 below).

       return    The current procedure will return with a comple-
                 tion code of TCL_RETURN, so that  the  procedure
                 that invoked it will return also.

       break     The current procedure will return with a comple-
                 tion code of TCL_BREAK, which will terminate the
                 innermost  nested  loop in the code that invoked
                 the current procedure.

       continue  The current procedure will return with a comple-
                 tion  code of TCL_CONTINUE, which will terminate
                 the current iteration of  the  innermost  nested
                 loop in the code that invoked the current proce-
                 dure.

       value     Value must be an integer;  it will  be  returned
                 as  the  completion  code for the current proce-
                 dure.

       The -code option is rarely used.  It is provided  so  that
       procedures  that  implement  new  control  structures  can
       reflect exceptional conditions back to their callers.

       Two additional options, -errorinfo and -errorcode, may  be
       used   to  provide  additional  information  during  error
       returns.  These options are ignored unless code is  error.

       The -errorinfo option specifies an initial stack trace for
       the errorInfo variable;  if it is not specified  then  the
       stack trace left in errorInfo will include the call to the
       procedure and higher levels on the stack but it  will  not
       include  any  information  about  the context of the error
       within the procedure.  Typically the info  value  is  sup-
       plied  from the value left in errorInfo after a catch com-
       mand trapped an error within the procedure.

       If the -errorcode option is specified then code provides a
       value  for  the  errorCode variable.  If the option is not
       specified then errorCode will default to NONE.


KEYWORDS
       break, continue, error, procedure, return


_________________________________________________________________

NAME
       Safe Base - A mechanism for creating and manipulating safe
       interpreters.

SYNOPSIS
       ::safe::interpCreate ?slave? ?options...?

       ::safe::interpInit slave ?options...?

       ::safe::interpConfigure slave ?options...?

       ::safe::interpDelete slave

       ::safe::interpAddToAccessPath slave directory

       ::safe::interpFindInAccessPath slave directory

       ::safe::setLogCmd ?cmd arg...?

OPTIONS
       ?-accessPath pathList?   ?-statics  boolean?  ?-noStatics?
       ?-nested boolean? ?-nestedLoadOk?  ?-deleteHook script?
_________________________________________________________________


DESCRIPTION
       Safe  Tcl  is  a  mechanism  for  executing  untrusted Tcl
       scripts safely and for providing mediated access  by  such
       scripts to potentially dangerous functionality.

       The  Safe  Base  ensures that untrusted Tcl scripts cannot
       harm the hosting  application.   The  Safe  Base  prevents
       integrity  and  privacy attacks. Untrusted Tcl scripts are
       prevented from corrupting the state of the hosting  appli-
       cation  or  computer. Untrusted scripts are also prevented
       from disclosing information stored on the hosting computer
       or in the hosting application to any party.

       The  Safe Base allows a master interpreter to create safe,
       restricted interpreters that contain a set  of  predefined
       aliases  for  the  source,  load, file, encoding, and exit
       commands and are able to use the auto-loading and  package
       mechanisms.

       No knowledge of the file system structure is leaked to the
       safe interpreter, because it has access only to a virtual-
       ized  path  containing  tokens.  When the safe interpreter
       requests to source a file, it uses the token in  the  vir-
       tual  path  as part of the file name to source; the master
       interpreter transparently translates the token into a real
       directory  name  and executes the requested operation (see
       the section SECURITY below for details).  Different levels
       of security can be selected by using the optional flags of
       the commands described below.

       All commands provided in the  master  interpreter  by  the
       Safe Base reside in the safe namespace:


COMMANDS
       The  following  commands are provided in the master inter-
       preter:

       ::safe::interpCreate ?slave? ?options...?
              Creates a safe interpreter,  installs  the  aliases
              described  in  the  section ALIASES and initializes
              the auto-loading and package mechanism as specified
              by  the  supplied options.  See the OPTIONS section
              below for a description of the optional  arguments.
              If  the  slave  argument is omitted, a name will be
              generated.  ::safe::interpCreate always returns the
              interpreter name.

       ::safe::interpInit slave ?options...?
              This  command  is similar to interpCreate except it
              that does not create the  safe  interpreter.  slave
              must  have  been  created by some other means, like
              interp create -safe.

       ::safe::interpConfigure slave ?options...?
              If no options are given, returns the  settings  for
              all  options  for  the  named safe interpreter as a
              list of options and their current values  for  that
              slave.   If  a  single  additional argument is pro-
              vided, it will return a list of 2 elements name and
              value  where  name  is the full name of that option
              and value the current value for that option and the
              slave.   If  more than two additional arguments are
              provided, it will reconfigure the safe  interpreter
              and change each and only the provided options.  See
              the section on OPTIONS below for  options  descrip-
              tion.  Example of use:
                     # Create a new interp with the same configuration as "$i0" :
                     set i1 [eval safe::interpCreate [safe::interpConfigure $i0]]
                     # Get the current deleteHook
                     set dh [safe::interpConfigure $i0  -del]
                     # Change (only) the statics loading ok attribute of an interp
                     # and its deleteHook (leaving the rest unchanged) :
                     safe::interpConfigure $i0  -delete {foo bar} -statics 0 ;

       ::safe::interpDelete slave
              Deletes the safe interpreter and cleans up the cor-
              responding master interpreter data structures.   If
              a  deleteHook  script was specified for this inter-
              preter it is evaluated before  the  interpreter  is
              deleted,  with  the  name  of the interpreter as an
              additional argument.

       ::safe::interpFindInAccessPath slave directory
              This command finds and returns the  token  for  the
              real  directory directory in the safe interpreter's
              current virtual access path.  It generates an error
              if the directory is not found.  Example of use:
                     $slave eval [list set tk_library [::safe::interpFindInAccessPath $name $tk_library]]

       ::safe::interpAddToAccessPath slave directory
              This  command  adds  directory  to the virtual path
              maintained for the safe interpreter in the  master,
              and  returns the token that can be used in the safe
              interpreter to  obtain  access  to  files  in  that
              directory.  If the directory is already in the vir-
              tual path, it only returns the token without adding
              the  directory  to the virtual path again.  Example
              of use:
                     $slave eval [list set tk_library [::safe::interpAddToAccessPath $name $tk_library]]

       ::safe::setLogCmd ?cmd arg...?
              This command installs a script that will be  called
              when interesting life cycle events occur for a safe
              interpreter.  When called  with  no  arguments,  it
              returns   the  currently  installed  script.   When
              called with one argument, an empty string, the cur-
              rently  installed  script is removed and logging is
              turned off.  The script will be  invoked  with  one
              additional  argument, a string describing the event
              of interest.  The main purpose is to help in debug-
              ging  safe  interpreters.   Using this facility you
              can get complete  error  messages  while  the  safe
              interpreter gets only generic error messages.  This
              prevents a safe interpreter  from  seeing  messages
              about  failures and other events that might contain
              sensitive information such as real directory names.
              Example of use:
                     ::safe::setLogCmd puts stderr
              Below  is the output of a sample session in which a
              safe interpreter attempted to  source  a  file  not
              found  in  its  virtual access path.  Note that the
              safe interpreter only  received  an  error  message
              saying that the file was not found:
                     NOTICE for slave interp10 : Created
                     NOTICE for slave interp10 : Setting accessPath=(/foo/bar) staticsok=1 nestedok=0 deletehook=()
                     NOTICE for slave interp10 : auto_path in interp10 has been set to {$p(:0:)}
                     ERROR for slave interp10 : /foo/bar/init.tcl: no such file or directory


OPTIONS
       The  following options are common to ::safe::interpCreate,
       ::safe::interpInit,  and   ::safe::interpConfigure.    Any
       option  name can be abbreviated to its minimal non-ambigu-
       ous name.  Option names are not case sensitive.


       -accessPath directoryList
              This option sets the list of directories from which
              the safe interpreter can source and load files.  If
              this option is not specified, or if it is given  as
              the  empty  list, the safe interpreter will use the
              same directories as its  master  for  auto-loading.
              See  the  section  SECURITY  below  for more detail
              about virtual paths, tokens and access control.

       -statics boolean
              This option specifies if the safe interpreter  will
              be allowed to load statically linked packages (like
              load {} Tk).  The default  value  is  true  :  safe
              interpreters  are allowed to load statically linked
              packages.

       -noStatics
              This option is a convenience shortcut for  -statics
              false  and thus specifies that the safe interpreter
              will not be allowed to load statically linked pack-
              ages.

       -nested boolean
              This  option specifies if the safe interpreter will
              be allowed to load packages into its own sub-inter-
              preters.   The default value is false : safe inter-
              preters are not allowed to load packages into their
              own sub-interpreters.

       -nestedLoadOk
              This  option  is a convenience shortcut for -nested
              true and thus specifies the safe  interpreter  will
              be allowed to load packages into its own sub-inter-
              preters.

       -deleteHook script
              When this option is given an non empty  script,  it
              will  be  evaluated  in the master with the name of
              the safe interpreter as an additional argument just
              before  actually  deleting  the  safe  interpreter.
              Giving  an  empty  value  removes   any   currently
              installed deletion hook script for that safe inter-
              preter.  The default value ({}) is not to have  any
              deletion call back.

ALIASES
       The following aliases are provided in a safe interpreter:

       source fileName
              The  requested  file, a Tcl source file, is sourced
              into the safe interpreter  if  it  is  found.   The
              source alias can only source files from directories
              in the virtual path for the safe  interpreter.  The
              source  alias  requires the safe interpreter to use
              one of the token  names  in  its  virtual  path  to
              denote  the  directory  in  which  the  file  to be
              sourced can be found.  See the section on  SECURITY
              for  more discussion of restrictions on valid file-
              names.

       load fileName
              The requested file, a shared object file, is dynam-
              ically  loaded  into  the safe interpreter if it is
              found.  The filename must contain a token name men-
              tioned in the virtual path for the safe interpreter
              for it to be found successfully.  Additionally, the
              shared object file must contain a safe entry point;
              see the manual page for the load command  for  more
              details.

       file ?subCmd args...?
              The  file alias provides access to a safe subset of
              the subcommands of the file command; it allows only
              dirname,  join, extension, root, tail, pathname and
              split subcommands. For more details on  what  these
              subcommands  do  see  the  manual page for the file
              command.

       encoding ?subCmd args...?
              The encoding alias provides access to a safe subset
              of  the  subcommands  of  the encoding command;  it
              disallows  setting  of  the  system  encoding,  but
              allows  all  other  subcommands including system to
              check the current encoding.

       exit   The calling interpreter is deleted and its computa-
              tion  is stopped, but the Tcl process in which this
              interpreter exists is not terminated.


SECURITY
       The Safe Base  does  not  attempt  to  completely  prevent
       annoyance  and  denial  of service attacks. These forms of
       attack prevent the application or  user  from  temporarily
       using  the computer to perform useful work, for example by
       consuming all available CPU time or all  available  screen
       real estate.  These attacks, while aggravating, are deemed
       to be of lesser importance in general than  integrity  and
       privacy attacks that the Safe Base is to prevent.

       The  commands available in a safe interpreter, in addition
       to the safe set as defined  in  interp  manual  page,  are
       mediated  aliases for source, load, exit, and safe subsets
       of file and encoding. The safe interpreter can also  auto-
       load code and it can request that packages be loaded.

       Because  some of these commands access the local file sys-
       tem, there is a potential for  information  leakage  about
       its  directory  structure.  To prevent this, commands that
       take file names as arguments in  a  safe  interpreter  use
       tokens  instead of the real directory names.  These tokens
       are translated to the real directory name while a  request
       to,  e.g.,  source a file is mediated by the master inter-
       preter.  This virtual path system  is  maintained  in  the
       master  interpreter  for  each safe interpreter created by
       ::safe::interpCreate or initialized by  ::safe::interpInit
       and  the  path  maps  tokens accessible in the safe inter-
       preter into real path names on the local file system  thus
       preventing  safe interpreters from gaining knowledge about
       the structure of the file system of the host on which  the
       interpreter is executing.  The only valid file names argu-
       ments for the source and  load  aliases  provided  to  the
       slave  are  path in the form of [file join token filename]
       (ie, when using the native file path formats:  token/file-
       name  on  Unix, token\filename on Windows, and token:file-
       name on the Mac), where token is representing one  of  the
       directories  of  the  accessPath  list and filename is one
       file in that directory  (no  sub  directories  access  are
       allowed).

       When a token is used in a safe interpreter in a request to
       source or load a file, the token is checked and translated
       to  a  real path name and the file to be sourced or loaded
       is located on the file system.  The safe interpreter never
       gains  knowledge  of  the actual path name under which the
       file is stored on the file system.

       To further prevent potential information leakage from sen-
       sitive  files that are accidentally included in the set of
       files that can be  sourced  by  a  safe  interpreter,  the
       source alias restricts access to files meeting the follow-
       ing constraints: the file name must fourteen characters or
       shorter,  must  not  contain more than one dot ("."), must
       end up with the extension .tcl or be called tclIndex.

       Each element of the  initial  access  path  list  will  be
       assigned  a  token that will be set in the slave auto_path
       and the first element of that list  will  be  set  as  the
       tcl_library for that slave.

       If  the  access path argument is not given or is the empty
       list, the default behavior is to let the slave access  the
       same  packages  as the master has access to (Or to be more
       precise: only packages written in Tcl (which by definition
       can't  be  dangerous as they run in the slave interpreter)
       and C extensions that provides a Safe_Init  entry  point).
       For  that  purpose, the master's auto_path will be used to
       construct the slave access path.  In order that the  slave
       successfully  loads  the Tcl library files (which includes
       the auto-loading mechanism itself) the tcl_library will be
       added  or moved to the first position if necessary, in the
       slave access path, so the slave tcl_library  will  be  the
       same  as the master's (its real path will still be invisi-
       ble to the slave  though).   In  order  that  auto-loading
       works  the  same  for  the slave and the master in this by
       default case, the  first-level  sub  directories  of  each
       directory  in  the master auto_path will also be added (if
       not already included) to the slave access path.   You  can
       always  specify  a  more  restrictive  path  for which sub
       directories will never be searched by explicitly  specify-
       ing  your directory list with the -accessPath flag instead
       of relying on this default mechanism.

       When the accessPath is changed after the first creation or
       initialization  (ie  through  interpConfigure  -accessPath
       list), an auto_reset is  automatically  evaluated  in  the
       safe  interpreter  to  synchronize its auto_index with the
       new token list.


KEYWORDS
       alias,  auto-loading,  auto_mkindex,  load,  master inter-
       preter, safe interpreter, slave interpreter, source


_________________________________________________________________

NAME
       scan  -  Parse  string  using conversion specifiers in the
       style of sscanf

SYNOPSIS
       scan string format ?varName varName ...?
_________________________________________________________________


INTRODUCTION
       This command parses fields from an  input  string  in  the
       same  fashion as the ANSI C sscanf procedure and returns a
       count of the number of conversions performed, or -1 if the
       end  of the input string is reached before any conversions
       have been performed.  String gives the input to be  parsed
       and  format  indicates how to parse it, using % conversion
       specifiers as in sscanf.  Each varName gives the name of a
       variable;  when  a field is scanned from string the result
       is converted back into a string and assigned to the corre-
       sponding variable.  If no varName variables are specified,
       then scan works in an inline manner,  returning  the  data
       that would otherwise be stored in the variables as a list.
       In the inline case, an empty string is returned  when  the
       end  of the input string is reached before any conversions
       have been performed.


DETAILS ON SCANNING
       Scan operates by scanning string and format together.   If
       the  next  character  in  format is a blank or tab then it
       matches any number of white  space  characters  in  string
       (including  zero).   Otherwise,  if it isn't a % character
       then it must match the next character of string.  When a %
       is encountered in format, it indicates the start of a con-
       version specifier.  A conversion specifier contains up  to 
       four  fields  after  the  %: a *, which indicates that the 
       converted value is to be discarded instead of assigned  to 
       a variable; a XPG3 position specifier; a number indicating 
       a maximum field width; a field size modifier; and  a  con-
       version  character.   All  of  these  fields  are optional
       except for the conversion character.  The fields that  are
       present must appear in the order given above.

       When scan finds a conversion specifier in format, it first
       skips any white-space characters  in  string  (unless  the
       specifier  is  [  or  c).  Then it converts the next input
       characters  according  to  the  conversion  specifier  and
       stores  the result in the variable given by the next argu-
       ment to scan.

       If the % is followed by a decimal number and a  $,  as  in
       ``%2$d'',  then  the variable to use is not taken from the
       next sequential argument.  Instead, it is taken  from  the
       argument  indicated  by the number, where 1 corresponds to
       the first varName.  If there are any positional specifiers
       in  format  then all of the specifiers must be positional.
       Every varName on the  argument  list  must  correspond  to
       exactly one conversion specifier or an error is generated,
       or in the inline case, any position can  be  specified  at
       most  once  and the empty positions will be filled in with
       empty strings.

       The following conversion characters are supported:

       d         The input field must be a decimal  integer.   It
                 is  read in and the value is stored in the vari-
                 able as a decimal string.  If the l or  L  field 
                 size  modifier  is given, the scanned value will 
                 have an internal representation that is at least 
                 64-bits in size.

       o         The  input field must be an octal integer. It is
                 read in and the value is stored in the  variable
                 as  a  decimal string.  If the l or L field size 
                 modifier is given, the scanned value  will  have 
                 an  internal  representation  that  is  at least 
                 64-bits in size.  If the value  exceeds  MAX_INT 
                 (017777777777 on platforms using 32-bit integers 
                 when the l and L modifiers are  not  given),  it 
                 will  be  truncated to a signed integer.  Hence, 
                 037777777777 will  appear  as  -1  on  a  32-bit 
                 machine by default.

       x         The  input  field must be a hexadecimal integer.
                 It is read in and the value  is  stored  in  the
                 variable  as  a  decimal  string.  If the l or L 
                 field size modifier is given, the scanned  value 
                 will  have an internal representation that is at 
                 least 64-bits in size.   If  the  value  exceeds 
                 MAX_INT  (0x7FFFFFFF  on  platforms using 32-bit 
                 integers when the l  and  L  modifiers  are  not 
                 given),  it  will be truncated to a signed inte-
                 ger.  Hence, 0xFFFFFFFF will appear as -1  on  a 
                 32-bit machine.

       u         The  input field must be a decimal integer.  The
                 value is stored in the variable as  an  unsigned
                 decimal  integer  string.   If  the l or L field 
                 size modifier is given, the scanned  value  will 
                 have an internal representation that is at least 
                 64-bits in size.

       i         The input field must be an  integer.   The  base
                 (i.e.  decimal, octal, or hexadecimal) is deter-
                 mined in the same fashion as described in  expr.
                 The value is stored in the variable as a decimal


                 string.  If the l or L field  size  modifier  is 
                 given,  the  scanned value will have an internal 
                 representation that is at least 64-bits in size.

       c         A  single  character  is  read in and its binary
                 value is stored in the  variable  as  a  decimal
                 string.   Initial  white space is not skipped in
                 this case, so the input field may  be  a  white-
                 space  character.   This conversion is different
                 from the ANSI standard in that the  input  field
                 always  consists  of  a  single character and no
                 field width may be specified.

       s         The input field consists of all  the  characters
                 up  to the next white-space character; the char-
                 acters are copied to the variable.

       e or f or g
                 The input field must be a floating-point  number
                 consisting of an optional sign, a string of dec-
                 imal digits possibly containing a decimal point,
                 and an optional exponent consisting of an e or E
                 followed by an optional sign  and  a  string  of
                 decimal digits.  It is read in and stored in the
                 variable as a floating-point string.

       [chars]   The input field consists of any number of  char-
                 acters  in chars.  The matching string is stored
                 in the variable.  If the first character between
                 the  brackets  is a ] then it is treated as part
                 of chars rather than the closing bracket for the
                 set.   If  chars contains a sequence of the form
                 a-b then any character between a and  b  (inclu-
                 sive)  will match.  If the first or last charac-
                 ter between the brackets is  a  -,  then  it  is
                 treated  as part of chars rather than indicating
                 a range.

       [^chars]  The input field consists of any number of  char-
                 acters  not  in  chars.   The matching string is
                 stored in the variable.  If the character  imme-
                 diately  following  the  ^  is  a  ]  then it is
                 treated as part of the set rather than the clos-
                 ing  bracket  for  the set.  If chars contains a
                 sequence of the  form  a-b  then  any  character
                 between  a  and  b  (inclusive) will be excluded
                 from the set.  If the first  or  last  character
                 between  the brackets is a -, then it is treated
                 as part of chars rather than indicating a range.

       n         No  input  is  consumed  from  the input string.
                 Instead, the total number of characters  scanned
                 from  the  input  string so far is stored in the
                 variable.


       The number of characters read from the input for a conver-
       sion  is the largest number that makes sense for that par-
       ticular conversion (e.g.  as many decimal digits as possi-
       ble  for  %d, as many octal digits as possible for %o, and
       so on).  The input field for a given conversion terminates
       either when a white-space character is encountered or when
       the maximum field width has been reached, whichever  comes
       first.  If a * is present in the conversion specifier then
       no variable is assigned and the next scan argument is  not
       consumed.


DIFFERENCES FROM ANSI SSCANF
       The behavior of the scan command is the same as the behav-
       ior of the ANSI C sscanf procedure except for the  follow-
       ing differences:

       [1]    %p conversion specifier is not currently supported.

       [2]    For %c conversions a single character value is con-
              verted  to a decimal string, which is then assigned
              to the corresponding varName; no field width may be
              specified for this conversion.

       [3]    The  h  modifier  is always ignored and the l and L 
              modifiers are ignored when converting  real  values 
              (i.e.  type  double is used for the internal repre-
              sentation).

       [4]    If the end of the input string  is  reached  before
              any  conversions  have  been performed and no vari-
              ables are given, an empty string is returned.


KEYWORDS
       conversion specifier, parse, scan


_________________________________________________________________

NAME
       seek - Change the access position for an open channel

SYNOPSIS
       seek channelId offset ?origin?
_________________________________________________________________


DESCRIPTION
       Changes the current access position for channelId.

       ChannelId  must  be an identifier for an open channel such 
       as a Tcl standard channel (stdin, stdout, or stderr),  the 
       return  value from an invocation of open or socket, or the 
       result of a channel creation command  provided  by  a  Tcl 
       extension.

       The  offset  and  origin arguments specify the position at
       which the next read or write  will  occur  for  channelId.
       Offset must be an integer (which may be negative) and ori-
       gin must be one of the following:

       start     The new access position  will  be  offset  bytes
                 from the start of the underlying file or device.

       current   The new access position  will  be  offset  bytes
                 from  the  current  access  position; a negative
                 offset moves the access  position  backwards  in
                 the underlying file or device.

       end       The  new  access  position  will be offset bytes
                 from the end of the file or device.  A  negative
                 offset places the access position before the end
                 of file, and a positive offset places the access
                 position after the end of file.

       The origin argument defaults to start.

       The  command  flushes  all buffered output for the channel
       before the command returns, even if the channel is in non-
       blocking  mode.   It also discards any buffered and unread
       input.  This command returns an empty  string.   An  error
       occurs if this command is applied to channels whose under-
       lying file or device does not support seeking.

       Note that offset values are byte  offsets,  not  character 
       offsets.   Both  seek  and tell operate in terms of bytes, 
       not characters, unlike read.


KEYWORDS
       access position, file, seek


_________________________________________________________________

NAME
       set - Read and write variables

SYNOPSIS
       set varName ?value?
_________________________________________________________________


DESCRIPTION
       Returns the value of variable varName.  If value is speci-
       fied, then set the value of varName to value,  creating  a
       new  variable if one doesn't already exist, and return its
       value.  If varName contains an open parenthesis  and  ends
       with  a close parenthesis, then it refers to an array ele-
       ment:  the characters before the  first  open  parenthesis
       are  the name of the array, and the characters between the
       parentheses are the index  within  the  array.   Otherwise
       varName refers to a scalar variable.  Normally, varName is
       unqualified (does not include the names of any  containing
       namespaces),  and the variable of that name in the current
       namespace is read or written.  If varName includes  names-
       pace  qualifiers  (in  the  array  name if it refers to an
       array element), the variable in the specified namespace is
       read or written.

       If no procedure is active, then varName refers to a names-
       pace variable (global variable if the current namespace is
       the  global  namespace).   If  a procedure is active, then
       varName refers to a parameter or  local  variable  of  the
       procedure unless the global command was invoked to declare
       varName to be global, or unless  a  variable  command  was
       invoked to declare varName to be a namespace variable.


KEYWORDS
       read, write, variable


_________________________________________________________________

NAME
       socket - Open a TCP network connection

SYNOPSIS
       socket ?options? host port

       socket -server command ?options? port
_________________________________________________________________


DESCRIPTION
       This  command opens a network socket and returns a channel
       identifier that may be used in future invocations of  com-
       mands  like read, puts and flush.  At present only the TCP
       network  protocol  is  supported;   future  releases   may
       include support for additional protocols.  The socket com-
       mand may be used to open either the client or server  side
       of  a  connection, depending on whether the -server switch
       is specified.


CLIENT SOCKETS
       If the -server option is not specified,  then  the  client
       side  of  a connection is opened and the command returns a
       channel identifier that can be used for both  reading  and
       writing.   Port  and  host  specify  a port to connect to;
       there must be a server accepting connections on this port.
       Port  is  an  integer  port  number  and  host is either a
       domain-style name such as www.sunlabs.com or  a  numerical
       IP  address  such as 127.0.0.1.  Use localhost to refer to
       the host on which the command is invoked.

       The following options may also be present before  host  to
       specify additional information about the connection:

       -myaddr addr
              Addr  gives  the  domain-style name or numerical IP
              address of the client-side network interface to use
              for  the  connection.  This option may be useful if
              the client machine has multiple network interfaces.
              If  the  option  is  omitted  then  the client-side
              interface will be chosen by the system software.

       -myport port
              Port specifies an integer port number  to  use  for
              the  client's  side  of  the  connection.   If this
              option is omitted, the client's port number will be
              chosen at random by the system software.

       -async The  -async  option will cause the client socket to
              be connected asynchronously. This  means  that  the
              socket  will be created immediately but may not yet
              be connected to the server, when the call to socket
              returns. When a gets or flush is done on the socket
              before the connection attempt succeeds or fails, if
              the  socket is in blocking mode, the operation will
              wait until the connection is completed or fails. If
              the  socket  is  in  nonblocking mode and a gets or
              flush is done on the socket before  the  connection
              attempt  succeeds  or  fails, the operation returns
              immediately and fblocked on the socket returns 1.


SERVER SOCKETS
       If the -server option is specified  then  the  new  socket
       will  be  a  server  for the port given by port.  Tcl will
       automatically accept connections to the given  port.   For
       each  connection Tcl will create a new channel that may be
       used to communicate with the  client.   Tcl  then  invokes
       command  with  three additional arguments: the name of the
       new channel, the address, in network address notation,  of
       the client's host, and the client's port number.

       The  following  additional  option  may  also be specified
       before host:

       -myaddr addr
              Addr gives the domain-style name  or  numerical  IP
              address of the server-side network interface to use
              for the connection.  This option may be  useful  if
              the server machine has multiple network interfaces.
              If the option is omitted then the server socket  is
              bound  to the special address INADDR_ANY so that it
              can accept connections from any interface.

       Server channels cannot be used for input or output;  their
       sole use is to accept new client connections. The channels
       created for each incoming client connection are opened for
       input  and  output.  Closing the server channel shuts down
       the server so that no new connections  will  be  accepted;
       however, existing connections will be unaffected.

       Server  sockets  depend on the Tcl event mechanism to find
       out when new connections are opened.  If  the  application
       doesn't  enter the event loop, for example by invoking the
       vwait command or calling the C  procedure  Tcl_DoOneEvent,
       then no connections will be accepted.

       If  port  is  specified as zero, the operating system will
       allocate an unused port for use as a server  socket.   The
       port  number  actually  allocated my be retrieved from the
       created server socket  using  the  fconfigure  command  to
       retrieve the -sockname option as described below.


CONFIGURATION OPTIONS
       The  fconfigure command can be used to query several read-
       only configuration options for socket channels:

       -error This option gets the current error  status  of  the
              given  socket.   This  is  useful  when you need to
              determine if an asynchronous connect operation suc-
              ceeded.   If  there was an error, the error message
              is returned.  If  there  was  no  error,  an  empty
              string is returned.

       -sockname
              This  option  returns a list of three elements, the
              address, the host name and the port number for  the
              socket.  If  the  host name cannot be computed, the
              second element is identical  to  the  address,  the
              first element of the list.

       -peername
              This option is not supported by server sockets. For
              client and accepted sockets, this option returns  a
              list  of three elements; these are the address, the
              host name and the port to which the peer socket  is
              connected or bound. If the host name cannot be com-
              puted, the second element of the list is  identical
              to the address, its first element.


KEYWORDS
       bind,  channel,  connection,  domain  name,  host, network
       address, socket, tcp


_________________________________________________________________

NAME
       source - Evaluate a file or resource as a Tcl script

SYNOPSIS
       source fileName

       source -rsrc resourceName ?fileName?

       source -rsrcid resourceId ?fileName?
_________________________________________________________________


DESCRIPTION
       This  command  takes the contents of the specified file or
       resource and passes it to the Tcl interpreter  as  a  text
       script.   The return value from source is the return value
       of the last command executed in the script.  If  an  error
       occurs  in  evaluating the contents of the script then the
       source command will return that error.  If a  return  com-
       mand  is invoked from within the script then the remainder
       of the file will be skipped and the  source  command  will
       return normally with the result from the return command.

       The  end-of-file character for files is '\32' (^Z) for all 
       platforms.  The source command will read files up to  this 
       character.   This  restriction does not exist for the read 
       or gets commands, allowing for files containing  code  and 
       data  segments  (scripted  documents).   If  you require a 
       ``^Z'' in code for string comparison, you can use ``\032'' 
       or ``\u001a'', which will be safely substituted by the Tcl 
       interpreter into ``^Z''.

       The -rsrc and -rsrcid  forms  of  this  command  are  only
       available  on  Macintosh computers.  These versions of the
       command allow you to source a script from a TEXT resource.
       You  may  specify  what  TEXT resource to source by either
       name or id.  By default Tcl  searches  all  open  resource
       files,  which  include  the  current  application  and any
       loaded C extensions.  Alternatively, you may  specify  the
       fileName where the TEXT resource can be found.


KEYWORDS
       file, script


_________________________________________________________________

NAME
       split - Split a string into a proper Tcl list

SYNOPSIS
       split string ?splitChars?
_________________________________________________________________


DESCRIPTION
       Returns a list created by splitting string at each charac-
       ter that is in the splitChars argument.  Each  element  of
       the result list will consist of the characters from string
       that  lie  between  instances   of   the   characters   in
       splitChars.   Empty  list  elements  will  be generated if
       string contains adjacent characters in splitChars,  or  if
       the  first  or  last character of string is in splitChars.
       If splitChars is an empty string then  each  character  of
       string  becomes  a  separate  element  of the result list.
       SplitChars defaults to the  standard  white-space  charac-
       ters.  For example,
              split "comp.unix.misc" .
       returns "comp unix misc" and
              split "Hello world" {}
       returns "H e l l o { } w o r l d".


KEYWORDS
       list, split, string


_________________________________________________________________

NAME
       string - Manipulate strings

SYNOPSIS
       string option arg ?arg ...?
_________________________________________________________________


DESCRIPTION
       Performs  one  of  several string operations, depending on
       option.  The legal options (which may be abbreviated) are:

       string bytelength string
              Returns a decimal string giving the number of bytes
              used to represent string in memory.  Because  UTF-8
              uses  one to three bytes to represent Unicode char-
              acters, the byte length will not be the same as the
              character  length  in  general.   The cases where a
              script cares about the byte length  are  rare.   In
              almost  all cases, you should use the string length
              operation (including determining the  length  of  a
              Tcl  ByteArray  object).   Refer  to the Tcl_NumUt-
              fChars manual entry for more details on  the  UTF-8
              representation.

       string compare ?-nocase? ?-length int? string1 string2
              Perform   a  character-by-character  comparison  of
              strings string1 and string2.  Returns -1, 0, or  1,
              depending  on  whether string1 is lexicographically
              less than, equal to, or greater than  string2.   If
              -length  is  specified,  then only the first length
              characters are used in the comparison.  If  -length
              is  negative,  it is ignored.  If -nocase is speci-
              fied, then the strings  are  compared  in  a  case-
              insensitive manner.

       string equal ?-nocase? ?-length int? string1 string2
              Perform   a  character-by-character  comparison  of
              strings string1 and string2.  Returns 1 if  string1
              and  string2  are  identical,  or  0  when not.  If
              -length is specified, then only  the  first  length
              characters  are used in the comparison.  If -length
              is negative, it is ignored.  If -nocase  is  speci-
              fied,  then  the  strings  are  compared in a case-
              insensitive manner.

       string first string1 string2 ?startIndex?
              Search string2 for a sequence  of  characters  that
              exactly match the characters in string1.  If found,
              return the index of  the  first  character  in  the
              first  such  match  within  string2.  If not found,
              return -1.  If startIndex is specified (in  any  of


              the  forms  accepted by the index method), then the
              search is constrained to start with  the  character
              in string2 specified by the index.  For example,
                     string first a 0a23456789abcdef 5
              will return 10, but
                     string first a 0123456789abcdef 11
              will return -1.

       string index string charIndex
              Returns  the  charIndex'th  character of the string
              argument.  A charIndex  of  0  corresponds  to  the
              first  character  of  the string.  charIndex may be
              specified as follows:

              integer   The  char  specified  at  this   integral
                        index.

              end       The last char of the string.

              end-integer
                        The  last  char  of  the string minus the
                        specified  integer  offset  (e.g.   end-1
                        would refer to the "c" in "abcd").

              If  charIndex  is  less  than  0 or greater than or
              equal to the length of the  string  then  an  empty
              string is returned.

       string is class ?-strict? ?-failindex varname? string
              Returns 1 if string is a valid member of the speci-
              fied character  class,  otherwise  returns  0.   If
              -strict  is specified, then an empty string returns
              0, otherwise and empty string will return 1 on  any
              class.   If  -failindex  is  specified, then if the
              function returns 0, the index in the  string  where
              the class was no longer valid will be stored in the
              variable named varname.  The varname  will  not  be
              set if the function returns 1.  The following char-
              acter classes are recognized (the class name can be
              abbreviated):

              alnum     Any  Unicode alphabet or digit character.

              alpha     Any Unicode alphabet character.

              ascii     Any character  with  a  value  less  than
                        \u0080 (those that are in the 7-bit ascii
                        range).

              boolean   Any of  the  forms  allowed  to  Tcl_Get-
                        Boolean.

              control   Any Unicode control character.


              digit     Any  Unicode  digit character.  Note that
                        this includes characters outside  of  the
                        [0-9] range.

              double    Any  of  the  valid forms for a double in
                        Tcl, with  optional  surrounding  whites-
                        pace.   In  case of under/overflow in the
                        value, 0 is returned and the varname will
                        contain -1.

              false     Any  of  the  forms  allowed  to Tcl_Get-
                        Boolean where the value is false.

              graph     Any Unicode  printing  character,  except
                        space.

              integer   Any  of the valid forms for an integer in
                        Tcl, with  optional  surrounding  whites-
                        pace.   In  case of under/overflow in the
                        value, 0 is returned and the varname will
                        contain -1.

              lower     Any  Unicode  lower case alphabet charac-
                        ter.

              print     Any Unicode printing character, including
                        space.

              punct     Any Unicode punctuation character.

              space     Any Unicode space character.

              true      Any  of  the  forms  allowed  to Tcl_Get-
                        Boolean where the value is true.

              upper     Any upper case alphabet character in  the
                        Unicode character set.

              wordchar  Any  Unicode word character.  That is any
                        alphanumeric character, and  any  Unicode
                        connector  punctuation  characters  (e.g.
                        underscore).

              xdigit    Any    hexadecimal    digit     character
                        ([0-9A-Fa-f]).

              In  the  case  of  boolean,  true and false, if the
              function will  return  0,  then  the  varname  will
              always  be  set to 0, due to the varied nature of a
              valid boolean value.

       string last string1 string2 ?lastIndex?
              Search string2 for a sequence  of  characters  that
              exactly match the characters in string1.  If found,
              return the index of the first character in the last
              such  match  within string2.  If there is no match,
              then return -1.  If lastIndex is specified (in  any
              of  the  forms  accepted by the index method), then
              only the characters in string2  at  or  before  the
              specified  lastIndex  will  be  considered  by  the
              search.  For example,
                     string last a 0a23456789abcdef 15
              will return 10, but
                     string last a 0a23456789abcdef 9
              will return 1.

       string length string
              Returns a decimal string giving the number of char-
              acters  in string.  Note that this is not necessar-
              ily the same as the number of bytes used  to  store
              the  string.   If  the object is a ByteArray object
              (such as  those  returned  from  reading  a  binary
              encoded  channel), then this will return the actual
              byte length of the object.

       string map ?-nocase? charMap string
              Replaces characters in string  based  on  the  key-
              value  pairs  in charMap.  charMap is a list of key
              value key value ...  as in  the  form  returned  by
              array  get.   Each  instance of a key in the string
              will be replaced with its corresponding value.   If
              -nocase is specified, then matching is done without
              regard to case differences. Both key and value  may
              be  multiple characters.  Replacement is done in an
              ordered manner, so the key appearing first  in  the
              list  will  be checked first, and so on.  string is
              only iterated over once, so  earlier  key  replace-
              ments  will  have  no affect for later key matches.
              For example,
                     string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc
              will return the string 01321221.

       string match ?-nocase? pattern string
              See if pattern matches string; return 1 if it does,
              0 if it doesn't.  If -nocase is specified, then the
              pattern attempts to match against the string  in  a
              case  insensitive  manner.   For the two strings to
              match, their contents must be identical except that
              the  following special sequences may appear in pat-
              tern:

              *         Matches any  sequence  of  characters  in
                        string, including a null string.

              ?         Matches any single character in string.

              [chars]   Matches any character in the set given by
                        chars.  If a sequence  of  the  form  x-y


                        appears  in  chars,  then  any  character
                        between x and y, inclusive,  will  match.
                        When used with -nocase, the end points of
                        the range are  converted  to  lower  case
                        first.   Whereas {[A-z]} matches '_' when
                        matching  case-sensitively   ('_'   falls
                        between  the  'Z'  and 'a'), with -nocase
                        this is considered like  {[A-Za-z]}  (and
                        probably  what  was  meant  in  the first
                        place).

              \x        Matches the  single  character  x.   This
                        provides  a  way  of avoiding the special
                        interpretation of the characters *?[]\ in
                        pattern.

       string range string first last
              Returns  a  range  of  consecutive  characters from
              string, starting with the character whose index  is
              first  and ending with the character whose index is
              last. An index of 0 refers to the  first  character
              of  the string.  first and last may be specified as
              for the index method.  If first is less  than  zero
              then  it is treated as if it were zero, and if last
              is greater than or  equal  to  the  length  of  the
              string  then  it  is treated as if it were end.  If
              first is greater than last then an empty string  is
              returned.

       string repeat string count
              Returns string repeated count number of times.

       string replace string first last ?newstring?
              Removes  a  range  of  consecutive  characters from
              string, starting with the character whose index  is
              first  and ending with the character whose index is
              last.  An index of 0 refers to the first  character
              of  the string.  First and last may be specified as
              for the index method.  If newstring  is  specified,
              then  it  is placed in the removed character range.
              If first is less than zero then it is treated as if
              it  were zero, and if last is greater than or equal
              to the length of the string then it is  treated  as
              if  it  were end.  If first is greater than last or
              the length of the initial string, or last  is  less
              than   0,  then  the  initial  string  is  returned
              untouched.

       string tolower string ?first? ?last?
              Returns a value equal to  string  except  that  all
              upper  (or  title) case letters have been converted
              to lower case.  If first is specified, it refers to
              the first char index in the string to start modify-
              ing.  If last is specified, it refers to  the  char
              index  in the string to stop at (inclusive).  first
              and last may be specified as for the index  method.

       string totitle string ?first? ?last?
              Returns  a  value  equal  to string except that the
              first character in string is converted to its  Uni-
              code  title case variant (or upper case if there is
              no title case variant) and the rest of  the  string
              is converted to lower case.  If first is specified,
              it refers to the first char index in the string  to
              start  modifying.   If last is specified, it refers
              to the char index in the string to stop at  (inclu-
              sive).   first and last may be specified as for the
              index method.

       string toupper string ?first? ?last?
              Returns a value equal to  string  except  that  all
              lower  (or  title) case letters have been converted
              to upper case.  If first is specified, it refers to
              the first char index in the string to start modify-
              ing.  If last is specified, it refers to  the  char
              index  in the string to stop at (inclusive).  first
              and last may be specified as for the index  method.

       string trim string ?chars?
              Returns  a  value  equal  to string except that any
              leading or trailing characters from the  set  given
              by  chars  are  removed.  If chars is not specified
              then white space is  removed  (spaces,  tabs,  new-
              lines, and carriage returns).

       string trimleft string ?chars?
              Returns  a  value  equal  to string except that any
              leading characters from the set given by chars  are
              removed.   If  chars  is  not  specified then white
              space is removed (spaces, tabs, newlines, and  car-
              riage returns).

       string trimright string ?chars?
              Returns  a  value  equal  to string except that any
              trailing characters from the set given by chars are
              removed.   If  chars  is  not  specified then white
              space is removed (spaces, tabs, newlines, and  car-
              riage returns).

       string wordend string charIndex
              Returns  the  index of the character just after the
              last one in the word containing character charIndex
              of  string.   charIndex may be specified as for the
              index method.  A word is considered to be any  con-
              tiguous  range  of alphanumeric (Unicode letters or
              decimal digits) or  underscore  (Unicode  connector
              punctuation)  characters,  or  any single character
              other than these.


       string wordstart string charIndex
              Returns the index of the  first  character  in  the
              word  containing  character  charIndex  of  string.
              charIndex may be specified as for the index method.
              A  word is considered to be any contiguous range of
              alphanumeric (Unicode letters or decimal digits) or
              underscore  (Unicode connector punctuation) charac-
              ters, or any single character other than these.


KEYWORDS
       case conversion, compare, index, match,  pattern,  string,
       word, equal, ctype


_________________________________________________________________

NAME
       subst - Perform backslash, command, and variable substitu-
       tions

SYNOPSIS
       subst ?-nobackslashes? ?-nocommands? ?-novariables? string
_________________________________________________________________


DESCRIPTION
       This command performs variable substitutions, command sub-
       stitutions, and  backslash  substitutions  on  its  string
       argument  and  returns  the fully-substituted result.  The
       substitutions are performed in exactly the same way as for
       Tcl  commands.   As a result, the string argument is actu-
       ally substituted twice, once by  the  Tcl  parser  in  the
       usual  fashion  for  Tcl  commands, and again by the subst
       command.

       If any of the -nobackslashes, -nocommands, or -novariables
       are  specified,  then  the corresponding substitutions are
       not performed.  For example, if -nocommands is  specified,
       command  substitution  is  not  performed:  open and close
       brackets are treated as ordinary characters with  no  spe-
       cial interpretation.

       Note that the substitution of one kind can include substi-
       tution  of  other  kinds.   For  example,  even  when  the 
       -novariables  option is specified, command substitution is 
       performed without restriction.  This means that any  vari-
       able  substitution  necessary to complete the command sub-
       stitution will still take place.   Likewise,  any  command 
       substitution necessary to complete a variable substitution 
       will take place, even when -nocommands is specified.   See 
       the EXAMPLES below.                                        

       If  an  error  occurs during substitution, then subst will 
       return that error.  If a  break  exception  occurs  during 
       command  or variable substitution, the result of the whole 
       substitution will be the string (as substituted) up to the 
       start of the substitution that raised the exception.  If a 
       continue exception occurs during the evaluation of a  com-
       mand  or  variable  substitution,  an empty string will be 
       substituted for that entire command or variable  substitu-
       tion  (as  long  as  it  is well-formed Tcl.)  If a return 
       exception occurs, or any other  return  code  is  returned 
       during command or variable substitution, then the returned 
       value is substituted for that substitution.  See the EXAM-
       PLES below.  In this way, all exceptional return codes are 
       ``caught'' by subst.  The subst command itself will either 
       return an error, or will complete successfully.


EXAMPLES
       When  it  performs  its substitutions, subst does not give
       any special treatment to double  quotes  or  curly  braces
       (except within command substitutions) so the script
              set a 44
              subst {xyz {$a}}
       returns ``xyz {44}'', not ``xyz {$a}'' and the script      
              set a "p\} q \{r"                                   
              subst {xyz {$a}}                                    
       return ``xyz {p} q {r}'', not ``xyz {p\} q \{r}''.         

       When  command  substitution  is performed, it includes any 
       variable substitution necessary to evaluate the script.    
              set a 44                                            
              subst -novariables {$a [format $a]}                 
       returns ``$a 44'', not ``$a $a''.  Similarly,  when  vari-
       able  substitution  is  performed, it includes any command 
       substitution necessary to retrieve the value of the  vari-
       able.                                                      
              proc b {} {return c}                                
              array set a {c c [b] tricky}                        
              subst -nocommands {[b] $a([b])}                     
       returns ``[b] c'', not ``[b] tricky''.                     

       The  continue and break exceptions allow command substitu-
       tions to prevent substitution of the rest of  the  command 
       substitution  and  the rest of string respectively, giving 
       script authors more options  when  processing  text  using 
       subst.  For example, the script                            
              subst {abc,[break],def}                             
       returns ``abc,'', not ``abc,,def'' and the script          
              subst {abc,[continue;expr 1+2],def}                 
       returns ``abc,,def'', not ``abc,3,def''.                   

       Other  exceptional  return  codes  substitute the returned 
       value                                                      
              subst {abc,[return foo;expr 1+2],def}               
       returns ``abc,foo,def'', not ``abc,3,def'' and             
              subst {abc,[return -code 10 foo;expr 1+2],def}      
       also returns ``abc,foo,def'', not ``abc,3,def''.


KEYWORDS
       backslash  substitution,  command  substitution,  variable
       substitution


_________________________________________________________________

NAME
       switch  -  Evaluate one of several scripts, depending on a
       given value

SYNOPSIS
       switch ?options? string pattern body ?pattern body ...?

       switch ?options? string {pattern body ?pattern body ...?}
_________________________________________________________________


DESCRIPTION
       The switch command matches  its  string  argument  against
       each  of  the  pattern  arguments in order.  As soon as it
       finds a pattern that matches string it evaluates the  fol-
       lowing  body argument by passing it recursively to the Tcl
       interpreter and returns the result of that evaluation.  If
       the  last pattern argument is default then it matches any-
       thing.  If no  pattern  argument  matches  string  and  no
       default is given, then the switch command returns an empty
       string.

       If the initial arguments to switch start with - then  they
       are  treated  as  options.  The following options are cur-
       rently supported:

       -exact    Use exact matching when comparing  string  to  a
                 pattern.  This is the default.

       -glob     When  matching string to the patterns, use glob-
                 style matching (i.e. the same as implemented  by
                 the string match command).

       -regexp   When  matching string to the patterns, use regu-
                 lar expression matching  (as  described  in  the
                 re_syntax reference page).

       --        Marks  the end of options.  The argument follow-
                 ing this one will be treated as string  even  if
                 it starts with a -.

       Two  syntaxes  are provided for the pattern and body argu-
       ments.  The first uses a separate argument for each of the
       patterns  and commands; this form is convenient if substi-
       tutions are desired on some of the patterns  or  commands.
       The  second  form  places all of the patterns and commands
       together into a single argument; the  argument  must  have
       proper list structure, with the elements of the list being
       the patterns and commands.  The second form makes it  easy
       to  construct multi-line switch commands, since the braces
       around the whole list make it  unnecessary  to  include  a
       backslash  at  the  end  of  each line.  Since the pattern
       arguments are in braces in the second form, no command  or
       variable  substitutions are performed on them;  this makes
       the behavior of the second form different than  the  first
       form in some cases.

       If a body is specified as ``-'' it means that the body for
       the next pattern should also be used as the body for  this
       pattern (if the next pattern also has a body of ``-'' then
       the body after that is used, and  so  on).   This  feature
       makes  it  possible  to  share a single body among several
       patterns.

       Beware of how you place comments in switch commands.  Com-
       ments  should  only be placed inside the execution body of
       one of the patterns, and not intermingled  with  the  pat-
       terns.

       Below are some examples of switch commands:
              switch abc a - b {format 1} abc {format 2} default {format 3}
       will return 2,
              switch -regexp aaab {
                ^a.*b$ -
                b {format 1}
                a* {format 2}
                default {format 3}
              }
       will return 1, and
              switch xyz {
                a
                   -
                b
                   {
                   # Correct Comment Placement
                   format 1
                }
                a*
                   {format 2}
                default
                   {format 3}
              }
       will return 3.


KEYWORDS
       switch, match, regular expression


_________________________________________________________________

NAME
       Tcl - Summary of Tcl language syntax.
_________________________________________________________________


DESCRIPTION
       The following rules define the syntax and semantics of the
       Tcl language:

       [1]    A Tcl script is a string  containing  one  or  more
              commands.   Semi-colons  and  newlines  are command
              separators unless quoted as described below.  Close
              brackets  are  command  terminators  during command
              substitution (see below) unless quoted.

       [2]    A command is evaluated in two  steps.   First,  the
              Tcl  interpreter  breaks the command into words and
              performs substitutions as described  below.   These
              substitutions are performed in the same way for all
              commands.  The first word is used to locate a  com-
              mand  procedure  to carry out the command, then all
              of the words of the command are passed to the  com-
              mand  procedure.   The command procedure is free to
              interpret each of its words in any  way  it  likes,
              such  as  an  integer,  variable name, list, or Tcl
              script.  Different commands interpret  their  words
              differently.

       [3]    Words  of  a  command  are separated by white space
              (except for newlines,  which  are  command  separa-
              tors).

       [4]    If  the  first  character of a word is double-quote
              (``"'') then the word is  terminated  by  the  next
              double-quote   character.   If  semi-colons,  close
              brackets, or white space characters (including new-
              lines)  appear  between  the  quotes  then they are
              treated as ordinary characters and included in  the
              word.  Command substitution, variable substitution,
              and backslash substitution  are  performed  on  the
              characters  between  the quotes as described below.
              The double-quotes are not retained as part  of  the
              word.

       [5]    If  the  first character of a word is an open brace
              (``{'') then the word is terminated by the matching
              close  brace (``}'').  Braces nest within the word:
              for each additional open brace  there  must  be  an
              additional  close  brace (however, if an open brace
              or close brace within the word  is  quoted  with  a
              backslash  then  it  is not counted in locating the
              matching  close  brace).   No   substitutions   are


              performed  on  the  characters  between  the braces
              except    for    backslash-newline    substitutions
              described  below,  nor  do  semi-colons,  newlines,
              close brackets, or white space receive any  special
              interpretation.   The  word will consist of exactly
              the  characters  between  the  outer  braces,   not
              including the braces themselves.

       [6]    If a word contains an open bracket (``['') then Tcl
              performs  command  substitution.   To  do  this  it
              invokes  the Tcl interpreter recursively to process
              the characters following the open bracket as a  Tcl
              script.   The script may contain any number of com-
              mands and must be terminated  by  a  close  bracket
              (``]'').  The result of the script (i.e. the result
              of its last command) is substituted into  the  word
              in  place of the brackets and all of the characters
              between them.  There may be any number  of  command
              substitutions  in a single word.  Command substitu-
              tion is not performed on words enclosed in  braces.

       [7]    If  a  word contains a dollar-sign (``$'') then Tcl
              performs variable  substitution:   the  dollar-sign
              and  the  following  characters are replaced in the
              word by the value of a variable.  Variable  substi-
              tution may take any of the following forms:

              $name          Name  is  the name of a scalar vari-
                             able;  the name is a sequence of one
                             or  more  characters that are a let-
                             ter, digit, or underscore.

              $name(index)   Name gives  the  name  of  an  array
                             variable and index gives the name of
                             an element within that array.   Name
                             must  contain  only letters, digits,
                             and underscores, but may be an empty
                             string.     Command   substitutions,
                             variable  substitutions,  and  back-
                             slash substitutions are performed on
                             the characters of index.

              ${name}        Name is the name of a  scalar  vari-
                             able.  It may contain any characters
                             whatsoever except for close  braces.

              There  may  be any number of variable substitutions
              in a single word.   Variable  substitution  is  not
              performed on words enclosed in braces.

       [8]    If  a  backslash (``\'') appears within a word then
              backslash substitution occurs.  In  all  cases  but
              those  described below the backslash is dropped and
              the following character is treated as  an  ordinary


              character  and  included  in the word.  This allows
              characters such as double quotes,  close  brackets,
              and  dollar  signs  to be included in words without
              triggering special processing.  The following table
              lists the backslash sequences that are handled spe-
              cially, along with the  value  that  replaces  each
              sequence.

              \a     Audible alert (bell) (0x7).

              \b     Backspace (0x8).

              \f     Form feed (0xc).

              \n     Newline (0xa).

              \r     Carriage-return (0xd).

              \t     Tab (0x9).

              \v     Vertical tab (0xb).

              \<newline>whiteSpace
                     A  single space character replaces the back-
                     slash, newline,  and  all  spaces  and  tabs
                     after  the newline.  This backslash sequence
                     is unique in that it is replaced in a  sepa-
                     rate pre-pass before the command is actually
                     parsed.  This means that it will be replaced
                     even  when it occurs between braces, and the
                     resulting space will be treated  as  a  word
                     separator if it isn't in braces or quotes.

              \\     Backslash (``\'').

              \ooo                                                              
                     The digits ooo (one, two, or three of  them) 
                     give  an  eight-bit octal value for the Uni-
                     code character that will be  inserted.   The 
                     upper  bits of the Unicode character will be 
                     0.                                           

              \xhh                                                              
                     The  hexadecimal digits hh give an eight-bit 
                     hexadecimal value for the Unicode  character 
                     that  will  be inserted.  Any number of hex-
                     adecimal digits may be present; however, all 
                     but  the last two are ignored (the result is 
                     always a one-byte quantity).  The upper bits 
                     of the Unicode character will be 0.          

              \uhhhh                                                            
                     The  hexadecimal  digits  hhhh  (one,   two, 
                     three,  or  four of them) give a sixteen-bit 


                     hexadecimal value for the Unicode  character 
                     that will be inserted.

              Backslash  substitution  is  not performed on words
              enclosed in braces, except for backslash-newline as
              described above.

       [9]    If  a  hash  character  (``#'')  appears at a point
              where Tcl is expecting the first character  of  the
              first  word  of  a command, then the hash character
              and the characters that follow it, up  through  the
              next newline, are treated as a comment and ignored.
              The comment character only has significance when it
              appears at the beginning of a command.

       [10]   Each character is processed exactly once by the Tcl
              interpreter as part of creating the words of a com-
              mand.  For example, if variable substitution occurs
              then no further substitutions are performed on  the
              value  of the variable;  the value is inserted into
              the word verbatim.  If command substitution  occurs
              then  the  nested  command is processed entirely by
              the recursive call to the Tcl interpreter; no  sub-
              stitutions  are  performed before making the recur-
              sive call and no additional substitutions are  per-
              formed on the result of the nested script.

       [11]   Substitutions  do not affect the word boundaries of
              a command.  For example, during variable  substitu-
              tion  the entire value of the variable becomes part
              of a single word, even if the variable's value con-
              tains spaces.


_________________________________________________________________

NAME
       tclvars - Variables used by Tcl
_________________________________________________________________


DESCRIPTION
       The  following  global  variables  are created and managed
       automatically by the  Tcl  library.   Except  where  noted
       below, these variables should normally be treated as read-
       only by application-specific code and by users.

       env    This variable is maintained  by  Tcl  as  an  array
              whose  elements  are  the environment variables for
              the process.  Reading an element  will  return  the
              value  of  the  corresponding environment variable.
              Setting an element of the  array  will  modify  the
              corresponding  environment variable or create a new
              one if it doesn't already exist.  Unsetting an ele-
              ment  of env will remove the corresponding environ-
              ment variable.   Changes  to  the  env  array  will
              affect  the  environment passed to children by com-
              mands like exec.  If the entire env array is  unset
              then Tcl will stop monitoring env accesses and will
              not update environment variables.
              Under Windows, the environment variables  PATH  and 
              COMSPEC  in  any capitalization are converted auto-
              matically to upper case.  For  instance,  the  PATH 
              variable  could be exported by the operating system 
              as ``path'', ``Path'', ``PaTh'', etc., causing oth-
              erwise simple Tcl code to have to support many spe-
              cial cases.  All other environment variables inher-
              ited  by  Tcl  are left unmodified.  Setting an env 
              array variable to blank is the same as unsetting it 
              as  this  is the behavior of the underlying Windows 
              OS.  It should be noted that relying on an existing 
              and  empty  environment variable won't work on win-
              dows and is discouraged for cross-platform usage.
              On the Macintosh, the environment variable is  con-
              structed  by  Tcl as no global environment variable
              exists.  The environment variables that are created
              for Tcl include:

              LOGIN  This  holds  the  Chooser name of the Macin-
                     tosh.

              USER   This also holds the Chooser name of the Mac-
                     intosh.

              SYS_FOLDER
                     The path to the system directory.


              APPLE_M_FOLDER
                     The path to the Apple Menu directory.

              CP_FOLDER
                     The path to the control panels directory.

              DESK_FOLDER
                     The path to the desk top directory.

              EXT_FOLDER
                     The path to the system extensions directory.

              PREF_FOLDER
                     The path to the preferences directory.

              PRINT_MON_FOLDER
                     The path to the print monitor directory.

              SHARED_TRASH_FOLDER
                     The path to the network trash directory.

              TRASH_FOLDER
                     The path to the trash directory.

              START_UP_FOLDER
                     The path to the start up directory.

              HOME   The path to the application's default direc-
                     tory.

              You  can also create your own environment variables
              for the Macintosh.  A file named   Tcl  Environment
              Variables  may  be placed in the preferences folder
              in the Mac system folder.  Each line of  this  file
              should be of the form VAR_NAME=var_data.

              The  last alternative is to place environment vari-
              ables in a 'STR#' resource  named  Tcl  Environment
              Variables of the application.  This is considered a
              little more ``Mac like'' than a Unix style Environ-
              ment  Variable  file.   Each  entry  in  the 'STR#'
              resource has the same format as above.  The  source
              code  file  tclMacEnv.c contains the implementation
              of the env mechanisms.   This  file  contains  many
              #define's that allow customization of the env mech-
              anisms to fit your applications needs.

       errorCode
              After an error has occurred, this variable will  be
              set  to hold additional information about the error
              in a form that is easy to  process  with  programs.
              errorCode  consists  of a Tcl list with one or more
              elements.  The first element of the list identifies
              a  general  class  of  errors,  and  determines the


              format of the rest of the list.  The following for-
              mats  for errorCode are used by the Tcl core; indi-
              vidual applications may define additional  formats.

              ARITH code msg
                     This format is used when an arithmetic error
                     occurs (e.g. an attempt to divide by zero in
                     the expr command).  Code identifies the pre-
                     cise error and msg provides a human-readable
                     description  of  the  error.   Code  will be
                     either DIVZERO (for an attempt to divide  by
                     zero), DOMAIN (if an argument is outside the
                     domain of a  function,  such  as  acos(-3)),
                     IOVERFLOW  (for  integer overflow), OVERFLOW
                     (for a floating-point overflow), or  UNKNOWN
                     (if  the cause of the error cannot be deter-
                     mined).

              CHILDKILLED pid sigName msg
                     This format is used when a child process has
                     been killed because of a signal.  The second
                     element of errorCode will be  the  process's
                     identifier  (in decimal).  The third element
                     will be the symbolic name of the signal that
                     caused  the process to terminate; it will be
                     one of the names from the include file  sig-
                     nal.h,  such as SIGPIPE.  The fourth element
                     will  be  a  short  human-readable   message
                     describing  the  signal,  such as ``write on
                     pipe with no readers'' for SIGPIPE.

              CHILDSTATUS pid code
                     This format is used when a child process has
                     exited  with  a  non-zero  exit status.  The
                     second element of errorCode will be the pro-
                     cess's identifier (in decimal) and the third
                     element will be the exit  code  returned  by
                     the process (also in decimal).

              CHILDSUSP pid sigName msg
                     This format is used when a child process has
                     been suspended because  of  a  signal.   The
                     second element of errorCode will be the pro-
                     cess's identifier, in  decimal.   The  third
                     element  will  be  the  symbolic name of the
                     signal that caused the process  to  suspend;
                     this  will  be  one  of  the  names from the
                     include file signal.h, such as SIGTTIN.  The
                     fourth  element  will be a short human-read-
                     able message describing the signal, such  as
                     ``background tty read'' for SIGTTIN.

              NONE   This  format  is  used  for  errors where no
                     additional information is available  for  an


                     error  besides the message returned with the
                     error.  In these cases errorCode  will  con-
                     sist  of  a list containing a single element
                     whose contents are NONE.

              POSIX errName msg
                     If the first element of errorCode is  POSIX,
                     then  the error occurred during a POSIX ker-
                     nel call.  The second element  of  the  list
                     will  contain the symbolic name of the error
                     that occurred, such as ENOENT; this will  be
                     one  of  the  values  defined in the include
                     file errno.h.  The third element of the list
                     will be a human-readable message correspond-
                     ing to errName, such as ``no  such  file  or
                     directory'' for the ENOENT case.

              To  set  errorCode, applications should use library
              procedures such as Tcl_SetErrorCode and  Tcl_Posix-
              Error,  or  they  may invoke the error command.  If
              one of these methods hasn't been used, then the Tcl
              interpreter  will  reset the variable to NONE after
              the next error.

       errorInfo
              After an error has occurred, this string will  con-
              tain one or more lines identifying the Tcl commands
              and procedures that were being  executed  when  the
              most  recent error occurred.  Its contents take the
              form of a stack trace showing  the  various  nested
              Tcl  commands  that had been invoked at the time of
              the error.

       tcl_library
              This variable holds the name of  a  directory  con-
              taining  the system library of Tcl scripts, such as
              those used for auto-loading.   The  value  of  this
              variable  is  returned by the info library command.
              See the library manual entry  for  details  of  the
              facilities  provided  by  the  Tcl  script library.
              Normally each application or package will have  its
              own application-specific script library in addition
              to the Tcl script library; each application  should
              set a global variable with a name like $app_library
              (where app is the application's name) to  hold  the
              network  file  name  for that application's library
              directory.  The initial value of tcl_library is set
              when an interpreter is created by searching several
              different directories until one is found that  con-
              tains  an  appropriate  Tcl startup script.  If the
              TCL_LIBRARY environment variable exists,  then  the
              directory   it   names   is   checked   first.   If
              TCL_LIBRARY isn't set or doesn't refer to an appro-
              priate  directory,  then  Tcl  checks several other


              directories based on a  compiled-in  default  loca-
              tion,  the  location  of  the binary containing the
              application, and the current working directory.

       tcl_patchLevel
              When an interpreter is created Tcl initializes this
              variable  to hold a string giving the current patch
              level for Tcl, such as 7.3p2 for Tcl 7.3  with  the
              first two official patches, or 7.4b4 for the fourth
              beta release of Tcl 7.4.  The value of  this  vari-
              able is returned by the info patchlevel command.

       tcl_pkgPath                                                       
              This variable holds a list of directories  indicat-
              ing  where  packages are normally installed.  It is 
              not used on Windows.  It typically contains  either 
              one or two entries; if it contains two entries, the 
              first is normally a directory  for  platform-depen-
              dent  packages  (e.g., shared library binaries) and 
              the second is normally a  directory  for  platform- 
              independent  packages  (e.g.,  script files). Typi-
              cally a package is installed as a  subdirectory  of 
              one of the entries in $tcl_pkgPath. The directories 
              in $tcl_pkgPath are  included  by  default  in  the 
              auto_path  variable,  so  they  and their immediate 
              subdirectories are automatically searched for pack-
              ages   during   package  require  commands.   Note: 
              tcl_pkgPath it not intended to be modified  by  the 
              application.   Its  value  is added to auto_path at 
              startup; changes to tcl_pkgPath are  not  reflected 
              in auto_path.  If you want Tcl to search additional 
              directories for packages you should add  the  names 
              of those directories to auto_path, not tcl_pkgPath.

       tcl_platform
              This is an associative array whose elements contain
              information  about the platform on which the appli-
              cation is running, such as the name of the  operat-
              ing  system,  its  current  release number, and the
              machine's instruction  set.   The  elements  listed
              below  will  always  be  defined, but they may have
              empty strings as values if  Tcl  couldn't  retrieve
              any  relevant information.  In addition, extensions
              and applications may add additional values  to  the
              array.  The predefined elements are:


              byteOrder                                                         
                     The  native  byte  order  of  this  machine: 
                     either littleEndian or bigEndian.

              debug  If  this  variable  exists,  then the inter-
                     preter was compiled with  debugging  symbols
                     enabled.   This  variable will only exist on


                     Windows so  extension  writers  can  specify
                     which  package  to  load  depending on the C
                     run-time library that is loaded.

              machine
                     The  instruction  set   executed   by   this
                     machine,  such as intel, PPC, 68k, or sun4m.
                     On UNIX machines, this is the value returned
                     by uname -m.

              os     The  name of the operating system running on
                     this machine, such as  Windows  95,  Windows
                     NT, MacOS, or SunOS.  On UNIX machines, this
                     is the value returned by uname -s.  On  Win-
                     dows  95  and Windows 98, the value returned
                     will be Windows 95 to provide  better  back-
                     wards  compatibility  to Windows 95; to dis-
                     tinguish between the two, check  the  osVer-
                     sion.

              osVersion
                     The  version number for the operating system
                     running on this machine.  On UNIX  machines,
                     this  is the value returned by uname -r.  On
                     Windows 95, the version will be 4.0; on Win-
                     dows 98, the version will be 4.10.

              platform
                     Either  windows,  macintosh,  or unix.  This
                     identifies the general operating environment
                     of the machine.

              threaded
                     If  this  variable  exists,  then the inter-
                     preter was compiled with threads enabled.

              user   This identifies the current  user  based  on
                     the login information available on the plat-
                     form.  This comes from the USER  or  LOGNAME
                     environment  variable on Unix, and the value
                     from GetUserName on Windows and Macintosh.

              wordSize
                     This gives the size  of  the  native-machine 
                     word  in  bytes (strictly, it is same as the 
                     result of evaluating sizeof(long) in C.)

       tcl_precision
              This variable controls the number of digits to gen-
              erate  when  converting  floating-point  values  to 
              strings.  It defaults to 12.  17 digits  is  ``per-
              fect''  for  IEEE  floating-point in that it allows 
              double-precision values to be converted to  strings 
              and  back  to  binary  with no loss of information. 


              However, using 17  digits  prevents  any  rounding, 
              which produces longer, less intuitive results.  For 
              example, expr 1.4 returns  1.3999999999999999  with 
              tcl_precision  set  to 17, vs. 1.4 if tcl_precision 
              is 12.                                              
              All  interpreters  in  a  process  share  a  single 
              tcl_precision value: changing it in one interpreter 
              will affect all other interpreters as  well.   How-
              ever,  safe  interpreters are not allowed to modify 
              the variable.                                       

       tcl_rcFileName
              This variable  is  used  during  initialization  to
              indicate  the name of a user-specific startup file.
              If it is set  by  application-specific  initializa-
              tion,  then the Tcl startup code will check for the
              existence of this file and source it if it  exists.
              For  example,  for  wish  the  variable  is  set to
              ~/.wishrc for Unix and ~/wishrc.tcl for Windows.

       tcl_rcRsrcName
              This variable is only used  on  Macintosh  systems.
              The variable is used during initialization to indi-
              cate the name  of  a  user-specific  TEXT  resource
              located  in  the  application or extension resource
              forks.  If it is set by  application-specific  ini-
              tialization,  then  the Tcl startup code will check
              for the existence of this resource and source it if
              it  exists.  For example, the Macintosh wish appli-
              cation has the variable is set to tclshrc.

       tcl_traceCompile
              The value of this variable can be  set  to  control
              how  much  tracing  information is displayed during
              bytecode compilation.  By default, tcl_traceCompile
              is  zero  and no information is displayed.  Setting
              tcl_traceCompile to 1 generates a one line  summary
              in stdout whenever a procedure or top level command
              is compiled.  Setting it to 2 generates a  detailed
              listing  in  stdout  of  the  bytecode instructions
              emitted during every compilation.  This variable is
              useful in tracking down suspected problems with the
              Tcl compiler.  It is also occasionally useful  when
              converting existing code to use Tcl8.0.

              This  variable  and  functionality  only  exist  if
              TCL_COMPILE_DEBUG was defined during Tcl's compila-
              tion.

       tcl_traceExec
              The  value  of  this variable can be set to control
              how much tracing information  is  displayed  during
              bytecode  execution.   By default, tcl_traceExec is
              zero and  no  information  is  displayed.   Setting


              tcl_traceExec  to  1  generates a one line trace in
              stdout on each call to a Tcl procedure.  Setting it
              to  2  generates  a line of output whenever any Tcl
              command is invoked that contains the  name  of  the
              command  and  its  arguments.  Setting it to 3 pro-
              duces a detailed trace showing the result  of  exe-
              cuting  each  bytecode instruction.  Note that when
              tcl_traceExec is 2 or 3, commands such as  set  and
              incr that have been entirely replaced by a sequence
              of bytecode instructions are  not  shown.   Setting
              this  variable is useful in tracking down suspected
              problems with  the  bytecode  compiler  and  inter-
              preter.   It  is also occasionally useful when con-
              verting code to use Tcl8.0.

              This  variable  and  functionality  only  exist  if
              TCL_COMPILE_DEBUG was defined during Tcl's compila-
              tion.

       tcl_wordchars
              The value of this variable is a regular  expression
              that  can  be  set  to  control what are considered
              ``word'' characters, for instances like selecting a
              word by double-clicking in text in Tk.  It is plat-
              form dependent.  On Windows,  it  defaults  to  \S,
              meaning  anything  but  a  Unicode space character.
              Otherwise it defaults to \w, which is  any  Unicode
              word character (number, letter, or underscore).

       tcl_nonwordchars
              The  value of this variable is a regular expression
              that can be set  to  control  what  are  considered
              ``non-word'' characters, for instances like select-
              ing a word by double-clicking in text in Tk.  It is
              platform dependent.  On Windows, it defaults to \s,
              meaning any Unicode space character.  Otherwise  it
              defaults  to  \W,  which  is anything but a Unicode
              word character (number, letter, or underscore).

       tcl_version
              When an interpreter is created Tcl initializes this
              variable  to  hold the version number for this ver-
              sion of Tcl in the form x.y.  Changes to  x  repre-
              sent  major changes with probable incompatibilities
              and changes to y represent small  enhancements  and
              bug  fixes that retain backward compatibility.  The
              value of this variable  is  returned  by  the  info
              tclversion command.


KEYWORDS
       arithmetic, bytecode, compiler, error, environment, POSIX,
       precision, subprocess, variables


_________________________________________________________________

NAME
       tell - Return current access position for an open channel

SYNOPSIS
       tell channelId
_________________________________________________________________


DESCRIPTION
       Returns  an integer string giving the current access posi-
       tion in channelId.  This value returned is a  byte  offset 
       that  can be passed to seek in order to set the channel to 
       a particular position.  Note that this value is  in  terms 
       of bytes, not characters like read.  The value returned is
       -1 for channels that do not support seeking.

       ChannelId must be an identifier for an open  channel  such 
       as  a Tcl standard channel (stdin, stdout, or stderr), the 
       return value from an invocation of open or socket, or  the 
       result  of  a  channel  creation command provided by a Tcl 
       extension.


       dardChannels(3)


KEYWORDS
       access position, channel, seeking


_________________________________________________________________

NAME
       time - Time the execution of a script

SYNOPSIS
       time script ?count?
_________________________________________________________________


DESCRIPTION
       This  command will call the Tcl interpreter count times to
       evaluate script (or once if count  isn't  specified).   It
       will then return a string of the form
              503 microseconds per iteration
       which  indicates  the  average amount of time required per
       iteration, in microseconds.  Time is measured  in  elapsed
       time, not CPU time.


KEYWORDS
       script, time


_________________________________________________________________

NAME
       trace - Monitor variable accesses, command usages and com-
       mand executions

SYNOPSIS
       trace option ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       This command causes Tcl commands to be  executed  whenever
       certain operations are invoked.  The legal option's (which
       may be abbreviated) are:

       trace add type name ops ?args?
              Where type is command, execution, or variable.

              trace add command name ops command
                     Arrange for command to be executed  whenever
                     command  name is modified in one of the ways
                     given  by  the  list  ops.   Name  will   be
                     resolved  using  the usual namespace resolu-
                     tion rules used by procedures.  If the  com-
                     mand  does  not  exist,  an  error  will  be
                     thrown.

                     Ops indicates which operations are of inter-
                     est,  and  is  a  list of one or more of the
                     following items:

                      rename Invoke command whenever the  command
                             is  renamed.   Note that renaming to
                             the empty string is considered dele-
                             tion,  and  will  not be traced with
                             'rename'.

                      delete Invoke command when the  command  is
                             deleted.   Commands  can  be deleted
                             explicitly by using the rename  com-
                             mand  to  rename  the  command to an
                             empty  string.   Commands  are  also
                             deleted   when  the  interpreter  is
                             deleted,  but  traces  will  not  be
                             invoked  because  there is no inter-
                             preter in which to execute them.

                     When the trace triggers,  depending  on  the
                     operations  being  traced, a number of argu-
                     ments are appended to command  so  that  the
                     actual command is as follows:
                             command oldName newName op
                     OldName   and   newName   give   the  traced


                     command's current (old) name, and  the  name
                     to  which  it  is  being  renamed (the empty
                     string if this is a 'delete' operation).  Op
                     indicates  what operation is being performed
                     on the command, and  is  one  of  rename  or
                     delete  as  defined above.  The trace opera-
                     tion cannot be used to stop a  command  from
                     being  deleted.   Tcl will always remove the
                     command once the trace is complete.   Recur-
                     sive  renaming  or  deleting  will not cause
                     further traces of the same type to be evalu-
                     ated, so a delete trace which itself deletes
                     the command, or a rename trace which  itself
                     renames  the  command will not cause further
                     trace evaluations to occur.

              trace add execution name ops command
                     Arrange for command to be executed  whenever
                     command  name is modified in one of the ways
                     given  by  the  list  ops.   Name  will   be
                     resolved  using  the usual namespace resolu-
                     tion rules used by procedures.  If the  com-
                     mand  does  not  exist,  an  error  will  be
                     thrown.

                     Ops indicates which operations are of inter-
                     est,  and  is  a  list of one or more of the
                     following items:

                      enter  Invoke command whenever the  command
                             name  is  executed,  just before the
                             actual execution takes place.

                      leave  Invoke command whenever the  command
                             name  is  executed,  just  after the
                             actual execution takes place.

                     enterstep
                             Invoke command for every tcl command
                             which  is executed inside the proce-
                             dure name, just  before  the  actual
                             execution  takes place.  For example
                             if we  have  'proc  foo  {}  {  puts
                             "hello"  }',  then a enterstep trace
                             would be invoked  just  before  puts
                             "hello"   is  executed.   Setting  a
                             enterstep trace on  a  command  will
                             not result in an error and is simply
                             ignored.

                     leavestep
                             Invoke command for every tcl command
                             which  is executed inside the proce-
                             dure name,  just  after  the  actual
                             execution  takes  place.   Setting a
                             leavestep trace on  a  command  will
                             not result in an error and is simply
                             ignored.

                     When the trace triggers,  depending  on  the
                     operations  being  traced, a number of argu-
                     ments are appended to command  so  that  the
                     actual command is as follows:

                     For enter and enterstep operations:
                             command command-string op
                     Command-string  gives  the  complete current
                     command being executed (the  traced  command
                     for  a enter operation, an arbitrary command
                     for a enterstep  operation),  including  all
                     arguments  in their fully expanded form.  Op
                     indicates what operation is being  performed
                     on  the  command  execution,  and  is one of
                     enter or enterstep as  defined  above.   The
                     trace operation can be used to stop the com-
                     mand from executing, by deleting the command
                     in  question.  Of course when the command is
                     subsequently executed, an 'invalid  command'
                     error will occur.

                     For leave and leavestep operations:
                             command command-string code result op
                     Command-string  gives  the  complete current
                     command being executed (the  traced  command
                     for  a enter operation, an arbitrary command
                     for a enterstep  operation),  including  all
                     arguments  in  their  fully  expanded  form.
                     Code gives the result code  of  that  execu-
                     tion,  and  result  the  result  string.  Op
                     indicates what operation is being  performed
                     on  the  command  execution,  and  is one of
                     leave or leavestep as defined  above.   Note
                     that  the  creation  of  many  enterstep  or
                     leavestep traces  can  lead  to  unintuitive
                     results, since the invoked commands from one
                     trace can themselves lead to further command
                     invocations for other traces.

                     Command  executes in the same context as the
                     code that invoked the traced operation: thus
                     the  command,  if  invoked from a procedure,
                     will have access to the same local variables
                     as  code in the procedure.  This context may
                     be different than the context in  which  the
                     trace was created. If command invokes a pro-
                     cedure (which it  normally  does)  then  the
                     procedure  will have to use upvar or uplevel
                     commands if it wishes to  access  the  local
                     variables  of  the  code  which  invoked the
                     trace operation.

                     While command is executing during an  execu-
                     tion  trace,  traces on name are temporarily
                     disabled. This allows the command to execute
                     name  in its body without invoking any other
                     traces again.  If an error occurs while exe-
                     cuting  the  command  body, then the command
                     name as a whole will return that same error.

                     When  multiple  traces are set on name, then
                     for  enter  and  enterstep  operations,  the
                     traced  commands  are invoked in the reverse
                     order of how the traces were originally cre-
                     ated;  and  for  leave  and leavestep opera-
                     tions, the traced commands  are  invoked  in
                     the original order of creation.

                     The  behavior  of  execution  traces is cur-
                     rently undefined for a command name imported
                     into another namespace.

              trace add variable name ops command
                     Arrange  for command to be executed whenever
                     variable name is accessed in one of the ways
                     given  by the list ops.  Name may refer to a
                     normal variable, an element of an array,  or
                     to  an  array  as  a whole (i.e. name may be
                     just the name of an array, with no parenthe-
                     sized  index).   If  name  refers to a whole
                     array, then command is invoked whenever  any
                     element of the array is manipulated.  If the
                     variable does not exist, it will be  created
                     but will not be given a value, so it will be
                     visible to namespace which queries, but  not
                     to info exists queries.

                     Ops indicates which operations are of inter-
                     est, and is a list of one  or  more  of  the
                     following items:

                      array  Invoke command whenever the variable
                             is  accessed  or  modified  via  the
                             array command, provided that name is
                             not a scalar variable  at  the  time
                             that  the  array command is invoked.
                             If name is a  scalar  variable,  the
                             access  via  the  array command will
                             not trigger the trace.

                      read   Invoke command whenever the variable
                             is read.


                      write  Invoke command whenever the variable
                             is written.

                      unset  Invoke command whenever the variable
                             is  unset.   Variables  can be unset
                             explicitly with the  unset  command,
                             or implicitly when procedures return
                             (all of their  local  variables  are
                             unset).   Variables  are  also unset
                             when interpreters are  deleted,  but
                             traces  will  not be invoked because
                             there is no interpreter in which  to
                             execute them.

                     When the trace triggers, three arguments are
                     appended to command so that the actual  com-
                     mand is as follows:
                             command name1 name2 op
                     Name1  and  name2  give  the name(s) for the
                     variable being accessed:  if the variable is
                     a  scalar  then  name1  gives the variable's
                     name and name2 is an empty  string;  if  the
                     variable  is  an  array  element  then name1
                     gives the name of the array and name2  gives
                     the index into the array; if an entire array
                     is being deleted and the  trace  was  regis-
                     tered  on  the  overall array, rather than a
                     single element, then name1 gives  the  array
                     name  and  name2  is an empty string.  Name1
                     and name2 are not necessarily  the  same  as
                     the name used in the trace variable command:
                     the upvar command allows a procedure to ref-
                     erence  a  variable  under a different name.
                     Op indicates what operation  is  being  per-
                     formed  on the variable, and is one of read,
                     write, or unset as defined above.

                     Command executes in the same context as  the
                     code  that invoked the traced operation:  if
                     the variable was accessed as part of  a  Tcl
                     procedure,  then command will have access to
                     the same local variables as code in the pro-
                     cedure.   This context may be different than
                     the context in which the trace was  created.
                     If  command  invokes  a  procedure (which it
                     normally does) then the procedure will  have
                     to  use  upvar  or  uplevel  if it wishes to
                     access the traced variable.  Note also  that
                     name1 may not necessarily be the same as the
                     name used to set the trace on the  variable;
                     differences  can occur if the access is made
                     through a variable defined  with  the  upvar
                     command.


                     For  read and write traces, command can mod-
                     ify the variable to affect the result of the
                     traced  operation.   If command modifies the
                     value of a variable during a read  or  write
                     trace,  then  the new value will be returned
                     as the result of the traced operation.   The
                     return value from  command is ignored except
                     that if it returns an error of any sort then
                     the  traced  operation also returns an error
                     with the same error message returned by  the
                     trace command (this mechanism can be used to
                     implement read-only variables, for example).
                     For  write  traces, command is invoked after
                     the variable's value has  been  changed;  it
                     can  write  a new value into the variable to
                     override the original value specified in the
                     write  operation.   To  implement  read-only
                     variables, command will have to restore  the
                     old value of the variable.

                     While  command is executing during a read or
                     write trace, traces on the variable are tem-
                     porarily  disabled.   This  means that reads
                     and writes invoked  by  command  will  occur
                     directly,  without  invoking command (or any
                     other traces) again.   However,  if  command
                     unsets  the  variable then unset traces will
                     be invoked.

                     When an unset trace is invoked, the variable
                     has  already been deleted: it will appear to
                     be undefined with no traces.   If  an  unset
                     occurs  because  of a procedure return, then
                     the trace will be invoked  in  the  variable
                     context  of the procedure being returned to:
                     the stack frame of the  returning  procedure
                     will  no  longer exist.  Traces are not dis-
                     abled during unset traces, so  if  an  unset
                     trace   command  creates  a  new  trace  and
                     accesses the variable,  the  trace  will  be
                     invoked.   Any  errors  in  unset traces are
                     ignored.

                     If there are multiple traces on  a  variable
                     they are invoked in order of creation, most-
                     recent  first.   If  one  trace  returns  an
                     error,  then  no  further traces are invoked
                     for the variable.  If an array element has a
                     trace  set, and there is also a trace set on
                     the array as a whole, the trace on the over-
                     all  array  is invoked before the one on the
                     element.

                     Once created, the trace  remains  in  effect
                     either  until  the trace is removed with the
                     trace  remove  variable  command   described
                     below, until the variable is unset, or until
                     the interpreter is  deleted.   Unsetting  an
                     element  of  array will remove any traces on
                     that element, but will not remove traces  on
                     the overall array.

                     This command returns an empty string.

       trace remove type name opList command
              Where  type  is  either command, execution or vari-
              able.

              trace remove command name opList command
                     If there is a trace set on command name with
                     the  operations  and command given by opList
                     and command, then the trace is  removed,  so
                     that  command  will  never again be invoked.
                     Returns an empty string.   If  name  doesn't
                     exist, the command will throw an error.

              trace remove execution name opList command
                     If there is a trace set on command name with
                     the operations and command given  by  opList
                     and  command,  then the trace is removed, so
                     that command will never  again  be  invoked.
                     Returns  an  empty string.   If name doesn't
                     exist, the command will throw an error.

              trace remove variable name opList command
                     If there is a trace  set  on  variable  name
                     with  the  operations  and  command given by
                     opList  and  command,  then  the  trace   is
                     removed, so that command will never again be
                     invoked.  Returns an empty string.

       trace info type name
              Where type is either command,  execution  or  vari-
              able.

              trace info command name
                     Returns  a  list  containing one element for
                     each trace currently set  on  command  name.
                     Each  element  of  the list is itself a list
                     containing  two  elements,  which  are   the
                     opList   and  command  associated  with  the
                     trace.  If name doesn't have any traces set,
                     then  the  result  of the command will be an
                     empty string.  If name  doesn't  exist,  the
                     command will throw an error.

              trace info execution name
                     Returns  a  list  containing one element for
                     each trace currently set  on  command  name.
                     Each  element  of  the list is itself a list
                     containing  two  elements,  which  are   the
                     opList   and  command  associated  with  the
                     trace.  If name doesn't have any traces set,
                     then  the  result  of the command will be an
                     empty string.  If name  doesn't  exist,  the
                     command will throw an error.

              trace info variable name
                     Returns  a  list  containing one element for
                     each trace currently set on  variable  name.
                     Each  element  of  the list is itself a list
                     containing  two  elements,  which  are   the
                     opList   and  command  associated  with  the
                     trace.  If name  doesn't  exist  or  doesn't
                     have  any traces set, then the result of the
                     command will be an empty string.

       For backwards compatibility, three other  subcommands  are
       available:

              trace variable name ops command
                     This  is  equivalent  to  trace add variable
                     name ops command.

              trace vdelete name ops command
                     This is equivalent to trace remove  variable
                     name ops command

              trace vinfo name
                     This  is  equivalent  to trace info variable
                     name

       These  subcommands  are  deprecated  and  will  likely  be
       removed  in  a  future  version of Tcl.  They use an older
       syntax in which array, read, write, unset are replaced  by
       a,  r, w and u respectively, and the ops argument is not a
       list, but simply a string concatenation of the operations,
       such as rwua.


KEYWORDS
       read, command, rename, variable, write, trace, unset


_________________________________________________________________

NAME
       unknown - Handle attempts to use non-existent commands

SYNOPSIS
       unknown cmdName ?arg arg ...?
_________________________________________________________________


DESCRIPTION
       This  command is invoked by the Tcl interpreter whenever a
       script tries to invoke a command that doesn't exist.   The
       default  implementation  of unknown is a library procedure
       defined when Tcl  initializes  an  interpreter.   You  can
       override  the default unknown to change its functionality.
       Note that there is no default implementation of unknown in
       a safe interpreter.

       If the Tcl interpreter encounters a command name for which
       there is not a defined command, then Tcl  checks  for  the
       existence of a command named unknown.  If there is no such
       command, then the interpreter returns an  error.   If  the
       unknown  command exists, then it is invoked with arguments
       consisting of the fully-substituted name and arguments for
       the  original  non-existent  command.  The unknown command
       typically  does  things  like  searching  through  library
       directories for a command procedure with the name cmdName,
       or expanding abbreviated command names to full-length,  or
       automatically executing unknown commands as sub-processes.
       In some cases (such as  expanding  abbreviations)  unknown
       will   change  the  original  command  slightly  and  then
       (re-)execute it.  The result of  the  unknown  command  is
       used  as the result for the original non-existent command.

       The default implementation of unknown behaves as  follows.
       It first calls the auto_load library procedure to load the
       command.  If this succeeds, then it executes the  original
       command  with  its  original  arguments.  If the auto-load
       fails then unknown calls auto_execok to see if there is an
       executable  file  by  the name cmd.  If so, it invokes the
       Tcl exec command with cmd and all the args  as  arguments.
       If  cmd  can't  be auto-executed, unknown checks to see if
       the command was invoked at top-level and  outside  of  any
       script.   If  so, then unknown takes two additional steps.
       First, it sees if cmd  has  one  of  the  following  three
       forms:  !!,  !event,  or ^old^new?^?.  If so, then unknown
       carries out history substitution in the same way that  csh
       would  for  these  constructs.  Finally, unknown checks to
       see if cmd is a unique abbreviation for  an  existing  Tcl
       command.   If so, it expands the command name and executes
       the command with the original arguments.  If none  of  the
       above  efforts  has  been  able  to  execute  the command,
       unknown generates an error return.  If the global variable
       auto_noload   is  defined,  then  the  auto-load  step  is
       skipped.  If the global variable  auto_noexec  is  defined
       then  the auto-exec step is skipped.  Under normal circum-
       stances the return value from unknown is the return  value
       from the command that was eventually executed.


KEYWORDS
       error, non-existent command


_________________________________________________________________

NAME
       unset - Delete variables

SYNOPSIS
       unset ?-nocomplain? ?--? ?name name name ...?
_________________________________________________________________


DESCRIPTION
       This  command removes one or more variables.  Each name is
       a variable name, specified in any of the  ways  acceptable
       to  the set command.  If a name refers to an element of an
       array then that element is removed without  affecting  the
       rest  of  the  array.  If a name consists of an array name
       with no parenthesized index,  then  the  entire  array  is
       deleted.   The  unset  command  returns an empty string as
       result.  If -nocomplain is specified as  the  first  argu-
       ment,  any possible errors are suppressed.  The option may 
       not be abbreviated, in order to disambiguate it from  pos-
       sible  variable names.  The option -- indicates the end of 
       the options, and should be used if you wish  to  remove  a 
       variable  with the same name as any of the options.  If an
       error occurs, any variables after the  named  one  causing
       the  error not deleted.  An error can occur when the named
       variable doesn't exist, or the name  refers  to  an  array
       element  but  the variable is a scalar, or the name refers
       to a variable in a non-existent namespace.


KEYWORDS
       remove, variable


_________________________________________________________________

NAME
       update - Process pending events and idle callbacks

SYNOPSIS
       update ?idletasks?
_________________________________________________________________


DESCRIPTION
       This  command  is  used  to  bring the application ``up to
       date'' by entering the event  loop  repeatedly  until  all
       pending  events  (including idle callbacks) have been pro-
       cessed.

       If the idletasks keyword is specified as  an  argument  to
       the  command,  then no new events or errors are processed;
       only idle callbacks are invoked.  This  causes  operations
       that  are  normally  deferred, such as display updates and
       window layout calculations, to be performed immediately.

       The update idletasks command is useful  in  scripts  where
       changes  have been made to the application's state and you
       want those changes to appear on the  display  immediately,
       rather than waiting for the script to complete.  Most dis-
       play updates are performed as idle  callbacks,  so  update
       idletasks will cause them to run.  However, there are some
       kinds of updates that only happen in response  to  events,
       such  as  those  triggered  by  window size changes; these
       updates will not occur in update idletasks.

       The update command with no options is  useful  in  scripts
       where  you  are  performing a long-running computation but
       you still want the application to respond to  events  such
       as  user  interactions;   if  you occasionally call update
       then user input will be processed during the next call  to
       update.


KEYWORDS
       event, flush, handler, idle, update


_________________________________________________________________

NAME
       uplevel - Execute a script in a different stack frame

SYNOPSIS
       uplevel ?level? arg ?arg ...?
_________________________________________________________________


DESCRIPTION
       All  of  the arg arguments are concatenated as if they had
       been passed to concat; the result is then evaluated in the
       variable  context indicated by level.  Uplevel returns the
       result of that evaluation.

       If level is an integer then it gives a  distance  (up  the
       procedure calling stack) to move before executing the com-
       mand.  If level consists of # followed by  a  number  then
       the  number  gives  an absolute level number.  If level is
       omitted then it defaults to 1.  Level cannot be  defaulted
       if the first command argument starts with a digit or #.

       For  example,  suppose  that  procedure a was invoked from
       top-level, and that it called b,  and  that  b  called  c.
       Suppose that c invokes the uplevel command.  If level is 1
       or #2  or omitted, then the command will  be  executed  in
       the  variable  context of b.  If level is 2 or #1 then the
       command will be executed in the variable context of a.  If
       level is 3 or #0 then the command will be executed at top-
       level (only global variables will be visible).

       The uplevel command causes the invoking procedure to  dis-
       appear  from the procedure calling stack while the command
       is being  executed.   In  the  above  example,  suppose  c
       invokes the command
              uplevel 1 {set x 43; d}
       where  d  is  another Tcl procedure.  The set command will
       modify the variable x in b's context, and d  will  execute
       at  level  3, as if called from b.  If it in turn executes
       the command
              uplevel {set x 42}
       then the set command will modify the same  variable  x  in
       b's context:  the procedure c does not appear to be on the
       call stack  when  d  is  executing.   The  command  ``info
       level''  may  be  used  to obtain the level of the current
       procedure.

       Uplevel makes it possible to implement  new  control  con-
       structs  as  Tcl procedures (for example, uplevel could be
       used to implement the while construct as a Tcl procedure).

       namespace  eval  is  another way (besides procedure calls)
       that the Tcl naming context can change.  It  adds  a  call
       frame  to  the  stack  to represent the namespace context.
       This means each namespace eval command counts  as  another
       call  level  for uplevel and upvar commands.  For example,
       info level 1 will return a list describing a command  that
       is  either  the  outermost procedure call or the outermost
       namespace eval command.   Also,  uplevel  #0  evaluates  a
       script at top-level in the outermost namespace (the global
       namespace).


KEYWORDS
       context, level, namespace, stack frame, variables


_________________________________________________________________

NAME
       upvar - Create link to variable in a different stack frame

SYNOPSIS
       upvar ?level? otherVar myVar ?otherVar myVar ...?
_________________________________________________________________


DESCRIPTION
       This command arranges for one or more local  variables  in
       the  current procedure to refer to variables in an enclos-
       ing procedure call or to global variables.  Level may have
       any  of  the  forms permitted for the uplevel command, and
       may be omitted if the first letter of the  first  otherVar
       isn't  # or a digit (it defaults to 1).  For each otherVar
       argument, upvar makes the variable by  that  name  in  the
       procedure  frame  given  by  level (or at global level, if
       level is #0) accessible in the current  procedure  by  the
       name given in the corresponding myVar argument.  The vari-
       able named by otherVar need not exist at the time  of  the
       call;   it  will be created the first time myVar is refer-
       enced, just like an ordinary  variable.   There  must  not
       exist  a  variable  by the name myVar at the time upvar is
       invoked.  MyVar is always treated as the name of  a  vari-
       able,  not  an array element.  Even if the name looks like
       an array element, such as a(b), a regular variable is cre-
       ated.   OtherVar may refer to a scalar variable, an array,
       or an array element.  Upvar returns an empty string.

       The upvar command simplifies the implementation  of  call-
       by-name  procedure  calling  and  also  makes it easier to
       build new control constructs as Tcl procedures.  For exam-
       ple, consider the following procedure:
              proc add2 name {
                upvar $name x
                set x [expr $x+2]
              }
       Add2  is  invoked  with  an  argument giving the name of a
       variable, and it adds two to the value of  that  variable.
       Although  add2  could  have been implemented using uplevel
       instead of upvar, upvar  makes  it  simpler  for  add2  to
       access the variable in the caller's procedure frame.

       namespace  eval  is  another way (besides procedure calls)
       that the Tcl naming context can change.  It  adds  a  call
       frame  to  the  stack  to represent the namespace context.
       This means each namespace eval command counts  as  another
       call  level  for uplevel and upvar commands.  For example,
       info level 1 will return a list describing a command  that
       is  either  the  outermost procedure call or the outermost
       namespace eval command.   Also,  uplevel  #0  evaluates  a
       script at top-level in the outermost namespace (the global
       namespace).

       If an upvar variable is unset (e.g. x in add2 above),  the 
       unset  operation affects the variable it is linked to, not 
       the upvar variable.  There is no way  to  unset  an  upvar 
       variable  except  by  exiting the procedure in which it is 
       defined.  However, it is possible  to  retarget  an  upvar 
       variable by executing another upvar command.               


Traces and upvar                                                  
       Upvar  interacts with traces in a straightforward but pos-
       sibly unexpected manner.  If a variable trace  is  defined 
       on  otherVar,  that  trace  will  be  triggered by actions 
       involving myVar.  However, the  trace  procedure  will  be 
       passed  the  name of myVar, rather than the name of other-
       Var.  Thus, the output  of  the  following  code  will  be 
       localVar rather than originalVar:                          
              proc traceproc { name index op } {                  
                puts $name                                        
              }                                                   
              proc setByUpvar { name value } {                    
                upvar $name localVar                              
                set localVar $value                               
              }                                                   
              set originalVar 1                                   
              trace variable originalVar w traceproc              
              setByUpvar originalVar 2                            
              }                                                   

       If  otherVar  refers to an element of an array, then vari-
       able traces set for the entire array will not  be  invoked 
       when  myVar is accessed (but traces on the particular ele-
       ment will still be invoked).  In particular, if the  array 
       is  env,  then changes made to myVar will not be passed to 
       subprocesses correctly.


KEYWORDS
       context, frame, global, level, namespace, procedure, vari-
       able


_________________________________________________________________

NAME
       variable - create and initialize a namespace variable

SYNOPSIS
       variable ?name value...? name ?value?
_________________________________________________________________


DESCRIPTION
       This command is normally used within a namespace eval com-
       mand to create one or more variables within  a  namespace.
       Each  variable  name is initialized with value.  The value
       for the last variable is optional.

       If a variable name does not exist, it is created.  In this
       case,  if  value is specified, it is assigned to the newly
       created variable.  If no value is specified, the new vari-
       able  is  left undefined.  If the variable already exists,
       it is set to value if value is specified or left unchanged
       if no value is given.  Normally, name is unqualified (does
       not include the names of any containing  namespaces),  and
       the variable is created in the current namespace.  If name
       includes any namespace qualifiers, the variable is created
       in  the  specified  namespace.   If  the  variable  is not
       defined, it will be visible to the  namespace  which  com-
       mand, but not to the info exists command.

       If  the  variable  command is executed inside a Tcl proce-
       dure, it creates local variables linked to the correspond-
       ing namespace variables (and therefore these variables are
       listed by info locals.)  In this way the variable  command
       resembles  the global command, although the global command
       only links to variables in the global namespace.   If  any
       values  are  given,  they are used to modify the values of
       the associated namespace variables.  If a namespace  vari-
       able does not exist, it is created and optionally initial-
       ized.

       A name argument cannot  reference  an  element  within  an
       array.   Instead,  name should reference the entire array,
       and the initialization value should be  left  off.   After
       the  variable has been declared, elements within the array
       can be set using ordinary set or array commands.


KEYWORDS
       global, namespace, procedure, variable


_________________________________________________________________

NAME
       vwait - Process events until a variable is written

SYNOPSIS
       vwait varName
_________________________________________________________________


DESCRIPTION
       This  command enters the Tcl event loop to process events,
       blocking the application if no events are ready.  It  con-
       tinues processing events until some event handler sets the
       value of variable varName.  Once varName has been set, the
       vwait  command  will  return  as soon as the event handler
       that modified varName completes.   varName  must  globally
       scoped  (either  with a call to global for the varName, or
       with the full namespace path specification).

       In some cases the vwait command may not return immediately
       after  varName  is set.  This can happen if the event han-
       dler that sets varName does not complete immediately.  For
       example,  if an event handler sets varName and then itself
       calls vwait to wait for a different variable, then it  may
       not  return  for  a  long time.  During this time the top-
       level vwait is blocked waiting for the  event  handler  to
       complete, so it cannot return either.


KEYWORDS
       event, variable, wait


_________________________________________________________________

NAME
       while  -  Execute script repeatedly as long as a condition
       is met

SYNOPSIS
       while test body
_________________________________________________________________


DESCRIPTION
       The while command evaluates test as an expression (in  the
       same  way that expr evaluates its argument).  The value of
       the expression must a proper boolean value;  if  it  is  a
       true  value then body is executed by passing it to the Tcl
       interpreter.  Once body has been  executed  then  test  is
       evaluated  again, and the process repeats until eventually
       test evaluates to a false boolean  value.   Continue  com-
       mands may be executed inside body to terminate the current
       iteration of the loop, and break commands may be  executed
       inside  body  to  cause immediate termination of the while
       command.   The  while  command  always  returns  an  empty
       string.

       Note: test should almost always be enclosed in braces.  If
       not, variable substitutions will be made before the  while
       command   starts  executing,  which  means  that  variable
       changes made by the loop body will not  be  considered  in
       the  expression.   This is likely to result in an infinite
       loop.  If test is enclosed in braces,  variable  substitu-
       tions  are  delayed  until  the  expression  is  evaluated
       (before each loop iteration), so changes in the  variables
       will be visible.  For an example, try the following script
       with and without the braces around $x<10:
              set x 0
              while {$x<10} {
                puts "x is $x"
                incr x
              }


KEYWORDS
       boolean value, loop, test, while


