2004-10-27  Donal K. Fellows  <donal.k.fellows@man.ac.uk>

	* doc/[a-s]*.n: Many small general documentation fixes.

2004-10-26  David Gravereaux <davygrvy@pobox.com>

	* generic/tclPipe.c (TclCleanupChildren): bad cast of resolvedPid
	caused PIDs on win95 to go negative.  winpipe-4.2 brought this to
	the surface.  Fixed with sprintf in place of TclFormatInt.  Thanks
	to hgiese [Patch 767676]

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: after.n,v 1.6 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH after n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
after \- Execute a command after a time delay

.LP
The \fBafter \fIms\fR and \fBafter idle\fR forms of the command
assume that the application is event driven:  the delayed commands
will not be executed unless the application enters the event loop.
In applications that are not normally event-driven, such as
\fBtclsh\fR, the event loop can be entered with the \fBvwait\fR
and \fBupdate\fR commands.

.SH "EXAMPLES"
This defines a command to make Tcl do nothing at all for \fIN\fR
seconds:

.CS
proc sleep {N} {
   \fBafter\fR [expr {int($N * 1000)}]
}
.CE
.PP
This arranges for the command \fIwake_up\fR to be run in eight hours
(providing the event loop is active at that time):

.CS
\fBafter\fR [expr {1000 * 60 * 60 * 8}] wake_up
.CE
.PP
The following command can be used to do long-running calculations (as
represented here by \fI::my_calc::one_step\fR, which is assumed to
return a boolean indicating whether another step should be performed)
in a step-by-step fashion, though the calculation itself needs to be
arranged so it can work step-wise.  This technique is extra careful to
ensure that the event loop is not starved by the rescheduling of
processing steps (arranging for the next step to be done using an
already-triggered timer event only when the event queue has been
drained) and is useful when you want to ensure that a Tk GUI remains
responsive during a slow task.

.CS
proc doOneStep {} {
   if {[::my_calc::one_step]} {
      \fBafter idle\fR [list \fBafter\fR 0 doOneStep]
   }
}
doOneStep
.CE

.SH "SEE ALSO"
bgerror(n), concat(n), update(n), vwait(n)

.SH KEYWORDS
cancel, delay, idle callback, sleep, time

'\"
'\" Copyright (c) 1993-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: array.n,v 1.13 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH array n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
array \- Manipulate array variables

Unsets all of the elements in the array that match \fIpattern\fR (using the
matching rules of \fBstring match\fR).  If \fIarrayName\fR isn't the name
of an array variable or there are no matching elements in the array, no
error will be raised.  If \fIpattern\fR is omitted and \fIarrayName\fR is
an array variable, then the command unsets the entire array.
The command always returns an empty string.
.VE 8.3

.SH EXAMPLES

.CS
\fBarray set\fR colorcount {
   red   1
   green 5
   blue  4
   white 9
}

foreach {color count} [\fBarray get\fR colorcount] {
   puts "Color: $color Count: $count"
}
 => Color: blue Count: 4
    Color: white Count: 9
    Color: green Count: 5
    Color: red Count: 1

foreach color [\fBarray names\fR colorcount] {
   puts "Color: $color Count: $colorcount($color)"
}
 => Color: blue Count: 4
    Color: white Count: 9
    Color: green Count: 5
    Color: red Count: 1









foreach color [lsort [\fBarray names\fR colorcount]] {
   puts "Color: $color Count: $colorcount($color)"
}
 => Color: blue Count: 4
    Color: green Count: 5
    Color: red Count: 1
    Color: white Count: 9

\fBarray statistics\fR colorcount
 => 4 entries in table, 4 buckets
    number of buckets with 0 entries: 1
    number of buckets with 1 entries: 2
    number of buckets with 2 entries: 1
    number of buckets with 3 entries: 0
    number of buckets with 4 entries: 0
    number of buckets with 5 entries: 0

'\"
'\" Copyright (c) 1997 by Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: binary.n,v 1.22 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH binary n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
binary \- Insert and extract fields from binary strings

\fBformat\fR) instead.
.SH EXAMPLES
This is a procedure to write a Tcl string to a binary-encoded channel as
UTF-8 data preceded by a length word:
.CS
proc writeString {channel string} {
    set data [encoding convertto utf-8 $string]
    puts -nonewline [\fBbinary format\fR Ia* \e
            [string length $data] $data]
}
.CE
.PP
This procedure reads a string from a channel that was written by the
previously presented \fBwriteString\fR procedure:
.CS
proc readString {channel} {
    if {![\fBbinary scan\fR [read $channel 4] I length]} {
        error "missing length"
    }
    set data [read $channel $length]
    return [encoding convertfrom utf-8 $data]
}
.CE

.SH "SEE ALSO"
format(n), scan(n), tclvars(n)

.SH KEYWORDS
binary, format, scan

.PP
The fact that adding and subtracting hours is defined in terms of
absolute time means that it will add fixed amounts of time in time zones
that observe summer time (Daylight Saving Time).  For example,
the following code sets the value of \fBx\fR to \fB04:00:00\fR because
the clock has changed in the interval in question.
.CS
set s [\fBclock scan\fR {2004-10-30 05:00:00} \\
           -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York]
set a [\fBclock add\fR $s 24 hours -timezone :America/New_York]
set x [\fBclock format\fR $a \\
           -format {%H:%M:%S} -timezone :America/New_York]
.CE
.PP
Adding and subtracting days and weeks is accomplished by converting
the given time to a calendar day and time of day in the appropriate
time zone and locale.  The requisite number of days (weeks are converted
to days by multiplying by seven) is added to the calendar day, and
the date and time are then converted back to a count of seconds from
the epoch time.
.PP
Adding and subtracting a given number of days across the point that
the time changes at the start or end of summer time (Daylight Saving Time)
results in the \fIsame local time\fR on the day in question.  For
instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR.
.CS
set s [\fBclock scan\fR {2004-10-30 05:00:00} \\
           -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York]
set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
set x [\fBclock format\fR $a \\
           -format {%H:%M:%S} -timezone :America/New_York]
.CE
.PP
In cases of ambiguity, where the same local time happens twice
on the same day, the earlier time is used.  In cases where the conversion
yields an impossible time (for instance, 02:30 during the Spring
Daylight Saving Time change using US rules), the time is converted
as if the clock had not changed.  Thus, the following code
will set the value of \fBx\fR to \fB03:30:00\fR.
.CS
set s [\fBclock scan\fR {2004-04-03 02:30:00} \\
           -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York]
set a [\fBclock add\fR $s 1 day -timezone :America/New_York]
set x [\fBclock format\fR $a \\
           -format {%H:%M:%S} -timezone :America/New_York]
.CE
.PP
Adding a given number of days or weeks works correctly across the conversion
between the Julian and Gregorian calendars; the omitted days are skipped.
The following code sets \fBz\fR to \fB1752-09-14\fR.
.CS
set x [\fBclock scan\fR 1752-09-02 -format %Y-%m-%d -locale en_US]
set y [\fBclock add\fR $x 1 day -locale en_US]
set z [\fBclock format\fR $y -format %Y-%m-%d -locale en_US]
.CE
.PP
In the bizarre case that adding the given number of days yields a date
that does not exist because it falls within the dropped days of the
Julian-to-Gregorian conversion, the date is converted as if it was
on the Julian calendar.
.PP

.PP
Daylight savings time correction is applied only when the relative time
is specified in units of days or more, i.e.\ days, weeks, fortnights, months or
years.  This means that when crossing the daylight savings time boundary,
different results will be given for \fBclock scan "1 day"\fR and
\fBclock scan "24 hours"\fR:
.CS
% \fBclock scan\fR "1 day" -base [\fBclock scan\fR 1999-10-31]
941443200
% \fBclock scan\fR "24 hours" -base [\fBclock scan\fR 1999-10-31]
941439600
.CE
.SH "SEE ALSO"
msgcat
.SH "COPYRIGHT"
Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.

'\"
'\" Copyright (c) 1997 Sun Microsystems, Inc.
'\" Copyright (c) 2001 ActiveState Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: dde.n,v 1.16 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH dde n 1.2 dde "Tcl Bundled Packages"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
dde \- Execute a Dynamic Data Exchange command

hang until the event queue is flushed.  This can create a deadlock
situation.
.SH EXAMPLE
This asks Internet Explorer (which must already be running) to go to a
particularly important website:
.CS
package require dde
\fBdde execute\fR iexplore WWW_OpenURL http://www.tcl.tk/
.CE

.SH "SEE ALSO"
tk(n), winfo(n), send(n)

.SH KEYWORDS
application, dde, name, remote execution

'\"
'\" Copyright (c) 1998 by Scriptics Corporation.
'\" 
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: encoding.n,v 1.6 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH encoding n "8.1" Tcl "Tcl Built-In Commands"
.BS
.SH NAME
encoding \- Manipulate encodings
.SH SYNOPSIS
\fBencoding \fIoption\fR ?\fIarg arg ...\fR?
.BE

.SH INTRODUCTION
.PP
Strings in Tcl are encoded using 16-bit Unicode characters.  Different
operating system interfaces or applications may generate strings in
other encodings such as Shift-JIS.  The \fBencoding\fR command helps
to bridge the gap between Unicode and these other formats.

.SH DESCRIPTION
.PP
Performs one of several encoding related operations, depending on
\fIoption\fR.  The legal \fIoption\fRs are:
.TP
\fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR
Convert \fIdata\fR to Unicode from the specified \fIencoding\fR.  The
characters in \fIdata\fR 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
\fIencoding\fR.  If \fIencoding\fR is not specified, the current
system encoding is used.
.TP
\fBencoding convertto\fR ?\fIencoding\fR? \fIstring\fR
Convert \fIstring\fR from Unicode to the specified \fIencoding\fR.
The result is a sequence of bytes that represents the converted
string.  Each byte is stored in the lower 8-bits of a Unicode
character.  If \fIencoding\fR is not specified, the current
system encoding is used.
.TP
\fBencoding names\fR
Returns a list containing the names of all of the encodings that are
currently available. 
.TP
\fBencoding system\fR ?\fIencoding\fR?
Set the system encoding to \fIencoding\fR. If \fIencoding\fR is
omitted then the command returns the current system encoding.  The
system encoding is used whenever Tcl passes strings to system calls.

.SH EXAMPLE
.PP
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
characters by simply typing the strings in place in the script.
However, because the \fBsource\fR command always reads files using the
current system encoding, Tcl will only source such files correctly
when the encoding used to write the file is the same.  This tends not
to be true in an internationalized setting.  For example, if such a
file was sourced in North America (where the ISO8859-1 is normally
used), each byte in the file would be treated 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
contain a sequence of Latin-1 characters that correspond to the bytes
of the original string.  The \fBencoding\fR command can be used to
convert this string to the expected Japanese Unicode characters.  For
example,
.CS
set s [\fBencoding convertfrom\fR euc-jp "\\xA4\\xCF"]
.CE
would return the Unicode string "\\u306F", which is the Hiragana
letter HA.

.SH "SEE ALSO"
Tcl_GetEncoding(3)

.SH KEYWORDS
encoding

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: file.n,v 1.38 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH file n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
file \- Manipulate file names and attributes

not the effective ones. 
.SH EXAMPLES
This procedure shows how to search for C files in a given directory
that have a correspondingly-named object file in the current
directory:
.CS
proc findMatchingCFiles {dir} {
   set files {}
   switch $::tcl_platform(platform) {
      windows {
         set ext .obj
      }
      unix {
         set ext .o
      }
   }
   foreach file [glob -nocomplain -directory $dir *.c] {
      set objectFile [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext
      if {[\fBfile exists\fR $objectFile]} {
         lappend files $file
      }
   }
   return $files
}
.CE
.PP
Rename a file and leave a symbolic link pointing from the old location
to the new place:
.CS
set oldName foobar.txt
set newName foo/bar.txt
# Make sure that where we're going to move to exists...
if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {
   \fBfile mkdir\fR [\fBfile dirname\fR $newName]
}
\fBfile rename\fR $oldName $newName
\fBfile link\fR -symbolic $oldName $newName
.CE

.SH "SEE ALSO"
filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
fblocked(n), flush(n)

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

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
'\" Copyright (c) 1998-2000 Ajuba Solutions
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: info.n,v 1.14 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH info n 8.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
info \- Return information about the state of the Tcl interpreter

.SH EXAMPLE
This command prints out a procedure suitable for saving in a Tcl
script:
.CS
proc printProc {procName} {
    set result [list proc $procName]
    set formals {}
    foreach var [\fBinfo args\fR $procName] {
        if {[\fBinfo default\fR $procName $var def]} {
            lappend formals [list $var $def]
        } else {
            # Still need the list-quoting because variable
            # names may properly contain spaces.
            lappend formals [list $var]
        }
    }
    puts [lappend result $formals [\fBinfo body\fR $procName]]
}
.CE

.SH "SEE ALSO"
global(n), proc(n)

.SH KEYWORDS
command, information, interpreter, level, namespace, procedure, variable

'\" Local Variables:
'\" mode: nroff
'\" End:

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\" Copyright (c) 2004 Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: interp.n,v 1.19 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH interp n 7.6 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
interp \- Create and manipulate Tcl interpreters

.VE 8.5
.SH CREDITS
This mechanism is based on the Safe-Tcl prototype implemented
by Nathaniel Borenstein and Marshall Rose.
.SH EXAMPLES
Creating and using an alias for a command in the current interpreter:
.CS
\fBinterp alias\fR {} getIndex {} lsearch {alpha beta gamma delta}
set idx [getIndex delta]
.CE
.PP
Executing an arbitrary command in a safe interpreter where every
invokation of \fBlappend\fR is logged:
.CS
set i [\fBinterp create\fR -safe]
\fBinterp hide\fR $i lappend
\fBinterp alias\fR $i lappend {} loggedLappend $i
proc loggedLappend {i args} {
   puts "logged invokation of lappend $args"
   \fBinterp invokehidden\fR $i lappend {expand}$args
}
\fBinterp eval\fR $i $someUntrustedScript
.CE
.PP
.VS 8.5
Setting a resource limit on an interpreter so that an infinite loop
terminates.
.CS
set i [\fBinterp create\fR]
\fBinterp limit\fR $i command -value 1000
\fBinterp eval\fR $i {
   set x 0
   while {1} {
      puts "Counting up... [incr x]"
   }
}
.CE
.VE 8.5

.SH "SEE ALSO"
load(n), safe(n), Tcl_CreateSlave(3)
.SH KEYWORDS
alias, master interpreter, safe interpreter, slave interpreter

.SH COMMANDS
.TP
\fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
Returns a translation of \fIsrc-string\fR according to the
user's current locale.  If additional arguments past \fIsrc-string\fR
are given, the \fBformat\fR command is used to substitute the
additional arguments in the translation of \fIsrc-string\fR.
.PP
\fB::msgcat::mc\fR will search the messages defined
in the current namespace for a translation of \fIsrc-string\fR; 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, \fB::msgcat::mcunknown\fR is called and the string
returned from \fB::msgcat::mcunknown\fR is returned.
.PP

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.
.PP
For example, executing the code
.CS
\fB::msgcat::mcset\fR en hello "hello from ::"
namespace eval foo {
   \fB::msgcat::mcset\fR en hello "hello from ::foo"
}
puts [\fB::msgcat::mc\fR hello]
namespace eval foo {puts [\fB::msgcat::mc\fR hello]}
.CE
will print
.CS
hello from ::
hello from ::foo
.CE
.PP
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.
.PP
For example, executing (in the ``en'' locale) the code 
.CS
\fB::msgcat::mcset\fR en m1 ":: message1"
\fB::msgcat::mcset\fR en m2 ":: message2"
\fB::msgcat::mcset\fR en m3 ":: message3"
namespace eval ::foo {
   \fB::msgcat::mcset\fR en m2 "::foo message2"
   \fB::msgcat::mcset\fR en m3 "::foo message3"
}
namespace eval ::foo::bar {
   \fB::msgcat::mcset\fR en m3 "::foo::bar message3"
}
namespace import \fB::msgcat::mc\fR
puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"
namespace eval ::foo {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"}
namespace eval ::foo::bar {puts "[\fBmc\fR m1]; [\fBmc\fR m2]; [\fBmc\fR m3]"}
.CE
will print
.CS
:: message1; :: message2; :: message3
:: message1; ::foo message2; ::foo message3
:: message1; ::foo message2; ::foo::bar message3
.CE

The file contains a series of calls to \fBmcset\fR and
\fBmcmset\fR, setting the necessary translation strings
for the language, likely enclosed in a \fBnamespace eval\fR
so that all source strings are tied to the namespace of
the package. For example, a short \fBes.msg\fR might contain:
.CS
namespace eval ::mypackage {
   \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!"
}
.CE
.SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES"
.PP
If a package is installed into a subdirectory of the
\fBtcl_pkgPath\fR and loaded via \fBpackage require\fR, the
following procedure is recommended.
.IP [1]
During package installation, create a subdirectory
\fBmsgs\fR under your package directory.
.IP [2]
Copy your *.msg files into that directory.
.IP [3]
 Add the following command to your package
initialization script:
.CS
# load language files, stored in msgs subdirectory
\fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs]
.CE
.SH "POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS"
.PP
It is possible that a message string used as an argument
to \fBformat\fR might have positionally dependent parameters that
might need to be repositioned.  For example, it might be
syntactically desirable to rearrange the sentence structure

.CS
format "We produced %1\\$d units in location %2\\$s" $num $city
format "In location %2\\$s we produced %1\\$d units" $num $city
.CE
.PP
Similarly, positional parameters can be used with \fBscan\fR to
extract values from internationalized strings.

.SH CREDITS
.PP
The message catalog code was developed by Mark Harrison.

.SH "SEE ALSO"
format(n), scan(n), namespace(n), package(n)

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

'\"
'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
'\" Copyright (c) 1997 Sun Microsystems, Inc.
'\" Copyright (c) 2000 Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: namespace.n,v 1.16 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH namespace n 8.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
namespace \- create and manipulate contexts for commands and variables

won't interfere with the commands and variables of other namespaces.
Tcl has always had one such collection,
which we refer to as the \fIglobal namespace\fR.
The global namespace holds all global variables and commands.
The \fBnamespace eval\fR command lets you create new namespaces.
For example,
.CS
\fBnamespace eval\fR Counter {
   \fBnamespace export\fR bump
   variable num 0

   proc bump {} {
      variable num
      incr num
   }

}
.CE
creates a new namespace containing the variable \fBnum\fR and
the procedure \fBbump\fR.
The commands and variables in this namespace are separate from
other commands and variables in the same program.
If there is a command named \fBbump\fR in the global namespace,
for example, it will be different from the command \fBbump\fR

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 \fBnamespace eval\fR commands.
For example, the following series of commands has the same effect
as the namespace definition shown above:
.CS
\fBnamespace eval\fR Counter {
   variable num 0
   proc bump {} {
      variable num
      return [incr num]
   }
}
\fBnamespace eval\fR Counter {
   proc test {args} {
      return $args
   }
}
\fBnamespace eval\fR Counter {
    rename test ""

}
.CE
Note that the \fBtest\fR procedure is added to the \fBCounter\fR namespace,
and later removed via the \fBrename\fR command.
.PP
Namespaces can have other namespaces within them,
so they nest hierarchically.
A nested namespace is encapsulated inside its parent namespace

.PP
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 \fBCounter\fR procedures like this:
.CS
Counter::bump 5
Counter::Reset
.CE
We could access the current count like this:
.CS
puts "count = $Counter::num"
.CE
When one namespace contains another, you may need more than one
qualifier to reach its elements.
If we had a namespace \fBFoo\fR that contained the namespace \fBCounter\fR,
you could invoke its \fBbump\fR procedure
from the global namespace like this:
.CS
Foo::Counter::bump 3
.CE
.PP
You can also use qualified names when you create and rename commands.
For example, you could add a procedure to the \fBFoo\fR
namespace like this:
.CS
proc Foo::Test {args} {return $args}
.CE
And you could move the same procedure to another namespace like this:
.CS
rename Foo::Test Bar::Test
.CE
.PP
There are a few remaining points about qualified names
that we should cover.
Namespaces have nonempty names except for the global namespace.
\fB::\fR is disallowed in simple command, variable, and namespace names
except as a namespace separator.

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.
.PP
In the following example,
.CS
set traceLevel 0
\fBnamespace eval\fR Debug {
   printTrace $traceLevel

}
.CE
Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR
and then in the global namespace.
It looks up the command \fBprintTrace\fR 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:
.CS
set traceLevel 0
\fBnamespace eval\fR Foo {
   variable traceLevel 3

   \fBnamespace eval\fR Debug {
      printTrace $traceLevel
   }

}
.CE
Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR.
Since it is not found there, Tcl then looks for it 
in the global namespace.
The variable \fBFoo::traceLevel\fR is completely ignored
during the name resolution process.
.PP
You can use the \fBnamespace which\fR command to clear up any question
about name resolution.
For example, the command:
.CS
\fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR \-variable traceLevel}
.CE
returns \fB::traceLevel\fR.
On the other hand, the command,
.CS
\fBnamespace eval\fR Foo {\fBnamespace which\fR \-variable traceLevel}
.CE
returns \fB::Foo::traceLevel\fR.
.PP
As mentioned above,
namespace names are looked up differently
than the names of variables and commands.
Namespace names are always resolved in the current namespace.

Namespaces are often used to represent libraries.
Some library commands are used so frequently
that it is a nuisance to type their qualified names.
For example, suppose that all of the commands in a package
like BLT are contained in a namespace called \fBBlt\fR.
Then you might access these commands like this:
.CS
Blt::graph .g \-background red
Blt::table . .g 0,0
.CE
If you use the \fBgraph\fR and \fBtable\fR commands frequently,
you may want to access them without the \fBBlt::\fR prefix.
You can do this by importing the commands into the current namespace,
like this:
.CS
\fBnamespace import\fR Blt::*
.CE
This adds all exported commands from the \fBBlt\fR namespace
into the current namespace context, so you can write code like this:
.CS
graph .g \-background red
table . .g 0,0
.CE
The \fBnamespace import\fR command only imports commands
from a namespace that that namespace exported
with a \fBnamespace export\fR command.
.PP
Importing \fIevery\fR 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
.CS
\fBnamespace import\fR Blt::graph Blt::table
.CE
imports only the \fBgraph\fR and \fBtable\fR commands into the
current context.
.PP
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 \fBnamespace import\fR command to pick up new commands
that have appeared in a namespace.  In that case, you can use the
\fB\-force\fR option, and existing commands will be silently overwritten:
.CS
\fBnamespace import\fR \-force Blt::graph Blt::table
.CE
If for some reason, you want to stop using the imported commands,
you can remove them with a \fBnamespace forget\fR command, like this:
.CS
\fBnamespace forget\fR Blt::*
.CE
This searches the current namespace for any commands imported from \fBBlt\fR.
If it finds any, it removes them.  Otherwise, it does nothing.
After this, the \fBBlt\fR commands must be accessed with the \fBBlt::\fR
prefix.
.PP
When you delete a command from the exporting namespace like this:
.CS
rename Blt::graph ""
.CE
the command is automatically removed from all namespaces that import it.
.SH "EXPORTING COMMANDS"
You can export commands from a namespace like this:
.CS
\fBnamespace eval\fR Counter {
   \fBnamespace export\fR 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!"
      }
   }

}
.CE
The procedures \fBbump\fR and \fBreset\fR are exported,
so they are included when you import from the \fBCounter\fR namespace,
like this:
.CS
\fBnamespace import\fR Counter::*
.CE
However, the \fBCheck\fR procedure is not exported,
so it is ignored by the import operation.
.PP
The \fBnamespace import\fR command only imports commands
that were declared as exported by their namespace.
The \fBnamespace export\fR command specifies what commands
may be imported by other namespaces.
If a \fBnamespace import\fR command specifies a command
that is not exported, the command is not imported.
.SH "SCOPED SCRIPTS"
The \fBnamespace code\fR command is the means by which a script may be
packaged for evaluation in a namespace other than the one in which it
was created.  It is used most often to create event handlers, Tk bindings,
and traces for evaluation in the global context.  For instance, the following
code indicates how to direct a variable trace callback into the current
namespace:
.CS
\fBnamespace eval\fR a {
   variable b
   proc theTraceCallback { n1 n2 op } {
      upvar 1 $n1 var
      puts "the value of $n1 has changed to $var"
      return
   }
   trace variable b w [\fBnamespace code\fR theTraceCallback]
}
set a::b c
.CE
When executed, it prints the message:
.CS
the value of a::b has changed to c
.CE

will be thrown when the subcommand is still not recognized during
reparsing. It is also an error for an \fB\-unknown\fR handler to
delete its namespace.
.VE 8.5
.SH EXAMPLES
Create a namespace containing a variable and an exported command:
.CS
\fBnamespace eval\fR foo {
   variable bar 0
   proc grill {} {
      variable bar
      puts "called [incr bar] times"
   }
   \fBnamespace export\fR grill
}
.CE
.PP
Call the command defined in the previous example in various ways.
.CS
# Direct call
foo::grill

# Import into current namespace, then call local alias
namespace import foo::grill
grill

# Create two ensembles, one with the default name and one with a
# specified name.  Then call through the ensembles.
\fBnamespace eval\fR foo {
   \fBnamespace ensemble\fR create
   \fBnamespace ensemble\fR create -command ::foobar
}
foo grill
foobar grill
.CE
.PP
Look up where the command imported in the previous example came from:
.CS
puts "grill came from [\fBnamespace which\fR grill]"
.CE

.SH "SEE ALSO"
interp(n), variable(n)

.SH KEYWORDS
command, ensemble, exported, internal, variable

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: open.n,v 1.21 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH open n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
open \- Open a file-based or command pipeline channel

input, but is redirected from a file, then the above problem does not occur.  
.LP
See the PORTABILITY ISSUES section of the \fBexec\fR command for additional
information not specific to command pipelines about executing
applications on the various platforms
.SH "EXAMPLE"
Open a command pipeline and catch any errors:

.CS
set fl [\fBopen\fR "| ls this_file_does_not_exist"]
set data [read $fl]
if {[catch {close $fl} err]} {
    puts "ls command failed: $err"
}
.CE

.SH "SEE ALSO"
file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),
puts(n), exec(n), pid(n), fopen(3)

.SH KEYWORDS
access mode, append, create, file, non-blocking, open, permissions,
pipeline, process, serial

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: package.n,v 1.9 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH package n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
package \- Facilities for package loading and version control

.CE
.PP
To test to see if the Snack package is available and load if it is
(often useful for optional enhancements to programs where the loss of
the functionality is not critical) do this:
.CS
if {[catch {\fBpackage require\fR Snack}]} {
   # We have the package, configure the app to use it
} else {
   # Set up a dummy interface to work around the absence
}
.CE
.PP
When writing a package implementation, you should put the following at
the \fIbottom\fR of your library script so it is only called once the
package has been successfully set up:
.CS

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: pid.n,v 1.6 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH pid n 7.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
pid \- Retrieve process identifiers

that isn't a process pipeline.
If no \fIfileId\fR argument is given then \fBpid\fR returns the process
identifier of the current process.
All process identifiers are returned as decimal strings.
.SH EXAMPLE
Print process information about the processes in a pipeline using the
SysV \fBps\fR program before reading the output of that pipeline:
.PP
.CS
set pipeline [open "| zcat somefile.gz | grep foobar | sort -u"]
# Print process information
exec ps -fp [\fBpid\fR $pipeline] >@stdout
# Print a separator and then the output of the pipeline
puts [string repeat - 70]
puts [read $pipeline]

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: proc.n,v 1.5 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH proc n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
proc \- Create a Tcl procedure

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.
.SH EXAMPLES
This is a procedure that accepts arbitrarily many arguments and prints
them out, one by one.
.CS
\fBproc\fR printArguments args {
   foreach arg $args {
      puts $arg
   }
}
.CE
.PP
This procedure is a bit like the \fBincr\fR command, except it
multiplies the contents of the named variable by the value, which
defaults to \fB2\fR:
.CS
\fBproc\fR mult {varName {multiplier 2}} {
   upvar 1 $varName var
   set var [expr {$var * $multiplier}]
}
.CE

.SH "SEE ALSO"
info(n), unknown(n)

.SH KEYWORDS
argument, procedure

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: puts.n,v 1.8 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH puts n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
puts \- Write to a channel

be used in an event-driven fashion with the \fBfileevent\fR command
(don't invoke \fBputs\fR unless you have recently been notified
via a file event that the channel is ready for more output data).
.SH EXAMPLES
Write a short message to the console (or wherever \fBstdout\fR is
directed):
.CS
\fBputs\fR "Hello, World!"
.CE
.PP
Print a message in several parts:
.CS
\fBputs\fR -nonewline "Hello, "
\fBputs\fR "World!"
.CE
.PP
Print a message to the standard error channel:
.CS
\fBputs\fR stderr "Hello, World!"
.CE
.PP
Append a log message to a file:
.CS
set chan [open my.log a]
set timestamp [clock format [clock seconds]]
\fBputs\fR $chan "$timestamp - Hello, World!"
close $chan
.CE

.SH "SEE ALSO"
file(n), fileevent(n), Tcl_StandardChannels(3)

.SH KEYWORDS
channel, newline, output, write

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: pwd.n,v 1.6 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH pwd n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
pwd \- Return the absolute path of the current working directory

.CS
set tarFile [file normalize somefile.tar]
set savedDir [\fBpwd\fR]
cd /tmp
exec tar -xf $tarFile
cd $savedDir
.CE

.SH "SEE ALSO"
file(n), cd(n), glob(n), filename(n)

.SH KEYWORDS
working directory

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: read.n,v 1.9 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH read n 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
read \- Read from a channel

from the serial port.
.TP
\fBread \fIchannelId\fR 
In this form \fBread\fR blocks until the reception of the end-of-file
character, see \fBfconfigure -eofchar\fR. If there no end-of-file
character has been configured for the channel, then \fBread\fR will
block forever.

.SH "EXAMPLE"
This example code reads a file all at once, and splits it into a list,
with each line in the file corresponding to an element in the list:

.CS
set fl [open /proc/meminfo]
set data [\fBread\fR $fl]
close $fl
set lines [split $data \\n]
.CE

.SH "SEE ALSO"
file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)

.SH KEYWORDS
blocking, channel, end of line, end of file, nonblocking, read, translation, encoding

'\"
'\" Copyright (c) 1998 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: regexp.n,v 1.16 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH regexp n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
regexp \- Match a regular expression against a string

\fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR
has been specified or to an empty string otherwise.
.SH EXAMPLES
Find the first occurrence of a word starting with \fBfoo\fR in a
string that is not actually an instance of \fBfoobar\fR, and get the
letters following it up to the end of the word into a variable:
.CS
\fBregexp\fR {\\<foo(?!bar\\>)(\\w*)} $string \-> restOfWord
.CE
Note that the whole matched substring has been placed in the variable
\fB\->\fR which is a name chosen to look nice given that we are not
actually interested in its contents.
.PP
Find the index of the word \fBbadger\fR (in any case) within a string
and store that in the variable \fBlocation\fR:
.CS
\fBregexp\fR \-indices {(?i)\\<badger\\>} $string location
.CE
.PP
Count the number of octal digits in a string:
.CS
\fBregexp\fR \-all {[0\-7]} $string
.CE
.PP
List all words (consisting of all sequences of non-whitespace
characters) in a string:
.CS
\fBregexp\fR \-all \-inline {\\S+} $string
.CE

.SH "SEE ALSO"
re_syntax(n), regsub(n)

.SH KEYWORDS
match, regular expression, string

'\"
'\" Copyright (c) 1997 Sun Microsystems, Inc.
'\" Copyright (c) 2002 ActiveState Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: registry.n,v 1.12 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH registry n 1.1 registry "Tcl Bundled Packages"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
registry \- Manipulate the Windows registry

Print out how double-clicking on a Tcl script file will invoke a Tcl
interpreter:
.CS
package require registry
set ext .tcl

# Read the type name
set type [\fBregistry get\fR HKEY_CLASSES_ROOT\e\e$ext {}]
# Work out where to look for the command
set path HKEY_CLASSES_ROOT\e\e$type\e\eShell\e\eOpen\e\ecommand
# Read the command!
set command [\fBregistry get\fR $path {}]

puts "$ext opens with $command"
.CE

.SH KEYWORDS
registry

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 2000 Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: regsub.n,v 1.12 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH regsub n 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
regsub \- Perform substitutions based on regular expression pattern matching

.VE 8.4
See the manual entry for \fBregexp\fR for details on the interpretation
of regular expressions.
.SH EXAMPLES
Replace (in the string in variable \fIstring\fR) every instance of
\fBfoo\fR which is a word by itself with \fBbar\fR:
.CS
\fBregsub\fR -all {\e<foo\e>} $string bar string
.CE
.PP
Insert double-quotes around the first instance of the word
\fBinteresting\fR, however it is capitalised.
.CS
\fBregsub\fR -nocase {\e<interesting\e>} $string {"&"} string
.CE
.PP
Convert all non-ASCII and Tcl-significant characters into \eu escape
sequences by using \fBregsub\fR and \fBsubst\fR in combination:
.CS
# This RE is just a character class for everything "bad"
set RE {[][{}\e$\es\eu0100-\euffff]}

# We will substitute with a fragment of Tcl script in brackets
set substitution {[format \e\e\e\eu%04x [scan "\e\e&" %c]]}

# Now we apply the substitution to get a subst-string that
# will perform the computational parts of the conversion.
set quoted [subst [\fBregsub\fR -all $RE $string $substitution]]
.CE

.SH "SEE ALSO"
regexp(n), re_syntax(n), subst(n)

.SH KEYWORDS
match, pattern, regular expression, substitute

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: rename.n,v 1.5 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH rename n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
rename \- Rename or delete a command

If a command is renamed into a different namespace,
future invocations of it will execute in the new namespace.
The \fBrename\fR command returns an empty string as result.
.SH EXAMPLE
The \fBrename\fR command can be used to wrap the standard Tcl commands
with your own monitoring machinery.  For example, you might wish to
count how often the \fBsource\fR command is called:

.CS
\fBrename\fR ::source ::theRealSource
set sourceCount 0
proc ::source args {
    global sourceCount
    puts "called source for the [incr sourceCount]'th time"
    uplevel 1 ::theRealSource $args
}
.CE

.SH "SEE ALSO"
namespace(n), proc(n)

.SH KEYWORDS
command, delete, namespace, rename

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Contributions from Don Porter, NIST, 2003.  (not subject to US copyright)
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: return.n,v 1.11 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH return n 8.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
return \- Return from a procedure, or set return code of a script

.PP
The \fBreturn\fR command serves a similar function within script
files that are evaluated by the \fBsource\fR command.  When \fBsource\fR
evaluates the contents of a file as a script, an invocation of
the \fBreturn\fR command will cause script evaluation
to immediately cease, and the value \fIresult\fR (or an empty string)
will be returned as the result of the \fBsource\fR command.

.SH "EXCEPTIONAL RETURN CODES"
.PP
In addition to the result of a procedure, the return
code of a procedure may also be set by \fBreturn\fR
through use of the \fB-code\fR option.
In the usual case where the \fB\-code\fR option isn't
specified the procedure will return normally.

procedures that implement a new control structure.
.PP
The \fBreturn -code\fR command acts similarly within script
files that are evaluated by the \fBsource\fR command.  During the
evaluation of the contents of a file as a script by \fBsource\fR,
an invocation of the \fBreturn -code \fIcode\fR command will cause
the return code of \fBsource\fR to be \fIcode\fR.

.SH "RETURN OPTIONS"
.PP
.VS 8.5
In addition to a result and a return code, evaluation of a command
in Tcl also produces a dictionary of return options.  In general
usage, all \fIoption value\fR pairs given as arguments to \fBreturn\fR
become entries in the return options dictionary, and any values at all

.TP
\fB-options \fIoptions\fR
.VS 8.5
The value \fIoptions\fR must be a valid dictionary.  The entries of that
dictionary are treated as additional \fIoption value\fR pairs for the
\fBreturn\fR command.
.VE 8.5

.SH "RETURN CODE HANDLING MECHANISMS"
.PP
Return codes are used in Tcl to control program flow.  A Tcl script
is a sequence of Tcl commands.  So long as each command evaluation
returns a return code of \fBTCL_OK\fR, evaluation will continue to the next
command in the script.  Any exceptional return code (non-\fBTCL_OK\fR)
returned by a command evaluation causes the flow on to the next

is provided the option \fB-level 0\fR, then the return code
of the \fBreturn\fR command itself will be the value \fIcode\fR
of the \fB-code\fR option (or \fBTCL_OK\fR by default).  Any other value
for the \fB-level\fR option (including the default value of 1)
will cause the return code of the \fBreturn\fR command itself
to be \fBTCL_RETURN\fR, triggering a return from the enclosing procedure.
.VE 8.5

.SH EXAMPLES

First, a simple example of using \fBreturn\fR to return from a
procedure, interrupting the procedure body.

.CS
proc printOneLine {} {
   puts "line 1"    ;# This line will be printed.
   \fBreturn\fR		
   puts "line 2"    ;# This line will not be printed.
}
.CE
.PP
Next, an example of using \fBreturn\fR to set the value
returned by the procedure.

.CS
proc returnX {} {\fBreturn\fR X}
puts [returnX]    ;# prints "X"
.CE
.PP
Next, a more complete example, using \fBreturn -code error\fR
to report invalid arguments.

.CS
proc factorial {n} {
   if {![string is integer $n] || ($n < 0)} {
      \fBreturn\fR -code error \\
            "expected non-negative integer,\\
             but got \\"$n\\""
   }
   if {$n < 2} {
      \fBreturn\fR 1
   }
   set m [expr {$n - 1}]
   set code [catch {factorial $m} factor]
   if {$code != 0} {
      \fBreturn\fR -code $code $factor
   }
   set product [expr {$n * $factor}]
   if {$product < 0} {
      \fBreturn\fR -code error \\
            "overflow computing factorial of $n"
   }
   \fBreturn\fR $product
}
.CE
.PP
Next, a procedure replacement for \fBbreak\fR.

.CS
proc myBreak {} {
   \fBreturn\fR -code break
}
.CE
.PP
.VS 8.5
With the \fB-level 0\fR option, \fBreturn\fR itself can serve
as a replacement for \fBbreak\fR.

.CS
interp alias {} Break {} \fBreturn\fR -level 0 -code break
.CE
.PP
An example of using \fBcatch\fR and \fBreturn -options\fR to
re-raise a caught error:

.CS
proc doSomething {} {
   set resource [allocate]
   catch {
      # Long script of operations
      # that might raise an error
   } result options
   deallocate $resource
   \fBreturn\fR -options $options $result
}
.CE
.PP
Finally an example of advanced use of the \fBreturn\fR options
to create a procedure replacement for \fBreturn\fR itself:

.CS
proc myReturn {args} {
   set result ""
   if {[llength $args] % 2} {
      set result [lindex $args end]
      set args [lrange $args 0 end-1]
   }
   set options [dict merge {-level 1} $args]
   dict incr options -level
   \fBreturn\fR -options $options $result
}
.CE
.VE 8.5

.SH "SEE ALSO"
break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n)

.SH KEYWORDS
break, catch, continue, error, procedure, return

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 2000 Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: scan.n,v 1.12 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH scan n 8.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
scan \- Parse string using conversion specifiers in the style of sscanf

If the end of the input string is reached before any conversions have been
performed and no variables are given, an empty string is returned.
.SH EXAMPLES
Parse a simple color specification of the form \fI#RRGGBB\fR using
hexadecimal conversions with field sizes:
.CS
set string "#08D03F"
\fBscan\fR $string "#%2x%2x%2x" r g b
.CE
.PP
Parse a \fIHH:MM\fR time string, noting that this avoids problems with
octal numbers by forcing interpretation as decimals (if we did not
care, we would use the \fB%i\fR conversion instead):
.CS
set string "08:08"   ;# *Not* octal!
if {[\fBscan\fR $string "%d:%d" hours minutes] != 2} {
   error "not a valid time string"
}
# We have to understand numeric ranges ourselves...
if {$minutes < 0 || $minutes > 59} {
   error "invalid number of minutes"
}
.CE
.PP
Break a string up into sequences of non-whitespace characters (note
the use of the \fB%n\fR conversion so that we get skipping over
leading whitespace correct):
.CS
set string " a string {with braced words} + leading space "
set words {}
while {[\fBscan\fR $string %s%n word length] == 2} {
   lappend words $word
   set string [string range $string $length end]
}
.CE
.PP
Parse a simple coordinate string, checking that it is complete by
looking for the terminating character explicitly:
.CS
set string "(5.2,-4e-2)"
# Note that the spaces before the literal parts of
# the scan pattern are significant, and that ")" is
# the Unicode character \\u0029
if {
   [\fBscan\fR $string " (%f ,%f %c" x y last] != 3
   || $last != 0x0029
} then {
   error "invalid coordinate string"
}
puts "X=$x, Y=$y"
.CE

.SH "SEE ALSO"
format(n), sscanf(3)

.SH KEYWORDS
conversion specifier, parse, scan

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: seek.n,v 1.7 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH seek n 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
seek \- Change the access position for an open channel

not characters, unlike \fBread\fR.
.VE 8.1
.SH EXAMPLES
Read a file twice:
.CS
set f [open file.txt]
set data1 [read $f]
\fBseek\fR $f 0
set data2 [read $f]
close $f
# $data1 == $data2 if the file wasn't updated
.CE
.PP
Read the last 10 bytes from a file:
.CS
set f [open file.data]
# This is guaranteed to work with binary data but
# may fail with other encodings...
fconfigure $f -translation binary
\fBseek\fR $f -10 end
set data [read $f 10]
close $f
.CE

.SH "SEE ALSO"
file(n), open(n), close(n), gets(n), tell(n), Tcl_StandardChannels(3)
 
.SH KEYWORDS
access position, file, seek

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: set.n,v 1.6 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH set n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
set \- Read and write variables

If a procedure is active and \fIvarName\fR is unqualified, then
\fIvarName\fR refers to a parameter or local variable of the procedure,
unless \fIvarName\fR was declared to resolve differently through one of the 
\fBglobal\fR, \fBvariable\fR or \fBupvar\fR commands.
.SH EXAMPLES
Store a random number in the variable \fIr\fR:
.CS
\fBset\fR r [expr rand()]
.CE
.PP
Store a short message in an array element:
.CS
\fBset\fR anAry(msg) "Hello, World!"
.CE
.PP
Store a short message in an array element specified by a variable:
.CS
\fBset\fR elemName "msg"
\fBset\fR anAry($elemName) "Hello, World!"
.CE
.PP
Copy a value into the variable \fIout\fR from a variable whose name is
stored in the \fIvbl\fR (note that it is often easier to use arrays in
practice instead of doing double-dereferencing):
.CS
\fBset\fR in0 "small random"
\fBset\fR in1 "large random"
\fBset\fR vbl in[expr {rand() >= 0.5}]
\fBset\fR out [\fBset\fR $vbl]
.CE

.SH "SEE ALSO"
expr(n), global(n), namespace(n), proc(n), trace(n), unset(n), upvar(n), variable(n)

.SH KEYWORDS
read, write, variable

'\"
'\" Copyright (c) 1996 Sun Microsystems, Inc.
'\" Copyright (c) 1998-1999 by Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: socket.n,v 1.12 2004/10/27 14:24:37 dkf Exp $
.so man.macros
.TH socket n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
socket \- Open a TCP network connection
.SH SYNOPSIS

.PP
Note that the default encoding for \fIall\fR sockets is the system
encoding, as returned by \fBencoding system\fR.  Most of the time, you
will need to use \fBfconfigure\fR to alter this to something else,
such as \fIutf\-8\fR (ideal for communicating with other Tcl
processes) or \fIiso8859\-1\fR (useful for many network protocols,
especially the older ones).

.SH "CLIENT SOCKETS"
.PP
If the \fB\-server\fR 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.
\fIPort\fR and \fIhost\fR specify a port
to connect to;  there must be a server accepting connections on

may not yet be connected to the server, when the call to \fBsocket\fR
returns. When a \fBgets\fR or \fBflush\fR 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 \fBgets\fR or \fBflush\fR is done on
the socket before the connection attempt succeeds or fails, the operation
returns immediately and \fBfblocked\fR on the socket returns 1.

.SH "SERVER SOCKETS"
.PP
If the \fB\-server\fR option is specified then the new socket
will be a server for the port given by \fIport\fR (either an integer
or a service name, where supported and understood by the host
operating system; if \fIport\fR is zero, the operating system will
allocate a free port to the server socket which may be discovered by

will be accepted.
.PP
If \fIport\fR is specified as zero, the operating system will allocate
an unused port for use as a server socket.  The port number actually
allocated may be retrieved from the created server socket using the
\fBfconfigure\fR command to retrieve the \fB\-sockname\fR option as
described below.

.SH "CONFIGURATION OPTIONS"
The \fBfconfigure\fR command can be used to query several readonly
configuration options for socket channels:
.TP
\fB\-error\fR
This option gets the current error status of the given socket.  This
is useful when you need to determine if an asynchronous connect

\fB\-peername\fR
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 computed, the second element of the
list is identical to the address, its first element.
.PP

.SH "EXAMPLES"
Here is a very simple time server:

.CS
proc Server {channel clientaddr clientport} {
   puts "Connection from $clientaddr registered"
   puts $channel [clock format [clock seconds]]
   close $channel
}

\fBsocket\fR -server Server 9900
vwait forever
.CE
.PP
And here is the corresponding client to talk to the server:

.CS
set server localhost
set sockChan [\fBsocket\fR $server 9900]
gets $sockChan line
close $sockChan
puts "The time on $server is $line"
.CE

.SH "SEE ALSO"
fconfigure(n), flush(n), open(n), read(n)

.SH KEYWORDS
bind, channel, connection, domain name, host, network address, socket, tcp

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 2000 Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: source.n,v 1.10 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH source n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
source \- Evaluate a file or resource as a Tcl script

the data stored in \fIfileName\fR.  When the \fB-encoding\fR option
is omitted, the system encoding is assumed.
.VE 8.5
.SH EXAMPLE
Run the script in the file \fBfoo.tcl\fR and then the script in the
file \fBbar.tcl\fR:
.CS
\fBsource\fR foo.tcl
\fBsource\fR bar.tcl
.CE
Alternatively:
.CS
foreach scriptFile {foo.tcl bar.tcl} {
   \fBsource\fR $scriptFile
}
.CE

.SH "SEE ALSO"
file(n), cd(n), encoding(n), info(n)

.SH KEYWORDS
file, script

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: split.n,v 1.5 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH split n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
split \- Split a string into a proper Tcl list

character of \fIstring\fR is in \fIsplitChars\fR.
If \fIsplitChars\fR is an empty string then each character of
\fIstring\fR becomes a separate element of the result list.
\fISplitChars\fR defaults to the standard white-space characters.
.SH EXAMPLES
Divide up a USENET group name into its hierarchical components:
.CS
\fBsplit\fR "comp.lang.tcl.announce" .
     \fI=> comp lang tcl announce\fR
.CE
.PP
See how the \fBsplit\fR command splits on \fIevery\fR character in
\fIsplitChars\fR, which can result in information loss if you are not
careful:
.CS
\fBsplit\fR "alpha beta gamma" "temp"
     \fI=> al {ha b} {} {a ga} {} a\fR
.CE
.PP
Extract the list words from a string that is not a well-formed list:
.CS
\fBsplit\fR "Example with {unbalanced brace character"
     \fI=> Example with \\{unbalanced brace character\fR
.CE
.PP
Split a string into its constituent characters
.CS
\fBsplit\fR "Hello world" {}
     \fI=> H e l l o { } w o r l d\fR
.CE
.SS "PARSING RECORD-ORIENTED FILES"
Parse a Unix /etc/passwd file, which consists of one entry per line,
with each line consisting of a colon-separated list of fields:

.CS
## Read the file
set fid [open /etc/passwd]
set content [read $fid]
close $fid

## Split into records on newlines
set records [\fBsplit\fR $content "\\n"]

## Iterate over the records
foreach rec $records {

   ## Split into fields on colons
   set fields [\fBsplit\fR $rec ":"]

   ## Assign fields to variables and print some out...
   lassign $fields \\
         userName password uid grp longName homeDir shell
   puts "$longName uses [file tail $shell] for a login shell"
}
.CE

.SH "SEE ALSO"
join(n), list(n), string(n)

.SH KEYWORDS
list, split, string

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: string.n,v 1.24 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH string n 8.1 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
string \- Manipulate strings

contiguous range of alphanumeric (Unicode letters or decimal digits)
or underscore (Unicode connector punctuation) characters, or any
single character other than these.
.SH EXAMPLE
Test if the string in the variable \fIstring\fR is a proper non-empty
prefix of the string \fBfoobar\fR.
.CS
set length [\fBstring length\fR $string]
if {$length == 0} {
   set isPrefix 0
} else {
   set isPrefix [\fBstring equal\fR -length $string $string "foobar"]
}
.CE

.SH "SEE ALSO"
expr(n), list(n)

.SH KEYWORDS
case conversion, compare, index, match, pattern, string, word, equal, ctype

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 2001 Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: subst.n,v 1.6 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH subst n 7.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
subst \- Perform backslash, command, and variable substitutions

.VE
.SH EXAMPLES
.PP
When it performs its substitutions, \fIsubst\fR does not give any
special treatment to double quotes or curly braces (except within
command substitutions) so the script
.CS
set a 44
\fBsubst\fR {xyz {$a}}
.CE
returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR''
.VS 8.4
and the script
.CS
set a "p\\} q \\{r"
\fBsubst\fR {xyz {$a}}
.CE
return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\\} q \\{r}\fR''.
.PP
When command substitution is performed, it includes any variable
substitution necessary to evaluate the script.  
.CS
set a 44
\fBsubst\fR -novariables {$a [format $a]}
.CE
returns ``\fB$a 44\fR'', not ``\fB$a $a\fR''.  Similarly, when
variable substitution is performed, it includes any command
substitution necessary to retrieve the value of the variable.
.CS
proc b {} {return c}
array set a {c c [b] tricky}
\fBsubst\fR -nocommands {[b] $a([b])}
.CE
returns ``\fB[b] c\fR'', not ``\fB[b] tricky\fR''.
.PP
The continue and break exceptions allow command substitutions to
prevent substitution of the rest of the command substitution and the
rest of \fIstring\fR respectively, giving script authors more options
when processing text using \fIsubst\fR.  For example, the script
.CS
\fBsubst\fR {abc,[break],def}
.CE
returns ``\fBabc,\fR'', not ``\fBabc,,def\fR'' and the script
.CS
\fBsubst\fR {abc,[continue;expr 1+2],def}
.CE
returns ``\fBabc,,def\fR'', not ``\fBabc,3,def\fR''.
.PP
Other exceptional return codes substitute the returned value
.CS
\fBsubst\fR {abc,[return foo;expr 1+2],def}
.CE
returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR'' and
.CS
\fBsubst\fR {abc,[return -code 10 foo;expr 1+2],def}
.CE
also returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR''.
.VE

.SH "SEE ALSO"
Tcl(n), eval(n), break(n), continue(n)

.SH KEYWORDS
backslash substitution, command substitution, variable substitution

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: switch.n,v 1.8 2004/10/27 14:24:37 dkf Exp $
'\" 
.so man.macros
.TH switch n 7.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
switch \- Evaluate one of several scripts, depending on a given value

then the body after that is used, and so on).
This feature makes it possible to share a single \fIbody\fR among
several patterns.
.PP
Beware of how you place comments in \fBswitch\fR commands.  Comments
should only be placed \fBinside\fR the execution body of one of the
patterns, and not intermingled with the patterns.

.SH "EXAMPLES"
The \fBswitch\fR command can match against variables and not just
literals, as shown here (the result is \fI2\fR):
.CS
set foo "abc"
\fBswitch\fR abc a \- b {expr 1} $foo {expr 2} default {expr 3}
.CE
.PP
Using glob matching and the fall-through body is an alternative to
writing regular expressions with alternations, as can be seen here
(this returns \fI1\fR):
.CS
\fBswitch\fR \-glob aaab {
   a*b     \-
   b       {expr 1}
   a*      {expr 2}
   default {expr 3}
}
.CE
.PP
Whenever nothing matches, the \fBdefault\fR clause (which must be
last) is taken.  This example has a result of \fI3\fR:
.CS
\fBswitch\fR xyz {
   a  \-
   b {
      # Correct Comment Placement
      expr 1
   }
   c {
      expr 2
   }
   default {
      expr 3
   }
}
.CE
.PP
.VS 8.5
When matching against regular expressions, information about what
exactly matched is easily obtained using the \fB\-matchvar\fR option:
.CS
\fBswitch\fR -regexp -matchvar foo -- $bar {
   a(b*)c {
      puts "Found [string length [lindex $foo 1]] 'b's"
   }
   d(e*)f(g*)h {
      puts "Found [string length [lindex $foo 1]] 'e's and\\
            [string length [lindex $foo 2]] 'g's"
   }