d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Tcl 7.5, various makefiles will be updated to use these sources as soon

Browse Source 
as I get these back down to my machine.
This commit is contained in:
Poul-Henning Kamp 1996-06-26 06:06:43 +00:00
commit 403acdc0da
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/vendor/tcl/dist/; revision=16756
svn path=/vendor/tcl/7.5/; revision=16758; tag=vendor/tcl/7.5
294 changed files with 100301 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

331
contrib/tcl/README Normal file
View File

@ -0,0 +1,331 @@
Tcl
by John Ousterhout (and many others at Sun Microsystems and elsewhere)
john.ousterhout@eng.sun.com
SCCS: @(#) README 1.29 96/04/19 11:42:58
1. Introduction
---------------
This directory and its descendants contain the sources and documentation
for Tcl, an embeddable scripting language. The information here corresponds
to release 7.5. The most important new feature in this release is support
for the PC and Mac platforms. In addition, there are major new facilities
for dynamic loading, package and version management, multiple interpreters,
safe execution of untrusted scripts, and a new I/O system that supports
nonblocking I/O and sockets. This release also contains many bug fixes.
Tcl 7.5 should be backwards compatible with Tcl 7.4 scripts (there are two
small incompatibilities described below, but they are relatively insignificant
and shouldn't affect most existing Tcl code and extensions).
2. Documentation
----------------
The best way to get started with Tcl is to read one of the introductory
books on Tcl:
Tcl and the Tk Toolkit, by John Ousterhout,
Addison-Wesley, 1994, ISBN 0-201-63337-X
Practical Programming in Tcl and Tk, by Brent Welch,
Prentice-Hall, 1995, ISBN 0-13-182007-9
Exploring Expect, by Don Libes,
O'Reilly and Associates, 1995, ISBN 1-56592-090-2
The "doc" subdirectory in this release contains a complete set of reference
manual entries for Tcl. Files with extension ".1" are for programs (for
example, tclsh.1); files with extension ".3" are for C library procedures;
and files with extension ".n" describe Tcl commands. The file "doc/Tcl.n"
gives a quick summary of the Tcl language syntax. To print any of the man
pages, cd to the "doc" directory and invoke your favorite variant of
troff using the normal -man macros, for example
ditroff -man Tcl.n
to print Tcl.n. If Tcl has been installed correctly and your "man"
program supports it, you should be able to access the Tcl manual entries
using the normal "man" mechanisms, such as
man Tcl
There is also an official home for Tcl and Tk on the Web:
http://www.sunlabs.com/research/tcl
These Web pages include release updates, reports on bug fixes and porting
issues, HTML versions of the manual pages, and pointers to many other
Tcl/Tk Web pages at other sites. Check them out!
3. Compiling and installing Tcl
-------------------------------
This release contains everything you should need to compile and run
Tcl under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95,
or Win 3.1 with Win32s).
Before trying to compile Tcl you should do the following things:
(a) Check for a binary release. Pre-compiled binary releases are
available now for PCs and Macintoshes, and they may be available
in the future for some flavors of UNIX. Binary releases are much
easier to install than source releases. To find out whether a
binary release is available for your platform, check the home page
for the Sun Tcl/Tk project (http://www.sunlabs.com/research/tcl)
and also check in the FTP directory from which you retrieved the
base distribution.
(b) Check for patches. Look in the FTP directory from which you
retrieved the base distribution and see if there are files with
names like tcl7.5p1.patch, tcl7.5p2.patch, etc. These files may
also have .gz or .Z extensions to indicate compression. If you find
any patch files, apply them to the source directory in order
from "p1" up. To apply an uncompressed patch file such as
tcl7.5p1.patch, invoke a shell command like the following from
the directory containing this file:
patch -p < tcl7.5p1.patch
If the patch file has a .gz extension, invoke a command like the
following:
gunzip -c tcl7.5p1.patch.gz | patch -p
If the patch file has a .Z extension, it was compressed with
compress. To apply it, invoke a command like the following:
zcat tcl7.5p1.patch.Z | patch -p
If you're applying a patch to a release that has already been
compiled, then before applying the patch you should cd to the
"unix" subdirectory and type "make distclean" to restore the
directory to a pristine state.
Once you've done this, change to the "unix" subdirectory if you're
compiling under UNIX, "win" if you're compiling under Windows, or
"mac" if you're compiling on a Macintosh. Then follow the instructions
in the README file in that directory for compiling Tcl, installing it,
and running the test suite.
4. Summary of changes in Tcl 7.5
--------------------------------
The most important change for Tcl 7.5 is that Tcl now runs on Macintosh
and PC platforms as well as UNIX. The PC port runs under Windows 3.1
(with Win32s), Windows 95, and Windows NT. This required a lot of
reorganization of the sources but it didn't require any changes to
Tcl's externally visible interfaces.
In addition to the ports, Tcl 7.5 also has many other new features.
The following feature changes have occurred since Tcl 7.4:
1. Dynamic loading. There is a new "load" command for loading binary
extensions into Tcl on the fly. This works now on most of the major
UNIX platforms as well as PCs and Macintoshes. Three new "info"
commands, "info loaded", "info sharedlibextension", and
"info nameofexecutable", were also added as part of the dynamic loading
implementation. You can also create Tcl and Tk themselves as shared
libraries with the --enable-shared switch to the configure script.
2. Packages and versions. There is a new "package" command for
package and version management. See the manual entries for "package"
and "pkg_mkIndex" for details on how to use it. There are also
C APIs to the package mechanism. See PkgRequire.3.
3. Multiple interpreters and Safe-Tcl. There is a new "interp" command
that allows you to create multiple interpreters within a single application
and set up communication between them with "aliases". The mechanism also
supports "safe" interpreters, which provide a generalized version of the
security mechanisms in Borenstein and Rose's Safe-Tcl. There are still
a few missing security features, such as resource control. You can use
"load" to add extensions (including Tk) into slave interpreters.
4. The event loop from Tk has been moved to Tcl. Tcl now has commands
"after", "fileevent", "update", and "vwait" (which replaces tkwait).
The "tkerror" command has been renamed to "bgerror". "Tkerror" is
still supported for backwards compatibility, but you should switch ASAP
to using "bgerror" instead. Many C procedures that used to be in Tk
have been moved to Tcl and renamed, such as Tcl_DoOneEvent, Tcl_DoWhenIdle,
Tcl_CreateFileHandler, and Tcl_CreateTimerHandler.
5. Tcl has a whole new I/O system. All of the Tcl commands like
"open" and "puts" should continue to operate as before, but there
is a totally new implementation that doesn't use the C stdio library:
- The new I/O system is more portable, and it can be extended
with new kinds of I/O channels; see CrtChannel.3 for details.
- Nonblocking I/O is supported on all platforms and there is a
new command "fconfigure" to enable it and other channel options;
see fconfigure.n for details. There is also a new "fblocked"
command.
- The I/O system automatically translates between different
end-of-line representations (such as CR on Macs and CRLF on
PC's) to the newline form used in UNIX and in all Tcl scripts;
the "fconfigure" command can be used to control this feature.
- There is a set of C APIs for manipulating Tcl_Channel's, which
are analogous to UNIX FILE's. The C procedures have roughly the
same functionality as the stdio procedures. See OpenFileChnl.3,
CrtCloseHdlr.3, and CrtChnlHdlr.3 for details.
- There is a new structure Tcl_File that provides platform-
independent access to file handles such as UNIX fd's. See
GetFile.3 for details.
- There are new procedures Tcl_GetErrno and Tcl_SetErrno for
accessing the "errno" variable in a safe and portable fashion.
See SetErrno.3.
6. There are new commands "file split", "file join", and "file pathtype",
which make it possible to handle file names in a way that will work on
all platforms. See the manual entries file.n and filename.n for
details.
7. There is a new "socket" command for network communication via
TCP sockets. It works for both the client and server sides. There
is also C-level support for sockets; see OpenTcp.3.
8. There is a new "clock" command, which contains the functionality
of the TclX clock-handling commands.
9. The "foreach" command has been generalized significantly to support
multiple lists and multiple variables iterating over each list.
10. There is a new "notifier" mechanism, which was added as part of
the ports. This allows the basic mechanisms for reporting events
to be implemented in different ways on different platforms. It
may also be useful for other purposes, such as merging the Tk and
Xt event loops so that Tk and Xt widgets can coexist in a single
application. See the manual entry Notifier.3 for more information.
11. There is an "AssocData" mechanism that allows extensions to store
their own data in an interpreter and get called back when the interpreter
is deleted. This is visible at C level via the procedures Tcl_SetAssocData
and Tcl_GetAssocData.
12. When manual pages are installed, additional links are created for
each of the procedures described in the manual page, so that it's
easier to invoke the "man" command.
13. There is a new variable "tcl_platform" with platform information.
This is an associative array with elements like "os" and "machine"
that contain various pieces of information about the platform.
14. There is a new procedure Tcl_CreateExitHandler that you can use to
make sure a C procedure is called before the Tcl application exits.
15. There is a new procedure Tcl_UpdateLinkedVar to force the Tcl-level
variable to be updated after you've changed the corresponding C-level
variable.
16. The procedures Tk_Preserve, Tk_Release, and Tk_EventuallyFree
have been moved from Tk to Tcl and given names like Tcl_Preserve.
Three incompatibilities were introduced by the changes. All of these
are at C-level, and only the first one should have much impact. Existing
scripts for Tcl 7.4 should run unchanged under Tcl 7.5.
1. The procedure Tcl_EnterFile no longer exists. However, a new
procedure Tcl_MakeFileChannel provides similar functionality.
Tcl_GetOpenFile still exists but only works under UNIX.
Tcl_CreatePipeline also remains, but it too works only under UNIX
now; use Tcl_OpenCommandChannel for better portability.
2. Tcl doesn't export any global C variables anymore, because this doesn't
work with Windows DLLs. The C variables tcl_AsyncReady and
tcl_FileCloseProc have been replaced with procedures Tcl_AsyncReady()
and Tcl_SetFileCloseProc(). The C variable tcl_RcFileName has been
replaced with a Tcl variable tcl_rcFileName (use Tcl_SetVar to set the
Tcl variable, instead of assigning to the old C variable).
3. Files are no longer shared between interpreters by default: if a
file is opened in one interpreter, it cannot normally be used in other
interpreters. However, the new procedure Tcl_ShareHandle allows files
to be shared between interpreters if requested explicitly.
For a complete list of all changes in this release, see the file "changes"
in this directory.
5. Tcl newsgroup
-----------------
There is a network news group "comp.lang.tcl" intended for the exchange
of information about Tcl, Tk, and related applications. Feel free to use
the newsgroup both for general information questions and for bug reports.
We read the newsgroup and will attempt to fix bugs and problems reported
to it.
When using comp.lang.tcl, please be sure that your e-mail return address
is correctly set in your postings. This allows people to respond directly
to you, rather than the entire newsgroup, for answers that are not of
general interest. A bad e-mail return address may prevent you from
getting answers to your questions. You may have to reconfigure your news
reading software to ensure that it is supplying valid e-mail addresses.
6. Tcl contributed archive
--------------------------
Many people have created exciting packages and applications based on Tcl
and/or Tk and made them freely available to the Tcl community. An archive
of these contributions is kept on the machine ftp.neosoft.com. You
can access the archive using anonymous FTP; the Tcl contributed archive is
in the directory "/pub/tcl". The archive also contains several FAQ
("frequently asked questions") documents that provide solutions to problems
that are commonly encountered by TCL newcomers.
7. Support and bug fixes
------------------------
We're very interested in receiving bug reports and suggestions for
improvements. We prefer that you send this information to the
comp.lang.tcl newsgroup rather than to any of us at Sun. We'll see
anything on comp.lang.tcl, and in addition someone else who reads
omp.lang.tcl may be able to offer a solution. The normal turn-around
time for bugs is 2-4 weeks. Enhancements may take longer and may not
happen at all unless there is widespread support for them (we're
trying to slow the rate at which Tcl turns into a kitchen sink). It's
very difficult to make incompatible changes to Tcl at this point, due
to the size of the installed base.
When reporting bugs, please provide a short tclsh script that we can
use to reproduce the bug. Make sure that the script runs with a
bare-bones tclsh and doesn't depend on any extensions or other
programs, particularly those that exist only at your site. Also,
please include three additional pieces of information with the
script:
(a) how do we use the script to make the problem happen (e.g.
what things do we click on, in what order)?
(b) what happens when you do these things (presumably this is
undesirable)?
(c) what did you expect to happen instead?
The Tcl community is too large for us to provide much individual
support for users. If you need help we suggest that you post questions
to comp.lang.tcl. We read the newsgroup and will attempt to answer
esoteric questions for which no-one else is likely to know the answer.
In addition, Tcl support and training are available commercially from
NeoSoft (info@neosoft.com), Computerized Processes Unlimited
(gwl@cpu.com), and Data Kinetics (education@dkl.com).
8. Tcl version numbers
----------------------
Each Tcl release is identified by two numbers separated by a dot, e.g.
6.7 or 7.0. If a new release contains changes that are likely to break
existing C code or Tcl scripts then the major release number increments
and the minor number resets to zero: 6.0, 7.0, etc. If a new release
contains only bug fixes and compatible changes, then the minor number
increments without changing the major number, e.g. 7.1, 7.2, etc. If
you have C code or Tcl scripts that work with release X.Y, then they
should also work with any release X.Z as long as Z > Y.
Alpha and beta releases have an additional suffix of the form a2 or b1.
For example, Tcl 7.0b1 is the first beta release of Tcl version 7.0,
Tcl 7.0b2 is the second beta release, and so on. A beta release is an
initial version of a new release, used to fix bugs and bad features before
declaring the release stable. An alpha release is like a beta release,
except it's likely to need even more work before it's "ready for prime
time". New releases are normally preceded by one or more alpha and beta
releases. We hope that lots of people will try out the alpha and beta
releases and report problems. We'll make new alpha/beta releases to fix
the problems, until eventually there is a beta release that appears to
be stable. Once this occurs we'll make the final release.
We can't promise to maintain compatibility among alpha and beta releases.
For example, release 7.1b2 may not be backward compatible with 7.1b1, even
though the final 7.1 release will be backward compatible with 7.0. This
allows us to change new features as we find problems during beta testing.
We'll try to minimize incompatibilities between beta releases, but if
a major problem turns up then we'll fix it even if it introduces an
incompatibility. Once the official release is made then there won't
be any more incompatibilities until the next release with a new major
version number.

4
contrib/tcl/README.FreeBSD Normal file
View File

@ -0,0 +1,4 @@
Tcl 7.5
originals can be found at: ftp://ftp.smli.com/pub/tcl
removed subdirectories "win", "mac", "compat"
phk@FreeBSD.org

2031
contrib/tcl/changes Normal file
View File

File diff suppressed because it is too large Load Diff

135
contrib/tcl/doc/AddErrInfo.3 Normal file
View File

@ -0,0 +1,135 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) AddErrInfo.3 1.21 96/03/25 19:55:32
'\"
.so man.macros
.TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
.sp
\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fB (char *) NULL\fR)
.sp
char *
\fBTcl_PosixError\fR(\fIinterp\fR)
.SH ARGUMENTS
.AS Tcl_Interp *message
.AP Tcl_Interp *interp in
Interpreter in which to record information.
.AP char *message in
Identifying string to record in \fBerrorInfo\fR variable.
.AP char *element in
String to record as one element of \fBerrorCode\fR variable.
Last \fIelement\fR argument must be NULL.
.BE
.SH DESCRIPTION
.PP
These procedures are used to manipulate two Tcl global variables
that hold information about errors.
The variable \fBerrorInfo\fR holds a stack trace of the
operations that were in progress when an error occurred, and
is intended to be human-readable.
The variable \fBerrorCode\fR holds a list of items that
are intended to be machine-readable.
The first item in \fBerrorCode\fR identifies the class of
.VS
error that occurred (e.g. POSIX means an error occurred in
.VE
a POSIX system call) and additional elements in \fBerrorCode\fR
hold additional pieces of information that depend on the class.
See the Tcl overview manual entry for details on the various
formats for \fBerrorCode\fR.
.PP
The \fBerrorInfo\fR variable is gradually built up as an
error unwinds through the nested operations.
Each time an error code is returned to \fBTcl_Eval\fR
it calls the procedure \fBTcl_AddErrorInfo\fR to add
additional text to \fBerrorInfo\fR describing the
command that was being executed when the error occurred.
By the time the error has been passed all the way back
to the application, it will contain a complete trace
of the activity in progress when the error occurred.
.PP
It is sometimes useful to add additional information to
\fBerrorInfo\fR beyond what can be supplied automatically
by \fBTcl_Eval\fR.
\fBTcl_AddErrorInfo\fR may be used for this purpose:
its \fImessage\fR argument contains an additional
string to be appended to \fBerrorInfo\fR.
For example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR
to record the name of the file being processed and the
line number on which the error occurred; for Tcl procedures, the
procedure name and line number within the procedure are recorded,
and so on.
The best time to call \fBTcl_AddErrorInfo\fR is just after
\fBTcl_Eval\fR has returned \fBTCL_ERROR\fR.
In calling \fBTcl_AddErrorInfo\fR, you may find it useful to
use the \fBerrorLine\fR field of the interpreter (see the
\fBTcl_Interp\fR manual entry for details).
.PP
The procedure \fBTcl_SetErrorCode\fR is used to set the
\fBerrorCode\fR variable.
Its \fIelement\fR arguments give one or more strings to record
in \fBerrorCode\fR: each \fIelement\fR will become one item
of a properly-formed Tcl list stored in \fBerrorCode\fR.
\fBTcl_SetErrorCode\fR is typically invoked just before returning
an error.
If an error is returned without calling \fBTcl_SetErrorCode\fR
then the Tcl interpreter automatically sets \fBerrorCode\fR
to \fBNONE\fR.
.PP
\fBTcl_PosixError\fR
.VS
sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
It reads the value of the \fBerrno\fR C variable and calls
\fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the \fBPOSIX\fR format.
The caller must previously have called \fBTcl_SetErrno\fR to set
\fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
is linked into an application as a shared library, or when the error
occurs in a dynamically loaded extension. See the manual entry for
\fBTcl_SetErrno\fR for more information.
.PP
\fBTcl_PosixError\fR returns a human-readable
.VE
diagnostic message for the error (this is the same value that
will appear as the third element in \fBerrorCode\fR).
It may be convenient to include this string as part of the
error message returned to the application in \fIinterp->result\fR.
.PP
It is important to call the procedures described here rather than
setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
\fBTcl_SetVar\fR.
The reason for this is that the Tcl interpreter keeps information
about whether these procedures have been called.
For example, the first time \fBTcl_AppendResult\fR is called
for an error, it clears the existing value of \fBerrorInfo\fR
and adds the error message in \fIinterp->result\fR to the variable
before appending \fImessage\fR; in subsequent calls, it just
appends the new \fImessage\fR.
When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
that \fBerrorCode\fR has been set; this allows the Tcl interpreter
to set \fBerrorCode\fR to \fBNONE\fB if it receives an error return
when \fBTcl_SetErrorCode\fR hasn't been called.
.PP
If the procedure \fBTcl_ResetResult\fR is called, it clears all
of the state associated with \fBerrorInfo\fR and \fBerrorCode\fR
(but it doesn't actually modify the variables).
If an error had occurred, this will clear the error state to
make it appear as if no error had occurred after all.
.SH "SEE ALSO"
Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
.SH KEYWORDS
error, stack, trace, variable

42
contrib/tcl/doc/AllowExc.3 Normal file
View File

@ -0,0 +1,42 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) AllowExc.3 1.5 96/03/25 19:55:47
'\"
.so man.macros
.TH Tcl_AllowExceptions 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_AllowExceptions \- allow all exceptions in next script evaluation
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_AllowExceptions\fR(\fIinterp\fR)
.SH ARGUMENTS
.AS Tcl_Interp *doublePtr
.AP Tcl_Interp *interp in
Interpreter in which script will be evaluated.
.BE
.SH DESCRIPTION
.PP
If a script is evaluated at top-level (i.e. no other scripts are
pending evaluation when the script is invoked), and if the script
terminates with a completion code other than TCL_OK, TCL_CONTINUE
or TCL_RETURN, then Tcl normally converts this into a TCL_ERROR
return with an appropriate message.
.PP
However, if \fBTcl_AllowExceptions\fR is invoked immediately before
calling a procedure such as \fBTcl_Eval\fR, then arbitrary completion
codes are permitted from the script, and they are returned without
modification.
This is useful in cases where the caller can deal with exceptions
such as TCL_BREAK or TCL_CONTINUE in a meaningful way.
.SH KEYWORDS
continue, break, exception, interpreter

75
contrib/tcl/doc/AppInit.3 Normal file
View File

@ -0,0 +1,75 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) AppInit.3 1.9 96/03/25 19:56:02
'\"
.so man.macros
.TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_AppInit \- perform application-specific initialization
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_AppInit\fR(\fIinterp\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter for the application.
.BE
.SH DESCRIPTION
.PP
\fBTcl_AppInit\fR is a ``hook'' procedure that is invoked by
the main programs for Tcl applications such as \fBtclsh\fR and \fBwish\fR.
Its purpose is to allow new Tcl applications to be created without
modifying the main programs provided as part of Tcl and Tk.
To create a new application you write a new version of
\fBTcl_AppInit\fR to replace the default version provided by Tcl,
then link your new \fBTcl_AppInit\fR with the Tcl library.
.PP
\fBTcl_AppInit\fR is invoked after by \fBTcl_Main\fR and \fBTk_Main\fR
after their own initialization and before entering the main loop
to process commands.
Here are some examples of things that \fBTcl_AppInit\fR might do:
.IP [1]
Call initialization procedures for various packages used by
the application.
Each initialization procedure adds new commands to \fIinterp\fR
for its package and performs other package-specific initialization.
.IP [2]
Process command-line arguments, which can be accessed from the
Tcl variables \fBargv\fR and \fBargv0\fR in \fIinterp\fR.
.IP [3]
Invoke a startup script to initialize the application.
.LP
.VS
\fBTcl_AppInit\fR returns TCL_OK or TCL_ERROR.
If it returns TCL_ERROR then it must leave an error message in
\fIinterp->result\fR; otherwise the result is ignored.
.PP
In addition to \fBTcl_AppInit\fR, your application should also contain
a procedure \fBmain\fR that calls \fBTcl_Main\fR as follows:
.CS
Tcl_Main(argc, argv, Tcl_AppInit);
.CE
The third argument to \fBTcl_Main\fR gives the address of the
application-specific initialization procedure to invoke.
This means that you don't have to use the name \fBTcl_AppInit\fR
for the procedure, but in practice the name is nearly always
\fBTcl_AppInit\fR (in versions before Tcl 7.4 the name \fBTcl_AppInit\fR
was implicit; there was no way to specify the procedure explicitly).
The best way to get started is to make a copy of the file
\fBtclAppInit.c\fR from the Tcl library or source directory.
It already contains a \fBmain\fR procedure and a template for
\fBTcl_AppInit\fR that you can modify for your application.
.VE
.SH KEYWORDS
application, argument, command, initialization, interpreter

89
contrib/tcl/doc/AssocData.3 Normal file
View File

@ -0,0 +1,89 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\"
'\" SCCS: @(#) AssocData.3 1.8 96/03/25 19:56:17
.so man.macros
.TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage
associations of string keys and user specified data with Tcl
interpreters.
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
ClientData
\fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR)
.sp
\fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR)
.sp
\fBTcl_DeleteAssocData\fR(\fIinterp, key\fR)
.SH ARGUMENTS
.AS Tcl_InterpDeleteProc *delProcPtr
.AP Tcl_Interp *interp in
Interpreter in which to execute the specified command.
.AP char *key in
Key for association with which to store data or from which to delete or
retrieve data. Typically the module prefix for a package.
.AP Tcl_InterpDeleteProc *delProc in
Procedure to call when \fIinterp\fR is deleted.
.AP Tcl_InterpDeleteProc **delProcPtr in
Pointer to location in which to store address of current deletion procedure
for association. Ignored if NULL.
.AP ClientData clientData in
Arbitrary one-word value associated with the given key in this
interpreter. This data is owned by the caller.
.BE
.SH DESCRIPTION
.PP
These procedures allow extensions to associate their own data with
a Tcl interpreter.
An association consists of a string key, typically the name of
the extension, and a one-word value, which is typically a pointer
to a data structure holding data specific to the extension.
Tcl makes no interpretation of either the key or the value for
an association.
.PP
Storage management is facilitated by storing with each association a
procedure to call when the interpreter is deleted. This
procedure can dispose of the storage occupied by the client's data in any
way it sees fit.
.PP
\fBTcl_SetAssocData\fR creates an association between a string
key and a user specified datum in the given interpreter.
If there is already an association with the given \fIkey\fR,
\fBTcl_SetAssocData\fR overwrites it with the new information.
It is up to callers to organize their use of names to avoid conflicts,
for example, by using package names as the keys.
If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a
procedure to invoke if the interpreter is deleted before the association
is deleted. \fIDeleteProc\fR should have arguments and result that match
the type \fBTcl_InterpDeleteProc\fR:
.CS
typedef void Tcl_InterpDeleteProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR);
.CE
When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR
arguments will be the same as the corresponding arguments passed to
\fBTcl_SetAssocData\fR.
The deletion procedure will \fInot\fR be invoked if the association
is deleted before the interpreter is deleted.
.PP
\fBTcl_GetAssocData\fR returns the datum stored in the association with the
specified key in the given interpreter, and if the \fIdelProcPtr\fR field
is non-\fBNULL\fR, the address indicated by it gets the address of the
delete procedure stored with this association. If no association with the
specified key exists in the given interpreter \fBTcl_GetAssocData\fR
returns \fBNULL\fR.
.PP
\fBTcl_DeleteAssocData\fR deletes an association with a specified key in
the given interpreter. It does not call the deletion procedure.
.SH KEYWORDS
association, data, deletion procedure, interpreter, key

164
contrib/tcl/doc/Async.3 Normal file
View File

@ -0,0 +1,164 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) Async.3 1.13 96/03/25 19:56:31
'\"
.so man.macros
.TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete \- handle asynchronous events
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_AsyncHandler
\fBTcl_AsyncCreate\fR(\fIproc, clientData\fR)
.sp
\fBTcl_AsyncMark\fR(\fIasync\fR)
.sp
int
\fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
.sp
\fBTcl_AsyncDelete\fR(\fIasync\fR)
.VS
.sp
int
\fBTcl_AsyncReady\fR()
.VE
.SH ARGUMENTS
.AS Tcl_AsyncHandler clientData
.AP Tcl_AsyncProc *proc in
Procedure to invoke to handle an asynchronous event.
.AP ClientData clientData in
One-word value to pass to \fIproc\fR.
.AP Tcl_AsyncHandler async in
Token for asynchronous event handler.
.AP Tcl_Interp *interp in
Tcl interpreter in which command was being evaluated when handler was
invoked, or NULL if handler was invoked when there was no interpreter
active.
.AP int code in
Completion code from command that just completed in \fIinterp\fR,
or 0 if \fIinterp\fR is NULL.
.BE
.SH DESCRIPTION
.PP
These procedures provide a safe mechanism for dealing with
asynchronous events such as signals.
If an event such as a signal occurs while a Tcl script is being
evaluated then it isn't safe to take any substantive action to
process the event.
For example, it isn't safe to evaluate a Tcl script since the
interpreter may already be in the middle of evaluating a script;
it may not even be safe to allocate memory, since a memory
allocation could have been in progress when the event occurred.
The only safe approach is to set a flag indicating that the event
occurred, then handle the event later when the world has returned
to a clean state, such as after the current Tcl command completes.
.PP
\fBTcl_AsyncCreate\fR creates an asynchronous handler and returns
a token for it.
The asynchronous handler must be created before
any occurrences of the asynchronous event that it is intended
to handle (it is not safe to create a handler at the time of
an event).
When an asynchronous event occurs the code that detects the event
(such as a signal handler) should call \fBTcl_AsyncMark\fR with the
token for the handler.
\fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it
will not invoke the handler immediately.
Tcl will call the \fIproc\fR associated with the handler later, when
the world is in a safe state, and \fIproc\fR can then carry out
the actions associated with the asynchronous event.
\fIProc\fR should have arguments and result that match the
type \fBTcl_AsyncProc\fR:
.CS
typedef int Tcl_AsyncProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
int \fIcode\fR);
.CE
The \fIclientData\fR will be the same as the \fIclientData\fR
argument passed to \fBTcl_AsyncCreate\fR when the handler was
created.
If \fIproc\fR is invoked just after a command has completed
execution in an interpreter, then \fIinterp\fR will identify
the interpreter in which the command was evaluated and
\fIcode\fR will be the completion code returned by that
command.
The command's result will be present in \fIinterp->result\fR.
When \fIproc\fR returns, whatever it leaves in \fIinterp->result\fR
will be returned as the result of the command and the integer
value returned by \fIproc\fR will be used as the new completion
code for the command.
.PP
It is also possible for \fIproc\fR to be invoked when no interpreter
is active.
This can happen, for example, if an asynchronous event occurs while
the application is waiting for interactive input or an X event.
In this case \fIinterp\fR will be NULL and \fIcode\fR will be
0, and the return value from \fIproc\fR will be ignored.
.PP
The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the
handlers that are ready.
.VS
The procedure \fBTcl_AsyncReady\fR will return non-zero whenever any
.VE
asynchronous handlers are ready; it can be checked to avoid calls
to \fBTcl_AsyncInvoke\fR when there are no ready handlers.
.VS
Tcl calls \fBTcl_AsyncReady\fR after each command is evaluated
.VE
and calls \fBTcl_AsyncInvoke\fR if needed.
Applications may also call \fBTcl_AsyncInvoke\fR at interesting
times for that application.
.VS
For example, Tcl's event handler calls \fBTcl_AsyncReady\fR
after each event and calls \fBTcl_AsyncInvoke\fR if needed.
.VE
The \fIinterp\fR and \fIcode\fR arguments to \fBTcl_AsyncInvoke\fR
have the same meaning as for \fIproc\fR: they identify the active
interpreter, if any, and the completion code from the command
that just completed.
.PP
\fBTcl_AsyncDelete\fR removes an asynchronous handler so that
its \fIproc\fR will never be invoked again.
A handler can be deleted even when ready, and it will still
not be invoked.
.PP
If multiple handlers become active at the same time, the
handlers are invoked in the order they were created (oldest
handler first).
The \fIcode\fR and \fIinterp->result\fR for later handlers
reflect the values returned by earlier handlers, so that
the most recently created handler has last say about
the interpreter's result and completion code.
If new handlers become ready while handlers are executing,
\fBTcl_AsyncInvoke\fR will invoke them all; at each point it
invokes the highest-priority (oldest) ready handler, repeating
this over and over until there are no longer any ready handlers.
.SH WARNING
.PP
It is almost always a bad idea for an asynchronous event
handler to modify \fIinterp->result\fR or return a code different
from its \fIcode\fR argument.
This sort of behavior can disrupt the execution of scripts in
subtle ways and result in bugs that are extremely difficult
to track down.
If an asynchronous event handler needs to evaluate Tcl scripts
then it should first save \fIinterp->result\fR plus the values
of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can
be done, for example, by storing them in dynamic strings).
When the asynchronous handler is finished it should restore
\fIinterp->result\fR, \fBerrorInfo\fR, and \fBerrorCode\fR,
and return the \fIcode\fR argument.
.SH KEYWORDS
asynchronous event, handler, signal

58
contrib/tcl/doc/BackgdErr.3 Normal file
View File

@ -0,0 +1,58 @@
'\"
'\" Copyright (c) 1992-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.
'\"
'\" SCCS: @(#) BackgdErr.3 1.3 96/03/25 19:56:51
'\"
.so man.macros
.TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_BackgroundError \- report Tcl error that occurred in background processing
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_BackgroundError\fR(\fIinterp\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter in which the error occurred.
.BE
.SH DESCRIPTION
.PP
This procedure is typically invoked when a Tcl error occurs during
``background processing'' such as executing an event handler.
When such an error occurs, the error condition is reported to Tcl
or to a widget or some other C code, and there is not usually any
obvious way for that code to report the error to the user.
In these cases the code calls \fBTcl_BackgroundError\fR with an
\fIinterp\fR argument identifying the interpreter in which the
error occurred. At the time \fBTcl_BackgroundError\fR is invoked,
\fIinterp->result\fR is expected to contain an error message.
\fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR
Tcl command to report the error in an application-specific fashion.
If no \fBbgerror\fR command exists, or if it returns with an error condition,
then \fBTcl_BackgroundError\fR reports the error itself by printing
a message on the standard error file.
.PP
\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR immediately
because this could potentially interfere with scripts that are in process
at the time the error occurred.
Instead, it invokes \fBbgerror\fR later as an idle callback.
\fBTcl_BackgroundError\fR saves the values of the \fBerrorInfo\fR and
\fBerrorCode\fR variables and restores these values just before
invoking \fBbgerror\fR.
.PP
It is possible for many background errors to accumulate before
\fBbgerror\fR is invoked. When this happens, each of the errors
is processed in order. However, if \fBbgerror\fR returns a
break exception, then all remaining error reports for the
interpreter are skipped.
.SH KEYWORDS
background, bgerror, error

45
contrib/tcl/doc/Backslash.3 Normal file
View File

@ -0,0 +1,45 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) Backslash.3 1.16 96/03/25 19:57:09
'\"
.so man.macros
.TH Tcl_Backslash 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Backslash \- parse a backslash sequence
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
char
\fBTcl_Backslash\fR(\fIsrc, countPtr\fR)
.SH ARGUMENTS
.AS char *countPtr
.AP char *src in
Pointer to a string starting with a backslash.
.AP int *countPtr out
If \fIcountPtr\fR isn't NULL, \fI*countPtr\fR gets filled
in with number of characters in the backslash sequence, including
the backslash character.
.BE
.SH DESCRIPTION
.PP
This is a utility procedure used by several of the Tcl
commands. It parses a backslash sequence and returns
the single character corresponding to the sequence.
\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number
of characters in the backslash sequence.
.PP
See the Tcl manual entry for information on the valid
backslash sequences.
All of the sequences described in the Tcl
manual entry are supported by \fBTcl_Backslash\fR.
.SH KEYWORDS
backslash, parse

63
contrib/tcl/doc/CallDel.3 Normal file
View File

@ -0,0 +1,63 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) CallDel.3 1.11 96/03/25 19:57:25
'\"
.so man.macros
.TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interpreter is deleted
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_CallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
.sp
\fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
.SH ARGUMENTS
.AS Tcl_InterpDeleteProc clientData
.AP Tcl_Interp *interp in
Interpreter with which to associated callback.
.AP Tcl_InterpDeleteProc *proc in
Procedure to call when \fIinterp\fR is deleted.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by
\fBTcl_DeleteInterp\fR if/when \fIinterp\fR is deleted at some future
time. \fIProc\fR will be invoked just before the interpreter
is deleted, but the interpreter will still be valid at the
time of the call.
\fIProc\fR should have arguments and result that match the
type \fBTcl_InterpDeleteProc\fR:
.CS
typedef void Tcl_InterpDeleteProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR);
.CE
The \fIclientData\fR and \fIinterp\fR parameters are
copies of the \fIclientData\fR and \fIinterp\fR arguments given
to \fBTcl_CallWhenDeleted\fR.
Typically, \fIclientData\fR points to an application-specific
data structure that \fIproc\fR uses to perform cleanup when an
interpreter is about to go away.
\fIProc\fR does not return a value.
.PP
\fBTcl_DontCallWhenDeleted\fR cancels a previous call to
\fBTcl_CallWhenDeleted\fR with the same arguments, so that
\fIproc\fR won't be called after all when \fIinterp\fR is
deleted.
If there is no deletion callback that matches \fIinterp\fR,
\fIproc\fR, and \fIclientData\fR then the call to
\fBTcl_DontCallWhenDeleted\fR has no effect.
.SH KEYWORDS
callback, delete, interpreter

36
contrib/tcl/doc/CmdCmplt.3 Normal file
View File

@ -0,0 +1,36 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) CmdCmplt.3 1.6 96/03/25 19:57:46
'\"
.so man.macros
.TH Tcl_CommandComplete 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CommandComplete \- Check for unmatched braces in a Tcl command
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_CommandComplete\fR(\fIcmd\fR)
.SH ARGUMENTS
.AS char *cmd
.AP char *cmd in
Command string to test for completeness.
.BE
.SH DESCRIPTION
.PP
\fBTcl_CommandComplete\fR takes a Tcl command string
as argument and determines whether it contains one or more
complete commands (i.e. there are no unclosed quotes, braces,
brackets, or variable references).
If the command string is complete then it returns 1; otherwise it returns 0.
.SH KEYWORDS
complete command, partial command

51
contrib/tcl/doc/Concat.3 Normal file
View File

@ -0,0 +1,51 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) Concat.3 1.10 96/03/25 19:58:01
'\"
.so man.macros
.TH Tcl_Concat 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Concat \- concatenate a collection of strings
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
char *
\fBTcl_Concat\fR(\fIargc, argv\fR)
.SH ARGUMENTS
.AP int argc in
Number of strings.
.AP char *argv[] in
Array of strings to concatenate. Must have \fIargc\fR entries.
.BE
.SH DESCRIPTION
.PP
\fBTcl_Concat\fR is a utility procedure used by several of the
Tcl commands. Given a collection of strings, it concatenates
them together into a single string, with the original strings
separated by spaces. This procedure behaves differently than
\fBTcl_Merge\fR, in that the arguments are simply concatenated:
no effort is made to ensure proper list structure.
However, in most common usage the arguments will all be proper
lists themselves; if this is true, then the result will also have
proper list structure.
.PP
\fBTcl_Concat\fR eliminates leading and trailing white space as it
copies strings from \fBargv\fR to the result. If an element of
\fBargv\fR consists of nothing but white space, then that string
is ignored entirely. This white-space removal was added to make
the output of the \fBconcat\fR command cleaner-looking.
.PP
The result string is dynamically allocated
using \fBmalloc()\fR; the caller must eventually release the space
by calling \fBfree()\fR.
.SH KEYWORDS
concatenate, strings

427
contrib/tcl/doc/CrtChannel.3 Normal file
View File

@ -0,0 +1,427 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) CrtChannel.3 1.23 96/03/28 17:55:41
.so man.macros
.TH Tcl_CreateChannel 3 7.5 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelFile, Tcl_GetChannelBufferSize, Tcl_SetDefaultTranslation, Tcl_SetChannelBufferSize \- procedures for creating and manipulating channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Channel
\fBTcl_CreateChannel\fR(\fItypePtr, channelName, inFile, outFile, instanceData\fR)
.sp
ClientData
\fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
.sp
Tcl_ChannelType *
\fBTcl_GetChannelType\fR(\fIchannel\fR)
.sp
char *
\fBTcl_GetChannelName\fR(\fIchannel\fR)
.sp
Tcl_File
\fBTcl_GetChannelFile\fR(\fIchannel, direction\fR)
.sp
void
\fBTcl_SetDefaultTranslation\fR(\fIchannel, transMode\fR)
.sp
int
\fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
.sp
void
\fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR)
.sp
.SH ARGUMENTS
.AS Tcl_FileHandle pipelineSpec in
.AP Tcl_ChannelType *typePtr in
Points to a structure containing the addresses of procedures that
can be called to perform I/O and other functions on the channel.
.AP char *channelName in
The name of this channel, such as \fBfile3\fR; must not be in use
by any other channel. Can be NULL, in which case the channel is
created without a name.
.AP Tcl_File inFile in
Tcl file for the input device to associate with this channel. If NULL,
input will not be allowed on the channel.
.AP Tcl_File outFile in
Tcl file for the output device to associate with this channel. If NULL,
output will not be allowed on the channel.
.AP ClientData instanceData in
Arbitrary one-word value to be associated with this channel. This
value is passed to procedures in \fItypePtr\fR when they are invoked.
.AP Tcl_Channel channel in
The channel to operate on.
.AP int direction in
\fBTCL_READABLE\fR means the input file is wanted; \fBTCL_WRITABLE\fR
means the output file is wanted.
.AP Tcl_EolTranslation transMode in
The translation mode; one of the constants \fBTCL_TRANSLATE_AUTO\fR,
\fBTCL_TRANSLATE_CR\fR, \fBTCL_TRANSLATE_LF\fR and \fBTCL_TRANSLATE_CRLF\fR.
.AP int size in
The size, in bytes, of buffers to allocate in this channel.
.BE
.SH DESCRIPTION
.PP
Tcl uses a two-layered channel architecture. It provides a generic upper
layer to enable C and Tcl programs to perform input and output using the
same APIs for a variety of files, devices, sockets etc. The generic C APIs
are described in the manual entry for \fBTcl_OpenFileChannel\fR.
.PP
The lower layer provides type-specific channel drivers for each type of
file, socket and device supported on each platform.
This manual entry describes the C APIs
used by the generic layer to communicate with type-specific channel drivers
to perform the input and output operations. It also explains how new types
of channels can be added by providing new channel drivers.
.PP
Channel drivers consist of a number of components: First, each channel
driver provides a \fBTcl_ChannelType\fR structure containing pointers to
functions implementing the various operations used by the generic layer to
communicate with the channel driver. The \fBTcl_ChannelType\fR structure
and the functions referenced by it are described in the section
TCL_CHANNELTYPE, below.
.PP
Second, channel drivers usually provide a Tcl command to create instances
of that type of channel. For example, the Tcl \fBopen\fR command creates
channels that use the \fBfile\fR and \fBcommand\fR channel drivers, and
the Tcl \fBsocket\fR command creates channels that use TCP sockets for
network communication.
.PP
Third, a channel driver optionally provides a C function to open channel
instances of that type. For example, \fBTcl_OpenFileChannel\fR opens a
channel that uses the \fBfile\fR channel driver, and
\fBTcl_OpenTcpClient\fR opens a channel that uses the TCP network protocol.
These creation functions typically use
\fBTcl_CreateChannel\fR internally to open the channel.
.PP
To add a new type of channel you must implement a C API or a Tcl command
that opens a channel by invoking \fBTcl_CreateChannel\fR.
When your driver calls \fBTcl_CreateChannel\fR it passes in
a \fBTcl_ChannelType\fR structure describing the driver's I/O
procedures.
The generic layer will then invoke the functions referenced in that
structure to perform operations on the channel.
.PP
\fBTcl_CreateChannel\fR opens a new channel and associates the supplied
\fItypePtr\fR, \fIinFile\fR, \fIoutFile\fR and \fIinstanceData\fR with it.
For a discussion of channel drivers, their operations and the
\fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below.
.PP
\fBTcl_GetChannelInstanceData\fR returns the instance data associated with
the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR
argument in the call to \fBTcl_CreateChannel\fR that created this channel.
.PP
\fBTcl_GetChannelType\fR returns a pointer to the \fBTcl_ChannelType\fR
structure used by the channel in the \fIchannel\fR argument. This is
the same as the \fItypePtr\fR argument in the call to
\fBTcl_CreateChannel\fR that created this channel.
.PP
\fBTcl_GetChannelName\fR returns a string containing the name associated
with the channel, or NULL if the \fIchannelName\fR argument to
\fBTcl_CreateChannel\fR was NULL.
.PP
\fBTcl_GetChannelFile\fR returns the \fIinFile\fR associated with
\fIchannel\fR if \fIdirection\fR is \fBTCL_READABLE\fR, or the
\fIoutFile\fR if \fIdirection\fR is \fBTCL_WRITABLE\fR. The operation
returns NULL if the respective value was specified as NULL in the call to
\fBTcl_CreateChannel\fR that created \fIchannel\fR.
.PP
\fBTcl_SetDefaultTranslation\fR sets the default end of line translation
mode. This mode will be installed as the translation mode for the channel
if an attempt is made to output on the channel while it is still in
\fBTCL_TRANSLATE_AUTO\fR mode. For a description of end of line translation
modes, see the manual entry for \fBfconfigure\fR.
.PP
\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
allocated to store input or output in \fIchan\fR. If the value was not set
by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then
the default value of 4096 is returned.
.PP
\fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that
will be allocated in subsequent operations on the channel to store input or
output. The \fIsize\fR argument should be between ten and one million,
allowing buffers of ten bytes to one million bytes. If \fIsize\fR is
outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
4096.
.SH TCL_CHANNELTYPE
.PP
A channel driver provides a \fBTcl_ChannelType\fR structure that contains
pointers to functions that implement the various operations on a channel;
these operations are invoked as needed by the generic layer. The
\fBTcl_ChannelType\fR structure contains the following fields:
.PP
.CS
typedef struct Tcl_ChannelType {
char *\fItypeName\fR;
Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
Tcl_DriverCloseProc *\fIcloseProc\fR;
Tcl_DriverInputProc *\fIinputProc\fR;
Tcl_DriverOutputProc *\fIoutputProc\fR;
Tcl_DriverSeekProc *\fIseekProc\fR;
Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
} Tcl_ChannelType;
.CE
.PP
The driver must provide implementations for all functions except
\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, and
\fIgetOptionProc\fR, which may be specified as NULL to indicate that the
channel does not support seeking. Other functions that can not be
implemented for this type of device should return \fBEINVAL\fR when invoked
to indicate that they are not implemented.
.SH TYPENAME
.PP
The \fItypeName\fR field contains a null-terminated string that
identifies the type of the device implemented by this driver, e.g.
\fBfile\fR or \fBsocket\fR.
.SH BLOCKMODEPROC
.PP
The \fIblockModeProc\fR field contains the address of a function called by
the generic layer to set blocking and nonblocking mode on the device.
\fIBlockModeProc\fR should match the following prototype:
.PP
.CS
typedef int Tcl_DriverBlockModeProc(
ClientData \fIinstanceData\fR,
Tcl_File \fIinFile\fR,
Tcl_File \fIoutFile\fR,
int \fImode\fR);
.CE
.PP
The \fIinstanceData\fR, \fIinFile\fR and \fIoutFile\fR arguments are the same
as the values passed to \fBTcl_CreateChannel\fR when this channel was created.
The \fImode\fR argument is either \fBTCL_MODE_BLOCKING\fR or
\fBTCL_MODE_NONBLOCKING\fR to set the device into blocking or nonblocking
mode. The function should return zero if the operation was successful,
or a nonzero POSIX error code if the operation failed.
.PP
If the operation is successful, the function can modify the supplied
\fIinstanceData\fR to record that the channel
entered blocking or nonblocking mode, and modify \fIinFile\fR and
\fIoutFile\fR to implement the blocking or nonblocking behavior.
For some device types, the blocking and nonblocking behavior can be
implemented by the underlying operating system; for other device types,
the behavior must be emulated in the channel driver.
.SH CLOSEPROC
.PP
The \fIcloseProc\fR field contains the address of a function called by the
generic layer to clean up driver-related information when the channel is
closed. \fICloseProc\fR must match the following prototype:
.PP
.CS
typedef int Tcl_DriverCloseProc(
ClientData \fIinstanceData\fR,
Tcl_Interp *\fIinterp\fR,
Tcl_File \fIinFile\fR,
Tcl_File \fIoutFile\fR);
.CE
.PP
The \fIinstanceData\fR, \fIinFile\fR, and \fIoutFile\fR arguments are the
same as the respective values provided to \fBTcl_CreateChannel\fR when the
channel was created. The function should release any storage maintained by
the channel driver for this channel, and close the input and output devices
identified by \fIinFile\fR and \fIoutFile\fR. All queued output will have
been flushed to the device before this function is called, and no further
driver operations will be invoked on this instance after calling the
\fIcloseProc\fR. If the close operation is successful, the procedure should
return zero; otherwise it should return a nonzero POSIX error code. In
addition, if an error occurs and \fIinterp\fR is not NULL, the procedure
should store an error message in \fIinterp->result\fR.
.SH INPUTPROC
.PP
The \fIinputProc\fR field contains the address of a function called by the
generic layer to read data from the file or device and store it in an
internal buffer. \fIInputProc\fR must match the following prototype:
.PP
.CS
typedef int Tcl_DriverInputProc(
ClientData \fIinstanceData\fR,
Tcl_File \fIinFile\fR,
char *\fIbuf\fR,
int \fIbufSize\fR,
int *\fIerrorCodePtr\fR);
.CE
.PP
\fIInstanceData\fR and \fIInFile\fR are the same as the values passed to
\fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
argument points to an array of bytes in which to store input from
the device, and the \fIbufSize\fR argument indicates how many bytes are
available at \fIbuf\fR.
.PP
The \fIerrorCodePtr\fR argument points to an integer variable provided by
the generic layer. If an error occurs, the function should set the variable
to a POSIX error code that identifies the error that occurred.
.PP
The function should read data from the input device identified by
\fIinFile\fR and store it at \fIbuf\fR. On success, the function should
return a positive integer indicating how many bytes were read from the
input device and stored at \fIbuf\fR. On error, the function should return
-1. If an error occurs after some data has been read from the device, that
data is lost.
.PP
If \fIinputProc\fR can determine that the input device has some data
available but less than requested by the \fIbufSize\fR argument, the
function should only attempt to read as much data as is available and
return without blocking. If the input device has no data available
whatsoever and the channel is in nonblocking mode, the function should
return an \fBEAGAIN\fR error. If the input device has no data available
whatsoever and the channel is in blocking mode, the function should block
for the shortest possible time until at least one byte of data can be read
from the device; then, it should return as much data as it can read without
blocking.
.SH OUTPUTPROC
.PP
The \fIoutputProc\fR field contains the address of a function called by the
generic layer to transfer data from an internal buffer to the output device.
\fIOutputProc\fR must match the following prototype:
.PP
.CS
typedef int Tcl_DriverOutputProc(
ClientData \fIinstanceData\fR,
Tcl_File \fIoutFile\fR,
char *\fIbuf\fR,
int \fItoWrite\fR,
int *\fIerrorCodePtr\fR);
.CE
.PP
\fIInstanceData\fR and \fIOutFile\fR are the same as the values passed to
\fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
argument contains an array of bytes to be written to the device, and the
\fItoWrite\fR argument indicates how many bytes are to be written from the
\fIbuf\fR argument.
.PP
The \fIerrorCodePtr\fR argument points to an integer variable provided by
the generic layer. If an error occurs, the function should set this
variable to a POSIX error code that identifies the error.
.PP
The function should write the data at \fIbuf\fR to the output device
identified by \fIoutFile\fR. On success, the function should return a
positive integer indicating how many bytes were written to the output
device.
The return value is normally the same as \fItoWrite\fR, but may be
less in some cases such as if the output operation is interrupted
by a signal.
If an error occurs the function should return -1.
In case of error, some data may have been written to the device.
.PP
If the channel is nonblocking and the output device is unable to absorb any
data whatsoever, the function should return -1 with an \fBEAGAIN\fR error
without writing any data.
.SH SEEKPROC
.PP
The \fIseekProc\fR field contains the address of a function called by the
generic layer to move the access point at which subsequent input or output
operations will be applied. \fISeekProc\fR must match the following
prototype:
.PP
.CS
typedef int Tcl_DriverSeekProc(
ClientData \fIinstanceData\fR,
Tcl_File \fIinFile\fR,
Tcl_File \fIoutFile\fR,
long \fIoffset\fR,
int \fIseekMode\fR,
int *\fIerrorCodePtr\fR);
.CE
.PP
The \fIinstanceData\fR, \fIinFile\fR and \fIoutFile\fR arguments are the
same as the values given to \fBTcl_CreateChannel\fR when this channel was
created. \fIOffset\fR and \fIseekMode\fR have the same meaning as for the
\fBTcl_SeekChannel\fR procedure (described in the manual entry for
\fBTcl_OpenFileChannel\fR).
.PP
The \fIerrorCodePtr\fR argument points to
an integer variable provided by the generic layer for returning
\fBerrno\fR values from the function.
The function should set this variable to a POSIX error code
if an error occurs. The function should store an \fBEINVAL\fR error code if
the channel type does not implement seeking.
.PP
The return value is the new access point or -1 in case of error. If an
error occurred, the function should not move the access point.
.SH SETOPTIONPROC
.PP
The \fIsetOptionProc\fR field contains the address of a function called by
the generic layer to set a channel type specific option on a channel.
\fIsetOptionProc\fR must match the following prototype:
.PP
.CS
typedef int Tcl_DriverSetOptionProc(
ClientData \fIinstanceData\fR,
Tcl_Interp *\fIinterp\fR,
char *\fIoptionName\fR,
char *\fIoptionValue\fR);
.CE
.PP
\fIoptionName\fR is the name of an option to set, and \fIoptionValue\fR is
the new value for that option, as a string. The \fIinstanceData\fR is the
same as the value given to \fBTcl_CreateChannel\fR when this channel was
created. The function should do whatever channel type specific action is
required to implement the new value of the option.
.PP
Some options are handled by the generic code and this function is never
called to set them, e.g. \fB-blockmode\fR. Other options are specific to
each channel type and the \fIsetOptionProc\fR procedure of the channel
driver will get called to implement them. The \fIsetOptionProc\fR field can
be NULL, which indicates that this channel type supports no type specific
options.
.PP
If the option value is successfully modified to the new value, the function
returns \fBTCL_OK\fR. It returns \fBTCL_ERROR\fR if the \fIoptionName\fR is
unrecognized or if \fIoptionValue\fR specifies a value for the option that
is not supported. In this case, the function leaves an error message in the
\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
error code.
.SH GETOPTIONPROC
.PP
The \fIgetOptionProc\fR field contains the address of a function called by
the generic layer to get the value of a channel type specific option on a
channel. \fIgetOptionProc\fR must match the following prototype:
.PP
.CS
typedef int Tcl_DriverGetOptionProc(
ClientData \fIinstanceData\fR,
char *\fIoptionName\fR,
Tcl_DString *\fIdsPtr\fR);
.CE
.PP
\fIOptionName\fR is the name of an option supported by this type of
channel. If the option name is not NULL, the function stores its current
value, as a string, in the Tcl dynamic string \fIdsPtr\fR.
If \fIoptionName\fR is NULL, the function stores in \fIdsPtr\fR an
alternating list of all supported options and their current values.
On success, the function returns \fBTCL_OK\fR. If an error occurs, the
function returns \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an
appropriate POSIX error code.
.PP
Some options are handled by the generic code and this function is never
called to retrieve their value, e.g. \fB-blockmode\fR. Other options are
specific to each channel type and the \fIgetOptionProc\fR procedure of the
channel driver will get called to implement them. The \fIgetOptionProc\fR
field can be NULL, which indicates that this channel type supports no type
specific options.
.SH "SEE ALSO"
Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3)
.SH KEYWORDS
blocking, channel driver, channel registration, channel type, nonblocking

92
contrib/tcl/doc/CrtChnlHdlr.3 Normal file
View File

@ -0,0 +1,92 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) CrtChnlHdlr.3 1.10 96/03/14 10:54:43
.so man.macros
.TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler \- call a procedure when a channel becomes readable or writable
.SH SYNOPSIS
.nf
.nf
\fB#include <tcl.h>\fR
.sp
void
\fBTcl_CreateChannelHandler\fR(\fIchannel, mask, proc, clientData\fR)
.sp
void
\fBTcl_DeleteChannelHandler\fR(\fIchannel, proc, clientData\fR)
.sp
.SH ARGUMENTS
.AS Tcl_ChannelProc clientData
.AP Tcl_Channel channel in
Tcl channel such as returned by \fBTcl_CreateChannel\fR.
.AP int mask in
Conditions under which \fIproc\fR should be called: OR-ed combination of
\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify
a zero value to temporarily disable an existing handler.
.AP Tcl_FileProc *proc in
Procedure to invoke whenever the channel indicated by \fIchannel\fR meets
the conditions specified by \fImask\fR.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateChannelHandler\fR arranges for \fIproc\fR to be called in the
future whenever input or output becomes possible on the channel identified
by \fIchannel\fR, or whenever an exceptional condition exists for
\fIchannel\fR. The conditions of interest under which \fIproc\fR will be
invoked are specified by the \fImask\fR argument.
See the manual entry for \fBfileevent\fR for a precise description of
what it means for a channel to be readable or writable.
\fIProc\fR must conform to the following prototype:
.CS
typedef void Tcl_ChannelProc(
ClientData \fIclientData\fR,
int \fImask\fR);
.CE
.PP
The \fIclientData\fR argument is the same as the value passed to
\fBTcl_CreateChannelHandler\fR when the handler was created. Typically,
\fIclientData\fR points to a data structure containing application-specific
information about the channel. \fIMask\fR is an integer mask indicating
which of the requested conditions actually exists for the channel; it will
contain a subset of the bits from the \fImask\fR argument to
\fBTcl_CreateChannelHandler\fR when the handler was created.
.PP
Each channel handler is identified by a unique combination of \fIchannel\fR,
\fIproc\fR and \fIclientData\fR.
There may be many handlers for a given channel as long as they don't
have the same \fIchannel\fR, \fIproc\fR, and \fIclientData\fR.
If \fBTcl_CreateChannelHandler\fR is invoked when there is already a handler
for \fIchannel\fR, \fIproc\fR, and \fIclientData\fR, then no new
handler is created; instead, the \fImask\fR is changed for the
existing handler.
.PP
\fBTcl_DeleteChannelHandler\fR deletes a channel handler identified by
\fIchannel\fR, \fIproc\fR and \fIclientData\fR; if no such handler exists,
the call has no effect.
.PP
Channel handlers are invoked via the Tcl event mechanism, so they
are only useful in applications that are event-driven.
Note also that the conditions specified in the \fImask\fR argument
to \fIproc\fR may no longer exist when \fIproc\fR is invoked: for
example, if there are two handlers for \fBTCL_READABLE\fR on the same
channel, the first handler could consume all of the available input
so that the channel is no longer readable when the second handler
is invoked.
For this reason it may be useful to use nonblocking I/O on channels
for which there are event handlers.
.SH "SEE ALSO"
Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
.SH KEYWORDS
blocking, callback, channel, events, handler, nonblocking.

59
contrib/tcl/doc/CrtCloseHdlr.3 Normal file
View File

@ -0,0 +1,59 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) CrtCloseHdlr.3 1.7 96/04/15 13:08:19
.so man.macros
.TH Tcl_CreateCloseHandler 3 7.5 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_CreateCloseHandler, Tcl_DeleteCloseHandler \- arrange for callbacks when channels are closed
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
void
\fBTcl_CreateCloseHandler\fR(\fIchannel, proc, clientData\fR)
.sp
void
\fBTcl_DeleteCloseHandler\fR(\fIchannel, proc, clientData\fR)
.sp
.SH ARGUMENTS
.AS Tcl_CloseProc callbackData in
.AP Tcl_Channel channel in
The channel for which to create or delete a close callback.
.AP Tcl_CloseProc *proc in
The procedure to call as the callback.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateCloseHandler\fR arranges for \fIproc\fR to be called when
\fIchannel\fR is closed with \fBTcl_Close\fR or
\fBTcl_UnregisterChannel\fR, or using the Tcl \fBclose\fR command.
\fIProc\fR should match the following prototype:
.PP
.CS
typedef void Tcl_CloseProc(
ClientData \fIclientData\fR);
.CE
.PP
The \fIclientData\fR is the same as the value provided in the call to
\fBTcl_CreateCloseHandler\fR.
.PP
\fBTcl_DeleteCloseHandler\fR removes a close callback for \fIchannel\fR.
The \fIproc\fR and \fIclientData\fR identify which close callback to
remove; \fBTcl_DeleteCloseHandler\fR does nothing if its \fIproc\fR and
\fIclientData\fR arguments do not match the \fIproc\fR and \fIclientData\fR
for a close handler for \fIchannel\fR.
.SH "SEE ALSO"
close(n), Tcl_Close(3), Tcl_UnregisterChannel(3)
.SH KEYWORDS
callback, channel closing

181
contrib/tcl/doc/CrtCommand.3 Normal file
View File

@ -0,0 +1,181 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) CrtCommand.3 1.22 96/03/25 19:58:44
'\"
.so man.macros
.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo \- implement new commands in C
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
.VS
.VE
Tcl_Command
\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
.sp
int
\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
.sp
.VS
int
\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
.sp
int
\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
.sp
.VS
char *
\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
.VE
.VE
.SH ARGUMENTS
.AS Tcl_CmdDeleteProc **deleteProcPtr
.AP Tcl_Interp *interp in
Interpreter in which to create new command.
.AP char *cmdName in
Name of command.
.AP Tcl_CmdProc *proc in
Implementation of new command: \fIproc\fR will be called whenever
\fIcmdName\fR is invoked as a command.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
.AP Tcl_CmdDeleteProc *deleteProc in
Procedure to call before \fIcmdName\fR is deleted from the interpreter;
allows for command-specific cleanup. If NULL, then no procedure is
called before the command is deleted.
.AP Tcl_CmdInfo *infoPtr in/out
.VS
Pointer to structure containing various information about a
Tcl command.
.AP Tcl_Command token in
Token for command, returned by previous call to \fBTcl_CreateCommand\fR.
The command must not have been deleted.
.VE
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
will call \fIproc\fR
to process the command. If there is already a command \fIcmdName\fR
associated with the interpreter, it is deleted.
.VS
\fBTcl_CreateCommand\fR returns a token that may be used to refer
to the command in subsequent calls to \fBTcl_GetCommandName\fR.
If \fBTcl_CreateCommand\fR is called for an interpreter that is in
the process of being deleted, then it does not create a new command
and it returns NULL.
.VE
\fIProc\fR should have arguments and result that match the type
\fBTcl_CmdProc\fR:
.CS
typedef int Tcl_CmdProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
int \fIargc\fR,
char *\fIargv\fR[]);
.CE
When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
parameters will be copies of the \fIclientData\fR and \fIinterp\fR
arguments given to \fBTcl_CreateCommand\fR.
Typically, \fIclientData\fR points to an application-specific
data structure that describes what to do when the command procedure
is invoked. \fIArgc\fR and \fIargv\fR describe the arguments to
the command, \fIargc\fR giving the number of arguments (including
the command name) and \fIargv\fR giving the values of the arguments
as strings. The \fIargv\fR array will contain \fIargc\fR+1 values;
the first \fIargc\fR values point to the argument strings, and the
last value is NULL.
.PP
\fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. See the Tcl overview man page
for details on what these codes mean. Most normal commands will only
return \fBTCL_OK\fR or \fBTCL_ERROR\fR. In addition, \fIproc\fR must set
\fIinterp->result\fR to point to a string value;
in the case of a \fBTCL_OK\fR return code this gives the result
of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
The \fBTcl_SetResult\fR procedure provides an easy interface for setting
the return value; for complete details on how the \fIinterp->result\fR
field is managed, see the \fBTcl_Interp\fR man page.
Before invoking a command procedure,
\fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
commands can return an empty result by doing nothing at all.
.PP
.VS
The contents of the \fIargv\fR array belong to Tcl and are not
guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
not modify them, nor should it set \fIinterp->result\fR to point
anywhere within the \fIargv\fR values.
Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
to return something from the \fIargv\fR array.
.VE
.PP
\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
\fIDeleteProc\fR is invoked before the command is deleted, and gives the
application an opportunity to release any structures associated
with the command. \fIDeleteProc\fR should have arguments and
result that match the type \fBTcl_CmdDeleteProc\fR:
.CS
typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
.CE
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument passed to \fBTcl_CreateCommand\fR.
.PP
\fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
Once the call completes, attempts to invoke \fIcmdName\fR in
\fIinterp\fR will result in errors.
If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
\fBTcl_DeleteCommand\fR does nothing and returns -1; otherwise
it returns 0.
There are no restrictions on \fIcmdName\fR: it may refer to
a built-in command, an application-specific command, or a Tcl procedure.
.PP
.VS
\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
exists as a command in \fIinterp\fR. If not then it returns 0.
Otherwise it places information about the command in the structure
pointed to by \fIinfoPtr\fR and returns 1.
Tcl_CmdInfo structures have fields named \fIproc\fR, \fIclientData\fR,
and \fIdeleteProc\fR, which have the same meaning as the corresponding
arguments to \fBTcl_CreateCommand\fR.
There is also a field \fIdeleteData\fR, which is the ClientData value
to pass to \fIdeleteProc\fR; it is normally the same as
\fIclientData\fR but may be set independently using the
\fBTcl_SetCommandInfo\fR procedure.
.PP
\fBTcl_SetCommandInfo\fR is used to modify the procedures and
ClientData values associated with a command.
Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
Otherwise, it copies the information from \fI*infoPtr\fR to
Tcl's internal structure for the command and returns 1.
Note that this procedure allows the ClientData for a command's
deletion procedure to be given a different value than the ClientData
for its command procedure.
.PP
\fBTcl_GetCommandName\fR provides a mechanism for tracking commands
that have been renamed. Given a token returned by \fBTcl_CreateCommand\fR
when the command was created, \fBTcl_GetCommandName\fR returns the
string name of the command. If the command has been renamed since it
was created, then \fBTcl_GetCommandName\fR returns the current name.
The command corresponding to \fItoken\fR must not have been deleted.
The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
owned by Tcl and is only guaranteed to retain its value as long as the
command isn't deleted or renamed; callers should copy the string if
they need to keep it for a long time.
.VE
.SH KEYWORDS
bind, command, create, delete, interpreter

90
contrib/tcl/doc/CrtFileHdlr.3 Normal file
View File

@ -0,0 +1,90 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) CrtFileHdlr.3 1.6 96/03/25 19:59:08
'\"
.so man.macros
.TH Tcl_CreateFileHandler 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_CreateFileHandler\fR(\fIfile, mask, proc, clientData\fR)
.sp
\fBTcl_DeleteFileHandler\fR(\fIfile\fR)
.SH ARGUMENTS
.AS Tcl_FileProc clientData
.AP Tcl_File file in
Generic file handle for an open file or device (such as returned by
\fBTcl_GetFile\fR call).
.AP int mask in
Conditions under which \fIproc\fR should be called:
OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR,
and \fBTCL_EXCEPTION\fR. May be set to 0 to temporarily disable
a handler.
.AP Tcl_FileProc *proc in
Procedure to invoke whenever the file or device indicated
by \fIfile\fR meets the conditions specified by \fImask\fR.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be
invoked in the future whenever I/O becomes possible on a file
or an exceptional condition exists for the file. The file
is indicated by \fIfile\fR, and the conditions of interest
are indicated by \fImask\fR. For example, if \fImask\fR
is \fBTCL_READABLE\fR, \fIproc\fR will be called when
the file is readable.
The callback to \fIproc\fR is made by \fBTcl_DoOneEvent\fR, so
\fBTcl_CreateFileHandler\fR is only useful in programs that dispatch
events through \fBTcl_DoOneEvent\fR or through Tcl commands such
as \fBvwait\fR.
.PP
\fIProc\fR should have arguments and result that match the
type \fBTcl_FileProc\fR:
.CS
typedef void Tcl_FileProc(
ClientData \fIclientData\fR,
int \fImask\fR);
.CE
The \fIclientData\fR parameter to \fIproc\fR is a copy
of the \fIclientData\fR
argument given to \fBTcl_CreateFileHandler\fR when the callback
was created. Typically, \fIclientData\fR points to a data
structure containing application-specific information about
the file. \fIMask\fR is an integer mask indicating which
of the requested conditions actually exists for the file; it
will contain a subset of the bits in the \fImask\fR argument
to \fBTcl_CreateFileHandler\fR.
.PP
.PP
There may exist only one handler for a given file at a given time.
If \fBTcl_CreateFileHandler\fR is called when a handler already
exists for \fIfile\fR, then the new callback replaces the information
that was previously recorded.
.PP
\fBTcl_DeleteFileHandler\fR may be called to delete the
file handler for \fIfile\fR; if no handler exists for the
file given by \fIfile\fR then the procedure has no effect.
.PP
The purpose of file handlers is to enable an application to respond to
events while waiting for files to become ready for I/O. For this to work
correctly, the application may need to use non-blocking I/O operations on
the files for which handlers are declared. Otherwise the application may
block if it reads or writes too much data; while waiting for the I/O to
complete the application won't be able to service other events. Use
\fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into
blocking or nonblocking mode as required.
.SH KEYWORDS
callback, file, handler

131
contrib/tcl/doc/CrtInterp.3 Normal file
View File

@ -0,0 +1,131 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) CrtInterp.3 1.14 96/03/26 15:14:45
'\"
.so man.macros
.TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted \- create and delete Tcl command interpreters
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Interp *
\fBTcl_CreateInterp\fR()
.sp
\fBTcl_DeleteInterp\fR(\fIinterp\fR)
.sp
int
\fBTcl_InterpDeleted\fR(\fIinterp\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Token for interpreter to be destroyed.
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateInterp\fR creates a new interpreter structure and returns
a token for it. The token is required in calls to most other Tcl
procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and
\fBTcl_DeleteInterp\fR.
Clients are only allowed to access a few of the fields of
Tcl_Interp structures; see the Tcl_Interp
and \fBTcl_CreateCommand\fR man pages for details.
The new interpreter is initialized with no defined variables and only
the built-in Tcl commands. To bind in additional commands, call
\fBTcl_CreateCommand\fR.
.PP
\fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter
will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have
been matched by calls to \fBTcl_Release\fR. At that time, all of the
resources associated with it, including variables, procedures, and
application-specific command bindings, will be deleted. After
\fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the
interpreter will fail and return \fBTCL_ERROR\fR. After the call to
\fBTcl_DeleteInterp\fR it is safe to examine \fIinterp->result\fR, query or
set the values of variables, define, undefine or retrieve procedures, and
examine the runtime evaluation stack. See below, in the section
\fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details.
.PP
\fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was
called with \fIinterp\fR as its argument; this indicates that the
interpreter will eventually be deleted, when the last call to
\fBTcl_Preserve\fR for it is matched by a call to \fBTcl_Release\fR. If
nonzero is returned, further calls to \fBTcl_Eval\fR in this interpreter
will return \fBTCL_ERROR\fR.
.PP
\fBTcl_InterpDeleted\fR is useful in deletion callbacks to distinguish
between when only the memory the callback is responsible for is being
deleted and when the whole interpreter is being deleted. In the former case
the callback may recreate the data being deleted, but this would lead to an
infinite loop if the interpreter were being deleted.
.SH "INTERPRETERS AND MEMORY MANAGEMENT"
.PP
\fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
be used by nested evaluations and C code in various extensions. Tcl
implements a simple mechanism that allows callers to use interpreters
without worrying about the interpreter being deleted in a nested call, and
without requiring special code to protect the interpreter, in most cases.
This mechanism ensures that nested uses of an interpreter can safely
continue using it even after \fBTcl_DeleteInterp\fR is called.
.PP
The mechanism relies on matching up calls to \fBTcl_Preserve\fR with calls
to \fBTcl_Release\fR. If \fBTcl_DeleteInterp\fR has been called, only when
the last call to \fBTcl_Preserve\fR is matched by a call to
\fBTcl_Release\fR, will the interpreter be freed. See the manual entry for
\fBTcl_Preserve\fR for a description of these functions.
.PP
The rules for when the user of an interpreter must call \fBTcl_Preserve\fR
and \fBTcl_Release\fR are simple:
.TP
Interpreters Passed As Arguments
Functions that are passed an interpreter as an argument can safely use the
interpreter without any special protection. Thus, when you write an
extension consisting of new Tcl commands, no special code is needed to
protect interpreters received as arguments. This covers the majority of all
uses.
.TP
Interpreter Creation And Deletion
When a new interpreter is created and used in a call to \fBTcl_Eval\fR,
\fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or
\fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and
\fBTcl_Release\fR should be wrapped around all uses of the interpreter.
Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR
has been called. To ensure that the interpreter is properly deleted when
it is no longer needed, call \fBTcl_InterpDeleted\fB to test if some other
code already called \fBTcl_DeleteInterp\fB; if not, call
\fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fB in your own code.
Do not call \fBTcl_DeleteInterp\fR on an interpreter for which
\fBTcl_InterpDeleted\fR returns nonzero.
.TP
Retrieving An Interpreter From A Data Structure
When an interpreter is retrieved from a data structure (e.g. the client
data of a callback) for use in \fBTcl_Eval\fR, \fBTcl_VarEval\fR,
\fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or \fBTcl_GetVar\fR, a pair of
calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around
all uses of the interpreter; it is unsafe to reuse the interpreter once
\fBTcl_Release\fR has been called. If an interpreter is stored inside a
callback data structure, an appropriate deletion cleanup mechanism should
be set up by the code that creates the data structure so that the
interpreter is removed from the data structure (e.g. by setting the field
to NULL) when the interpreter is deleted. Otherwise, you may be using an
interpreter that has been freed and whose memory may already have been
reused.
.PP
All uses of interpreters in Tcl and Tk have already been protected.
Extension writers should ensure that their code also properly protects any
additional interpreters used, as described above.
.SH KEYWORDS
command, create, delete, interpreter
.SH "SEE ALSO"
Tcl_Preserve(3), Tcl_Release(3)

95
contrib/tcl/doc/CrtMathFnc.3 Normal file
View File

@ -0,0 +1,95 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) CrtMathFnc.3 1.8 96/03/25 19:59:55
'\"
.so man.macros
.TH Tcl_CreateMathFunc 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateMathFunc \- Define a new math function for expressions
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
.SH ARGUMENTS
.AS Tcl_ValueType clientData
.AP Tcl_Interp *interp in
Interpreter in which new function will be defined.
.AP char *name in
Name for new function.
.AP int numArgs in
Number of arguments to new function; also gives size of \fIargTypes\fR array.
.AP Tcl_ValueType *argTypes in
Points to an array giving the permissible types for each argument to
function.
.AP Tcl_MathProc *proc in
Procedure that implements the function.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR when it is invoked.
.BE
.SH DESCRIPTION
.PP
Tcl allows a number of mathematical functions to be used in
expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
\fBTcl_CreateMathFunc\fR allows applications to add additional functions
to those already provided by Tcl or to replace existing functions.
\fIName\fR is the name of the function as it will appear in expressions.
If \fIname\fR doesn't already exist as a function then a new function
is created. If it does exist, then the existing function is replaced.
\fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
Each entry in the \fIargTypes\fR array must be either TCL_INT, TCL_DOUBLE,
or TCL_EITHER to indicate whether the corresponding argument must be an
integer, a double-precision floating value, or either, respectively.
.PP
Whenever the function is invoked in an expression Tcl will invoke
\fIproc\fR. \fIProc\fR should have arguments and result that match
the type \fBTcl_MathProc\fR:
.CS
typedef int Tcl_MathProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
Tcl_Value *\fIargs\fR,
Tcl_Value *\fIresultPtr\fR);
.CE
.PP
When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
\fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
which describe the actual arguments to the function:
.CS
typedef struct Tcl_Value {
Tcl_ValueType \fItype\fR;
.VS
.VE
long \fIintValue\fR;
double \fIdoubleValue\fR;
} Tcl_Value;
.CE
.PP
The \fItype\fR field indicates the type of the argument and is
either TCL_INT or TCL_DOUBLE.
It will match the \fIargTypes\fR value specified for the function unless
the \fIargTypes\fR value was TCL_EITHER. Tcl converts
the argument supplied in the expression to the type requested in
\fIargTypes\fR, if that is necessary.
Depending on the value of the \fItype\fR field, the \fIintValue\fR
or \fIdoubleValue\fR field will contain the actual value of the argument.
.PP
\fIProc\fR should compute its result and store it either as an integer
in \fIresultPtr->intValue\fR or as a floating value in
\fIresultPtr->doubleValue\fR.
It should set also \fIresultPtr->type\fR to either TCL_INT or TCL_DOUBLE
to indicate which value was set.
Under normal circumstances \fIproc\fR should return TCL_OK.
If an error occurs while executing the function, \fIproc\fR should
return TCL_ERROR and leave an error message in \fIinterp->result\fR.
.SH KEYWORDS
expression, mathematical function

71
contrib/tcl/doc/CrtModalTmt.3 Normal file
View File

@ -0,0 +1,71 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) CrtModalTmt.3 1.3 96/03/25 20:00:19
'\"
.so man.macros
.TH Tcl_CreateModalTimeout 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateModalTimeout, Tcl_DeleteModalTimeout \- special timer for modal operations
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_CreateModalTimeout\fR(\fImilliseconds, proc, clientData\fR)
.sp
\fBTcl_DeleteModalTimeout\fR(\fIproc, clientData\fR)
.SH ARGUMENTS
.AS Tcl_TimerToken milliseconds
.AP int milliseconds in
How many milliseconds to wait before invoking \fIproc\fR.
.AP Tcl_TimerProc *proc in
Procedure to invoke after \fImilliseconds\fR have elapsed.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateModalTimeout\fR provides an alternate form of timer
from those provided by \fBTcl_CreateTimerHandler\fR.
These timers are called ``modal'' because they are typically
used in situations where a particular operation must be completed
before the application does anything else.
If such an operation needs a timeout, it cannot use normal timer
events: if normal timer events were processed, arbitrary Tcl scripts
might be invoked via other event handlers, which could interfere with
the completion of the modal operation.
The purpose of modal timers is to allow a single timeout to occur
without allowing any normal timer events to occur.
.PP
\fBTcl_CreateModalTimeout\fR behaves just like \fBTcl_CreateTimerHandler\fR
except that it creates a modal timeout.
Its arguments have the same meaning as for \fBTcl_CreateTimerHandler\fR
and \fIproc\fR is invoked just as for \fBTcl_CreateTimerHandler\fR.
\fBTcl_DeleteModalTimeout\fR deletes the most recently created
modal timeout; its arguments must match the corresponding arguments
to the most recent call to \fBTcl_CreateModalTimeout\fR.
.PP
Modal timeouts differ from a normal timers in three ways. First,
they will trigger regardless of whether the TCL_TIMER_EVENTS flag
has been passed to \fBTcl_DoOneEvent\fR.
Typically modal timers are used with the TCL_TIMER_EVENTS flag
off so that normal timers don't fire but modal ones do.
Second, if several modal timers have been created they stack:
only the top timer on the stack (the most recently created one)
is active at any point in time.
Modal timeouts must be deleted in inverse order from their creation.
Third, modal timeouts are not deleted when they fire: once a modal
timeout has fired, it will continue firing every time \fBTcl_DoOneEvent\fR
is called, until the timeout is deleted by calling
\fBTcl_DeleteModalTimeout\fR.
.PP
Modal timeouts are only needed in a few special situations, and they
should be used with caution.
.SH KEYWORDS
callback, clock, handler, modal timeout

142
contrib/tcl/doc/CrtSlave.3 Normal file
View File

@ -0,0 +1,142 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) CrtSlave.3 1.13 96/03/25 20:00:42
'\"
.so man.macros
.TH Tcl_CreateSlave 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetSlaves, Tcl_GetMaster, Tcl_CreateAlias, Tcl_GetAlias, Tcl_GetAliases \- manage
multiple Tcl interpreters and aliases.
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_IsSafe\fR(\fIinterp\fR)
.sp
int
\fBTcl_MakeSafe\fR(\fIinterp\fR)
.sp
Tcl_Interp *
\fBTcl_CreateSlave\fR(\fIinterp, slaveName, isSafe\fR)
.sp
Tcl_Interp *
\fBTcl_GetSlave\fR(\fIinterp, slaveName\fR)
.sp
Tcl_Interp *
\fBTcl_GetMaster\fR(\fIinterp\fR)
.sp
int
\fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
.sp
int
\fBTcl_CreateAlias\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, argc, argv\fR)
.sp
int
\fBTcl_GetAlias\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)
.SH ARGUMENTS
.AS Tcl_InterpDeleteProc **delProcPtr
.AP Tcl_Interp *interp in
Interpreter in which to execute the specified command.
.AP char *slaveName in
Name of slave interpreter to create or manipulate.
.AP int isSafe in
Zero means the interpreter may have all Tcl functions. Non-zero means the
new interpreter's functionality should be limited to make it safe.
.AP Tcl_Interp *slaveInterp in
Interpreter to use for creating the source command for an alias (see
below).
.AP char *srcCmd in
Name of source command for alias.
.AP Tcl_Interp *targetInterp in
Interpreter that contains the target command for an alias.
.AP char *targetCmd in
Name of target command for alias in \fItargetInterp\fR.
.AP int argc in
Count of additional arguments to pass to the alias command.
.AP char **argv in
Vector of strings, the additional arguments to pass to the alias command.
This storage is owned by the caller.
.AP Tcl_Interp **targetInterpPtr in
Pointer to location to store the address of the interpreter where a target
command is defined for an alias.
.AP char **targetCmdPtr out
Pointer to location to store the address of the name of the target command
for an alias.
.AP int *argcPtr out
Pointer to location to store count of additional arguments to be passed to
the alias. The location is in storage owned by the caller.
.AP char ***argvPtr out
Pointer to location to store a vector of strings, the additional arguments
to pass to an alias. The location is in storage owned by the caller, the
vector of strings is owned by the called function.
.BE
.SH DESCRIPTION
.PP
These procedures are intended for access to the multiple interpreter
facility from inside C programs. They enable managing multiple interpreters
in a hierarchical relationship, and the management of aliases, commands
that when invoked in one interpreter execute a command in another
interpreter. The return value for those procedures that return an \fBint\fR
is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
then the \fBresult\fR field of the interpreter contains an error message.
.PP
\fBTcl_CreateSlave\fR creates a new interpreter as a slave of the given
interpreter. It also creates a slave command in the given interpreter which
allows the master interpreter to manipulate the slave. The slave
interpreter and the slave command have the specified name. If \fIisSafe\fR
is \fB1\fR, the new slave interpreter is made ``safe'' by removing all
unsafe functionality. If the creation failed, \fBNULL\fR is returned.
.PP
\fBTcl_IsSafe\fR returns \fB1\fR if the given interpreter is ``safe'',
\fB0\fR otherwise.
.PP
\fBTcl_MakeSafe\fR makes the given interpreter ``safe'' by removing all
non-core and core unsafe functionality. Note that if you call this after
adding some extension to an interpreter, all traces of that extension will
be removed from the interpreter. This operation always succeeds and returns
\fBTCL_OK\fR.
.PP
\fBTcl_GetSlave\fR returns a pointer to a slave interpreter of the given
interpreter. The slave interpreter is identified by the name specified.
If no such slave interpreter exists, \fBNULL\fR is returned.
.PP
\fBTcl_GetMaster\fR returns a pointer to the master interpreter of the
given interpreter. If the given interpreter has no master (it is a
top-level interpreter) then \fBNULL\fR is returned.
.PP
\fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
\fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation
of the relative path succeeds, \fBTCL_OK\fR is returned, else
\fBTCL_ERROR\fR is returned and the \fIresult\fR field in
\fIaskingInterp\fR contains the error message.
.PP
\fBTcl_GetAlias\fR returns information about an alias of a specified name
in a given interpreter. Any of the result fields can be \fBNULL\fR, in
which case the corresponding datum is not returned. If a result field is
non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
pointer to the string containing the name of the target command.
.PP
In order to map over all slave interpreters, use \fBTcl_Eval\fR with the
command \fBinterp slaves\fR and use the value (a Tcl list) deposited in the
\fBresult\fR field of the interpreter. Similarly, to map over all aliases
whose source commands are defined in an interpreter, use \fBTcl_Eval\fR
with the command \fBinterp aliases\fR and use the value (a Tcl list)
deposited in the \fBresult\fR field. Note that the storage of this list
belongs to Tcl, so you should copy it before invoking any other Tcl
commands in that interpreter.
.SH "SEE ALSO"
For a description of the Tcl interface to multiple interpreters, see
\fIinterp(n)\fR.
.SH KEYWORDS
alias, command, interpreter, master, slave

73
contrib/tcl/doc/CrtTimerHdlr.3 Normal file
View File

@ -0,0 +1,73 @@
'\"
'\" Copyright (c) 1990 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.
'\"
'\" SCCS: @(#) CrtTimerHdlr.3 1.3 96/03/25 20:00:55
'\"
.so man.macros
.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a
given time
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_TimerToken
\fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR)
.sp
\fBTcl_DeleteTimerHandler\fR(\fItoken\fR)
.SH ARGUMENTS
.AS Tcl_TimerToken milliseconds
.AP int milliseconds in
How many milliseconds to wait before invoking \fIproc\fR.
.AP Tcl_TimerProc *proc in
Procedure to invoke after \fImilliseconds\fR have elapsed.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.AP Tcl_TimerToken token in
Token for previously-created timer handler (the return value
from some previous call to \fBTcl_CreateTimerHandler\fR).
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateTimerHandler\fR arranges for \fIproc\fR to be
invoked at a time \fImilliseconds\fR milliseconds in the
future.
The callback to \fIproc\fR will be made by \fBTcl_DoOneEvent\fR,
so \fBTcl_CreateTimerHandler\fR is only useful in programs that
dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands
such as \fBvwait\fR.
The call to \fIproc\fR may not be made at the exact time given by
\fImilliseconds\fR: it will be made at the next opportunity
after that time. For example, if \fBTcl_DoOneEvent\fR isn't
called until long after the time has elapsed, or if there
are other pending events to process before the call to
\fIproc\fR, then the call to \fIproc\fR will be delayed.
.PP
\fIProc\fR should have arguments and return value that match
the type \fBTcl_TimerProc\fR:
.CS
typedef void Tcl_TimerProc(ClientData \fIclientData\fR);
.CE
The \fIclientData\fR parameter to \fIproc\fR is a
copy of the \fIclientData\fR argument given to
\fBTcl_CreateTimerHandler\fR when the callback
was created. Typically, \fIclientData\fR points to a data
structure containing application-specific information about
what to do in \fIproc\fR.
.PP
\fBTcl_DeleteTimerHandler\fR may be called to delete a
previously-created timer handler. It deletes the handler
indicated by \fItoken\fR so that no call to \fIproc\fR
will be made; if that handler no longer exists
(e.g. because the time period has already elapsed and \fIproc\fR
has been invoked) then \fBTcl_DeleteTimerHandler\fR does nothing.
.SH KEYWORDS
callback, clock, handler, timer

106
contrib/tcl/doc/CrtTrace.3 Normal file
View File

@ -0,0 +1,106 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) CrtTrace.3 1.14 96/03/25 20:01:10
'\"
.so man.macros
.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Trace
\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)
.sp
\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
.SH ARGUMENTS
.AS Tcl_CmdTraceProc (clientData)()
.AP Tcl_Interp *interp in
Interpreter containing command to be traced or untraced.
.AP int level in
Only commands at or below this nesting level will be traced. 1 means
top-level commands only, 2 means top-level commands or those that are
invoked as immediate consequences of executing top-level commands
(procedure bodies, bracketed commands, etc.) and so on.
.AP Tcl_CmdTraceProc *proc in
Procedure to call for each command that's executed. See below for
details on the calling sequence.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.AP Tcl_Trace trace in
Token for trace to be removed (return value from previous call
to \fBTcl_CreateTrace\fR).
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateTrace\fR arranges for command tracing. From now on, \fIproc\fR
will be invoked before Tcl calls command procedures to process
commands in \fIinterp\fR. The return value from
\fBTcl_CreateTrace\fR is a token for the trace,
which may be passed to \fBTcl_DeleteTrace\fR to remove the trace. There may
be many traces in effect simultaneously for the same command interpreter.
.PP
\fIProc\fR should have arguments and result that match the
type \fBTcl_CmdTraceProc\fR:
.CS
typedef void Tcl_CmdTraceProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
int \fIlevel\fR,
char *\fIcommand\fR,
Tcl_CmdProc *\fIcmdProc\fR,
ClientData \fIcmdClientData\fR,
int \fIargc\fR,
char *\fIargv\fR[]);
.CE
The \fIclientData\fR and \fIinterp\fR parameters are
copies of the corresponding arguments given to \fBTcl_CreateTrace\fR.
\fIClientData\fR typically points to an application-specific
data structure that describes what to do when \fIproc\fR
is invoked. \fILevel\fR gives the nesting level of the command
(1 for top-level commands passed to \fBTcl_Eval\fR by the application,
2 for the next-level commands passed to \fBTcl_Eval\fR as part of parsing
or interpreting level-1 commands, and so on). \fICommand\fR
points to a string containing the text of the
command, before any argument substitution.
\fICmdProc\fR contains the address of the command procedure that
will be called to process the command (i.e. the \fIproc\fR argument
of some previous call to \fBTcl_CreateCommand\fR) and \fIcmdClientData\fR
contains the associated client data for \fIcmdProc\fR (the \fIclientData\fR
value passed to \fBTcl_CreateCommand\fR). \fIArgc\fR and \fIargv\fR give
the final argument information that will be passed to \fIcmdProc\fR, after
command, variable, and backslash substitution.
\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
.PP
Tracing will only occur for commands at nesting level less than
or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
parameter to \fIproc\fR will always be less than or equal to the
\fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
.PP
Calls to \fIproc\fR will be made by the Tcl parser immediately before
it calls the command procedure for the command (\fIcmdProc\fR). This
occurs after argument parsing and substitution, so tracing for
substituted commands occurs before tracing of the commands
containing the substitutions. If there is a syntax error in a
command, or if there is no command procedure associated with a
command name, then no tracing will occur for that command. If a
string passed to Tcl_Eval contains multiple commands (bracketed, or
on different lines) then multiple calls to \fIproc\fR will occur,
one for each command. The \fIcommand\fR string for each of these
trace calls will reflect only a single command, not the entire string
passed to Tcl_Eval.
.PP
\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be
made to the procedure associated with the trace. After \fBTcl_DeleteTrace\fR
returns, the caller should never again use the \fItrace\fR token.
.SH KEYWORDS
command, create, delete, interpreter, trace

153
contrib/tcl/doc/DString.3 Normal file
View File

@ -0,0 +1,153 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) DString.3 1.19 96/03/25 20:01:32
'\"
.so man.macros
.TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_DStringInit\fR(\fIdsPtr\fR)
.sp
char *
\fBTcl_DStringAppend\fR(\fIdsPtr, string, length\fR)
.sp
char *
\fBTcl_DStringAppendElement\fR(\fIdsPtr, string\fR)
.sp
\fBTcl_DStringStartSublist\fR(\fIdsPtr\fR)
.sp
\fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
.sp
int
\fBTcl_DStringLength\fR(\fIdsPtr\fR)
.sp
char *
\fBTcl_DStringValue\fR(\fIdsPtr\fR)
.sp
.VS
\fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
.VE
.sp
\fBTcl_DStringFree\fR(\fIdsPtr\fR)
.sp
\fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
.sp
.VS
\fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
.VE
.SH ARGUMENTS
.AS Tcl_DString newLength
.AP Tcl_DString *dsPtr in/out
Pointer to structure that is used to manage a dynamic string.
.AP char *string in
Pointer to characters to add to dynamic string.
.AP int length in
Number of characters from string to add to dynamic string. If -1,
add all characters up to null terminating character.
.AP int newLength in
New length for dynamic string, not including null terminating
character.
.AP Tcl_Interp *interp in/out
Interpreter whose result is to be set from or moved to the
dynamic string.
.BE
.SH DESCRIPTION
.PP
Dynamic strings provide a mechanism for building up arbitrarily long
strings by gradually appending information. If the dynamic string is
short then there will be no memory allocation overhead; as the string
gets larger, additional space will be allocated as needed.
.PP
\fBTcl_DStringInit\fR initializes a dynamic string to zero length.
The Tcl_DString structure must have been allocated by the caller.
No assumptions are made about the current state of the structure;
anything already in it is discarded.
If the structure has been used previously, \fBTcl_DStringFree\fR should
be called first to free up any memory allocated for the old
string.
.PP
\fBTcl_DStringAppend\fR adds new information to a dynamic string,
allocating more memory for the string if needed.
If \fIlength\fR is less than zero then everything in \fIstring\fR
is appended to the dynamic string; otherwise \fIlength\fR
specifies the number of bytes to append.
\fBTcl_DStringAppend\fR returns a pointer to the characters of
the new string. The string can also be retrieved from the
\fIstring\fR field of the Tcl_DString structure.
.PP
\fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR
except that it doesn't take a \fIlength\fR argument (it appends
all of \fIstring\fR) and it converts the string to a proper list element
before appending.
\fBTcl_DStringAppendElement\fR adds a separator space before the
new list element unless the new list element is the first in a
list or sub-list (i.e. either the current string is empty, or it
contains the single character ``{'', or the last two characters of
the current string are `` {'').
\fBTcl_DStringAppendElement\fR returns a pointer to the
characters of the new string.
.PP
\fBTcl_DStringStartSublist\fR and \fBTcl_DStringEndSublist\fR can be
used to create nested lists.
To append a list element that is itself a sublist, first
call \fBTcl_DStringStartSublist\fR, then call \fBTcl_DStringAppendElement\fR
for each of the elements in the sublist, then call
\fBTcl_DStringEndSublist\fR to end the sublist.
\fBTcl_DStringStartSublist\fR appends a space character if needed,
followed by an open brace; \fBTcl_DStringEndSublist\fR appends
a close brace.
Lists can be nested to any depth.
.PP
\fBTcl_DStringLength\fR is a macro that returns the current length
of a dynamic string (not including the terminating null character).
\fBTcl_DStringValue\fR is a macro that returns a pointer to the
current contents of a dynamic string.
.PP
.VS
.PP
\fBTcl_DStringSetLength\fR changes the length of a dynamic string.
If \fInewLength\fR is less than the string's current length, then
the string is truncated.
If \fInewLength\fR is greater than the string's current length,
then the string will become longer and new space will be allocated
for the string if needed.
However, \fBTcl_DStringSetLength\fR will not initialize the new
space except to provide a terminating null character; it is up to the
caller to fill in the new space.
\fBTcl_DStringSetLength\fR does not free up the string's storage space
even if the string is truncated to zero length, so \fBTcl_DStringFree\fR
will still need to be called.
.VE
.PP
\fBTcl_DStringFree\fR should be called when you're finished using
the string. It frees up any memory that was allocated for the string
and reinitializes the string's value to an empty string.
.PP
\fBTcl_DStringResult\fR sets the result of \fIinterp\fR to the value of
the dynamic string given by \fIdsPtr\fR. It does this by moving
a pointer from \fIdsPtr\fR to \fIinterp->result\fR.
This saves the cost of allocating new memory and copying the string.
\fBTcl_DStringResult\fR also reinitializes the dynamic string to
an empty string.
.PP
.VS
\fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR.
It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and
it clears \fIinterp\fR's result.
If possible it does this by moving a pointer rather than by copying
the string.
.VE
.SH KEYWORDS
append, dynamic string, free, result

66
contrib/tcl/doc/DetachPids.3 Normal file
View File

@ -0,0 +1,66 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) DetachPids.3 1.14 96/03/25 20:01:48
'\"
.so man.macros
.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_DetachPids, Tcl_ReapDetachedProcs \- manage child processes in background
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
.sp
.VS
\fBTcl_ReapDetachedProcs\fR()
.VE
.SH ARGUMENTS
.AS int *statusPtr
.AP int numPids in
Number of process ids contained in the array pointed to by \fIpidPtr\fR.
.AP int *pidPtr in
Address of array containing \fInumPids\fR process ids.
.BE
.SH DESCRIPTION
.PP
.VS
\fBTcl_DetachPids\fR and \fBTcl_ReapDetachedProcs\fR provide a
mechanism for managing subprocesses that are running in background.
These procedures are needed because the parent of a process must
eventually invoke the \fBwaitpid\fR kernel call (or one of a few other
similar kernel calls) to wait for the child to exit. Until the
parent waits for the child, the child's state cannot be completely
reclaimed by the system. If a parent continually creates children
and doesn't wait on them, the system's process table will eventually
overflow, even if all the children have exited.
.PP
\fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility
for one or more processes whose process ids are contained in the
\fIpidPtr\fR array passed as argument. The caller presumably
has started these processes running in background and doesn't
want to have to deal with them again.
.PP
\fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call
on each of the background processes so that its state can be cleaned
up if it has exited. If the process hasn't exited yet,
\fBTcl_ReapDetachedProcs\fR doesn't wait for it to exit; it will check again
the next time it is invoked.
Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the
\fBexec\fR command is executed, so in most cases it isn't necessary
for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR.
However, if you call \fBTcl_DetachPids\fR in situations where the
\fBexec\fR command may never get executed, you may wish to call
\fBTcl_ReapDetachedProcs\fR from time to time so that background
processes can be cleaned up.
.VE
.SH KEYWORDS
background, child, detach, process, wait

108
contrib/tcl/doc/DoOneEvent.3 Normal file
View File

@ -0,0 +1,108 @@
'\"
'\" Copyright (c) 1990-1992 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.
'\"
'\" SCCS: @(#) DoOneEvent.3 1.5 96/03/25 20:02:05
'\"
.so man.macros
.TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_DoOneEvent \- wait for events and invoke event handlers
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_DoOneEvent\fR(\fIflags\fR)
.SH ARGUMENTS
.AS int flags
.AP int flags in
This parameter is normally zero. It may be an OR-ed combination
of any of the following flag bits:
TCL_WINDOW_EVENTS,
TCL_FILE_EVENTS, TCL_TIMER_EVENTS, TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or
TCL_DONT_WAIT.
.BE
.SH DESCRIPTION
.PP
This procedure is the entry point to Tcl's event loop; it is responsible for
waiting for events and dispatching event handlers created with
procedures such as \fBTk_CreateEventHandler\fR, \fBTcl_CreateFileHandler\fR,
\fBTcl_CreateTimerHandler\fR, and \fBTcl_DoWhenIdle\fR.
\fBTcl_DoOneEvent\fR checks to see if
events are already present on the Tcl event queue; if so,
it calls the handler(s) for the first (oldest) event, removes it from
the queue, and returns.
If there are no events ready to be handled, then \fBTcl_DoOneEvent\fR
checks for new events from all possible sources.
If any are found, it puts all of them on Tcl's event queue, calls
handlers for the first event on the queue, and returns.
If no events are found, \fBTcl_DoOneEvent\fR checks for \fBTcl_DoWhenIdle\fR
callbacks; if any are found, it invokes all of them and returns.
Finally, if no events or idle callbacks have been found, then
\fBTcl_DoOneEvent\fR sleeps until an event occurs; then it adds any
ew events to the Tcl event queue, calls handlers for the first event,
and returns.
The normal return value is 1 to signify that some event
was processed (see below for other alternatives).
.PP
If the \fIflags\fR argument to \fBTcl_DoOneEvent\fR is non-zero,
it restricts the kinds of events that will be processed by
\fBTcl_DoOneEvent\fR.
\fIFlags\fR may be an OR-ed combination of any of the following bits:
.TP 27
\fBTCL_WINDOW_EVENTS\fR \-
Process window system events.
.TP 27
\fBTCL_FILE_EVENTS\fR \-
Process file events.
.TP 27
\fBTCL_TIMER_EVENTS\fR \-
Process timer events.
.TP 27
\fBTCL_IDLE_EVENTS\fR \-
Process idle callbacks.
.TP 27
\fBTCL_ALL_EVENTS\fR \-
Process all kinds of events: equivalent to OR-ing together all of the
above flags or specifying none of them.
.TP 27
\fBTCL_DONT_WAIT\fR \-
Don't sleep: process only events that are ready at the time of the
call.
.LP
If any of the flags \fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR,
\fBTCL_TIMER_EVENTS\fR, or \fBTCL_IDLE_EVENTS\fR is set, then the only
events that will be considered are those for which flags are set.
Setting none of these flags is equivalent to the value
\fBTCL_ALL_EVENTS\fR, which causes all event types to be processed.
If an application has defined additional event sources with
\fBTcl_CreateEventSource\fR, then additional \fIflag\fR values
may also be valid, depending on those event sources.
.PP
The \fBTCL_DONT_WAIT\fR flag causes \fBTcl_DoOneEvent\fR not to put
the process to sleep: it will check for events but if none are found
then it returns immediately with a return value of 0 to indicate
that no work was done.
\fBTcl_DoOneEvent\fR will also return 0 without doing anything if
the only alternative is to block forever (this can happen, for example,
if \fIflags\fR is \fBTCL_IDLE_EVENTS\fR and there are no
\fBTcl_DoWhenIdle\fR callbacks pending, or if no event handlers or
timer handlers exist).
.PP
\fBTcl_DoOneEvent\fR may be invoked recursively. For example,
it is possible to invoke \fBTcl_DoOneEvent\fR recursively
from a handler called by \fBTcl_DoOneEvent\fR. This sort
of operation is useful in some modal situations, such
as when a
notification dialog has been popped up and an application wishes to
wait for the user to click a button in the dialog before
doing anything else.
.SH KEYWORDS
callback, event, handler, idle, timer

87
contrib/tcl/doc/DoWhenIdle.3 Normal file
View File

@ -0,0 +1,87 @@
'\"
'\" Copyright (c) 1990 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.
'\"
'\" SCCS: @(#) DoWhenIdle.3 1.4 96/03/25 20:02:20
'\"
.so man.macros
.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR)
.sp
\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR)
.SH ARGUMENTS
.AS Tcl_IdleProc clientData
.AP Tcl_IdleProc *proc in
Procedure to invoke.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
when the application becomes idle. The application is
considered to be idle when \fBTcl_DoOneEvent\fR has been
called, couldn't find any events to handle, and is about
to go to sleep waiting for an event to occur. At this
point all pending \fBTcl_DoWhenIdle\fR handlers are
invoked. For each call to \fBTcl_DoWhenIdle\fR there will
be a single call to \fIproc\fR; after \fIproc\fR is
invoked the handler is automatically removed.
\fBTcl_DoWhenIdle\fR is only usable in programs that
use \fBTcl_DoOneEvent\fR to dispatch events.
.PP
\fIProc\fR should have arguments and result that match the
type \fBTcl_IdleProc\fR:
.CS
typedef void Tcl_IdleProc(ClientData \fIclientData\fR);
.CE
The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR
points to a data structure containing application-specific information about
what \fIproc\fR should do.
.PP
\fBTcl_CancelIdleCall\fR
may be used to cancel one or more previous
calls to \fBTcl_DoWhenIdle\fR: if there is a \fBTcl_DoWhenIdle\fR
handler registered for \fIproc\fR and \fIclientData\fR, then it
is removed without invoking it. If there is more than one
handler on the idle list that refers to \fIproc\fR and \fIclientData\fR,
all of the handlers are removed. If no existing handlers match
\fIproc\fR and \fIclientData\fR then nothing happens.
.PP
\fBTcl_DoWhenIdle\fR is most useful in situations where
(a) a piece of work will have to be done but (b) it's
possible that something will happen in the near future
that will change what has to be done or require something
different to be done. \fBTcl_DoWhenIdle\fR allows the
actual work to be deferred until all pending events have
been processed. At this point the exact work to be done
will presumably be known and it can be done exactly once.
.PP
For example, \fBTcl_DoWhenIdle\fR might be used by an editor
to defer display updates until all pending commands have
been processed. Without this feature, redundant redisplays
might occur in some situations, such as the processing of
a command file.
.SH BUGS
.PP
At present it is not safe for an idle callback to reschedule itself
continuously. This will interact badly with certain features of Tk
that attempt to wait for all idle callbacks to complete. If you would
like for an idle callback to reschedule itself continuously, it is
better to use a timer handler with a zero timeout period.
.SH KEYWORDS
callback, defer, idle callback

106
contrib/tcl/doc/Eval.3 Normal file
View File

@ -0,0 +1,106 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) Eval.3 1.17 96/03/25 20:02:33
'\"
.so man.macros
.TH Tcl_Eval 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
.VS
\fBTcl_Eval\fR(\fIinterp, cmd\fR)
.VE
.sp
int
\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
.sp
int
\fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
.sp
int
\fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
.SH ARGUMENTS
.AS Tcl_Interp **termPtr;
.AP Tcl_Interp *interp in
Interpreter in which to execute the command. String result will be
stored in \fIinterp->result\fR.
.AP char *cmd in
Command (or sequence of commands) to execute. Must be in writable
memory (\fBTcl_Eval\fR makes temporary modifications to the command).
.AP char *string in
String forming part of Tcl command.
.AP char *fileName in
Name of file containing Tcl command string.
.BE
.SH DESCRIPTION
.PP
All four of these procedures execute Tcl commands.
\fBTcl_Eval\fR is the core procedure: it parses commands
from \fIcmd\fR and executes them in
.VS
order until either an error occurs or it reaches the end of the string.
.VE
The return value from \fBTcl_Eval\fR is one
of the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
\fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
a string with additional information (result value or error message).
This return information corresponds to the last command executed from
\fIcmd\fR.
.PP
\fBTcl_VarEval\fR takes any number of string arguments
of any length, concatenates
them into a single string, then calls \fBTcl_Eval\fR to
execute that string as a Tcl command.
It returns the result of the command and also modifies
\fIinterp->result\fR in the usual fashion for Tcl commands. The
last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
of arguments.
.PP
\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
its contents as a Tcl command by calling \fBTcl_Eval\fR. It returns
a standard Tcl result that reflects the result of evaluating the
file.
If the file couldn't be read then a Tcl error is returned to describe
why the file couldn't be read.
.PP
\fBTcl_GlobalEval\fR is similar to \fBTcl_Eval\fR except that it
processes the command at global level.
This means that the variable context for the command consists of
global variables only (it ignores any Tcl procedure that is active).
This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
.PP
During the processing of a Tcl command it is legal to make nested
calls to evaluate other commands (this is how conditionals, loops,
and procedures are implemented).
If a code other than
\fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
caller should normally return immediately, passing that same
return code back to its caller, and so on until the top-level application is
reached. A few commands, like \fBfor\fR, will check for certain
return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
specially without returning.
.PP
\fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
in progress for \fIinterp\fR.
If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
about to be returned from the topmost \fBTcl_Eval\fR invocation for
\fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
and sets \fIinterp->result\fR to point to an error message indicating that
the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
invoked in an inappropriate place. This means that top-level
applications should never see a return code from \fBTcl_Eval\fR other then
\fBTCL_OK\fR or \fBTCL_ERROR\fR.
.SH KEYWORDS
command, execute, file, global, interpreter, variable

66
contrib/tcl/doc/Exit.3 Normal file
View File

@ -0,0 +1,66 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) Exit.3 1.4 96/03/25 20:02:50
'\"
.so man.macros
.TH Tcl_Exit 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Exit, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers)
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_Exit\fR(\fIstatus\fR)
.sp
\fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR)
.sp
\fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR)
.SH ARGUMENTS
.AS Tcl_ExitProc clientData
.AP int status in
Provides information about why application exited. Exact meaning may
be platform-specific. 0 usually means a normal exit, 1 means that an
error occurred.
.AP Tcl_ExitProc *proc in
Procedure to invoke before exiting application.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_Exit\fR is the procedure that is invoked to end a Tcl application.
It is invoked by the \fBexit\fR command, as well as anyplace else that
terminates the application.
No-one should ever invoke the \fBexit\fR procedure directly; always
invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers.
.PP
\fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
by \fBTcl_Exit\fR before it terminates the application.
This provides a hook for cleanup operations such as flushing buffers
and freeing global memory.
\fIProc\fR should have arguments and return value that match
the type \fBTcl_ExitProc\fR:
.CS
typedef void Tcl_ExitProc(ClientData \fIclientData\fR);
.CE
The \fIclientData\fR parameter to \fIproc\fR is a
copy of the \fIclientData\fR argument given to
\fBTcl_CreateExitHandler\fR when the callback
was created. Typically, \fIclientData\fR points to a data
structure containing application-specific information about
what to do in \fIproc\fR.
.PP
\fBTcl_DeleteExitHandler\fR may be called to delete a
previously-created exit handler. It removes the handler
indicated by \fIproc\fR and \fIclientData\fR so that no call
to \fIproc\fR will be made. If no such handler exists then
\fBTcl_DeleteExitHandler\fR does nothing.
.SH KEYWORDS
callback, end application, exit

106
contrib/tcl/doc/ExprLong.3 Normal file
View File

@ -0,0 +1,106 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) ExprLong.3 1.17 96/03/25 20:03:03
'\"
.so man.macros
.TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString \- evaluate an expression
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_ExprLong\fR(\fIinterp, string, longPtr\fR)
.sp
int
\fBTcl_ExprDouble\fR(\fIinterp, string, doublePtr\fR)
.sp
int
\fBTcl_ExprBoolean\fR(\fIinterp, string, booleanPtr\fR)
.sp
int
\fBTcl_ExprString\fR(\fIinterp, string\fR)
.SH ARGUMENTS
.AS Tcl_Interp *booleanPtr
.AP Tcl_Interp *interp in
Interpreter in whose context to evaluate \fIstring\fR.
.AP char *string in
Expression to be evaluated. Must be in writable memory (the expression
parser makes temporary modifications to the string during parsing, which
it undoes before returning).
.AP long *longPtr out
Pointer to location in which to store the integer value of the
expression.
.AP int *doublePtr out
Pointer to location in which to store the floating-point value of the
expression.
.AP int *booleanPtr out
Pointer to location in which to store the 0/1 boolean value of the
expression.
.BE
.SH DESCRIPTION
.PP
These four procedures all evaluate an expression, returning
the result in one of four different forms.
The expression is given by the \fIstring\fR argument, and it
can have any of the forms accepted by the \fBexpr\fR command.
The \fIinterp\fR argument refers to an interpreter used to
evaluate the expression (e.g. for variables and nested Tcl
commands) and to return error information. \fIInterp->result\fR
is assumed to be initialized in the standard fashion when any
of the procedures are invoked.
.PP
For all of these procedures the return value is a standard
Tcl result: \fBTCL_OK\fR means the expression was successfully
evaluated, and \fBTCL_ERROR\fR means that an error occurred while
evaluating the expression. If \fBTCL_ERROR\fR is returned then
\fIinterp->result\fR will hold a message describing the error.
If an error occurs while executing a Tcl command embedded in
the expression then that error will be returned.
.PP
If the expression is successfully evaluated, then its value is
returned in one of four forms, depending on which procedure
is invoked.
\fBTcl_ExprLong\fR stores an integer value at \fI*longPtr\fR.
If the expression's actual value is a floating-point number,
then it is truncated to an integer.
If the expression's actual value is a non-numeric string then
an error is returned.
.PP
\fBTcl_ExprDouble\fR stores a floating-point value at \fI*doublePtr\fR.
If the expression's actual value is an integer, it is converted to
floating-point.
If the expression's actual value is a non-numeric string then
an error is returned.
.PP
\fBTcl_ExprBoolean\fR stores a 0/1 integer value at \fI*booleanPtr\fR.
If the expression's actual value is an integer or floating-point
number, then \fBTcl_ExprBoolean\fR stores 0 at \fI*booleanPtr\fR if
the value was zero and 1 otherwise.
.VS
If the expression's actual value is a non-numeric string then
it must be one of the values accepted by \fBTcl_GetBoolean\fR,
such as ``yes'' or ``no'', or else an error occurs.
.VE
.PP
\fBTcl_ExprString\fR returns the value of the expression as a
string stored in \fIinterp->result\fR.
.VS
If the expression's actual value is an integer
then \fBTcl_ExprString\fR converts it to a string using \fBsprintf\fR
with a ``%d'' converter.
If the expression's actual value is a floating-point
number, then \fBTcl_ExprString\fR calls \fBTcl_PrintDouble\fR
to convert it to a string.
.VE
.SH KEYWORDS
boolean, double, evaluate, expression, integer, string

46
contrib/tcl/doc/FindExec.3 Normal file
View File

@ -0,0 +1,46 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) FindExec.3 1.3 96/03/25 20:03:17
'\"
.so man.macros
.TH Tcl_FindExecutable 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_FindExecutable \- identify the binary file containing the application
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
char *
\fBTcl_FindExecutable\fR(\fIargv0\fR)
.SH ARGUMENTS
.AS char *argv0 in
.AP char *argv0 in
The first command-line argument to the program, which gives the
application's name.
.BE
.SH DESCRIPTION
.PP
This procedure computes the full path name of the executable file
from which the application was invoked and saves it for Tcl's
internal use.
The executable's path name is needed for several purposes in
Tcl. For example, is is needed on some platforms in the
implementation of the \fBload\fR command.
It is also returned by the \fBinfo nameofexecutable\fR command.
.PP
On UNIX platforms this procedure is typically invoked as the very
first thing in the application's main program; it must be passed
\fIargv[0]\fR as its argument. \fBTcl_FindExecutable\fR uses \fIargv0\fR
along with the \fBPATH\fR environment variable to find the
application's executable, if possible. If it fails to find
the binary, then future calls to \fBinfo nameofexecutable\fR
will return an empty string.
.SH KEYWORDS
binary, executable file

130
contrib/tcl/doc/GetFile.3 Normal file
View File

@ -0,0 +1,130 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) GetFile.3 1.8 96/03/25 20:03:31
'\"
.so man.macros
.TH Tcl_GetFile 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_GetFile, Tcl_FreeFile, Tcl_GetFileInfo \- procedures to manipulate generic file handles
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_File
\fBTcl_GetFile\fR(\fIosHandle, type\fR)
.sp
\fBTcl_FreeFile\fR(\fIhandle\fR)
.sp
ClientData
\fBTcl_GetFileInfo\fR(\fIhandle, typePtr\fR)
.sp
ClientData
\fBTcl_GetNotifierData\fR(\fIhandle, freeProcPtr\fR)
.sp
\fBTcl_SetNotifierData\fR(\fIhandle, freeProc, clientData\fR)
.SH ARGUMENTS
.AS Tcl_FileFreeProc **freeProcPtr
.AP ClientData osHandle in
Platform-specific file handle to be associated with the generic file handle.
.AP int type in
The type of platform-specific file handle associated with the generic file
handle. See below for a list of valid types.
.AP Tcl_File handle in
Generic file handle associated with platform-specific file information.
.AP int *typePtr in/out
If \fI*typePtr\fR is not NULL, then the specified word is set to
contain the type associated with \fIhandle\fR.
.AP Tcl_FileFreeProc *freeProc in
Procedure to call when \fIhandle\fR is deleted.
.AP Tcl_FileFreeProc **freeProcPtr in/out
Pointer to location in which to store address of current free procedure
for file handle. Ignored if NULL.
.AP ClientData clientData in
Arbitrary one-word value associated with the given file handle. This
data is owned by the caller.
.BE
.SH DESCRIPTION
.PP
A \fBTcl_File\fR is an opaque handle used to refer to files in a
platform independent way in Tcl routines like
\fBTcl_CreateFileHandler\fR. A file handle has an associated
platform-dependent \fIosHandle\fR, a \fItype\fR and additional private
data used by the notifier to generate events for the file. The type
is an integer that determines how the platform-specific drivers will
interpret the \fIosHandle\fR. The types that are defined by the core
are:
.TP 22
\fBTCL_UNIX_FD\fR
The \fIosHandle\fR is a Unix file descriptor.
.TP 22
\fBTCL_MAC_FILE\fR
The file is a Macintosh file handle.
.TP 22
\fBTCL_WIN_FILE\fR
The \fIosHandle\fR is a Windows normal file \fBHANDLE\fR.
.TP 22
\fBTCL_WIN_PIPE\fR
The \fIosHandle\fR is a Windows anonymous pipe \fBHANDLE\fR.
.TP 22
\fBTCL_WIN_SOCKET\fR
The \fIosHandle\fR is a Windows \fBSOCKET\fR.
.TP 22
\fBTCL_WIN_CONSOLE\fR
The \fIosHandle\fR is a Windows console buffer \fBHANDLE\fR.
.PP
\fBTcl_GetFile\fR locates the file handle corresponding to a particular
\fIosHandle\fR and a \fItype\fR. If a file handle already existed for the
given file, then that handle will be returned. If this is the first time that
the file handle for a particular file is being retrieved, then a new file
handle will be allocated and returned.
.PP
When a file handle is no longer in use, it should be deallocated with
a call to \fBTcl_FreeFile\fR. A call to this function will invoke the
notifier free procedure \fIproc\fR, if there is one. After the
notifier has cleaned up, any resources used by the file handle will be
deallocated. \fBTcl_FreeFile\fR will not close the platform-specific
\fIosHandle\fR.
.PP
\fBTcl_GetFileInfo\fR may be used to retrieve the platform-specific
\fIosHandle\fR and type associated with a file handle. If
\fItypePtr\fR is not NULL, then the word at \fI*typePtr\fR is set to
the type of the file handle. The return value of the function is the
associated platform-specific \fIosHandle\fR. Note that this function
may be used to extract the platform-specific file handle from a
\fBTcl_File\fR so that it may be used in external interfaces.
However, programs written using this interface will be
platform-specific.
.PP
The \fBTcl_SetNotifierData\fR and \fBTcl_GetNotifierData\fR procedures are
intended to be used only by notifier writers. See the
\fITcl_CreateEventSource(3)\fR manual entry for more information on
the notifier.
.PP
\fBTcl_SetNotifierData\fR may be used by notifier writers to associate
notifier-specific information with a \fBTcl_File\fR. The \fIdata\fR
argument specifies a word that may be retrieved with a later call to
\fBTcl_GetNotifierData\fR. If the \fIfreeProc\fR argument is non-NULL
it specifies the address of a procedure to invoke when the
\fBTcl_File\fR is deleted. \fIfreeProc\fR should have arguments and
result that match the type \fBTcl_FileFreeProc\fR:
.CS
typedef void Tcl_FileFreeProc(
ClientData \fIclientData\fR);
.CE
When \fIfreeProc\fR is invoked the \fIclientData\fR argument will be
the same as the corresponding argument passed to
\fBTcl_SetNotifierData\fR.
.PP
\fBTcl_GetNotifierData\fR returns the \fIclientData\fR associated with
the given \fBTcl_File\fR, and if the \fIfreeProcPtr\fR field is
non-\fBNULL\fR, the address indicated by it gets the address of the
free procedure stored with this file.
.SH KEYWORDS
generic file handle, file type, file descriptor, notifier

81
contrib/tcl/doc/GetInt.3 Normal file
View File

@ -0,0 +1,81 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) GetInt.3 1.12 96/03/25 20:03:44
'\"
.so man.macros
.TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, double, or boolean
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_GetInt\fR(\fIinterp, string, intPtr\fR)
.sp
int
\fBTcl_GetDouble\fR(\fIinterp, string, doublePtr\fR)
.sp
int
\fBTcl_GetBoolean\fR(\fIinterp, string, boolPtr\fR)
.SH ARGUMENTS
.AS Tcl_Interp *doublePtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP char *string in
Textual value to be converted.
.AP int *intPtr out
Points to place to store integer value converted from \fIstring\fR.
.AP double *doublePtr out
Points to place to store double-precision floating-point
value converted from \fIstring\fR.
.AP int *boolPtr out
Points to place to store boolean value (0 or 1) converted from \fIstring\fR.
.BE
.SH DESCRIPTION
.PP
These procedures convert from strings to integers or double-precision
floating-point values or booleans (represented as 0- or 1-valued
integers). Each of the procedures takes a \fIstring\fR argument,
converts it to an internal form of a particular type, and stores
the converted value at the location indicated by the procedure's
third argument. If all goes well, each of the procedures returns
TCL_OK. If \fIstring\fR doesn't have the proper syntax for the
desired type then TCL_ERROR is returned, an error message is left
in \fIinterp->result\fR, and nothing is stored at *\fIintPtr\fR
or *\fIdoublePtr\fR or *\fIboolPtr\fR.
.PP
\fBTcl_GetInt\fR expects \fIstring\fR to consist of a collection
of integer digits, optionally signed and optionally preceded by
white space. If the first two characters of \fIstring\fR are ``0x''
then \fIstring\fR is expected to be in hexadecimal form; otherwise,
if the first character of \fIstring\fR is ``0'' then \fIstring\fR
is expected to be in octal form; otherwise, \fIstring\fR is
expected to be in decimal form.
.PP
\fBTcl_GetDouble\fR expects \fIstring\fR to consist of a floating-point
number, which is: white space; a sign; a sequence of digits; a
decimal point; a sequence of digits; the letter ``e''; and a
signed decimal exponent. Any of the fields may be omitted, except that
the digits either before or after the decimal point must be present
and if the ``e'' is present then it must be followed by the
exponent number.
.PP
\fBTcl_GetBoolean\fR expects \fIstring\fR to specify a boolean
value. If \fIstring\fR is any of \fB0\fR, \fBfalse\fR,
\fBno\fR, or \fBoff\fR, then \fBTcl_GetBoolean\fR stores a zero
value at \fI*boolPtr\fR.
If \fIstring\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
then 1 is stored at \fI*boolPtr\fR.
Any of these values may be abbreviated, and upper-case spellings
are also acceptable.
.SH KEYWORDS
boolean, conversion, double, floating-point, integer

57
contrib/tcl/doc/GetOpnFl.3 Normal file
View File

@ -0,0 +1,57 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) GetOpnFl.3 1.2 96/03/26 13:40:26
.so man.macros
.TH Tcl_GetOpenFile 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_GetOpenFile \- Get a standard IO File * handle from a channel.
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR)
.sp
.SH ARGUMENTS
.AS Tcl_Interp checkUsage
.AP Tcl_Interp *interp in
Tcl interpreter from which file handle is to be obtained.
.AP char *string in
String identifying channel, such as \fBstdin\fR or \fBfile4\fR.
.AP int write in
Non-zero means the file will be used for writing, zero means it will
be used for reading.
.AP int checkUsage in
If non-zero, then an error will be generated if the file wasn't opened
for the access indicated by \fIwrite\fR.
.AP ClientData *filePtr out
Points to word in which to store pointer to FILE structure for
the file given by \fIstring\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_GetOpenFile\fR takes as argument a file identifier of the form
returned by the \fBopen\fR command and
returns at \fI*filePtr\fR a pointer to the FILE structure for
the file.
The \fIwrite\fR argument indicates whether the FILE pointer will
be used for reading or writing.
In some cases, such as a channel that connects to a pipeline of
subprocesses, different FILE pointers will be returned for reading
and writing.
\fBTcl_GetOpenFile\fR normally returns TCL_OK.
If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't
make any sense or \fIcheckUsage\fR was set and the file wasn't opened
for the access specified by \fIwrite\fR) then TCL_ERROR is returned
and \fIinterp->result\fR will contain an error message.
In the current implementation \fIcheckUsage\fR is ignored and consistency
checks are always performed.
.SH KEYWORDS
channel, file handle, permissions, pipeline, read, write

73
contrib/tcl/doc/GetStdChan.3 Normal file
View File

@ -0,0 +1,73 @@
'\"
'\" Copyright (c) 1996 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.
'\"
'\" @(#) GetStdChan.3 1.2 96/03/08 13:59:57
'\"
.so man.macros
.TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_GetStdChannel, Tcl_SetStdChannel \- procedures for retrieving and replacing the standard channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Channel
\fBTcl_GetStdChannel\fR(\fItype\fR)
.sp
\fBTcl_SetStdChannel\fR(\fIchannel, type\fR)
.sp
.SH ARGUMENTS
.AS Tcl_Channel channel in
.AP int type in
The identifier for the standard channel to retrieve or modify. Must be one of
\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR.
.AP Tcl_Channel channel in
The channel to use as the new value for the specified standard channel.
.BE
.SH DESCRIPTION
.PP
Tcl defines three special channels that are used by various I/O related
commands if no other channels are specified. The standard input channel
has a channel name of \fBstdin\fR and is used by \fBread\fR and \fBgets\fR.
The standard output channel is named \fBstdout\fR and is used by
\fBputs\fR. The standard error channel is named \fBstderr\fR and is used for
reporting errors. In addition, the standard channels are inherited by any
child processes created using \fBexec\fR or \fBopen\fR in the absence of any
other redirections.
.PP
The standard channels are actually aliases for other normal channels. The
current channel associated with a standard channel can be retrieved by calling
\fBTcl_GetStdChannel\fR with one of
\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR as the \fItype\fR. The
return value will be a valid channel, or NULL.
.PP
A new channel can be set for the standard channel specified by \fItype\fR
by calling \fBTcl_SetStdChannel\fR with a new channel or NULL in the
\fIchannel\fR argument. If the specified channel is closed by a later call to
\fBTcl_Close\fR, then the corresponding standard channel will automatically be
set to NULL.
.PP
If \fBTcl_GetStdChannel\fR is called before \fBTcl_SetStdChannel\fR, Tcl will
construct a new channel to wrap the appropriate platform-specific standard
file handle. If \fBTcl_SetStdChannel\fR is called before
\fBTcl_GetStdChannel\fR, then the default channel will not be created.
.PP
If one of the standard channels is set to NULL, either by calling
\fBTcl_SetStdChannel\fR with a null \fIchannel\fR argument, or by calling
\fBTcl_Close\fR on the channel, then the next call to \fBTcl_CreateChannel\fR
will automatically set the standard channel with the newly created channel. If
more than one standard channel is NULL, then the standard channels will be
assigned starting with standard input, followed by standard output, with
standard error being last.
.SH "SEE ALSO"
Tcl_Close(3), Tcl_CreateChannel(3)
.SH KEYWORDS
standard channel, standard input, standard output, standard error

208
contrib/tcl/doc/Hash.3 Normal file
View File

@ -0,0 +1,208 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) Hash.3 1.15 96/03/25 20:04:01
'\"
.so man.macros
.TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_InitHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_InitHashTable\fR(\fItablePtr, keyType\fR)
.sp
\fBTcl_DeleteHashTable\fR(\fItablePtr\fR)
.sp
Tcl_HashEntry *
\fBTcl_CreateHashEntry\fR(\fItablePtr, key, newPtr\fR)
.sp
\fBTcl_DeleteHashEntry\fR(\fIentryPtr\fR)
.sp
Tcl_HashEntry *
\fBTcl_FindHashEntry\fR(\fItablePtr, key\fR)
.sp
ClientData
\fBTcl_GetHashValue\fR(\fIentryPtr\fR)
.sp
\fBTcl_SetHashValue\fR(\fIentryPtr, value\fR)
.sp
char *
\fBTcl_GetHashKey\fR(\fItablePtr, entryPtr\fR)
.sp
Tcl_HashEntry *
\fBTcl_FirstHashEntry\fR(\fItablePtr, searchPtr\fR)
.sp
Tcl_HashEntry *
\fBTcl_NextHashEntry\fR(\fIsearchPtr\fR)
.sp
char *
\fBTcl_HashStats\fR(\fItablePtr\fR)
.SH ARGUMENTS
.AS Tcl_HashSearch *searchPtr
.AP Tcl_HashTable *tablePtr in
Address of hash table structure (for all procedures but
\fBTcl_InitHashTable\fR, this must have been initialized by
previous call to \fBTcl_InitHashTable\fR).
.AP int keyType in
Kind of keys to use for new hash table. Must be either
TCL_STRING_KEYS, TCL_ONE_WORD_KEYS, or an integer value
greater than 1.
.AP char *key in
Key to use for probe into table. Exact form depends on
\fIkeyType\fR used to create table.
.AP int *newPtr out
The word at \fI*newPtr\fR is set to 1 if a new entry was created
and 0 if there was already an entry for \fIkey\fR.
.AP Tcl_HashEntry *entryPtr in
Pointer to hash table entry.
.AP ClientData value in
New value to assign to hash table entry. Need not have type
ClientData, but must fit in same space as ClientData.
.AP Tcl_HashSearch *searchPtr in
Pointer to record to use to keep track of progress in enumerating
all the entries in a hash table.
.BE
.SH DESCRIPTION
.PP
A hash table consists of zero or more entries, each consisting of
a key and a value.
Given the key for an entry, the hashing routines can very quickly
locate the entry, and hence its value.
There may be at most one entry in a hash table with a
particular key, but many entries may have the same value.
Keys can take one of three forms: strings,
one-word values, or integer arrays.
All of the keys in a given table have the same form, which is
specified when the table is initialized.
.PP
The value of a hash table entry can be anything that fits in
the same space as a ``char *'' pointer.
Values for hash table entries are managed entirely by clients,
not by the hash module itself.
Typically each entry's value is a pointer to a data structure
managed by client code.
.PP
Hash tables grow gracefully as the number of entries increases,
so that there are always less than three entries per hash bucket,
on average.
This allows for fast lookups regardless of the number of entries
in a table.
.PP
\fBTcl_InitHashTable\fR initializes a structure that describes
a new hash table.
The space for the structure is provided by the caller, not by
the hash module.
The value of \fIkeyType\fR indicates what kinds of keys will
be used for all entries in the table. \fIKeyType\fR must have
one of the following values:
.IP \fBTCL_STRING_KEYS\fR 25
Keys are null-terminated ASCII strings.
They are passed to hashing routines using the address of the
first character of the string.
.IP \fBTCL_ONE_WORD_KEYS\fR 25
Keys are single-word values; they are passed to hashing routines
and stored in hash table entries as ``char *'' values.
The pointer value is the key; it need not (and usually doesn't)
actually point to a string.
.IP \fIother\fR 25
If \fIkeyType\fR is not TCL_STRING_KEYS or TCL_ONE_WORD_KEYS,
then it must be an integer value greater than 1.
In this case the keys will be arrays of ``int'' values, where
\fIkeyType\fR gives the number of ints in each key.
This allows structures to be used as keys.
All keys must have the same size.
Array keys are passed into hashing functions using the address
of the first int in the array.
.PP
\fBTcl_DeleteHashTable\fR deletes all of the entries in a hash
table and frees up the memory associated with the table's
bucket array and entries.
It does not free the actual table structure (pointed to
by \fItablePtr\fR), since that memory is assumed to be managed
by the client.
\fBTcl_DeleteHashTable\fR also does not free or otherwise
manipulate the values of the hash table entries.
If the entry values point to dynamically-allocated memory, then
it is the client's responsibility to free these structures
before deleting the table.
.PP
\fBTcl_CreateHashEntry\fR locates the entry corresponding to a
particular key, creating a new entry in the table if there
wasn't already one with the given key.
If an entry already existed with the given key then \fI*newPtr\fR
is set to zero.
If a new entry was created, then \fI*newPtr\fR is set to a non-zero
value and the value of the new entry will be set to zero.
The return value from \fBTcl_CreateHashEntry\fR is a pointer to
the entry, which may be used to retrieve and modify the entry's
value or to delete the entry from the table.
.PP
\fBTcl_DeleteHashEntry\fR will remove an existing entry from a
table.
The memory associated with the entry itself will be freed, but
the client is responsible for any cleanup associated with the
entry's value, such as freeing a structure that it points to.
.PP
\fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR
except that it doesn't create a new entry if the key doesn't exist;
instead, it returns NULL as result.
.PP
\fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to
read and write an entry's value, respectively.
Values are stored and retrieved as type ``ClientData'', which is
large enough to hold a pointer value. On almost all machines this is
large enough to hold an integer value too.
.PP
\fBTcl_GetHashKey\fR returns the key for a given hash table entry,
either as a pointer to a string, a one-word (``char *'') key, or
as a pointer to the first word of an array of integers, depending
on the \fIkeyType\fR used to create a hash table.
In all cases \fBTcl_GetHashKey\fR returns a result with type
``char *''.
When the key is a string or array, the result of \fBTcl_GetHashKey\fR
points to information in the table entry; this information will
remain valid until the entry is deleted or its table is deleted.
.PP
\fBTcl_FirstHashEntry\fR and \fBTcl_NextHashEntry\fR may be used
to scan all of the entries in a hash table.
A structure of type ``Tcl_HashSearch'', provided by the client,
is used to keep track of progress through the table.
\fBTcl_FirstHashEntry\fR initializes the search record and
returns the first entry in the table (or NULL if the table is
empty).
Each subsequent call to \fBTcl_NextHashEntry\fR returns the
next entry in the table or
NULL if the end of the table has been reached.
A call to \fBTcl_FirstHashEntry\fR followed by calls to
\fBTcl_NextHashEntry\fR will return each of the entries in
the table exactly once, in an arbitrary order.
It is unadvisable to modify the structure of the table, e.g.
by creating or deleting entries, while the search is in
progress.
.PP
\fBTcl_HashStats\fR returns a dynamically-allocated string with
overall information about a hash table, such as the number of
entries it contains, the number of buckets in its hash array,
and the utilization of the buckets.
It is the caller's responsibility to free the result string
by passing it to \fBfree\fR.
.PP
The header file \fBtcl.h\fR defines the actual data structures
used to implement hash tables.
This is necessary so that clients can allocate Tcl_HashTable
structures and so that macros can be used to read and write
the values of entries.
However, users of the hashing routines should never refer directly
to any of the fields of any of the hash-related data structures;
use the procedures and macros defined here.
.SH KEYWORDS
hash table, key, lookup, search, value

119
contrib/tcl/doc/Interp.3 Normal file
View File

@ -0,0 +1,119 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) Interp.3 1.14 96/03/25 20:04:19
'\"
.so man.macros
.TH Tcl_Interp 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Interp \- client-visible fields of interpreter structures
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
typedef struct {
char *\fIresult\fR;
Tcl_FreeProc *\fIfreeProc\fR;
int \fIerrorLine\fR;
} Tcl_Interp;
typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
.BE
.SH DESCRIPTION
.PP
The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
structure. This pointer is then passed into other Tcl procedures
to process commands in the interpreter and perform other operations
on the interpreter. Interpreter structures contain many many fields
that are used by Tcl, but only three that may be accessed by
clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
.PP
The \fIresult\fR and \fIfreeProc\fR fields are used to return
results or error messages from commands.
This information is returned by command procedures back to \fBTcl_Eval\fR,
and by \fBTcl_Eval\fR back to its callers.
The \fIresult\fR field points to the string that represents the
result or error message, and the \fIfreeProc\fR field tells how
to dispose of the storage for the string when it isn't needed anymore.
The easiest way for command procedures to manipulate these
fields is to call procedures like \fBTcl_SetResult\fR
or \fBTcl_AppendResult\fR; they
will hide all the details of managing the fields.
The description below is for those procedures that manipulate the
fields directly.
.PP
Whenever a command procedure returns, it must ensure
that the \fIresult\fR field of its interpreter points to the string
being returned by the command.
The \fIresult\fR field must always point to a valid string.
If a command wishes to return no result then \fIinterp->result\fR
should point to an empty string.
Normally, results are assumed to be statically allocated,
which means that the contents will not change before the next time
\fBTcl_Eval\fR is called or some other command procedure is invoked.
In this case, the \fIfreeProc\fR field must be zero.
Alternatively, a command procedure may dynamically
allocate its return value (e.g. using \fBmalloc\fR)
and store a pointer to it in \fIinterp->result\fR.
In this case, the command procedure must also set \fIinterp->freeProc\fR
to the address of a procedure that can free the value (usually \fBfree\fR).
If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
to free the space pointed to by \fIinterp->result\fR before it
invokes the next command.
If a client procedure overwrites \fIinterp->result\fR when
\fIinterp->freeProc\fR is non-zero, then it is responsible for calling
\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR
macro should be used for this purpose).
.PP
\fIFreeProc\fR should have arguments and result that match the
\fBTcl_FreeProc\fR declaration above: it receives a single
argument which is a pointer to the result value to free.
In most applications \fBfree\fR is the only non-zero value ever
used for \fIfreeProc\fR.
However, an application may store a different procedure address
in \fIfreeProc\fR in order to use an alternate memory allocator
or in order to do other cleanup when the result memory is freed.
.PP
As part of processing each command, \fBTcl_Eval\fR initializes
\fIinterp->result\fR
and \fIinterp->freeProc\fR just before calling the command procedure for
the command. The \fIfreeProc\fR field will be initialized to zero,
and \fIinterp->result\fR will point to an empty string. Commands that
do not return any value can simply leave the fields alone.
Furthermore, the empty string pointed to by \fIresult\fR is actually
part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
If a command wishes to return a short string, it can simply copy
it to the area pointed to by \fIinterp->result\fR. Or, it can use
the sprintf procedure to generate a short result string at the location
pointed to by \fIinterp->result\fR.
.PP
It is a general convention in Tcl-based applications that the result
of an interpreter is normally in the initialized state described
in the previous paragraph.
Procedures that manipulate an interpreter's result (e.g. by
returning an error) will generally assume that the result
has been initialized when the procedure is called.
If such a procedure is to be called after the result has been
changed, then \fBTcl_ResetResult\fR should be called first to
reset the result to its initialized state.
.PP
The \fIerrorLine\fR
field is valid only after \fBTcl_Eval\fR returns
a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR
field identifies the line number of the command being executed when
the error occurred. The line numbers are relative to the command
being executed: 1 means the first line of the command passed to
\fBTcl_Eval\fR, 2 means the second line, and so on.
The \fIerrorLine\fR field is typically used in conjunction with
\fBTcl_AddErrorInfo\fR to report information about where an error
occurred.
\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR.
.SH KEYWORDS
free, initialized, interpreter, malloc, result

116
contrib/tcl/doc/LinkVar.3 Normal file
View File

@ -0,0 +1,116 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) LinkVar.3 1.12 96/03/25 20:04:31
'\"
.so man.macros
.TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
.sp
\fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
.sp
.VS
\fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
.VE
.SH ARGUMENTS
.AS Tcl_Interp writable
.AP Tcl_Interp *interp in
Interpreter that contains \fIvarName\fR.
Also used by \fBTcl_LinkVar\fR to return error messages.
.AP char *varName in
Name of global variable.
.AP char *addr in
Address of C variable that is to be linked to \fIvarName\fR.
.AP int type in
Type of C variable. Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE,
TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with
TCL_LINK_READ_ONLY to make Tcl variable read-only.
.BE
.SH DESCRIPTION
.PP
\fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable
named by \fIvarName\fR in sync with the C variable at the address
given by \fIaddr\fR.
Whenever the Tcl variable is read the value of the C variable will
be returned, and whenever the Tcl variable is written the C
variable will be updated to have the same value.
\fBTcl_LinkVar\fR normally returns TCL_OK; if an error occurs
while setting up the link (e.g. because \fIvarName\fR is the
name of array) then TCL_ERROR is returned and \fIinterp->result\fR
contains an error message.
.PP
The \fItype\fR argument specifies the type of the C variable,
and must have one of the following values, optionally OR'ed with
TCL_LINK_READ_ONLY:
.TP
\fBTCL_LINK_INT\fR
The C variable is of type \fBint\fR.
Any value written into the Tcl variable must have a proper integer
form acceptable to \fBTcl_GetInt\fR; attempts to write
non-integer values into \fIvarName\fR will be rejected with
Tcl errors.
.TP
\fBTCL_LINK_DOUBLE\fR
The C variable is of type \fBdouble\fR.
Any value written into the Tcl variable must have a proper real
form acceptable to \fBTcl_GetDouble\fR; attempts to write
non-real values into \fIvarName\fR will be rejected with
Tcl errors.
.TP
\fBTCL_LINK_BOOLEAN\fR
The C variable is of type \fBint\fR.
If its value is zero then it will read from Tcl as ``0'';
otherwise it will read from Tcl as ``1''.
Whenever \fIvarName\fR is
modified, the C variable will be set to a 0 or 1 value.
Any value written into the Tcl variable must have a proper boolean
form acceptable to \fBTcl_GetBoolean\fR; attempts to write
non-boolean values into \fIvarName\fR will be rejected with
Tcl errors.
.TP
\fBTCL_LINK_STRING\fR
The C variable is of type \fBchar *\fR.
If its value is not null then it must be a pointer to a string
allocated with \fBmalloc\fR.
Whenever the Tcl variable is modified the current C string will be
freed and new memory will be allocated to hold a copy of the variable's
new value.
If the C variable contains a null pointer then the Tcl variable
will read as ``NULL''.
.PP
If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the
variable will be read-only from Tcl, so that its value can only be
changed by modifying the C variable.
Attempts to write the variable from Tcl will be rejected with errors.
.PP
\fBTcl_UnlinkVar\fR removes the link previously set up for the
variable given by \fIvarName\fR. If there does not exist a link
for \fIvarName\fR then the procedure has no effect.
.PP
.VS
\fBTcl_UpdateLinkedVar\fR may be invoked after the C variable has
changed to force the Tcl variable to be updated immediately.
In many cases this procedure is not needed, since any attempt to
read the Tcl variable will return the latest value of the C variable.
However, if a trace has been set on the Tcl variable (such as a
Tk widget that wishes to display the value of the variable), the
trace will not trigger when the C variable has changed.
\fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl
variable are invoked.
.VE
.SH KEYWORDS
boolean, integer, link, read-only, real, string, traces, variable

366
contrib/tcl/doc/Notifier.3 Normal file
View File

@ -0,0 +1,366 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) Notifier.3 1.10 96/03/28 09:38:26
'\"
.so man.macros
.TH Tcl_CreateEventSource 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_WatchFile, Tcl_FileReady, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_WaitForEvent \- Event sources, the event notifier, and the event queue
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_CreateEventSource(\fIsetupProc, checkProc, clientData\fB)\fR
.sp
\fBTcl_DeleteEventSource(\fIsetupProc, checkProc, clientData\fB)\fR
.sp
\fBTcl_WatchFile(\fIfile, mask\fB)\fR
.sp
\fBTcl_SetMaxBlockTime(\fItimePtr\fB)\fR
.sp
int
\fBTcl_FileReady(\fIfile, mask\fB)\fR
.sp
\fBTcl_QueueEvent(\fIevPtr, position\fB)\fR
.sp
int
\fBTcl_WaitForEvent(\fItimePtr\fB)\fR
.SH ARGUMENTS
.AS Tcl_EventSetupProc *setupProc
.AP Tcl_EventSetupProc *setupProc in
Procedure to invoke to prepare for event wait in \fBTcl_DoWhenIdle\fR.
.AP Tcl_EventCheckProc *checkProc in
Procedure for \fBTcl_DoWhenIdle\fR to invoke after waiting for
events. Checks to see if any events have occurred and, if so,
queues them.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIsetupProc\fR and \fIcheckProc\fR.
.AP Tcl_File file in
Generic file handle as returned by \fBTcl_GetFile\fR.
.AP int mask in
Indicates the events of interest on \fIfile\fR: an OR'ed combination
of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR, and \fBTCL_EXCEPTION\fR.
.AP Tcl_Time *timePtr in
Indicates the maximum amount of time to wait for an event. This
is specified as an interval (how long to wait), not an absolute
time (when to wakeup). If the pointer passed to \fBTcl_WaitForEvent\fR
is NULL, it means there is no maximum wait time: wait forever if
necessary.
.AP Tcl_Event *evPtr in
An event to add to the event queue. The storage for the event must
have been allocated by the caller using \fBmalloc\fR or \fBckalloc\fR.
.AP Tcl_QueuePosition position in
Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR,
\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
.AP int flags in
A copy of the \fIflags\fR argument passed to \fBTcl_DoOneEvent\fR.
.BE
.SH INTRODUCTION
.PP
The procedures described here are the building blocks out of which
the Tcl event notifier is constructed. The event notifier is the
lowest layer in the Tcl event mechanism. It consists of three
things:
.IP [1]
Event sources: these represent the ways in which events can be
generated. For example, there is a timer event source that implements
the \fBTcl_CreateTimerHandler\fR procedure and the \fBafter\fR command,
and there is a file event source that implements the
\fBTcl_CreateFileHandler\fR procedure. An event source must work
with the notifier to detect events at the right times, record them
on the event queue, and eventually notify higher-level software that
they have occurred.
.IP [2]
The event queue: there is a single queue for the whole application,
containing events that have been detected but not yet serviced.
The event queue guarantees a fair discipline of event handling, so
that no event source can starve the others. It also allows events
to be saved for servicing at a future time.
.IP [3]
The procedure \fBTcl_DoOneEvent\fR: this is procedure that is invoked
by the application to service events. It works with the event sources
and the event queue to detect and handle events, and calls
\fBTcl_WaitForEvent\fR to actually wait for an event to occur.
.PP
The easiest way to understand how the notifier works is to consider
what happens when \fBTcl_DoOneEvent\fR is called.
\fBTcl_DoOneEvent\fR is passed a \fIflags\fR
argument that indicates what sort of events it is OK to process and
also whether or not to block if no events are ready.
\fBTcl_DoOneEvent\fR does the following things:
.IP [1]
Check the event queue to see if it contains any events that can
be serviced. If so, service the first possible event, remove it
from the queue, and return.
.IP [2]
Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR
invokes a \fIsetup procedure\fR in each event source.
The event source will call procedures like \fBTcl_WatchFile\fR and
\fBTcl_SetMaxBlockTime\fR to indicate what low-level events to look
for in \fBTcl_WaitForEvent\fR.
.IP [3]
Call \fBTcl_WaitForEvent\fR. This procedure is implemented differently
on different platforms; it waits for an event to occur, based on the
information provided by the event sources.
It may cause the application to block if \fItimePtr\fR specifies
an interval other than 0.
\fBTcl_WaitForEvent\fR returns when something has happened,
such as a file becoming readable or the interval given by \fItimePtr\fR
expiring. If there are no events for \fBTcl_WaitForEvent\fR to
wait for, so that it would block forever, then it returns immediately
and \fBTcl_DoOneEvent\fR returns 0.
.IP [4]
Call a \fIcheck procedure\fR in each event source. The check
procedure determines whether any events of interest to this source
occurred (e.g. by calling \fBTcl_FileReady\fR). If so,
the events are added to the event queue.
.IP [5]
Check the event queue to see if it contains any events that can
be serviced. If so, service the first possible event, remove it
from the queue, and return.
.IP [6]
See if there are idle callbacks pending.
If so, invoke all of them and return.
.IP [7]
Either return 0 to indicate that no events were ready, or go back to
step [2] if blocking was requested by the caller.
.PP
The procedures in this file allow you to do two things. First, they
allow you to create new event sources, such as one for UNIX signals
or one to notify when subprocesses have exited. Second, the procedures
can be used to build a new version of \fBTcl_DoOneEvent\fR. This
might be necessary to support a new operating system with different
low-level event reporting mechanisms, or it might be necessary to
merge Tcl's event loop with that of some other toolkit like Xt.
.SH "CREATING A NEW EVENT SOURCE"
.PP
An event source consists of three procedures invoked by the notifier,
plus additional C procedures that are invoked by higher-level code
to arrange for event-driven callbacks. The three procedures called
by the notifier consist of the setup and check procedures described
above, plus an additional procedure that is invoked when an event
is removed from the event queue for servicing.
.PP
The procedure \fBTcl_CreateEventSource\fR creates a new event source.
Its arguments specify the setup procedure and check procedure for
the event source.
\fISetupProc\fR should match the following prototype:
.CS
typedef void Tcl_EventSetupProc(
ClientData \fIclientData\fR,
int \fIflags\fR);
.CE
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_CreateEventSource\fR; it is typically used to
point to private information managed by the event source.
The \fIflags\fR argument will be the same as the \fIflags\fR
argument passed to \fBTcl_DoOneEvent\fR except that it will never
by 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
\fIFlags\fR indicates what kinds of events should be considered;
if the bit corresponding to this event source isn't set, the event
source should return immediately without doing anything. For
example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
bit.
.PP
\fISetupProc\fR's job is to provide information to
\fBTcl_WaitForEvent\fR about how to wait for events.
It usually does this by calling \fBTcl_WatchFile\fR or
\fBTcl_SetMaxBlockTime\fR.
For example, \fIsetupProc\fR can call \fBTcl_WatchFile\fR to indicate
that \fBTcl_WaitForEvent\fR should return when the conditions
given by the \fImask\fR argument become true for the file given
by \fIfile\fR.
The UNIX version of \fBTcl_WaitForEvent\fR uses the
information passed to \fBTcl_WatchFile\fR to set the file masks
for \fBselect\fR, which it uses to wait for events.
If \fBTcl_WatchFile\fR isn't called by any event sources then
\fBTcl_WaitForEvent\fR will ignore files while waiting.
.PP
\fISetupProc\fR can also invoke \fBTcl_SetMaxBlockTime\fR to set an
upper bound on how long \fBTcl_WaitForEvent\fR will block.
If no event source calls \fBTcl_SetMaxBlockTime\fR then
\fBTcl_WaitForEvent\fR will wait as long as necessary for an event
to occur; otherwise, it will only wait as long as the shortest
interval passed to \fBTcl_SetMaxBlockTime\fR by one of the event
sources.
For example, the timer event source uses this procedure to limit the
wait time to the interval before the next timer event is ready.
If an event source knows that it already has events ready to report,
it can request a zero maximum block time.
The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
a structure that describes a time interval in seconds and
microseconds:
.CS
typedef struct Tcl_Time {
long \fIsec\fR;
long \fIusec\fR;
} Tcl_Time;
.CE
The \fIusec\fR field should be less than 1000000.
.PP
Information provided to \fBTcl_WatchFile\fR and \fBTcl_SetMaxBlockTime\fR
is only used for the next call to \fBTcl_WaitForEvent\fR; it is
discarded after \fBTcl_WaitForEvent\fR returns.
The next time an event wait is done each of the event sources'
setup procedures will be called again, and they can specify new
information for that event wait.
.PP
In addition to the generic procedures \fBTcl_WatchFile\fR and
\fBTcl_SetMaxBlockTime\fR, other platform-specific procedures may
also be available for \fIsetupProc\fR, if there is additional
information needed by \fBTcl_WaitForEvent\fR on that platform.
.PP
The second procedure provided by each event source is its check
procedure, indicated by the \fIcheckProc\fR argument to
\fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the
following prototype:
.CS
typedef void Tcl_EventCheckProc(
ClientData \fIclientData\fR,
int \fIflags\fR);
.CE
The arguments to this procedure are the same as those for \fIsetupProc\fR.
\fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
for events. Presumably at least one event source is now prepared to
queue an event. \fBTcl_DoOneEvent\fR calls each of the event sources
in turn, so they all have a chance to queue any events that are ready.
The check procedure does two things. First, it must see if any events
have triggered. Different event sources do this in different ways,
but the procedure \fBTcl_FileReady\fR may be useful for some event
sources. It takes as arguments a file identifier \fIfile\fR and
a mask of interesting conditions; it returns another mask indicating
which of those conditions were found to be present on the file during
the most recent call to \fBTcl_WaitForEvent\fR.
\fBTcl_WaitForEvent\fR only checks a file if \fBTcl_WatchFile\fR was
called by at least one event source, so it is possible for
\fBTcl_FileReady\fR to return 0 even if the file is ready.
.PP
If an event source's check procedure detects that an interesting
event has occurred, then it must add the event to Tcl's event queue.
To do this, the event source calls \fBTcl_QueueEvent\fR.
The \fIevPtr\fR argument is a pointer to a dynamically allocated
structure containing the event (see below for more information
on memory management issues).
Each event source can define its own event structure with
whatever information is relevant to that event source.
However, the first element of the structure must be a structure
of type \fBTcl_Event\fR, and the address of this structure is used when
communicating between the event source and the rest of the notifier.
A \fBTcl_Event\fR has the following definition:
.CS
typedef struct Tcl_Event {
Tcl_EventProc *\fIproc\fR;
struct Tcl_Event *\fInextPtr\fR;
};
.CE
The event source must fill in the \fIproc\fR field of
the event before calling \fBTcl_QueueEvent\fR.
The \fInextPtr\fR is used to link together the events in the queue
and should not be modified by the event source.
.PP
An event may be added to the queue at any of three positions, depending
on the \fIposition\fR argument to \fBTcl_QueueEvent\fR:
.IP \fBTCL_QUEUE_TAIL\fR 24
Add the event at the back of the queue, so that all other pending
events will be serviced first. This is almost always the right
place for new events.
.IP \fBTCL_QUEUE_HEAD\fR 24
Add the event at the front of the queue, so that it will be serviced
before all other queued events.
.IP \fBTCL_QUEUE_MARK\fR 24
Add the event at the front of the queue, unless there are other
events at the front whose position is \fBTCL_QUEUE_MARK\fR; if so,
add the new event just after all other \fBTCL_QUEUE_MARK\fR events.
This value of \fIposition\fR is used to insert an ordered sequence of
events at the front of the queue, such as a series of
Enter and Leave events synthesized during a grab or ungrab operation
in Tk.
.PP
When it is time to handle an event from the queue (steps 1 and 5
above) \fBTcl_DoOneEvent\fR will invoke the \fIproc\fR specified
in the first queued \fBTcl_Event\fR structure.
\fIProc\fR must match the following prototype:
.CS
typedef int Tcl_EventProc(
Tcl_Event *\fIevPtr\fR,
int \fIflags\fR);
.CE
The first argument to \fIproc\fR is a pointer to the event, which will
be the same as the first argument to the \fBTcl_QueueEvent\fR call that
added the event to the queue.
The second argument to \fIproc\fR is the \fIflags\fR argument for the
current call to \fBTcl_DoOneEvent\fR; this is used by the event source
to return immediately if its events are not relevant.
.PP
It is up to \fIproc\fR to handle the event, typically by invoking
one or more Tcl commands or C-level callbacks.
Once the event source has finished handling the event it returns 1
to indicate that the event can be removed from the queue.
If for some reason the event source decides that the event cannot
be handled at this time, it may return 0 to indicate that the event
should be deferred for processing later; in this case \fBTcl_DoOneEvent\fR
will go on to the next event in the queue and attempt to service it.
There are several reasons why an event source might defer an event.
One possibility is that events of this type are excluded by the
\fIflags\fR argument.
For example, the file event source will always return 0 if the
\fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR.
Another example of deferring events happens in Tk if
\fBTk_RestrictEvents\fR has been invoked to defer certain kinds
of window events.
.PP
When \fIproc\fR returns 1, \fBTcl_DoOneEvent\fR will remove the
event from the event queue and free its storage.
Note that the storage for an event must be allocated by
the event source (using \fBmalloc\fR or the Tcl macro \fBckalloc\fR)
before calling \fBTcl_QueueEvent\fR, but it
will be freed by \fBTcl_DoOneEvent\fR, not by the event source.
.SH "CREATING A NEW NOTIFIER"
.PP
The notifier consists of all the procedures described in this
manual entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR.
Most of these procedures are generic, in that they are the
same for all platforms. However, four of the procedures are
platform-dependent: \fBTcl_WatchFile\fR,
\fBTcl_FileReady\fR, \fBTcl_WaitForEvent\fR, and \fBTcl_Sleep\fR.
To support a new platform, you must write new versions of these
procedures.
\fBTcl_WatchFile\fR and \fBTcl_FileReady\fR have already been
described previously in this document, and \fBTcl_Sleep\fR
is described in its own manual entry.
.PP
\fBTcl_WaitForEvent\fR is the lowest-level procedure in the
notifier; it is responsible for waiting for an ``interesting''
event to occur or for a given time to elapse.
Before \fBTcl_WaitForEvent\fR is invoked, each of the event
sources' setup procedure will have been invoked; the setup
procedures will have provided information about what to wait
for by invoking procedures like \fBTcl_WatchFile\fR.
The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR gives
the maximum time to block for an event, based on calls to
\fBTcl_SetMaxBlockTime\fR made by setup procedures and
on other information (such as the \fBTCL_DONT_WAIT\fR bit in \fIflags\fR).
\fBTcl_WaitForEvent\fR uses information saved by \fBTcl_WatchFile\fR,
plus the \fItimePtr\fR argument to decide what to wait for
and how long to block.
It returns TCL_OK as soon as one of the specified events has occurred
or the given amount of time has elapsed.
However, if there are no event handlers (neither \fBTcl_WatchFile\fR nor
\fBTcl_SetMaxBlockTime\fR has been called since the last call to
\fBTcl_WaitForEvent\fR), so that the procedure would block forever,
then it returns immediately with a result of TCL_ERROR.
.PP
The easiest way to create a new notifier is to look at the code
for an existing notifier, such as the files \fBgeneric/tclNotify.c\fR
and \fBunix/tclUnixNotfy.c\fR.
.SH KEYWORDS
block time, event notifier, event queue, event sources, file events

441
contrib/tcl/doc/OpenFileChnl.3 Normal file
View File

@ -0,0 +1,441 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) OpenFileChnl.3 1.27 96/03/22 14:55:07
.so man.macros
.TH Tcl_OpenFileChannel 3 7.5 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_GetChannelOption, Tcl_SetChannelOption \- buffered I/O facilities using channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
typedef ... Tcl_Channel;
.sp
Tcl_Channel
\fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR)
.sp
Tcl_Channel
\fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR)
.sp
Tcl_Channel
\fBTcl_MakeFileChannel\fR(\fIinOsFile, outOsFile, readOrWrite\fR)
.sp
Tcl_Channel
\fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
.sp
void
\fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
.sp
int
\fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR)
.sp
int
\fBTcl_Close\fR(\fIinterp, channel\fR)
.sp
int
\fBTcl_Read\fR(\fIchannel, buf, toRead\fR)
.sp
int
\fBTcl_Gets\fR(\fIchannel, lineRead\fR)
.sp
int
\fBTcl_Write\fR(\fIchannel, buf, toWrite\fR)
.sp
int
\fBTcl_Flush\fR(\fIchannel\fR)
.sp
int
\fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
.sp
int
\fBTcl_Tell\fR(\fIchannel\fR)
.sp
int
\fBTcl_GetChannelOption\fR(\fIchannel, optionName, optionValue\fR)
.sp
int
\fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR)
.sp
int
\fBTcl_Eof\fR(\fIchannel\fR)
.sp
int
\fBTcl_InputBlocked\fR(\fIchannel\fR)
.sp
int
\fBTcl_InputBuffered\fR(\fIchannel\fR)
.sp
.SH ARGUMENTS
.AS Tcl_ChannelType newClientProcPtr in
.AP Tcl_Interp *interp in
Used for error reporting and to look up a channel registered in it.
.AP char *fileName in
The name of a local or network file.
.AP char *mode in
Specifies how the file is to be accessed. May have any of the
values allowed for the \fImode\fR argument to the Tcl
\fBopen\fR command.
For \fBTcl_OpenCommandChannel\fR, may be NULL.
.AP int permissions in
POSIX-style permission flags such as 0644.
If a new file is created, these permissions will be set on the
created file.
.AP int argc in
The number of elements in \fIargv\fR.
.AP char **argv in
Arguments for constructing a command pipeline.
These values have the same meaning as the non-switch arguments
to the Tcl \fBexec\fR command.
.AP int flags in
Specifies the disposition of the stdio handles in pipeline: OR-ed
combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR,
and \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for
the first child in the pipe is the pipe channel, otherwise it is the same
as the standard input of the invoking process; likewise for
\fBTCL_STDOUT\fR and \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set,
then the pipe can redirect stdio handles to override the stdio handles for
which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.
If it is set, then such redirections cause an error.
.AP ClientData inOsFile in
Operating system specific handle for input from a file. For Unix this is a
file descriptor, for Windows it is a HANDLE, etc.
.AP ClientData outOsFile in
Operating system specific handle for output to a file.
.AP int readOrWrite in
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
which of \fIinOsFile\fR and \fIoutOsFile\fR contains a valid value.
.AP int *modePtr out
Points at an integer variable that will receive an OR-ed combination of
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
open for reading and writing.
.AP Tcl_Channel channel in
A Tcl channel for input or output. Must have been the return value
from a procedure such as \fBTcl_OpenFileChannel\fR.
.AP char *buf in
An array of bytes in which to store channel input, or from which
to read channel output.
.AP int toRead in
The number of bytes to read from the channel.
.AP Tcl_DString *lineRead in
A pointer to a Tcl dynamic string in which to store the line read from the
channel. Must have been initialized by the caller.
.AP int toWrite in
The number of bytes to read from \fIbuf\fR and output to the channel.
.AP int offset in
How far to move the access point in the channel at which the next input or
output operation will be applied, measured in bytes from the position
given by \fIseekMode\fR. May be either positive or negative.
.AP int seekMode in
Relative to which point to seek; used with \fIoffset\fR to calculate the new
access point for the channel. Legal values are \fBSEEK_SET\fR,
\fBSEEK_CUR\fR, and \fBSEEK_END\fR.
.AP char *optionName in
The name of an option applicable to this channel, such as \fB\-blocking\fR.
May have any of the values accepted by the \fBfconfigure\fR command.
.AP Tcl_DString *optionValue in
Where to store the value of an option or a list of all options and their
values. Must have been initialized by the caller.
.AP char *newValue in
New value for the option given by \fIoptionName\fR.
.BE
.SH DESCRIPTION
.PP
The Tcl channel mechanism provides a device-independent and
platform-independent mechanism for performing buffered input
and output operations on a variety of file, socket, and device
types.
The channel mechanism is extensible to new channel types, by
providing a low level channel driver for the new type; the channel driver
interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
channel mechanism provides a buffering scheme modelled after
Unix's standard I/O, and it also allows for nonblocking I/O on
channels.
.PP
The procedures described in this manual entry comprise the C APIs of the
generic layer of the channel architecture. For a description of the channel
driver architecture and how to implement channel drivers for new types of
channels, see the manual entry for \fBTcl_CreateChannel\fR.
.SH TCL_OPENFILECHANNEL
.PP
\fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and
returns a channel handle that can be used to perform input and output on
the file. This API is modelled after the \fBfopen\fR procedure of
the Unix standard I/O library.
The syntax and meaning of all arguments is similar to those
given in the Tcl \fBopen\fR command when opening a file.
If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
returns NULL and records a POSIX error code that can be
retrieved with \fBTcl_GetErrno\fR.
In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
leaves an error message in \fIinterp->result\fR after any error.
.SH TCL_OPENCOMMANDCHANNEL
.PP
\fBTcl_OpenCommandChannel\fR provides a C-level interface to the
functions of the \fBexec\fR and \fBopen\fR commands.
It creates a sequence of subprocesses specified
by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can
be used to communicate with these subprocesses.
The \fIflags\fR argument indicates what sort of communication will
exist with the command pipeline.
.PP
If the \fBTCL_STDIN\fR flag is set then the standard input for the
first subprocess will be tied to the channel: writing to the channel
will provide input to the subprocess. If \fBTCL_STDIN\fR is not set,
then standard input for the first subprocess will be the same as this
application's standard input. If \fBTCL_STDOUT\fR is set then
standard output from the last subprocess can be read from the channel;
otherwise it goes to this application's standard output. If
\fBTCL_STDERR\fR is set, standard error output for all subprocesses is
returned to the channel and results in an error when the channel is
closed; otherwise it goes to this application's standard error. If
\fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can
redirect the stdio handles to override \fBTCL_STDIN\fR,
\fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an
error for argc and argv to override stdio channels for which
\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set.
.PP
If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR
returns NULL and records a POSIX error code that can be retrieved with
\fBTcl_GetErrno\fR.
In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in
\fIinterp->result\fR if \fIinterp\fR is not NULL.
.SH TCL_MAKEFILECHANNEL
.PP
\fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
platform-specific, file handle.
.SH TCL_GETCHANNEL
.PP
\fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in
\fIinterp\fR. If a channel by that name is not registered in that interpreter,
the procedure returns NULL. If the \fImode\fR argument is not NULL, it
points at an integer variable that will receive an OR-ed combination of
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
open for reading and writing.
.SH TCL_REGISTERCHANNEL
.PP
\fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible
in \fIinterp\fR. After this call, Tcl programs executing in that
interpreter can refer to the channel in input or output operations using the
name given in the call to \fBTcl_CreateChannel\fR.
After this call the channel becomes the property of the interpreter.
The caller should not call \fBTcl_Close\fR for the channel; the
channel will be closed automatically when it is unregistered from
the interpreter.
Furthermore, it is not generally safe to reference the channel
anymore, since it could be deleted at any time by a \fBclose\fR
command in the interpreter.
.SH TCL_UNREGISTERCHANNEL
.PP
\fBTcl_UnregisterChannel\fR removes a channel from the set of channels
accessible in \fIinterp\fR. After this call, Tcl programs will no longer
be able to use the channel's name to refer to the channel in that
interpreter. If this operation removed the last registration of the channel
in any interpreter, the channel is also closed and destroyed.
.SH TCL_CLOSE
.PP
\fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
currently open channel.
The channel should not be registered in any interpreter when
\fBTcl_Close\fR is called; see the manual entry for \fBTcl_CreateChannel\fR
for a description of \fBTcl_RegisterChannel\fR and \fBTcl_UnregisterChannel\fR.
Buffered output is flushed to the channel's output device prior to
destroying the channel, and any buffered input is discarded.
If this is a blocking channel, the call does not return until all
buffered data is successfully sent to the channel's output device.
If this is a nonblocking channel and there is buffered output that
cannot be written without blocking, the call
returns immediately; output is flushed in the background and
the channel will be closed once all of the buffered data has
been output.
In this case errors during flushing are not reported.
.PP
If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR.
If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a
POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
If the channel is being closed synchronously and an error occurs during
closing of the channel and \fIinterp\fR is not NULL, an error message is
left in \fIinterp->result\fR.
.PP
Note: it is not safe to call \fBTcl_Close\fR on a channel that has
been registered in an interpreter using \fBTcl_RegisterChannel\fR;
see the documentation for \fBTcl_RegisterChannel\fR for details.
.SH TCL_READ
.PP
\fBTcl_Read\fR consumes up to \fItoRead\fR bytes of data from
\fIchannel\fR and stores it at \fIbuf\fR.
The return value of \fBTcl_Read\fR is the number of characters written
at \fIbuf\fR.
The buffer produced by \fBTcl_Read\fR is not NULL terminated. Its contents
are valid from the zeroth position up to and excluding the position
indicated by the return value.
If an error occurs, the return value is -1 and \fBTcl_Read\fR records
a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
.PP
The return value may be smaller than the value of \fItoRead\fR, indicating
that less data than requested was available, also called a \fIshort
read\fR.
In blocking mode, this can only happen on an end-of-file.
In nonblocking mode, a short read can also occur if there is not
enough input currently available: \fBTcl_Read\fR returns a short
count rather than waiting for more data.
.PP
If the channel is in blocking mode, a return value of zero indicates an end
of file condition. If the channel is in nonblocking mode, a return value of
zero indicates either that no input is currently available or an end of
file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR
to tell which of these conditions actually occurred.
.PP
\fBTcl_Read\fR translates platform-specific end-of-line representations
into the canonical \fB\en\fR internal representation according to the
current end-of-line recognition mode. End-of-line recognition and the
various platform-specific modes are described in the manual entry for the
Tcl \fBfconfigure\fR command.
.SH TCL_GETS
.PP
\fBTcl_Gets\fR reads a line of input from a channel and appends all of
the characters of the line except for the terminating end-of-line character(s)
to the dynamic string given by \fIdsPtr\fR.
The end-of-line character(s) are read and discarded.
.PP
If a line was successfully read, the return value is greater than or
equal to zero, and it indicates the number of characters stored
in the dynamic string.
If an error occurs, \fBTcl_Gets\fR returns -1 and records a POSIX error
code that can be retrieved with \fBTcl_GetErrno\fR.
\fBTcl_Gets\fR also returns -1 if the end of the file is reached;
the \fBTcl_Eof\fR procedure can be used to distinguish an error
from an end-of-file condition.
.PP
If the channel is in nonblocking mode, the return value can also
be -1 if no data was available or the data that was available
did not contain an end-of-line character.
When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be
invoked to determine if the channel is blocked because of input
unavailability.
.SH TCL_WRITE
.PP
\fBTcl_Write\fR accepts \fItoWrite\fR bytes of data at \fIbuf\fR for output
on \fIchannel\fR. This data may not appear on the output device
immediately. If the data should appear immediately, call \fBTcl_Flush\fR
after the call to \fBTcl_Write\fR, or set the \fB-buffering\fR option on
the channel to \fBnone\fR. If you wish the data to appear as soon as an end
of line is accepted for output, set the \fB\-buffering\fR option on the
channel to \fBline\fR mode.
.PP
The \fItoWrite\fR argument specifies how many bytes of data are provided in
the \fIbuf\fR argument. If it is negative, \fBTcl_Write\fR expects the data
to be NULL terminated and it outputs everything up to the NULL.
.PP
The return value of \fBTcl_Write\fR is a count of how many
characters were accepted for output to the channel. This is either equal to
\fItoWrite\fR or -1 to indicate that an error occurred.
If an error occurs, \fBTcl_Write\fR also records a POSIX error code
that may be retrieved with \fBTcl_GetErrno\fR.
.PP
Newline characters in the output data are translated to platform-specific
end-of-line sequences according to the \fB\-translation\fR option for
the channel.
.SH TCL_FLUSH
.PP
\fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR
to be written to its underlying file or device as soon as possible.
If the channel is in blocking mode, the call does not return until
all the buffered data has been sent to the channel or some error occurred.
The call returns immediately if the channel is nonblocking; it starts
a background flush that will write the buffered data to the channel
eventually, as fast as the channel is able to absorb it.
.PP
The return value is normally \fBTCL_OK\fR.
If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and
records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
.SH TCL_SEEK
.PP
\fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent
data will be read or written. Buffered output is flushed to the channel and
buffered input is discarded, prior to the seek operation.
.PP
\fBTcl_Seek\fR normally returns the new access point.
If an error occurs, \fBTcl_Seek\fR returns -1 and records a POSIX error
code that can be retrieved with \fBTcl_GetErrno\fR.
After an error, the access point may or may not have been moved.
.SH TCL_TELL
.PP
\fBTcl_Tell\fR returns the current access point for a channel. The returned
value is -1 if the channel does not support seeking.
.SH TCL_GETCHANNELOPTION
.PP
\fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of
the options currently in effect for a channel, or a list of all options and
their values. The \fIchannel\fR argument identifies the channel for which
to query an option or retrieve all options and their values.
If \fIoptionName\fR is not NULL, it is the name of the
option to query; the option's value is copied to the Tcl dynamic string
denoted by \fIoptionValue\fR. If
\fIoptionName\fR is NULL, the function stores an alternating list of option
names and their values in \fIoptionValue\fR, using a series of calls to
\fBTcl_DStringAppendElement\fR. The various preexisting options and
their possible values are described in the manual entry for the Tcl
\fBfconfigure\fR command. Other options can be added by each channel type.
These channel type specific options are described in the manual entry for
the Tcl command that creates a channel of that type; for example, the
additional options for TCP based channels are described in the manual entry
for the Tcl \fBsocket\fR command.
The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns
\fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX
error code.
.SH TCL_SETCHANNELOPTION
.PP
\fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR.
\fIOptionName\fR is the option to set and \fInewValue\fR is the value to
set.
The procedure normally returns \fBTCL_OK\fR. If an error occurs,
it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL,
\fBTcl_SetChannelOption\fR leaves an error message in \fIinterp->result\fR.
.SH TCL_EOF
.PP
\fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered
an end of file during the last input operation.
.SH TCL_INPUTBLOCKED
.PP
\fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in
nonblocking mode and the last input operation returned less data than
requested because there was insufficient data available.
The call always returns zero if the channel is in blocking mode.
.SH TCL_INPUTBUFFERED
.PP
\fBTcl_InputBuffered\fR returns the number of bytes of input currently
buffered in the internal buffers for a channel. If the channel is not open
for reading, this function always returns zero.
.SH "SEE ALSO"
DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3)
.SH KEYWORDS
access point, blocking, buffered I/O, channel, channel driver, end of file,
flush, input, nonblocking, output, read, seek, write

152
contrib/tcl/doc/OpenTcp.3 Normal file
View File

@ -0,0 +1,152 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) OpenTcp.3 1.16 96/03/17 09:51:18
.so man.macros
.TH Tcl_OpenTcpClient 3 7.5 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_OpenTcpClient, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
.SH SYNOPSIS
.nf
\fB#include <tcl.h> \fR
.sp
Tcl_Channel
\fBTcl_OpenTcpClient\fR(\fIinterp, port, host, myaddr, myport, async\fR)
.sp
Tcl_Channel
\fBTcl_MakeTcpClientChannel\fR(\fIsock\fR)
.sp
Tcl_Channel
\fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
.sp
.SH ARGUMENTS
.AS Tcl_ChannelType newClientProcPtr in
.AP Tcl_Interp *interp in
Tcl interpreter to use for error reporting. If non-NULL and an
error occurs, an error message is left in \fIinterp->result\fR.
.AP int port in
A port number to connect to as a client or to listen on as a server.
.AP char *host in
A string specifying a host name or address for the remote end of the connection.
.AP int myport in
A port number for the client's end of the socket. If 0, a port number
is allocated at random.
.AP char *myaddr in
A string specifying the host name or address for network interface to use
for the local end of the connection. If NULL, a default interface is
chosen.
.AP int async in
If nonzero, the client socket is connected asynchronously to the server.
.AP ClientData sock in
Platform-specific handle for client TCP socket.
.AP Tcl_TcpAcceptProc *proc in
Pointer to a procedure to invoke each time a new connection is
accepted via the socket.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE
.SH DESCRIPTION
.PP
These functions are convenience procedures for creating
channels that communicate over TCP sockets.
The operations on a channel
are described in the manual entry for \fBTcl_OpenFileChannel\fR.
.SH TCL_OPENTCPCLIENT
.PP
\fBTcl_OpenTcpClient\fR opens a client TCP socket connected to a \fIport\fR
on a specific \fIhost\fR, and returns a channel that can be used to
communicate with the server. The host to connect to can be specified either
as a domain name style name (e.g. \fBwww.sunlabs.com\fR), or as a string
containing the alphanumeric representation of its four-byte address (e.g.
\fB127.0.0.1\fR). Use the string \fBlocalhost\fR to connect to a TCP socket on
the host on which the function is invoked.
.PP
The \fImyaddr\fR and \fImyport\fR arguments allow a client to specify an
address for the local end of the connection. If \fImyaddr\fR is NULL, then
an interface is chosen automatically by the operating system.
If \fImyport\fR is 0, then a port number is chosen at random by
the operating system.
.PP
If \fIasync\fR is zero, the call to \fBTcl_OpenTcpClient\fR returns only
after the client socket has either successfully connected to the server, or
the attempted connection has failed.
If \fIasync\fR is nonzero the socket is connected asynchronously and the
returned channel may not yet be connected to the server when the call to
\fBTcl_OpenTcpClient\fR returns. If the channel is in blocking mode and an
input or output operation is done on the channel before the connection is
completed or fails, that operation will wait until the connection either
completes successfully or fails. If the channel is in nonblocking mode, the
input or output operation will return immediately and a subsequent call to
\fBTcl_InputBlocked\fR on the channel will return nonzero.
.PP
The returned channel is opened for reading and writing.
If an error occurs in opening the socket, \fBTcl_OpenTcpClient\fR returns
NULL and records a POSIX error code that can be retrieved
with \fBTcl_GetErrno\fR.
In addition, if \fIinterp\fR is non-NULL, an error message
is left in \fIinterp->result\fR.
.SH TCL_MAKETCPCLIENTCHANNEL
.PP
\fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an
existing, platform specific, handle for a client TCP socket.
.SH TCL_OPENTCPSERVER
.PP
\fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified
\fIport\fR and uses the Tcl event mechanism to accept requests from clients
to connect to it. The \fImyaddr\fP argument specifies the network interface.
If \fImyaddr\fP is NULL the special address INADDR_ANY should be used to
allow connections from any network interface.
Each time a client connects to this socket, Tcl creates a channel
for the new connection and invokes \fIproc\fR with information about
the channel. \fIProc\fR must match the following prototype:
.CS
typedef void Tcl_TcpAcceptProc(
ClientData \fIclientData\fR,
Tcl_Channel \fIchannel\fR,
char *\fIhostName\fR,
int \fIport\fP);
.CE
.PP
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle
for the new channel, \fIhostName\fR points to a string containing
the name of the client host making the connection, and \fIport\fP
will contain the client's port number.
The new channel
is opened for both input and output.
If \fIproc\fR raises an error, the connection is closed automatically.
\fIProc\fR has no return value, but if it wishes to reject the
connection it can close \fIchannel\fR.
.PP
\fBTcl_OpenTcpServer\fR normally returns a pointer to a channel
representing the server socket.
If an error occurs, \fBTcl_OpenTcpServer\fR returns NULL and
records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
In addition, if \fIinterp->result\fR is non-NULL, an error message
is left in \fIinterp->result\fR.
.PP
The channel returned by \fBTcl_OpenTcpServer\fR cannot be used for
either input or output.
It is simply a handle for the socket used to accept connections.
The caller can close the channel to shut down the server and disallow
further connections from new clients.
.PP
TCP server channels operate correctly only in applications that dispatch
events through \fBTcl_DoOneEvent\fR or through Tcl commands such as
\fBvwait\fR; otherwise Tcl will never notice that a connection request from
a remote client is pending.
.SH "SEE ALSO"
Tcl_OpenFileChannel(3), vwait(n)
.SH KEYWORDS
client, server, TCP

59
contrib/tcl/doc/PkgRequire.3 Normal file
View File

@ -0,0 +1,59 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) PkgRequire.3 1.4 96/02/15 20:03:16
'\"
.so man.macros
.TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_PkgRequire, Tcl_PkgProvide \- package version control
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
char *
\fBTcl_PkgRequire\fR(\fIinterp, name, version, exact\fR)
.sp
int
\fBTcl_PkgProvide\fR(\fIinterp, name, version\fR)
.SH ARGUMENTS
.AS Tcl_FreeProc clientData
.AP Tcl_Interp *interp in
Interpreter where package is needed or available.
.AP char *name in
Name of package.
.AP char *version in
A version string consisting of one or more decimal numbers
separated by dots.
.AP int exact in
Non-zero means that only the particular version specified by
\fIversion\fR is acceptable.
Zero means that newer versions than \fIversion\fR are also
acceptable as long as they have the same major version number
as \fIversion\fR.
.BE
.SH DESCRIPTION
.PP
These procedures provide C-level interfaces to Tcl's package and
version management facilities.
\fBTcl_PkgRequire\fR is equivalent to the \fBpackage require\fR
command, and \fBTcl_PkgProvide\fR is equivalent to the
\fBpackage provide\fR command.
See the documentation for the Tcl commands for details on what these
procedures do.
If \fBTcl_PkgRequire\fR completes successfully it returns a pointer
to the version string for the version of the package that is provided
in the interpreter (which may be different than \fIversion\fR); if
an error occurs it returns NULL and leaves an error message in
\fIinterp->result\fR.
\fBTcl_PkgProvide\fR returns TCL_OK if it completes successfully;
if an error occurs it returns TCL_ERROR and leaves an error message
in \fIinterp->result\fR.
.SH KEYWORDS
package, provide, require, version

100
contrib/tcl/doc/Preserve.3 Normal file
View File

@ -0,0 +1,100 @@
'\"
'\" Copyright (c) 1990 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.
'\"
'\" SCCS: @(#) Preserve.3 1.12 96/03/25 20:05:27
'\"
.so man.macros
.TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it's being used
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_Preserve\fR(\fIclientData\fR)
.sp
\fBTcl_Release\fR(\fIclientData\fR)
.sp
\fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR)
.SH ARGUMENTS
.AS Tcl_FreeProc clientData
.AP ClientData clientData in
Token describing structure to be freed or reallocated. Usually a pointer
to memory for structure.
.AP Tcl_FreeProc *freeProc in
Procedure to invoke to free \fIclientData\fR.
.BE
.SH DESCRIPTION
.PP
These three procedures help implement a simple reference count mechanism
for managing storage. They are designed to solve a problem
having to do with widget deletion, but are also useful in many other
situations. When a widget is deleted, its
widget record (the structure holding information specific to the
widget) must be returned to the storage allocator.
However, it's possible that the widget record is in active use
by one of the procedures on the stack at the time of the deletion.
This can happen, for example, if the command associated with a button
widget causes the button to be destroyed: an X event causes an
event-handling C procedure in the button to be invoked, which in
turn causes the button's associated Tcl command to be executed,
which in turn causes the button to be deleted, which in turn causes
the button's widget record to be de-allocated.
Unfortunately, when the Tcl command returns, the button's
event-handling procedure will need to reference the
button's widget record.
Because of this, the widget record must not be freed as part of the
deletion, but must be retained until the event-handling procedure has
finished with it.
In other situations where the widget is deleted, it may be possible
to free the widget record immediately.
.PP
\fBTcl_Preserve\fR and \fBTcl_Release\fR
implement short-term reference counts for their \fIclientData\fR
argument.
The \fIclientData\fR argument identifies an object and usually
consists of the address of a structure.
The reference counts guarantee that an object will not be freed
until each call to \fBTcl_Preserve\fR for the object has been
matched by calls to \fBTcl_Release\fR.
There may be any number of unmatched \fBTcl_Preserve\fR calls
in effect at once.
.PP
\fBTcl_EventuallyFree\fR is invoked to free up its \fIclientData\fR
argument.
It checks to see if there are unmatched \fBTcl_Preserve\fR calls
for the object.
If not, then \fBTcl_EventuallyFree\fR calls \fIfreeProc\fR immediately.
Otherwise \fBTcl_EventuallyFree\fR records the fact that \fIclientData\fR
needs eventually to be freed.
When all calls to \fBTcl_Preserve\fR have been matched with
calls to \fBTcl_Release\fR then \fIfreeProc\fR will be called by
\fBTcl_Release\fR to do the cleanup.
.PP
All the work of freeing the object is carried out by \fIfreeProc\fR.
\fIFreeProc\fR must have arguments and result that match the
type \fBTcl_FreeProc\fR:
.CS
typedef void Tcl_FreeProc(ClientData \fIclientData\fR);
.CE
The \fIclientData\fR argument to \fIfreeProc\fR will be the
same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR.
.PP
This mechanism can be used to solve the problem described above
by placing \fBTcl_Preserve\fR and \fBTcl_Release\fR calls around
actions that may cause undesired storage re-allocation. The
mechanism is intended only for short-term use (i.e. while procedures
are pending on the stack); it will not work efficiently as a
mechanism for long-term reference counts.
The implementation does not depend in any way on the internal
structure of the objects being freed; it keeps the reference
counts in a separate structure.
.SH KEYWORDS
free, reference count, storage

45
contrib/tcl/doc/PrintDbl.3 Normal file
View File

@ -0,0 +1,45 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) PrintDbl.3 1.6 96/03/25 20:05:45
'\"
.so man.macros
.TH Tcl_PrintDouble 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_PrintDouble \- Convert floating value to string
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_PrintDouble\fR(\fIinterp, value, dst\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter that controls the conversion.
.AP double value in
Floating-point value to be converted.
.AP char *dst out
Where to store string representing \fIvalue\fR. Must have at
least TCL_DOUBLE_SPACE characters of storage.
.BE
.SH DESCRIPTION
.PP
\fBTcl_PrintDouble\fR generates a string that represents the value
of \fIvalue\fR and stores it in memory at the location given by
\fIdst\fR. It uses %g format to generate the string, with two
special twists. First, the string is guaranteed to contain either
a ``.'' or an ``e'' so that it doesn't look like an integer (where
%g would generate an integer with no decimal point, \fBTcl_PrintDouble\fR
adds ``.0''). Second, the number of significant digits printed at
\fIdst\fR is controlled by the \fBtcl_precision\fR variable in
\fIinterp\fR; if \fBtcl_precision\fR is undefined then 6 significant
digits are printed.
.SH KEYWORDS
conversion, double-precision, floating-point, string

53
contrib/tcl/doc/RecordEval.3 Normal file
View File

@ -0,0 +1,53 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) RecordEval.3 1.16 96/03/25 20:06:06
'\"
.so man.macros
.TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_RecordAndEval \- save command on history list before evaluating
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_RecordAndEval\fR(\fIinterp, cmd, eval\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp;
.AP Tcl_Interp *interp in
Tcl interpreter in which to evaluate command.
.AP char *cmd in
Command (or sequence of commands) to execute.
.AP int flags in
.VS
An OR'ed combination of flag bits. TCL_NO_EVAL means record the
command but don't evaluate it. TCL_EVAL_GLOBAL means evaluate
the command at global level instead of the current stack level.
.VE
.BE
.SH DESCRIPTION
.PP
\fBTcl_RecordAndEval\fR is invoked to record a command as an event
on the history list and then execute it using \fBTcl_Eval\fR
.VS
(or \fBTcl_GlobalEval\fR if the TCL_EVAL_GLOBAL bit is set in \fIflags\fR).
.VE
It returns a completion code such as TCL_OK just like \fBTcl_Eval\fR
and it leaves information in \fIinterp->result\fR.
If you don't want the command recorded on the history list then
you should invoke \fBTcl_Eval\fR instead of \fBTcl_RecordAndEval\fR.
Normally \fBTcl_RecordAndEval\fR is only called with top-level
commands typed by the user, since the purpose of history is to
allow the user to re-issue recently-invoked commands.
If the \fIflags\fR argument contains the TCL_NO_EVAL bit then
the command is recorded without being evaluated.
.SH KEYWORDS
command, event, execute, history, interpreter, record

124
contrib/tcl/doc/RegExp.3 Normal file
View File

@ -0,0 +1,124 @@
'\"
'\" Copyright (c) 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.
'\"
'\" SCCS: @(#) RegExp.3 1.8 96/02/15 20:01:42
'\"
.so man.macros
.TH Tcl_RegExpMatch 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange \- Pattern matching with regular expressions
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
.sp
.VS
Tcl_RegExp
\fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR)
.sp
int
\fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
.sp
\fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
.VE
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Tcl interpreter to use for error reporting.
.AP char *string in
String to check for a match with a regular expression.
.AP char *pattern in
String in the form of a regular expression pattern.
.AP Tcl_RegExp regexp in
.VS
Compiled regular expression. Must have been returned previously
by \fBTcl_RegExpCompile\fR.
.AP char *start in
If \fIstring\fR is just a portion of some other string, this argument
identifies the beginning of the larger string.
If it isn't the same as \fIstring\fR, then no \fB^\fR matches
will be allowed.
.AP int index in
Specifies which range is desired: 0 means the range of the entire
match, 1 or greater means the range that matched a parenthesized
sub-expression.
.AP char **startPtr out
The address of the first character in the range is stored here, or
NULL if there is no such range.
.AP char **endPtr out
The address of the character just after the last one in the range
is stored here, or NULL if there is no such range.
.VE
.BE
.SH DESCRIPTION
.PP
\fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
matches \fIregexp\fR, where \fIregexp\fR is interpreted
as a regular expression using the same rules as for the
\fBregexp\fR Tcl command.
If there is a match then \fBTcl_RegExpMatch\fR returns 1.
If there is no match then \fBTcl_RegExpMatch\fR returns 0.
If an error occurs in the matching process (e.g. \fIpattern\fR
is not a valid regular expression) then \fBTcl_RegExpMatch\fR
returns \-1 and leaves an error message in \fIinterp->result\fR.
.PP
.VS
\fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
provide lower-level access to the regular expression pattern matcher.
\fBTcl_RegExpCompile\fR compiles a regular expression string into
the internal form used for efficient pattern matching.
The return value is a token for this compiled form, which can be
used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
If an error occurs while compiling the regular expression then
\fBTcl_RegExpCompile\fR returns NULL and leaves an error message
in \fIinterp->result\fR.
.VS
Note: the return value from \fBTcl_RegExpCompile\fR is only valid
up to the next call to \fBTcl_RegExpCompile\fR; it is not safe to
retain these values for long periods of time.
.VE
.PP
\fBTcl_RegExpExec\fR executes the regular expression pattern matcher.
It returns 1 if \fIstring\fR contains a range of characters that
match \fIregexp\fR, 0 if no match is found, and
\-1 if an error occurs.
In the case of an error, \fBTcl_RegExpExec\fR leaves an error
message in \fIinterp->result\fR.
When searching a string for multiple matches of a pattern,
it is important to distinguish between the start of the original
string and the start of the current search.
For example, when searching for the second occurrence of a
match, the \fIstring\fR argument might point to the character
just after the first match; however, it is important for the
pattern matcher to know that this is not the start of the entire string,
so that it doesn't allow \fB^\fR atoms in the pattern to match.
The \fIstart\fR argument provides this information by pointing
to the start of the overall string containing \fIstring\fR.
\fIStart\fR will be less than or equal to \fIstring\fR; if it
is less than \fIstring\fR then no \fB^\fR matches will be allowed.
.PP
\fBTcl_RegExpRange\fR may be invoked after \fBTcl_RegExpExec\fR
returns; it provides detailed information about what ranges of
the string matched what parts of the pattern.
\fBTcl_RegExpRange\fR returns a pair of pointers in \fI*startPtr\fR
and \fI*endPtr\fR that identify a range of characters in
the source string for the most recent call to \fBTcl_RegExpExec\fR.
\fIIndex\fR indicates which of several ranges is desired:
if \fIindex\fR is 0, information is returned about the overall range
of characters that matched the entire pattern; otherwise,
information is returned about the range of characters that matched the
\fIindex\fR'th parenthesized subexpression within the pattern.
If there is no range corresponding to \fIindex\fR then NULL
is stored in \fI*firstPtr\fR and \fI*lastPtr\fR.
.VE
.SH KEYWORDS
match, pattern, regular expression, string, subexpression

48
contrib/tcl/doc/SetErrno.3 Normal file
View File

@ -0,0 +1,48 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) SetErrno.3 1.5 96/02/15 20:01:31
.so man.macros
.TH Tcl_SetErrno 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_SetErrno, Tcl_GetErrno \- manipulate errno to store and retrieve error codes
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
void
\fBTcl_SetErrno\fR(\fIerrorCode\fR)
.sp
int
\fBTcl_GetErrno\fR()
.sp
.SH ARGUMENTS
.AS Tcl_Interp *errorCode in
.AP int errorCode in
A POSIX error code such as \fBENOENT\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_SetErrno\fR and \fBTcl_GetErrno\fR provide portable access
to the \fBerrno\fR variable, which is used to record a POSIX error
code after system calls and other operations such as \fBTcl_Gets\fR.
These procedures are necessary because global variable accesses cannot
be made across module boundaries on some platforms.
.PP
\fBTcl_SetErrno\fR sets the \fBerrno\fR variable to the value of the
\fIerrorCode\fR argument
C procedures that wish to return error information to their callers
via \fBerrno\fR should call \fBTcl_SetErrno\fR rather than setting
\fBerrno\fR directly.
.PP
\fBTcl_GetErrno\fR returns the current value of \fBerrno\fR.
Procedures wishing to access \fBerrno\fR should call this procedure
instead of accessing \fBerrno\fR directly.
.SH KEYWORDS
errno, error code, global variables

55
contrib/tcl/doc/SetRecLmt.3 Normal file
View File

@ -0,0 +1,55 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) SetRecLmt.3 1.6 96/03/25 20:06:36
'\"
.so man.macros
.TH Tcl_SetRecursionLimit 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_SetRecursionLimit \- set maximum allowable nesting depth in interpreter
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_SetRecursionLimit\fR(\fIinterp, depth\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter whose recursion limit is to be set.
Must be greater than zero.
.AP int depth in
New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR.
.BE
.SH DESCRIPTION
.PP
At any given time Tcl enforces a limit on the number of recursive
calls that may be active for \fBTcl_Eval\fR and related procedures
such as \fBTcl_GlobalEval\fR.
Any call to \fBTcl_Eval\fR that exceeds this depth is aborted with
an error.
By default the recursion limit is 1000.
.PP
\fBTcl_SetRecursionLimit\fR may be used to change the maximum
allowable nesting depth for an interpreter.
The \fIdepth\fR argument specifies a new limit for \fIinterp\fR,
and \fBTcl_SetRecursionLimit\fR returns the old limit.
To read out the old limit without modifying it, invoke
\fBTcl_SetRecursionDepth\fR with \fIdepth\fR equal to 0.
.PP
The \fBTcl_SetRecursionLimit\fR only sets the size of the Tcl
call stack: it cannot by itself prevent stack overflows 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 \fBTcl_SetRecursionLimit\fR.
If this happens, see if there is a mechanism in your system for
increasing the maximum size of the C stack.
.SH KEYWORDS
nesting depth, recursion

145
contrib/tcl/doc/SetResult.3 Normal file
View File

@ -0,0 +1,145 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) SetResult.3 1.18 96/03/25 20:06:54
'\"
.so man.macros
.TH Tcl_SetResult 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result string
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
.sp
\fBTcl_AppendResult(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
.sp
.VS
\fBTcl_AppendElement\fR(\fIinterp, string\fR)
.VE
.sp
\fBTcl_ResetResult\fR(\fIinterp\fR)
.sp
\fBTcl_FreeResult\fR(\fIinterp\fR)
.SH ARGUMENTS
.AS Tcl_FreeProc freeProc
.AP Tcl_Interp *interp out
Interpreter whose result is to be modified.
.AP char *string in
String value to become result for \fIinterp\fR or to be
appended to existing result.
.AP Tcl_FreeProc *freeProc in
Address of procedure to call to release storage at
\fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
\fBTCL_VOLATILE\fR.
.BE
.SH DESCRIPTION
.PP
The procedures described here are utilities for setting the
result/error string in a Tcl interpreter.
.PP
\fBTcl_SetResult\fR
arranges for \fIstring\fR to be the return string for the current Tcl
command in \fIinterp\fR, replacing any existing result.
If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
refers to an area of static storage that is guaranteed not to be
modified until at least the next call to \fBTcl_Eval\fR.
If \fIfreeProc\fR
is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
to \fBmalloc()\fR and is now the property of the Tcl system.
\fBTcl_SetResult\fR will arrange for the string's storage to be
released by calling \fBfree()\fR when it is no longer needed.
If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
points to an area of memory that is likely to be overwritten when
\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
In this case \fBTcl_SetResult\fR will make a copy of the string in
dynamically allocated storage and arrange for the copy to be the
return string for the current Tcl command.
.PP
If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
of a procedure that Tcl should call to free the string.
This allows applications to use non-standard storage allocators.
When Tcl no longer needs the storage for the string, it will
call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
result that match the type \fBTcl_FreeProc\fR:
.CS
typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
.CE
When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
.PP
If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
and \fBTcl_SetResult\fR
re-initializes \fIinterp\fR's result to point to the pre-allocated result
area, with an empty string in the result area.
.PP
If \fBTcl_SetResult\fR is called at a time when \fIinterp\fR holds a
result, \fBTcl_SetResult\fR does whatever is necessary to dispose
of the old result (see the \fBTcl_Interp\fR manual entry for details
on this).
.PP
\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
It takes each of its \fIstring\fR arguments and appends them in order
to the current result associated with \fIinterp\fR.
If the result is in its initialized empty state (e.g. a command procedure
was just invoked or \fBTcl_ResetResult\fR was just called),
then \fBTcl_AppendResult\fR sets the result to the concatenation of
its \fIstring\fR arguments.
\fBTcl_AppendResult\fR may be called repeatedly as additional pieces
of the result are produced.
\fBTcl_AppendResult\fR takes care of all the
storage management issues associated with managing \fIinterp\fR's
result, such as allocating a larger result area if necessary.
Any number of \fIstring\fR arguments may be passed in a single
call; the last argument in the list must be a NULL pointer.
.PP
\fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
that it allows results to be built up in pieces.
However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR
argument and it appends that argument to the current result
as a proper Tcl list element.
\fBTcl_AppendElement\fR adds backslashes or braces if necessary
to ensure that \fIinterp\fR's result can be parsed as a list and that
\fIstring\fR will be extracted as a single element.
Under normal conditions, \fBTcl_AppendElement\fR will add a space
character to \fIinterp\fR's result just before adding the new
list element, so that the list elements in the result are properly
separated.
.VS
However if the new list element is the first in a list or sub-list
(i.e. \fIinterp\fR's current result is empty, or consists of the
single character ``{'', or ends in the characters `` {'') then no
space is added.
.VE
.PP
\fBTcl_ResetResult\fR clears the result for \fIinterp\fR,
freeing the memory associated with it if the current result was
dynamically allocated.
It leaves the result in its normal initialized state with
\fIinterp->result\fR pointing to a static buffer containing
\fBTCL_RESULT_SIZE\fR characters, of which the first character
is zero.
\fBTcl_ResetResult\fR also clears the error state managed by
\fBTcl_AddErrorInfo\fR and \fBTcl_SetErrorCode\fR.
.PP
\fBTcl_FreeResult\fR is a macro that performs part of the work
of \fBTcl_ResetResult\fR.
It frees up the memory associated with \fIinterp\fR's result
and sets \fIinterp->freeProc\fR to zero, but it doesn't
change \fIinterp->result\fR or clear error state.
\fBTcl_FreeResult\fR is most commonly used when a procedure
is about to replace one result value with another.
.SH "SEE ALSO"
Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
.SH KEYWORDS
append, command, element, list, result, return value, interpreter

162
contrib/tcl/doc/SetVar.3 Normal file
View File

@ -0,0 +1,162 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) SetVar.3 1.22 96/03/25 20:07:08
'\"
.so man.macros
.TH Tcl_SetVar 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_SetVar, Tcl_SetVar2, Tcl_GetVar, Tcl_GetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
char *
\fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR)
.sp
char *
\fBTcl_SetVar2\fR(\fIinterp, name1, name2, newValue, flags\fR)
.sp
char *
\fBTcl_GetVar\fR(\fIinterp, varName, flags\fR)
.sp
char *
\fBTcl_GetVar2\fR(\fIinterp, name1, name2, flags\fR)
.sp
int
\fBTcl_UnsetVar\fR(\fIinterp, varName, flags\fR)
.sp
int
\fBTcl_UnsetVar2\fR(\fIinterp, name1, name2, flags\fR)
.SH ARGUMENTS
.AS Tcl_Interp *newValue
.AP Tcl_Interp *interp in
Interpreter containing variable.
.AP char *varName in
Name of variable. May refer to a scalar variable or an element of
an array variable.
.VS
If the name references an element of an array, then it
must be in writable memory: Tcl will make temporary modifications
to it while looking up the name.
.VE
.AP char *newValue in
New value for variable.
.AP int flags in
OR-ed combination of bits providing additional information for
operation. See below for valid values.
.AP char *name1 in
Name of scalar variable, or name of array variable if \fIname2\fR
is non-NULL.
.AP char *name2 in
If non-NULL, gives name of element within array and \fIname1\fR
must refer to an array variable.
.BE
.SH DESCRIPTION
.PP
These procedures may be used to create, modify, read, and delete
Tcl variables from C code.
\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR will create a new variable
or modify an existing one.
Both of these procedures set the given variable to the value
given by \fInewValue\fR, and they return a pointer to a
copy of the variable's new value, which is stored in Tcl's
variable structure.
Tcl keeps a private copy of the variable's value, so the caller
may change \fInewValue\fR after these procedures return without
affecting the value of the variable.
If an error occurs in setting the variable (e.g. an array
variable is referenced without giving an index into the array),
then NULL is returned.
.PP
The name of the variable may be specified in either of two ways.
If \fBTcl_SetVar\fR is called, the variable name is given as
a single string, \fIvarName\fR.
If \fIvarName\fR contains an open parenthesis and ends with a
close parenthesis, then the value between the parentheses is
treated as an index (which can have any string value) and
the characters before the first open
parenthesis are treated as the name of an array variable.
If \fIvarName\fR doesn't have parentheses as described above, then
the entire string is treated as the name of a scalar variable.
If \fBTcl_SetVar2\fR is called, then the array name and index
have been separated by the caller into two separate strings,
\fIname1\fR and \fIname2\fR respectively; if \fIname2\fR is
zero it means that a scalar variable is being referenced.
.PP
The \fIflags\fR argument may be used to specify any of several
options to the procedures.
It consists of an OR-ed combination of any of the following
bits:
.TP
\fBTCL_GLOBAL_ONLY\fR
Under normal circumstances the procedures look up variables
at the current level of procedure call for \fIinterp\fR, or
at global level if there is no call active.
However, if this bit is set in \fIflags\fR then the variable
is looked up at global level even if there is a procedure
call active.
.TP
\fBTCL_LEAVE_ERR_MSG\fR
If an error is returned and this bit is set in \fIflags\fR, then
an error message will be left in \fI\%interp->result\fR. If this
flag bit isn't set then no error message is left (\fI\%interp->result\fR
will not be modified).
.TP
\fBTCL_APPEND_VALUE\fR
If this bit is set then \fInewValue\fR is appended to the current
value, instead of replacing it.
If the variable is currently undefined, then this bit is ignored.
.TP
\fBTCL_LIST_ELEMENT\fR
If this bit is set, then \fInewValue\fR is converted to a valid
Tcl list element before setting (or appending to) the variable.
A separator space is appended before the new list element unless
.VS
the list element is going to be the first element in a list or
sublist (i.e. the variable's current value is empty, or contains
the single character ``{'', or ends in `` }'').
.VE
.PP
\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR return the current value
of a variable.
The arguments to these procedures are treated in the same way
as the arguments to \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR.
Under normal circumstances, the return value is a pointer
to the variable's value (which is stored in Tcl's variable
structure and will not change before the next call to \fBTcl_SetVar\fR
or \fBTcl_SetVar2\fR).
The only bits of \fIflags\fR that are used are TCL_GLOBAL_ONLY
and TCL_LEAVE_ERR_MSG, both of
which have
the same meaning as for \fBTcl_SetVar\fR.
If an error occurs in reading the variable (e.g. the variable
doesn't exist or an array element is specified for a scalar
variable), then NULL is returned.
.PP
\fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove
a variable, so that future calls to \fBTcl_GetVar\fR or \fBTcl_GetVar2\fR
for the variable will return an error.
The arguments to these procedures are treated in the same way
as the arguments to \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR.
.VS
If the variable is successfully removed then TCL_OK is returned.
If the variable cannot be removed because it doesn't exist then
TCL_ERROR is returned.
.VE
If an array element is specified, the given element is removed
but the array remains.
If an array name is specified without an index, then the entire
array is removed.
.SH "SEE ALSO"
Tcl_TraceVar
.SH KEYWORDS
array, interpreter, scalar, set, unset, variable

37
contrib/tcl/doc/Sleep.3 Normal file
View File

@ -0,0 +1,37 @@
'\"
'\" Copyright (c) 1990 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.
'\"
'\" SCCS: @(#) Sleep.3 1.3 96/03/25 20:07:21
'\"
.so man.macros
.TH Tcl_Sleep 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Sleep \- delay execution for a given number of milliseconds
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_Sleep\fR(\fIms\fR)
.SH ARGUMENTS
.AP int ms in
Number of milliseconds to sleep.
.BE
.SH DESCRIPTION
.PP
This procedure delays the calling process by the number of
milliseconds given by the \fIms\fR parameter and returns
after that time has elapsed. It is typically used for things
like flashing a button, where the delay is short and the
application needn't do anything while it waits. For longer
delays where the application needs to respond to other events
during the delay, the procedure \fBTcl_CreateTimerHandler\fR
should be used instead of \fBTcl_Sleep\fR.
.SH KEYWORDS
sleep, time, wait

166
contrib/tcl/doc/SplitList.3 Normal file
View File

@ -0,0 +1,166 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) SplitList.3 1.19 96/03/25 20:07:46
'\"
.so man.macros
.TH Tcl_SplitList 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement \- manipulate Tcl lists
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_SplitList\fR(\fIinterp, list, argcPtr, argvPtr\fR)
.sp
char *
\fBTcl_Merge\fR(\fIargc, argv\fR)
.sp
int
\fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR)
.sp
int
\fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
.SH ARGUMENTS
.AS Tcl_Interp ***argvPtr
.AP Tcl_Interp *interp out
.VS
Interpreter to use for error reporting. If NULL, then no error message
is left.
.VE
.AP char *list in
Pointer to a string with proper list structure.
.AP int *argcPtr out
Filled in with number of elements in \fIlist\fR.
.AP char ***argvPtr out
\fI*argvPtr\fR will be filled in with the address of an array of
pointers to the strings that are the extracted elements of \fIlist\fR.
There will be \fI*argcPtr\fR valid entries in the array, followed by
a NULL entry.
.AP int argc in
Number of elements in \fIargv\fR.
.AP char **argv in
Array of strings to merge together into a single list.
Each string will become a separate element of the list.
.AP char *src in
String that is to become an element of a list.
.AP int *flagsPtr in
Pointer to word to fill in with information about \fIsrc\fR.
The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR.
.AP char *dst in
Place to copy converted list element. Must contain enough characters
to hold converted string.
.AP int flags in
Information about \fIsrc\fR. Must be value returned by previous
call to \fBTcl_ScanElement\fR, possibly OR-ed
with \fBTCL_DONT_USE_BRACES\fR.
.BE
.SH DESCRIPTION
.PP
These procedures may be used to disassemble and reassemble Tcl lists.
\fBTcl_SplitList\fR breaks a list up into its constituent elements,
returning an array of pointers to the elements using
\fIargcPtr\fR and \fIargvPtr\fR.
While extracting the arguments, \fBTcl_SplitList\fR obeys the usual
rules for backslash substitutions and braces. The area of
memory pointed to by \fI*argvPtr\fR is dynamically allocated; in
addition to the array of pointers, it
also holds copies of all the list elements. It is the caller's
responsibility to free up all of this storage.
For example, suppose that you have called \fBTcl_SplitList\fR with
the following code:
.CS
int argc, code;
char *string;
char **argv;
\&...
code = Tcl_SplitList(interp, string, &argc, &argv);
.CE
Then you should eventually free the storage with a call like the
following:
.CS
free((char *) argv);
.CE
.PP
\fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was
successfully parsed.
If there was a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned
and \fIinterp->result\fR will point to an error message describing the
.VS
problem (if \fIinterp\fR was not NULL).
.VE
If \fBTCL_ERROR\fR is returned then no memory is allocated and \fI*argvPtr\fR
is not modified.
.PP
\fBTcl_Merge\fR is the inverse of \fBTcl_SplitList\fR: it
takes a collection of strings given by \fIargc\fR
and \fIargv\fR and generates a result string
that has proper list structure.
This means that commands like \fBindex\fR may be used to
extract the original elements again.
In addition, if the result of \fBTcl_Merge\fR is passed to \fBTcl_Eval\fR,
it will be parsed into \fIargc\fR words whose values will
be the same as the \fIargv\fR strings passed to \fBTcl_Merge\fR.
\fBTcl_Merge\fR will modify the list elements with braces and/or
backslashes in order to produce proper Tcl list structure.
The result string is dynamically allocated
using \fBmalloc()\fR; the caller must eventually release the space
using \fBfree()\fR.
.PP
If the result of \fBTcl_Merge\fR is passed to \fBTcl_SplitList\fR,
the elements returned by \fBTcl_SplitList\fR will be identical to
those passed into \fBTcl_Merge\fR.
However, the converse is not true: if \fBTcl_SplitList\fR
is passed a given string, and the resulting \fIargc\fR and
\fIargv\fR are passed to \fBTcl_Merge\fR, the resulting string
may not be the same as the original string passed to \fBTcl_SplitList\fR.
This is because \fBTcl_Merge\fR may use backslashes and braces
differently than the original string.
.PP
\fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR are the
procedures that do all of the real work of \fBTcl_Merge\fR.
\fBTcl_ScanElement\fR scans its \fIsrc\fR argument
and determines how to use backslashes and braces
when converting it to a list element.
It returns an overestimate of the number of characters
required to represent \fIsrc\fR as a list element, and
it stores information in \fI*flagsPtr\fR that is needed
by \fBTcl_ConvertElement\fR.
.PP
\fBTcl_ConvertElement\fR is a companion procedure to \fBTcl_ScanElement\fR.
It does the actual work of converting a string to a list element.
Its \fIflags\fR argument must be the same as the value returned
by \fBTcl_ScanElement\fR.
\fBTcl_ConvertElement\fR writes a proper list element to memory
starting at *\fIdst\fR and returns a count of the total number
of characters written, which will be no more than the result
returned by \fBTcl_ScanElement\fR.
\fBTcl_ConvertElement\fR writes out only the actual list element
without any leading or trailing spaces: it is up to the caller to
include spaces between adjacent list elements.
.PP
\fBTcl_ConvertElement\fR uses one of two different approaches to
handle the special characters in \fIsrc\fR. Wherever possible, it
handles special characters by surrounding the string with braces.
This produces clean-looking output, but can't be used in some situations,
such as when \fIsrc\fR contains unmatched braces.
In these situations, \fBTcl_ConvertElement\fR handles special
characters by generating backslash sequences for them.
The caller may insist on the second approach by OR-ing the
flag value returned by \fBTcl_ScanElement\fR with
\fBTCL_DONT_USE_BRACES\fR.
Although this will produce an uglier result, it is useful in some
special situations, such as when \fBTcl_ConvertElement\fR is being
used to generate a portion of an argument for a Tcl command.
In this case, surrounding \fIsrc\fR with curly braces would cause
the command not to be parsed correctly.
.SH KEYWORDS
backslash, convert, element, list, merge, split, strings

67
contrib/tcl/doc/StaticPkg.3 Normal file
View File

@ -0,0 +1,67 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) StaticPkg.3 1.3 96/03/15 08:29:37
'\"
.so man.macros
.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_StaticPackage \- make a statically linked package available via the \fBload\fR command
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_StaticPackage\fR(\fIinterp, pkgName, initProc, safeInitProc\fR)
.SH ARGUMENTS
.AS Tcl_PackageInitProc *safeInitProc
.AP Tcl_Interp *interp in
If not NULL, points to an interpreter into which the package has
already been loaded (i.e., the caller has already invoked the
appropriate initialization procedure). NULL means the package
hasn't yet been incorporated into any interpreter.
.AP char *pkgName in
Name of the package; should be properly capitalized (first letter
upper-case, all others lower-case).
.AP Tcl_PackageInitProc *initProc in
Procedure to invoke to incorporate this package into a trusted
interpreter.
.AP Tcl_PackageInitProc *safeInitProc in
Procedure to call to incorporate this package into a safe interpreter
(one that will execute untrusted scripts). NULL means the package
can't be used in safe interpreters.
.BE
.SH DESCRIPTION
.PP
This procedure may be invoked to announce that a package has been
linked statically with a Tcl application and, optionally, that it
has already been loaded into an interpreter.
\fBTcl_StaticPackage\fR is typically invoked by the \fBTcl_AppInit\fR
procedure for the application.
Once \fBTcl_StaticPackage\fR has been invoked for a package, it
may be loaded into interpreters using the \fBload\fR command.
.PP
When the \fBload\fR command is used later to load the package into
an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will
be invoked, depending on whether the target interpreter is safe
or not.
\fIinitProc\fR and \fIsafeInitProc\fR must both match the
following prototype:
.CS
typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR);
.CE
The \fIinterp\fR argument identifies the interpreter in which the
package is to be loaded. The initialization procedure must return
\fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed
successfully; in the event of an error it should set \fIinterp->result\fR
to point to an error message.
The result or error from the initialization procedure will be returned
as the result of the \fBload\fR command that caused the
initialization procedure to be invoked.
.SH KEYWORDS
initialization procedure, package, static linking

39
contrib/tcl/doc/StrMatch.3 Normal file
View File

@ -0,0 +1,39 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) StrMatch.3 1.11 96/03/25 20:08:06
'\"
.so man.macros
.TH Tcl_StringMatch 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_StringMatch \- test whether a string matches a pattern
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_StringMatch\fR(\fIstring\fR, \fIpattern\fR)
.SH ARGUMENTS
.AP char *string in
String to test.
.AP char *pattern in
Pattern to match against string. May contain special
characters from the set *?\e[].
.BE
.SH DESCRIPTION
.PP
This utility procedure determines whether a string matches
a given pattern. If it does, then \fBTcl_StringMatch\fR returns
1. Otherwise \fBTcl_StringMatch\fR returns 0. The algorithm
used for matching is the same algorithm used in the ``string match''
Tcl command and is similar to the algorithm used by the C-shell
for file name matching; see the Tcl manual entry for details.
.SH KEYWORDS
match, pattern, string

189
contrib/tcl/doc/Tcl.n Normal file
View File

@ -0,0 +1,189 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) Tcl.n 1.127 96/03/25 20:08:20
'
.so man.macros
.TH Tcl n "" Tcl "Tcl Built-In Commands"
.BS
.SH NAME
Tcl \- Summary of Tcl language syntax.
.BE
.SH DESCRIPTION
.PP
The following rules define the syntax and semantics of the Tcl language:
.IP [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.
.IP [2]
A command is evaluated in two steps.
First, the Tcl interpreter breaks the command into \fIwords\fR
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 command procedure to
carry out the command, then all of the words of the command are
passed to the command 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.
.IP [3]
Words of a command are separated by white space (except for
newlines, which are command separators).
.IP [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 newlines) 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.
.IP [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.
.IP [6]
If a word contains an open bracket (``['') then Tcl performs
\fIcommand substitution\fR.
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 commands 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 substitution is not performed on words enclosed in braces.
.IP [7]
If a word contains a dollar-sign (``$'') then Tcl performs \fIvariable
substitution\fR: the dollar-sign and the following characters are
replaced in the word by the value of a variable.
Variable substitution may take any of the following forms:
.RS
.TP 15
\fB$\fIname\fR
\fIName\fR is the name of a scalar variable; the name is terminated
by any character that isn't a letter, digit, or underscore.
.TP 15
\fB$\fIname\fB(\fIindex\fB)\fR
\fIName\fR gives the name of an array variable and \fIindex\fR gives
the name of an element within that array.
\fIName\fR must contain only letters, digits, and underscores.
Command substitutions, variable substitutions, and backslash
substitutions are performed on the characters of \fIindex\fR.
.TP 15
\fB${\fIname\fB}\fR
\fIName\fR is the name of a scalar variable. It may contain any
characters whatsoever except for close braces.
.LP
There may be any number of variable substitutions in a single word.
Variable substitution is not performed on words enclosed in braces.
.RE
.IP [8]
If a backslash (``\e'') appears within a word then
\fIbackslash substitution\fR occurs.
.VS
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.
.VE
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 specially, along with the value that replaces each sequence.
.RS
.VS
.TP 6
\e\fBa\fR
Audible alert (bell) (0x7).
.VE
.TP 6
\e\fBb\fR
Backspace (0x8).
.TP 6
\e\fBf\fR
Form feed (0xc).
.TP 6
\e\fBn\fR
Newline (0xa).
.TP 6
\e\fBr\fR
Carriage-return (0xd).
.TP 6
\e\fBt\fR
Tab (0x9).
.TP 6
\e\fBv\fR
Vertical tab (0xb).
.TP 6
\e\fB<newline>\fIwhiteSpace\fR
.VS
A single space character replaces the backslash, newline, and all
spaces and tabs after the newline.
This backslash sequence is unique in that it is replaced in a separate
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.
.VE
.TP 6
\e\e
Backslash (``\e'').
.TP 6
\e\fIooo\fR
The digits \fIooo\fR (one, two, or three of them) give the octal value of
the character.
.TP 6
\e\fBx\fIhh\fR
.VS
The hexadecimal digits \fIhh\fR give the hexadecimal value of
the character. Any number of digits may be present.
.VE
.LP
Backslash substitution is not performed on words enclosed in braces,
except for backslash-newline as described above.
.RE
.IP [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.
.IP [10]
Each character is processed exactly once by the Tcl interpreter
as part of creating the words of a command.
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 substitutions are performed before making the recursive
call and no additional substitutions are performed on the result
of the nested script.
.IP [11]
Substitutions do not affect the word boundaries of a command.
For example, during variable substitution the entire value of
the variable becomes part of a single word, even if the variable's
value contains spaces.

61
contrib/tcl/doc/Tcl_Main.3 Normal file
View File

@ -0,0 +1,61 @@
'\"
'\" Copyright (c) 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.
'\"
'\" SCCS: @(#) Tcl_Main.3 1.8 96/03/25 20:08:33
'\"
.so man.macros
.TH Tcl_Main 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Main \- main program for Tcl-based applications
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_Main\fR(\fIargc, argv, appInitProc\fR)
.SH ARGUMENTS
.AS Tcl_AppInitProc *appInitProc
.AP int argc in
Number of elements in \fIargv\fR.
.AP char *argv[] in
Array of strings containing command-line arguments.
.AP Tcl_AppInitProc *appInitProc in
Address of an application-specific initialization procedure.
The value for this argument is usually \fBTcl_AppInit\fR.
.BE
.SH DESCRIPTION
.PP
\fBTcl_Main\fR acts as the main program for most Tcl-based applications.
Starting with Tcl 7.4 it is not called \fBmain\fR anymore because it
is part of the Tcl library and having a function \fBmain\fR
in a library (particularly a shared library) causes problems on many
systems.
Having \fBmain\fR in the Tcl library would also make it hard to use
Tcl in C++ programs, since C++ programs must have special C++
\fBmain\fR functions.
.PP
Normally each application contains a small \fBmain\fR function that does
nothing but invoke \fBTcl_Main\fR.
\fBTcl_Main\fR then does all the work of creating and running a
\fBtclsh\fR-like application.
.PP
When it is has finished its own initialization, but before
it processes commands, \fBTcl_Main\fR calls the procedure given by
the \fIappInitProc\fR argument. This procedure provides a ``hook''
for the application to perform its own initialization, such as defining
application-specific commands. The procedure must have an interface
that matches the type \fBTcl_AppInitProc\fR:
.CS
typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR);
.CE
\fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR;
for more details on this procedure, see the documentation
for \fBTcl_AppInit\fR.
.SH KEYWORDS
application-specific initialization, command-line arguments, main program

349
contrib/tcl/doc/TraceVar.3 Normal file
View File

@ -0,0 +1,349 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) TraceVar.3 1.25 96/03/25 20:08:44
'\"
.so man.macros
.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 \- monitor accesses to a variable
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_TraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR
.sp
int
\fBTcl_TraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
.sp
\fBTcl_UntraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR
.sp
\fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
.sp
ClientData
\fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR
.sp
ClientData
\fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR
.SH ARGUMENTS
.AS Tcl_VarTraceProc prevClientData
.AP Tcl_Interp *interp in
Interpreter containing variable.
.AP char *varName in
Name of variable. May refer to a scalar variable, to
an array variable with no index, or to an array variable
with a parenthesized index.
.VS
If the name references an element of an array, then it
must be in writable memory: Tcl will make temporary modifications
to it while looking up the name.
.VE
.AP int flags in
OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and
TCL_TRACE_UNSETS, and TCL_GLOBAL_ONLY. Not all flags are used by all
procedures. See below for more information.
.AP Tcl_VarTraceProc *proc in
Procedure to invoke whenever one of the traced operations occurs.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.AP char *name1 in
Name of scalar or array variable (without array index).
.AP char *name2 in
For a trace on an element of an array, gives the index of the
element. For traces on scalar variables or on whole arrays,
is NULL.
.AP ClientData prevClientData in
If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or
\fBTcl_VarTraceInfo2\fR, so this call will return information about
next trace. If NULL, this call will return information about first
trace.
.BE
.SH DESCRIPTION
.PP
\fBTcl_TraceVar\fR allows a C procedure to monitor and control
access to a Tcl variable, so that the C procedure is invoked
whenever the variable is read or written or unset.
If the trace is created successfully then \fBTcl_TraceVar\fR returns
TCL_OK. If an error occurred (e.g. \fIvarName\fR specifies an element
of an array, but the actual variable isn't an array) then TCL_ERROR
is returned and an error message is left in \fIinterp->result\fR.
.PP
The \fIflags\fR argument to \fBTcl_TraceVar\fR indicates when the
trace procedure is to be invoked and provides information
for setting up the trace. It consists of an OR-ed combination
of any of the following values:
.TP
\fBTCL_GLOBAL_ONLY\fR
Normally, the variable will be looked up at the current level of
procedure call; if this bit is set then the variable will be looked
up at global level, ignoring any active procedures.
.TP
\fBTCL_TRACE_READS\fR
Invoke \fIproc\fR whenever an attempt is made to read the variable.
.TP
\fBTCL_TRACE_WRITES\fR
Invoke \fIproc\fR whenever an attempt is made to modify the variable.
.TP
\fBTCL_TRACE_UNSETS\fR
Invoke \fIproc\fR whenever the variable is unset.
A variable may be unset either explicitly by an \fBunset\fR command,
or implicitly when a procedure returns (its local variables are
automatically unset) or when the interpreter is deleted (all
variables are automatically unset).
.PP
Whenever one of the specified operations occurs on the variable,
\fIproc\fR will be invoked.
It should have arguments and result that match the type
\fBTcl_VarTraceProc\fR:
.CS
typedef char *Tcl_VarTraceProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
char *\fIname1\fR,
char *\fIname2\fR,
int \fIflags\fR);
.CE
The \fIclientData\fR and \fIinterp\fR parameters will
have the same values as those passed to \fBTcl_TraceVar\fR when the
trace was created.
\fIClientData\fR typically points to an application-specific
data structure that describes what to do when \fIproc\fR
is invoked.
\fIName1\fR and \fIname2\fR give the name of the traced variable
in the normal two-part form (see the description of \fBTcl_TraceVar2\fR
below for details).
\fIFlags\fR is an OR-ed combination of bits providing several
pieces of information.
One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, or TCL_TRACE_UNSETS
will be set in \fIflags\fR to indicate which operation is being performed
on the variable.
The bit TCL_GLOBAL_ONLY will be set whenever the variable being
accessed is a global one not accessible from the current level of
procedure call: the trace procedure will need to pass this flag
back to variable-related procedures like \fBTcl_GetVar\fR if it
attempts to access the variable.
The bit TCL_TRACE_DESTROYED will be set in \fIflags\fR if the trace is
about to be destroyed; this information may be useful to \fIproc\fR
so that it can clean up its own internal data structures (see
the section TCL_TRACE_DESTROYED below for more details).
Lastly, the bit TCL_INTERP_DESTROYED will be set if the entire
interpreter is being destroyed.
When this bit is set, \fIproc\fR must be especially careful in
the things it does (see the section TCL_INTERP_DESTROYED below).
The trace procedure's return value should normally be NULL; see
ERROR RETURNS below for information on other possibilities.
.PP
\fBTcl_UntraceVar\fR may be used to remove a trace.
If the variable specified by \fIinterp\fR, \fIvarName\fR, and \fIflags\fR
has a trace set with \fIflags\fR, \fIproc\fR, and
\fIclientData\fR, then the corresponding trace is removed.
If no such trace exists, then the call to \fBTcl_UntraceVar\fR
has no effect.
The same bits are valid for \fIflags\fR as for calls to \fBTcl_TraceVar\fR.
.PP
\fBTcl_VarTraceInfo\fR may be used to retrieve information about
traces set on a given variable.
The return value from \fBTcl_VarTraceInfo\fR is the \fIclientData\fR
associated with a particular trace.
The trace must be on the variable specified by the \fIinterp\fR,
\fIvarName\fR, and \fIflags\fR arguments (only the TCL_GLOBAL_ONLY
bit from \fIflags\fR is used; other bits are ignored) and its trace procedure
must the same as the \fIproc\fR argument.
If the \fIprevClientData\fR argument is NULL then the return
value corresponds to the first (most recently created) matching
trace, or NULL if there are no matching traces.
If the \fIprevClientData\fR argument isn't NULL, then it should
be the return value from a previous call to \fBTcl_VarTraceInfo\fR.
In this case, the new return value will correspond to the next
matching trace after the one whose \fIclientData\fR matches
\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR
or if there are no more matching traces after it.
This mechanism makes it possible to step through all of the
traces for a given variable that have the same \fIproc\fR.
.SH "TWO-PART NAMES"
.PP
The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and
\fBTcl_VarTraceInfo2\fR are identical to \fBTcl_TraceVar\fR,
\fBTcl_UntraceVar\fR, and \fBTcl_VarTraceInfo\fR, respectively,
except that the name of the variable has already been
separated by the caller into two parts.
\fIName1\fR gives the name of a scalar variable or array,
and \fIname2\fR gives the name of an element within an
array.
If \fIname2\fR is NULL it means that either the variable is
a scalar or the trace is to be set on the entire array rather
than an individual element (see WHOLE-ARRAY TRACES below for
more information).
.SH "ACCESSING VARIABLES DURING TRACES"
.PP
During read and write traces, the
trace procedure can read, write, or unset the traced
variable using \fBTcl_GetVar2\fR, \fBTcl_SetVar2\fR, and
other procedures.
While \fIproc\fR is executing, traces are temporarily disabled
for the variable, so that calls to \fBTcl_GetVar2\fR and
\fBTcl_SetVar2\fR will not cause \fIproc\fR or other trace procedures
to be invoked again.
Disabling only occurs for the variable whose trace procedure
is active; accesses to other variables will still be traced.
.VS
However, if a variable is unset during a read or write trace then unset
traces will be invoked.
.VE
.PP
During unset traces the variable has already been completely
expunged.
It is possible for the trace procedure to read or write the
variable, but this will be a new version of the variable.
Traces are not disabled during unset traces as they are for
read and write traces, but existing traces have been removed
from the variable before any trace procedures are invoked.
If new traces are set by unset trace procedures, these traces
will be invoked on accesses to the variable by the trace
procedures.
.SH "CALLBACK TIMING"
.PP
When read tracing has been specified for a variable, the trace
procedure will be invoked whenever the variable's value is
read. This includes \fBset\fR Tcl commands, \fB$\fR-notation
in Tcl commands, and invocations of the \fBTcl_GetVar\fR
and \fBTcl_GetVar2\fR procedures.
\fIProc\fR is invoked just before the variable's value is
returned.
It may modify the value of the variable to affect what
is returned by the traced access.
.VS
If it unsets the variable then the access will return an error
just as if the variable never existed.
.VE
.PP
When write tracing has been specified for a variable, the
trace procedure will be invoked whenever the variable's value
is modified. This includes \fBset\fR commands,
commands that modify variables as side effects (such as
\fBcatch\fR and \fBscan\fR), and calls to the \fBTcl_SetVar\fR
and \fBTcl_SetVar2\fR procedures).
\fIProc\fR will be invoked after the variable's value has been
modified, but before the new value of the variable has been
returned.
It may modify the value of the variable to override the change
and to determine the value actually returned by the traced
access.
.VS
If it deletes the variable then the traced access will return
an empty string.
.VE
.PP
When unset tracing has been specified, the trace procedure
will be invoked whenever the variable is destroyed.
The traces will be called after the variable has been
completely unset.
.SH "WHOLE-ARRAY TRACES"
.PP
If a call to \fBTcl_TraceVar\fR or \fBTcl_TraceVar2\fR specifies
the name of an array variable without an index into the array,
then the trace will be set on the array as a whole.
This means that \fIproc\fR will be invoked whenever any
element of the array is accessed in the ways specified by
\fIflags\fR.
When an array is unset, a whole-array trace will be invoked
just once, with \fIname1\fR equal to the name of the array
and \fIname2\fR NULL; it will not be invoked once for each
element.
.SH "MULTIPLE TRACES"
.PP
It is possible for multiple traces to exist on the same variable.
When this happens, all of the trace procedures will be invoked on each
access, in order from most-recently-created to least-recently-created.
When there exist whole-array traces for an array as well as
traces on individual elements, the whole-array traces are invoked
before the individual-element traces.
.VS
If a read or write trace unsets the variable then all of the unset
traces will be invoked but the remainder of the read and write traces
will be skipped.
.VE
.SH "ERROR RETURNS"
.PP
Under normal conditions trace procedures should return NULL, indicating
successful completion.
If \fIproc\fR returns a non-NULL value it signifies that an
error occurred.
The return value must be a pointer to a static character string
containing an error message.
If a trace procedure returns an error, no further traces are
invoked for the access and the traced access aborts with the
given message.
Trace procedures can use this facility to make variables
read-only, for example (but note that the value of the variable
will already have been modified before the trace procedure is
called, so the trace procedure will have to restore the correct
value).
.PP
The return value from \fIproc\fR is only used during read and
write tracing.
During unset traces, the return value is ignored and all relevant
trace procedures will always be invoked.
.SH "RESTRICTIONS"
.PP
A trace procedure can be called at any time, even when there
is a partially-formed result in the interpreter's result area. If
the trace procedure does anything that could damage this result (such
as calling \fBTcl_Eval\fR) then it must save the original values of
the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore
them before it returns.
.SH "UNDEFINED VARIABLES"
.PP
It is legal to set a trace on an undefined variable.
The variable will still appear to be undefined until the
first time its value is set.
If an undefined variable is traced and then unset, the unset will fail
with an error (``no such variable''), but the trace
procedure will still be invoked.
.SH "TCL_TRACE_DESTROYED FLAG"
.PP
In an unset callback to \fIproc\fR, the TCL_TRACE_DESTROYED bit
is set in \fIflags\fR if the trace is being removed as part
of the deletion.
Traces on a variable are always removed whenever the variable
is deleted; the only time TCL_TRACE_DESTROYED isn't set is for
a whole-array trace invoked when only a single element of an
array is unset.
.SH "TCL_INTERP_DESTROYED"
.PP
When an interpreter is destroyed, unset traces are called for
all of its variables.
The TCL_INTERP_DESTROYED bit will be set in the \fIflags\fR
argument passed to the trace procedures.
Trace procedures must be extremely careful in what they do if
the TCL_INTERP_DESTROYED bit is set.
It is not safe for the procedures to invoke any Tcl procedures
on the interpreter, since its state is partially deleted.
All that trace procedures should do under these circumstances is
to clean up and free their own internal data structures.
.SH BUGS
.PP
Tcl doesn't do any error checking to prevent trace procedures
from misusing the interpreter during traces with TCL_INTERP_DESTROYED
set.
.SH KEYWORDS
clientData, trace, variable

76
contrib/tcl/doc/Translate.3 Normal file
View File

@ -0,0 +1,76 @@
'\"
'\" Copyright (c) 1989-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.
'\"
'\" SCCS: @(#) Translate.3 1.21 96/03/25 20:08:58
'\"
.so man.macros
.TH Tcl_TranslateFileName 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
char *
.VS
\fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR)
.VE
.SH ARGUMENTS
.AS Tcl_DString *bufferPtr
.AP Tcl_Interp *interp in
Interpreter in which to report an error, if any.
.AP char *name in
File name, which may start with a ``~''.
.AP Tcl_DString *bufferPtr in/out
.VS
If needed, this dynamic string is used to store the new file name.
At the time of the call it should be uninitialized or empty. The
caller must eventually call \fBTcl_DStringFree\fR to free up
anything stored here.
.VE
.BE
.SH DESCRIPTION
.PP
.VS
This utility procedure translates a file name to a form suitable for
passing to the local operating system. It converts network names into
native form and does tilde substitution.
.PP
If
\fBTcl_TranslateFileName\fR has to do tilde substitution or translate
the name then it uses
the dynamic string at \fI*bufferPtr\fR to hold the new string it
generates.
After \fBTcl_TranslateFileName\fR returns a non-NULL result, the caller must
eventually invoke \fBTcl_DStringFree\fR to free any information
placed in \fI*bufferPtr\fR. The caller need not know whether or
not \fBTcl_TranslateFileName\fR actually used the string; \fBTcl_TranslateFileName\fR
initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to
\fBTcl_DStringFree\fR will be safe in either case.
.VE
.PP
If an error occurs (e.g. because there was no user by the given
name) then NULL is returned and an error message will be left
at \fIinterp->result\fR.
.VS
When an error occurs, \fBTcl_TranslateFileName\fR
frees the dynamic string itself so that the caller need not call
\fBTcl_DStringFree\fR.
.VE
.PP
The caller is responsible for making sure that \fIinterp->result\fR
has its default empty value when \fBTcl_TranslateFileName\fR is invoked.
.VS
.SH "SEE ALSO"
filename
.VE
.SH KEYWORDS
file name, home directory, tilde, translate, user

76
contrib/tcl/doc/UpVar.3 Normal file
View File

@ -0,0 +1,76 @@
'\"
'\" Copyright (c) 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.
'\"
'\" SCCS: @(#) UpVar.3 1.6 96/03/25 20:09:19
'\"
.so man.macros
.TH Tcl_UpVar 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_UpVar, Tcl_UpVar2 \- link one variable to another
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_UpVar(\fIinterp, frameName, sourceName, destName, flags\fB)\fR
.sp
int
\fBTcl_UpVar2(\fIinterp, frameName, name1, name2, destName, flags\fB)\fR
.SH ARGUMENTS
.AS Tcl_VarTraceProc prevClientData
.AP Tcl_Interp *interp in
Interpreter containing variables; also used for error reporting.
.AP char *frameName in
Identifies the stack frame containing source variable.
May have any of the forms accepted by
the \fBupvar\fR command, such as \fB#0\fR or \fB1\fR.
.AP char *sourceName in
Name of source variable, in the frame given by \fIframeName\fR.
May refer to a scalar variable or to an array variable with a
parenthesized index.
.AP char *destName in
Name of destination variable, which is to be linked to source
variable so that references to \fIdestName\fR
refer to the other variable. Must not currently exist except as
an upvar-ed variable.
.AP int flags in
Either TCL_GLOBAL_ONLY or 0; if non-zero, then \fIdestName\fR is
a global variable; otherwise it is a local to the current procedure
(or global if no procedure is active).
.AP char *name1 in
First part of source variable's name (scalar name, or name of array
without array index).
.AP char *name2 in
If source variable is an element of an array, gives the index of the element.
For scalar source variables, is NULL.
.BE
.SH DESCRIPTION
.PP
\fBTcl_UpVar\fR and \fBTcl_UpVar2\fR provide the same functionality
as the \fBupvar\fR command: they make a link from a source variable
to a destination variable, so that references to the destination are
passed transparently through to the source.
The name of the source variable may be specified either as a single
string such as \fBxyx\fR or \fBa(24)\fR (by calling \fBTcl_UpVar\fR)
or in two parts where the array name has been separated from the
element name (by calling \fBTcl_UpVar2\fR).
The destination variable name is specified in a single string; it
may not be an array element.
.PP
Both procedures return either TCL_OK or TCL_ERROR, and they
leave an error message in \fIinterp->result\fR if an error
occurs.
.PP
As with the \fBupvar\fR command, the source variable need not exist;
if it does exist, unsetting it later does not destroy the link. The
destination variable may exist at the time of the call, but if so
it must exist as a linked variable.
.SH KEYWORDS
linked variable, upvar, variable

109
contrib/tcl/doc/after.n Normal file
View File

@ -0,0 +1,109 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) after.n 1.4 96/03/25 20:09:33
'\"
.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
.SH SYNOPSIS
\fBafter \fIms\fR
.sp
\fBafter \fIms \fR?\fIscript script script ...\fR?
.sp
\fBafter cancel \fIid\fR
.sp
\fBafter cancel \fIscript script script ...\fR
.sp
\fBafter idle \fR?\fIscript script script ...\fR?
.sp
\fBafter info \fR?\fIid\fR?
.BE
.SH DESCRIPTION
.PP
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:
.TP
\fBafter \fIms\fR
\fIMs\fR must be an integer giving a time in milliseconds.
The command sleeps for \fIms\fR milliseconds and then returns.
While the command is sleeping the application does not respond to
events.
.TP
\fBafter \fIms \fR?\fIscript script script ...\fR?
In this form the command returns immediately, but it arranges
for a Tcl command to be executed \fIms\fR milliseconds later as an
event handler.
The command will be executed exactly once, at the given time.
The delayed command is formed by concatenating all the \fIscript\fR
arguments in the same fashion as the \fBconcat\fR 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
\fBbgerror\fR mechanism is used to report the error.
The \fBafter\fR command returns an identifier that can be used
to cancel the delayed command using \fBafter cancel\fR.
.TP
\fBafter cancel \fIid\fR
Cancels the execution of a delayed command that
was previously scheduled.
\fIId\fR indicates which command should be canceled; it must have
been the return value from a previous \fBafter\fR command.
If the command given by \fIid\fR has already been executed then
the \fBafter cancel\fR command has no effect.
.TP
\fBafter cancel \fIscript script ...\fR
This command also cancels the execution of a delayed command.
The \fIscript\fR arguments are concatenated together with space
separators (just as in the \fBconcat\fR 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 \fBafter cancel\fR command has no effect.
.TP
\fBafter idle \fIscript \fR?\fIscript script ...\fR?
Concatenates the \fIscript\fR arguments together with space
separators (just as in the \fBconcat\fR command), and arranges
for the resulting script to be evaluated 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 \fBafter cancel\fR.
If an error occurs while executing the script then the
\fBbgerror\fR mechanism is used to report the error.
.TP
\fBafter info \fR?\fIid\fR?
This command returns information about existing event handlers.
If no \fIid\fR argument is supplied, the command returns
a list of the identifiers for all existing
event handlers created by the \fBafter\fR command for this
interpreter.
If \fIid\fR is supplied, it specifies an existing handler;
\fIid\fR must have been the return value from some previous call
to \fBafter\fR and it must not have triggered yet or been cancelled.
In this case the command returns a list with two elements.
The first element of the list is the script associated
with \fIid\fR, and the second element is either
\fBidle\fR or \fBtimer\fR to indicate what kind of event
handler it is.
.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 "SEE ALSO"
bgerror
.SH KEYWORDS
cancel, delay, idle callback, sleep, time

32
contrib/tcl/doc/append.n Normal file
View File

@ -0,0 +1,32 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) append.n 1.6 96/03/25 20:09:44
'\"
.so man.macros
.TH append n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
append \- Append to variable
.SH SYNOPSIS
\fBappend \fIvarName \fR?\fIvalue value value ...\fR?
.BE
.SH DESCRIPTION
.PP
Append all of the \fIvalue\fR arguments to the current value
of variable \fIvarName\fR. If \fIvarName\fR doesn't exist,
it is given a value equal to the concatenation of all the
\fIvalue\fR arguments.
This command provides an efficient way to build up long
variables incrementally.
For example, ``\fBappend a $b\fR'' is much more efficient than
``\fBset a $a$b\fR'' if \fB$a\fR is long.
.SH KEYWORDS
append, variable

125
contrib/tcl/doc/array.n Normal file
View File

@ -0,0 +1,125 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) array.n 1.7 96/03/25 20:09:58
'\"
.so man.macros
.TH array n 7.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
array \- Manipulate array variables
.SH SYNOPSIS
\fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
This command performs one of several operations on the
variable given by \fIarrayName\fR.
Unless otherwise specified for individual commands below,
\fIarrayName\fR must be the name of an existing array variable.
The \fIoption\fR argument determines what action is carried
out by the command.
The legal \fIoptions\fR (which may be abbreviated) are:
.TP
\fBarray anymore \fIarrayName searchId\fR
Returns 1 if there are any more elements left to be processed
in an array search, 0 if all elements have already been
returned.
\fISearchId\fR indicates which search on \fIarrayName\fR to
check, and must have been the return value from a previous
invocation of \fBarray startsearch\fR.
This option is particularly useful if an array has an element
with an empty name, since the return value from
\fBarray nextelement\fR won't indicate whether the search
has been completed.
.TP
\fBarray donesearch \fIarrayName searchId\fR
This command terminates an array search and destroys all the
state associated with that search. \fISearchId\fR indicates
which search on \fIarrayName\fR to destroy, and must have
been the return value from a previous invocation of
\fBarray startsearch\fR. Returns an empty string.
.TP
\fBarray exists \fIarrayName\fR
.VS
Returns 1 if \fIarrayName\fR is an array variable, 0 if there
is no variable by that name or if it is a scalar variable.
.VE
.TP
\fBarray get \fIarrayName\fR ?\fIpattern\fR?
.VS
Returns a list containing pairs of elements. The first
element in each pair is the name of an element in \fIarrayName\fR
and the second element of each pair is the value of the
array element. The order of the pairs is undefined.
.VS
If \fIpattern\fR is not specified, then all of the elements of the
array are included in the result.
If \fIpattern\fR is specified, then only those elements whose names
match \fIpattern\fR (using the glob-style matching rules of
\fBstring match\fR) are included.
.VE
If \fIarrayName\fR isn't the name of an array variable, or if
the array contains no elements, then an empty list is returned.
.VE
.TP
\fBarray names \fIarrayName\fR ?\fIpattern\fR?
Returns a list containing the names of all of the elements in
.VS
the array that match \fIpattern\fR (using the glob-style matching
rules of \fBstring match\fR).
If \fIpattern\fR 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 \fIarrayName\fR
isn't the name of an array variable, then an empty string is
returned.
.VE
.TP
\fBarray nextelement \fIarrayName searchId\fR
Returns the name of the next element in \fIarrayName\fR, or
an empty string if all elements of \fIarrayName\fR have
already been returned in this search. The \fIsearchId\fR
argument identifies the search, and must have
been the return value of an \fBarray startsearch\fR command.
Warning: if elements are added to or deleted from the array,
then all searches are automatically terminated just as if
\fBarray donesearch\fR had been invoked; this will cause
\fBarray nextelement\fR operations to fail for those searches.
.TP
\fBarray set \fIarrayName list\fR
.VS
Sets the values of one or more elements in \fIarrayName\fR.
\fIlist\fR must have a form like that returned by \fBarray get\fR,
consisting of an even number of elements.
Each odd-numbered element in \fIlist\fR is treated as an element
name within \fIarrayName\fR, and the following element in \fIlist\fR
is used as a new value for that array element.
.VE
.TP
\fBarray size \fIarrayName\fR
Returns a decimal string giving the number of elements in the
array.
.VS
If \fIarrayName\fR isn't the name of an array then 0 is returned.
.VE
.TP
\fBarray startsearch \fIarrayName\fR
This command initializes an element-by-element search through the
array given by \fIarrayName\fR, such that invocations of the
\fBarray nextelement\fR command will return the names of the
individual elements in the array.
When the search has been completed, the \fBarray donesearch\fR
command should be invoked.
The return value is a
search identifier that must be used in \fBarray nextelement\fR
and \fBarray donesearch\fR commands; it allows multiple
searches to be underway simultaneously for the same array.
.SH KEYWORDS
array, element names, search

67
contrib/tcl/doc/bgerror.n Normal file
View File

@ -0,0 +1,67 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) bgerror.n 1.3 96/03/25 20:10:12
'\"
.so man.macros
.TH bgerror n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
bgerror \- Command invoked to process background errors
.SH SYNOPSIS
\fBbgerror \fImessage\fR
.BE
.SH DESCRIPTION
.PP
The \fBbgerror\fR command doesn't exist as built-in part of Tcl. Instead,
individual applications or users can define a \fBbgerror\fR
command (e.g. as a Tcl procedure) if they wish to handle background
errors.
.PP
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 executing a command specified
with the \fBafter\fR 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.
.PP
When Tcl detects a background error, it saves information about the
error and invokes the \fBbgerror\fR command later as an idle event handler.
Before invoking \fBbgerror\fR, Tcl restores the \fBerrorInfo\fR
and \fBerrorCode\fR variables to their values at the time the
error occurred, then it invokes \fBbgerror\fR with
the error message as its only argument.
Tcl assumes that the application has implemented the \fBbgerror\fR
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 \fBbgerror\fR command as long as no error is generated.
.PP
If another Tcl error occurs within the \fBbgerror\fR command
(for example, because no \fBbgerror\fR command has been defined)
then Tcl reports the error itself by writing a message to stderr.
.PP
If several background errors accumulate before \fBbgerror\fR
is invoked to process them, \fBbgerror\fR will be invoked once
for each error, in the order they occurred.
However, if \fBbgerror\fR returns with a break exception, then
any remaining errors are skipped without calling \fBbgerror\fR.
.PP
Tcl has no default implementation for \fBbgerror\fR.
However, in applications using Tk there will be a default
\fBbgerror\fR procedure that posts a dialog box containing
the error message and offers the user a chance to see a stack
trace showing where the error occurred.
.SH KEYWORDS
background error, reporting

34
contrib/tcl/doc/break.n Normal file
View File

@ -0,0 +1,34 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) break.n 1.6 96/03/25 20:10:27
'\"
.so man.macros
.TH break n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
break \- Abort looping command
.SH SYNOPSIS
\fBbreak\fR
.BE
.SH DESCRIPTION
.PP
This command is typically invoked inside the body of a looping command
such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
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 the innermost containing loop command, which then
aborts its execution and returns normally.
Break exceptions are also handled in a few other situations, such
as the \fBcatch\fR command, Tk event bindings, and the outermost
scripts of procedure bodies.
.SH KEYWORDS
abort, break, loop

59
contrib/tcl/doc/case.n Normal file
View File

@ -0,0 +1,59 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) case.n 1.8 96/03/25 20:10:49
'\"
.so man.macros
.TH case n 7.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
case \- Evaluate one of several scripts, depending on a given value
.SH SYNOPSIS
\fBcase\fI string \fR?\fBin\fR? \fIpatList body \fR?\fIpatList body \fR...?
.sp
\fBcase\fI string \fR?\fBin\fR? {\fIpatList body \fR?\fIpatList body \fR...?}
.BE
.SH DESCRIPTION
.PP
\fINote: the \fBcase\fI command is obsolete and is supported only
for backward compatibility. At some point in the future it may be
removed entirely. You should use the \fBswitch\fI command instead.\fR
.PP
The \fBcase\fR command matches \fIstring\fR against each of
the \fIpatList\fR arguments in order.
Each \fIpatList\fR argument is a list of one or
more patterns. If any of these patterns matches \fIstring\fR then
\fBcase\fR evaluates the following \fIbody\fR argument
by passing it recursively to the Tcl interpreter and returns the result
of that evaluation.
Each \fIpatList\fR argument consists of a single
pattern or list of patterns. Each pattern may contain any of the wild-cards
described under \fBstring match\fR. If a \fIpatList\fR
argument is \fBdefault\fR, the corresponding body will be evaluated
if no \fIpatList\fR matches \fIstring\fR. If no \fIpatList\fR argument
matches \fIstring\fR and no default is given, then the \fBcase\fR
command returns an empty string.
.PP
Two syntaxes are provided for the \fIpatList\fR and \fIbody\fR arguments.
The first uses a separate argument for each of the patterns and commands;
this form is convenient if substitutions 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 case commands,
since the braces around the whole list make it unnecessary to include a
backslash at the end of each line.
Since the \fIpatList\fR 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.
.SH KEYWORDS
case, match, regular expression

40
contrib/tcl/doc/catch.n Normal file
View File

@ -0,0 +1,40 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) catch.n 1.6 96/03/25 20:11:08
'\"
.so man.macros
.TH catch n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
catch \- Evaluate script and trap exceptional returns
.SH SYNOPSIS
\fBcatch\fI script \fR?\fIvarName\fR?
.BE
.SH DESCRIPTION
.PP
The \fBcatch\fR command may be used to prevent errors from aborting
command interpretation. \fBCatch\fR calls the Tcl interpreter recursively
to execute \fIscript\fR, and always returns a TCL_OK code, regardless of
any errors that might occur while executing \fIscript\fR. The return
value from \fBcatch\fR is a decimal string giving the
code returned by the Tcl interpreter after executing \fIscript\fR.
This will be \fB0\fR (TCL_OK) if there were no errors in \fIscript\fR;
otherwise
it will have a non-zero value corresponding to one of the exceptional
return codes (see tcl.h for the definitions of code values). If the
\fIvarName\fR argument is given, then it gives the name of a variable;
\fBcatch\fR will set the variable to the string returned
from \fIscript\fR (either a result or an error message).
.PP
Note that \fBcatch\fR catches all exceptions, including those
generated by \fBbreak\fR and \fBcontinue\fR as well as errors.
.SH KEYWORDS
catch, error

28
contrib/tcl/doc/cd.n Normal file
View File

@ -0,0 +1,28 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) cd.n 1.6 96/03/28 08:40:52
'\"
.so man.macros
.TH cd n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
cd \- Change working directory
.SH SYNOPSIS
\fBcd \fR?\fIdirName\fR?
.BE
.SH DESCRIPTION
.PP
Change the current working directory to \fIdirName\fR, or to the
home directory (as specified in the HOME environment variable) if
\fIdirName\fR is not given.
Returns an empty string.
.SH KEYWORDS
working directory

176
contrib/tcl/doc/clock.n Normal file
View File

@ -0,0 +1,176 @@
'\"
'\" Copyright (c) 1992-1995 Karl Lehenbauer and Mark Diekhans.
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" This documentation is derived from the time and date facilities of
'\" TclX, by Mark Diekhans and Karl Lehenbauer.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) clock.n 1.12 96/04/16 08:20:08
'\"
.so man.macros
.TH clock n 7.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
clock \- Obtain and manipulate time
.SH SYNOPSIS
\fBclock \fIoption\fR ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
This command performs one of several operations that may obtain
or manipulate strings or values that represent some notion of
time. The \fIoption\fR argument determines what action is carried
out by the command. The legal \fIoptions\fR (which may be
abbreviated) are:
.TP
\fBclock clicks\fR
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 resolution clock available on the system such as a CPU cycle
counter. This value should only be used for the relative measurement
of elapsed time.
.TP
\fBclock format \fIclockValue\fR ?\fB\-format \fIstring\fR? ?\fB\-gmt \fIboolean\fR?
Converts an integer time value, typically returned by
\fBclock seconds\fR, \fBclock scan\fR, or the \fBatime\fR, \fBmtime\fR,
or \fBctime\fR options of the \fBfile\fR command, to human-readable
form. If the \fB\-format\fR 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 \fB%\fR followed by a field
descriptor character. All other characters are copied into the result.
Valid field descriptors are:
.RS
.IP \fB%%\fR
Insert a %.
.IP \fB%a\fR
Abbreviated weekday name. (Mon, Tue, etc.)
.IP \fB%A\fR
Full weekday name. (Monday, Tuesday, etc.)
.IP \fB%b\fR
Abbreviated month name. (Jan, Feb, etc.)
.IP \fB%B\fR
Full month name.
.IP \fB%d\fR
Day of month (01 - 31).
.IP \fB%D\fR
Date as %m/%d/%y.
.IP \fB%e\fR
Day of month (1 - 31), no leading zeros.
.IP \fB%h\fR
Abbreviated month name.
.IP \fB%H\fR
Hour (00 - 23).
.IP \fB%I\fR
Hour (00 - 12).
.IP \fB%j\fR
Day number of year (001 - 366).
.IP \fB%m\fR
Month number (01 - 12).
.IP \fB%M\fR
Minute (00 - 59).
.IP \fB%n\fR
Insert a newline.
.IP \fB%p\fR
AM or PM.
.IP \fB%r\fR
Time as %I:%M:%S %p.
.IP \fB%R\fR
Time as %H:%M.
.IP \fB%S\fR
Seconds (00 - 59).
.IP \fB%t\fR
Insert a tab.
.IP \fB%T\fR
Time as %H:%M:%S.
.IP \fB%U\fR
Week number of year (01 - 52), Sunday is the first day of the week.
.IP \fB%w\fR
Weekday number (Sunday = 0).
.IP \fB%W\fR
Week number of year (01 - 52), Monday is the first day of the week.
.IP \fB%x\fR
Local specific date format.
.IP \fB%X\fR
Local specific time format.
.IP \fB%y\fR
Year within century (00 - 99).
.IP \fB%Y\fR
Year as ccyy (e.g. 1990)
.IP \fB%Z\fR
Time zone name.
.RE
.sp
.RS
If the \fB\-format\fR argument is not specified, the format string
"\fB%a %b %d %H:%M:%S %Z %Y\fR" is used. If the \fB\-gmt\fR 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.
.RE
.TP
\fBclock scan \fIdateString\fR ?\fB\-base \fIclockVal\fR? ?\fB\-gmt \fIboolean\fR?
Convert \fIdateString\fR to an integer clock value (see \fBclock seconds\fR).
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 \fB\-gmt\fR
argument is true, in which case the clock value is calculated assuming
that the specified time is relative to Greenwich Mean Time.
.sp
If the \fB\-base\fR 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.
.sp
The \fIdateString\fR consists of zero or more specifications of the
following form:
.RS
.TP
\fItime\fR
A time of day, which is of the form: \fIhh\fR?\fI:mm\fR?\fI:ss\fR??
?\fImeridian\fR? ?\fIzone\fR? or \fIhhmm \fR?\fImeridian\fR?
?\fIzone\fR?. If no meridian is specified, \fIhh\fR is interpreted on
a 24-hour clock.
.TP
\fIdate\fR
A specific month and day with optional year. The
acceptable formats are \fImm/dd\fR?\fI/yy\fR?, \fImonthname dd\fR
?, \fIyy\fR?, \fIdd monthname \fR?\fIyy\fR? and \fIday, dd monthname
yy\fR. The default year is the current year. If the year is less
then 100, then 1900 is added to it.
.TP
\fIrelative time\fR
A specification relative to the current time. The format is \fInumber
unit\fR acceptable units are \fByear\fR, \fBfortnight\fR, \fBmonth\fR, \fBweek\fR, \fBday\fR,
\fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR). The
unit can be specified as a singular or plural, as in \fB3 weeks\fR.
These modifiers may also be specified:
\fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR,
\fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR.
.RE
.sp
.RS
The actual date is calculated according to the following 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 produced after allowing for daylight savings time
differences.
.RE
.TP
\fBclock seconds\fR
Return the current date and time as a system-dependent integer value. The
unit of the value is seconds, allowing it to be used for relative time
calculations. The value is usually defined as total elapsed time from
an ``epoch''. You shouldn't assume the value of the epoch.
.SH KEYWORDS
clock, date, time

59
contrib/tcl/doc/close.n Normal file
View File

@ -0,0 +1,59 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) close.n 1.10 96/02/15 20:01:34
'\"
.so man.macros
.TH close n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
close \- Close an open channel.
.SH SYNOPSIS
\fBclose \fIchannelId\fR
.BE
.SH DESCRIPTION
.PP
Closes the channel given by \fIchannelId\fR. \fIChannelId\fR must be a
channel identifier such as the return value from a previous \fBopen\fR
or \fBsocket\fR command.
All buffered output is flushed to the channel's output device,
any buffered input is discarded, the underlying file or device is closed,
and \fIchannelId\fR becomes unavailable for use.
.VS br
.PP
If the channel is blocking, the command does not return until all output
is flushed.
If the channel is nonblocking 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.
.VE
.PP
If \fIchannelId\fR is a blocking channel for a command pipeline then
\fBclose\fR waits for the child processes to complete.
.VS br
.PP
If the channel is shared between interpreters, then \fBclose\fR
makes \fIchannelId\fR unavailable in the invoking interpreter but has no
other effect until all of the sharing interpreters have closed the
channel.
When the last interpreter in which the channel is registered invokes
\fBclose\fR, the cleanup actions described above occur. See the
\fBinterp\fR command for a description of channel sharing.
.PP
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.
.VE
.PP
The command returns an empty string, and may generate an error if
an error occurs while flushing output.
.SH KEYWORDS
blocking, channel, close, nonblocking

44
contrib/tcl/doc/concat.n Normal file
View File

@ -0,0 +1,44 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) concat.n 1.7 96/03/25 20:11:56
'\"
.so man.macros
.TH concat n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
concat \- Join lists together
.SH SYNOPSIS
.VS
\fBconcat\fI \fR?\fIarg arg ...\fR?
.VE
.BE
.SH DESCRIPTION
.PP
This command treats each argument as a list and concatenates them
into a single list.
It also eliminates leading and trailing spaces in the \fIarg\fR's
and adds a single separator space between \fIarg\fR's.
It permits any number of arguments. For example,
the command
.CS
\fBconcat a b {c d e} {f {g h}}\fR
.CE
will return
.CS
\fBa b c d e f {g h}\fR
.CE
as its result.
.PP
.VS
If no \fIarg\fRs are supplied, the result is an empty string.
.VE
.SH KEYWORDS
concatenate, join, lists

34
contrib/tcl/doc/continue.n Normal file
View File

@ -0,0 +1,34 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) continue.n 1.6 96/03/25 20:12:09
'\"
.so man.macros
.TH continue n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
continue \- Skip to the next iteration of a loop
.SH SYNOPSIS
\fBcontinue\fR
.BE
.SH DESCRIPTION
.PP
This command is typically invoked inside the body of a looping command
such as \fBfor\fR or \fBforeach\fR or \fBwhile\fR.
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 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 \fBcatch\fR command and the outermost scripts of procedure
bodies.
.SH KEYWORDS
continue, iteration, loop

27
contrib/tcl/doc/eof.n Normal file
View File

@ -0,0 +1,27 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) eof.n 1.8 96/02/15 20:01:59
'\"
.so man.macros
.TH eof n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
eof \- Check for end of file condition on channel
.SH SYNOPSIS
\fBeof \fIchannelId\fR
.BE
.SH DESCRIPTION
.PP
Returns 1 if an end of file condition occurred during the most
recent input operation on \fIchannelId\fR (such as \fBgets\fR),
0 otherwise.
.SH KEYWORDS
channel, end of file

58
contrib/tcl/doc/error.n Normal file
View File

@ -0,0 +1,58 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) error.n 1.7 96/03/25 20:12:35
'\"
.so man.macros
.TH error n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
error \- Generate an error
.SH SYNOPSIS
\fBerror \fImessage\fR ?\fIinfo\fR? ?\fIcode\fR?
.BE
.SH DESCRIPTION
.PP
Returns a TCL_ERROR code, which causes command interpretation to be
unwound. \fIMessage\fR is a string that is returned to the application
to indicate what went wrong.
.PP
If the \fIinfo\fR argument is provided and is non-empty,
it is used to initialize the global variable \fBerrorInfo\fR.
\fBerrorInfo\fR 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 \fBerrorInfo\fR. If the
\fIinfo\fR argument is present, it is used to initialize
\fBerrorInfo\fR and the first increment of unwind information
will not be added by the Tcl interpreter. In other
words, the command containing the \fBerror\fR command will not appear
in \fBerrorInfo\fR; in its place will be \fIinfo\fR.
This feature is most useful in conjunction with the \fBcatch\fR command:
if a caught error cannot be handled successfully, \fIinfo\fR can be used
to return a stack trace reflecting the original point of occurrence
of the error:
.CS
\fBcatch {...} errMsg
set savedInfo $errorInfo
\&...
error $errMsg $savedInfo\fR
.CE
.PP
If the \fIcode\fR argument is present, then its value is stored
in the \fBerrorCode\fR global variable. This variable is intended
to hold a machine-readable description of the error in cases where
such information is available; see the \fBtclvars\fR manual
page for information on the proper format for the variable.
If the \fIcode\fR argument is not
present, then \fBerrorCode\fR is automatically reset to
``NONE'' by the Tcl interpreter as part of processing the
error generated by the command.
.SH KEYWORDS
error, errorCode, errorInfo

30
contrib/tcl/doc/eval.n Normal file
View File

@ -0,0 +1,30 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) eval.n 1.5 96/03/25 20:12:53
'\"
.so man.macros
.TH eval n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
eval \- Evaluate a Tcl script
.SH SYNOPSIS
\fBeval \fIarg \fR?\fIarg ...\fR?
.BE
.SH DESCRIPTION
.PP
\fBEval\fR takes one or more arguments, which together comprise a Tcl
script containing one or more commands.
\fBEval\fR concatenates all its arguments in the same
fashion as the \fBconcat\fR command, passes the concatenated string to the
Tcl interpreter recursively, and returns the result of that
evaluation (or any error generated by it).
.SH KEYWORDS
concatenate, evaluate, script

185
contrib/tcl/doc/exec.n Normal file
View File

@ -0,0 +1,185 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) exec.n 1.12 96/03/25 20:13:20
'\"
.so man.macros
.TH exec n 7.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
exec \- Invoke subprocess(es)
.SH SYNOPSIS
\fBexec \fR?\fIswitches\fR? \fIarg \fR?\fIarg ...\fR?
.BE
.SH DESCRIPTION
.PP
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 \fIarg\fR becomes one word of a command, and
each distinct command becomes a subprocess.
.PP
If the initial arguments to \fBexec\fR start with \fB\-\fR then
.VS
they are treated as command-line switches and are not part
of the pipeline specification. The following switches are
currently supported:
.TP 13
\fB\-keepnewline\fR
Retains a trailing newline in the pipeline's output.
Normally a trailing newline will be deleted.
.TP 13
\fB\-\|\-\fR
Marks the end of switches. The argument following this one will
be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
.VE
.PP
If an \fIarg\fR (or pair of \fIarg\fR's) has one of the forms
described below then it is used by \fBexec\fR to control the
flow of input and output among the subprocess(es).
Such arguments will not be passed to the subprocess(es). In forms
.VS
such as ``< \fIfileName\fR'' \fIfileName\fR may either be in a
separate argument from ``<'' or in the same argument with no
intervening space (i.e. ``<\fIfileName\fR'').
.VE
.TP 15
|
Separates distinct commands in the pipeline. The standard output
of the preceding command will be piped into the standard input
of the next command.
.TP 15
|&
Separates distinct commands in the pipeline. Both standard output
and standard error of the preceding command will be piped into
the standard input of the next command.
This form of redirection overrides forms such as 2> and >&.
.TP 15
<\0\fIfileName\fR
The file named by \fIfileName\fR is opened and used as the standard
input for the first command in the pipeline.
.TP 15
<@\0\fIfileId\fR
.VS
\fIFileId\fR must be the identifier for an open file, such as the return
value from a previous call to \fBopen\fR.
It is used as the standard input for the first command in the pipeline.
\fIFileId\fR must have been opened for reading.
.VE
.TP 15
<<\0\fIvalue\fR
\fIValue\fR is passed to the first command as its standard input.
.TP 15
>\0\fIfileName\fR
Standard output from the last command is redirected to the file named
\fIfileName\fR, overwriting its previous contents.
.TP 15
2>\0\fIfileName\fR
.VS
Standard error from all commands in the pipeline is redirected to the
file named \fIfileName\fR, overwriting its previous contents.
.TP 15
>&\0\fIfileName\fR
Both standard output from the last command and standard error from all
commands are redirected to the file named \fIfileName\fR, overwriting
its previous contents.
.VE
.TP 15
>>\0\fIfileName\fR
Standard output from the last command is
redirected to the file named \fIfileName\fR, appending to it rather
than overwriting it.
.TP 15
2>>\0\fIfileName\fR
.VS
Standard error from all commands in the pipeline is
redirected to the file named \fIfileName\fR, appending to it rather
than overwriting it.
.TP 15
>>&\0\fIfileName\fR
Both standard output from the last command and standard error from
all commands are redirected to the file named \fIfileName\fR,
appending to it rather than overwriting it.
.TP 15
>@\0\fIfileId\fR
\fIFileId\fR must be the identifier for an open file, such as the return
value from a previous call to \fBopen\fR.
Standard output from the last command is redirected to \fIfileId\fR's
file, which must have been opened for writing.
.TP 15
2>@\0\fIfileId\fR
\fIFileId\fR must be the identifier for an open file, such as the return
value from a previous call to \fBopen\fR.
Standard error from all commands in the pipeline is
redirected to \fIfileId\fR's file.
The file must have been opened for writing.
.TP 15
>&@\0\fIfileId\fR
\fIFileId\fR must be the identifier for an open file, such as the return
value from a previous call to \fBopen\fR.
Both standard output from the last command and standard error from
all commands are redirected to \fIfileId\fR's file.
The file must have been opened for writing.
.VE
.PP
If standard output has not been redirected then the \fBexec\fR
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 \fBexec\fR will return an error
and the error message will include the pipeline's output followed by
error messages describing the abnormal terminations; the
\fBerrorCode\fR 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 \fBexec\fR will return an error; the error message
will include the pipeline's standard output, followed by messages
about abnormal terminations (if any), followed by the standard error
output.
.PP
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.
.VS
However, if \fB\-keepnewline\fR is specified then the trailing
newline is retained.
.VE
.PP
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 standard input.
.PP
If the last \fIarg\fR is ``&'' then the pipeline will be
executed in background.
.VS
In this case the \fBexec\fR command will return a list whose
elements are the process identifiers for all of the subprocesses
in the pipeline.
.VE
The standard output from the last command in the pipeline will
go to the application's standard output if it hasn't been
redirected, and error output from all of
the commands in the pipeline will go to the application's
standard error file unless redirected.
.PP
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 substitutions
are performed on the arguments to commands.
.SH KEYWORDS
execute, pipeline, redirection, subprocess

28
contrib/tcl/doc/exit.n Normal file
View File

@ -0,0 +1,28 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) exit.n 1.6 96/03/25 20:13:32
'\"
.so man.macros
.TH exit n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
exit \- End the application
.SH SYNOPSIS
\fBexit \fR?\fIreturnCode\fR?
.BE
.SH DESCRIPTION
.PP
Terminate the process, returning \fIreturnCode\fR to the
system as the exit status.
If \fIreturnCode\fR isn't specified then it defaults
to 0.
.SH KEYWORDS
exit, process

299
contrib/tcl/doc/expr.n Normal file
View File

@ -0,0 +1,299 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) expr.n 1.17 96/03/14 10:54:40
'\"
.so man.macros
.TH expr n 7.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
expr \- Evaluate an expression
.SH SYNOPSIS
\fBexpr \fIarg \fR?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
.VS
Concatenates \fIarg\fR's (adding separator spaces between them),
evaluates the result as a Tcl expression, and returns the value.
.VE
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 corresponding C operators.
Expressions almost always yield numeric results
(integer or floating-point values).
For example, the expression
.CS
\fBexpr 8.2 + 6\fR
.CE
evaluates to 14.2.
Tcl expressions differ from C expressions in the way that
operands are specified. Also, Tcl expressions support
non-numeric operands and string comparisons.
.SH OPERANDS
.PP
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 processor.
Where possible, operands are interpreted as integer values.
Integer values may be specified in decimal (the normal case), in octal (if the
first character of the operand is \fB0\fR), or in hexadecimal (if the first
two characters of the operand are \fB0x\fR).
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'' suffixes 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 interpretation is possible, then an operand is left
as a string (and only a limited set of operators may be applied to
it).
.PP
Operands may be specified in any of the following ways:
.IP [1]
As an numeric value, either integer or floating-point.
.IP [2]
As a Tcl variable, using standard \fB$\fR notation.
The variable's value will be used as the operand.
.IP [3]
As a string enclosed in double-quotes.
The expression parser will perform backslash, variable, and
command substitutions on the information between the quotes,
and use the resulting value as the operand
.IP [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 substitutions.
.IP [5]
As a Tcl command enclosed in brackets.
The command will be executed and its result will be used as
the operand.
.IP [6]
.VS
As a mathematical function whose arguments have any of the above
forms for operands, such as ``\fBsin($x)\fR''. See below for a list of defined
functions.
.VE
.LP
Where substitutions occur above (e.g. inside quoted strings), they
are performed by the expression processor.
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.
.PP
For some examples of simple expressions, suppose the variable
\fBa\fR has the value 3 and
the variable \fBb\fR 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:
.CS
.ta 6c
\fBexpr 3.1 + $a 6.1
expr 2 + "$a.$b" 5.6
expr 4*[llength "6 2"] 8
expr {{word one} < "word $a"} 0\fR
.CE
.SH OPERATORS
.PP
The valid operators are listed below, grouped in decreasing order
of precedence:
.TP 20
\fB\-\0\0+\0\0~\0\0!\fR
.VS
Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
.VE
may be applied to string operands, and bit-wise NOT may be
applied only to integers.
.TP 20
\fB*\0\0/\0\0%\fR
Multiply, divide, remainder. None of these operands may be
applied to string operands, and remainder may be applied only
to integers.
.VS
The remainder will always have the same sign as the divisor and
an absolute value smaller than the divisor.
.VE
.TP 20
\fB+\0\0\-\fR
Add and subtract. Valid for any numeric operands.
.TP 20
\fB<<\0\0>>\fR
Left and right shift. Valid for integer operands only.
A right shift always propagates the sign bit.
.TP 20
\fB<\0\0>\0\0<=\0\0>=\fR
Boolean less, greater, less than or equal, and greater than or equal.
Each operator produces 1 if the condition is true, 0 otherwise.
These operators may be applied to strings as well as numeric operands,
in which case string comparison is used.
.TP 20
\fB==\0\0!=\fR
Boolean equal and not equal. Each operator produces a zero/one result.
Valid for all operand types.
.TP 20
\fB&\fR
Bit-wise AND. Valid for integer operands only.
.TP 20
\fB^\fR
Bit-wise exclusive OR. Valid for integer operands only.
.TP 20
\fB|\fR
Bit-wise OR. Valid for integer operands only.
.TP 20
\fB&&\fR
Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise.
Valid for numeric operands only (integers or floating-point).
.TP 20
\fB||\fR
Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
Valid for numeric operands only (integers or floating-point).
.TP 20
\fIx\fB?\fIy\fB:\fIz\fR
If-then-else, as in C. If \fIx\fR
evaluates to non-zero, then the result is the value of \fIy\fR.
Otherwise the result is the value of \fIz\fR.
The \fIx\fR operand must have a numeric value.
.LP
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
.CS
\fBexpr 4*2 < 7\fR
.CE
returns 0.
.PP
The \fB&&\fR, \fB||\fR, and \fB?:\fR 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
.CS
\fBexpr {$v ? [a] : [b]}\fR
.CE
only one of \fB[a]\fR or \fB[b]\fR will actually be evaluated,
depending on the value of \fB$v\fR. Note, however, that this is
only true if the entire expression is enclosed in braces; otherwise
the Tcl parser will evaluate both \fB[a]\fR and \fB[b]\fR before
invoking the \fBexpr\fR command.
.SH "MATH FUNCTIONS"
.PP
.VS
Tcl supports the following mathematical functions in expressions:
.DS
.ta 3c 6c 9c
\fBacos\fR \fBcos\fR \fBhypot\fR \fBsinh\fR
\fBasin\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR
\fBatan\fR \fBexp\fR \fBlog10\fR \fBtan\fR
\fBatan2\fR \fBfloor\fR \fBpow\fR \fBtanh\fR
\fBceil\fR \fBfmod\fR \fBsin\fR
.DE
Each of these functions invokes the math library function of the same
name; see the manual entries for the library functions for details
on what they do. Tcl also implements the following functions for
conversion between integers and floating-point numbers:
.TP
\fBabs(\fIarg\fB)\fR
Returns the absolute value of \fIarg\fR. \fIArg\fR may be either
integer or floating-point, and the result is returned in the same form.
.TP
\fBdouble(\fIarg\fB)\fR
If \fIarg\fR is a floating value, returns \fIarg\fR, otherwise converts
\fIarg\fR to floating and returns the converted value.
.TP
\fBint(\fIarg\fB)\fR
If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts
\fIarg\fR to integer by truncation and returns the converted value.
.TP
\fBround(\fIarg\fB)\fR
If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts
\fIarg\fR to integer by rounding and returns the converted value.
.PP
In addition to these predefined functions, applications may
define additional functions using \fBTcl_CreateMathFunc\fR().
.VE
.SH "TYPES, OVERFLOW, AND PRECISION"
.PP
All internal computations involving integers are done with the C type
\fIlong\fR, and all internal computations involving floating-point are
done with the C type \fIdouble\fR.
When converting 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.
.PP
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,
.CS
\fBexpr 5 / 4\fR
.CE
returns 1, while
.CS
\fBexpr 5 / 4.0\fR
\fBexpr 5 / ( [string length "abcd"] + 0.0 )\fR
.CE
both return 1.25.
.VS
Floating-point values are always returned with a ``.''
or an ``e'' so that they will not look like integer values. For
example,
.CS
\fBexpr 20.0/5.0\fR
.CE
returns ``4.0'', not ``4''. The global variable \fBtcl_precision\fR
determines the the number of significant digits that are retained
when floating values are converted to strings (except that trailing
zeroes are omitted). If \fBtcl_precision\fR
is unset then 6 digits of precision are used.
To retain all of the significant bits of an IEEE floating-point
number set \fBtcl_precision\fR to 17; if a value is converted to
string with 17 digits of precision and then converted back to binary
for some later calculation, the resulting binary value is guaranteed
to be identical to the original one.
.VE
.SH "STRING OPERATIONS"
.PP
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.
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 \fIsprintf\fR format specifier
\fB%d\fR for integers and \fB%g\fR for floating-point values.
For example, the commands
.CS
\fBexpr {"0x03" > "2"}\fR
\fBexpr {"0y" < "0x12"}\fR
.CE
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''.
.VS
Because of Tcl's tendency to treat values as numbers whenever
possible, it isn't generally a good idea to use operators like \fB==\fR
when you really want string comparison and the values of the
operands could be arbitrary; it's better in these cases to use the
\fBstring compare\fR command instead.
.VE
.SH KEYWORDS
arithmetic, boolean, compare, expression

32
contrib/tcl/doc/fblocked.n Normal file
View File

@ -0,0 +1,32 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) fblocked.n 1.6 96/02/23 13:46:30
.so man.macros
.TH fblocked n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
fblocked \- Test whether the last input operation exhausted all available input
.SH SYNOPSIS
\fBfblocked \fIchannelId\fR
.BE
.SH DESCRIPTION
.PP
The \fBfblocked\fR command returns 1 if the most recent input operation
on \fIchannelId\fR returned less information than requested because all
available input was exhausted.
For example, if \fBgets\fR is invoked when there are only three
characters available for input and no end-of-line sequence, \fBgets\fR
returns an empty string and a subsequent call to \fBfblocked\fR will
return 1.
.PP
.SH "SEE ALSO"
gets(n), read(n)
.SH KEYWORDS
blocking, nonblocking

178
contrib/tcl/doc/fconfigure.n Normal file
View File

@ -0,0 +1,178 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) fconfigure.n 1.23 96/04/16 08:20:07
'\"
.so man.macros
.TH fconfigure n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
fconfigure \- Set and get options on a channel
.SH SYNOPSIS
.nf
\fBfconfigure \fIchannelId\fR
\fBfconfigure \fIchannelId\fR \fIname\fR
\fBfconfigure \fIchannelId\fR \fIname value \fR?\fIname value ...\fR?
.fi
.BE
.SH DESCRIPTION
.PP
The \fBfconfigure\fR command sets and retrieves options for channels.
\fIChannelId\fR identifies the channel for which to set or query an option.
If no \fIname\fR or \fIvalue\fR arguments are supplied, the command
returns a list containing alternating option names and values for the channel.
If \fIname\fR is supplied but no \fIvalue\fR then the command returns
the current value of the given option.
If one or more pairs of \fIname\fR and \fIvalue\fR are supplied, the
command sets each of the named options to the corresponding \fIvalue\fR;
in this case the return value is an empty string.
.PP
The options described below are supported for all channels. 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 \fBsocket\fR command for its additional options.
.TP
\fB\-blocking\fR \fIboolean\fR
The \fB\-blocking\fR option determines whether I/O operations 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
nonblocking mode it will affect the operation of the \fBgets\fR,
\fBread\fR, \fBputs\fR, \fBflush\fR, and \fBclose\fR commands;
see the documentation for those commands for details.
For nonblocking mode to work correctly, the application must be
using the Tcl event loop (e.g. by calling \fBTcl_DoOneEvent\fR or
invoking the \fBvwait\fR command).
.TP
\fB\-buffering\fR \fInewValue\fR
If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output
until its internal buffer is full or until the \fBflush\fR command is
invoked. If \fInewValue\fR is \fBline\fR, then the I/O system will
automatically flush output for the channel whenever a newline character
is output. If \fInewValue\fR is \fBnone\fR, the I/O system will flush
automatically after every output operation.
The default is for \fB\-buffering\fR to be set to \fBfull\fR except for
channels that connect to terminal-like devices; for these channels the
initial setting is \fBline\fR.
.TP
\fB\-buffersize\fR \fInewSize\fR
\fINewvalue\fR 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 output. \fINewvalue\fR must be between ten and one million, allowing
buffers of ten to one million bytes in size.
.TP
\fB\-eofchar\fR \fIchar\fR
.TP
\fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR
This option supports DOS file systems that use Control-z (\ex1a) as
an end of file marker.
If \fIchar\fR 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 \fIchar\fR is the empty string, then there is no special
end of file character marker.
For read-write channels, a two-element 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 \fB\-eofchar\fR is the empty string in all
cases except for files under Windows. In that case the \fB\-eofchar\fR
is Control-z (\ex1a) for reading and the empty string for writing.
.TP
\fB\-translation\fR \fImode\fR
.TP
\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR
In Tcl scripts the end of a line is always represented using a
single newline character (\en).
However, in actual files and devices the end of a line may be
represented differently on different platforms, 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 \fBgets\fP and \fBread\fP)
the Tcl I/O system automatically translates the external end-of-line
representation into newline characters.
Upon output (i.e., with \fBputs\fP),
the I/O system translates newlines to the external
end-of-line representation.
The default translation mode, \fBauto\fP, handles all the common
cases automatically, but the \fB\-translation\fR option provides
explicit control over the end of line translations.
.RS
.PP
The value associated with \fB\-translation\fR is a single item for
read-only and write-only channels.
The value is a two-element list for read-write channels;
the read translation mode is the first element 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:
.TP
\fBauto\fR
As the input translation mode, \fBauto\fR treats any of newline (\fBlf\fP),
carriage return (\fBcr\fP), or carriage return followed by a newline (\fBcrlf\fP)
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, \fBauto\fR chooses a platform specific
representation; for sockets on all platforms Tcl
chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, for the
Macintosh platform it chooses \fBcr\fR and for the various flavors of
Windows it chooses \fBcrlf\fR.
The default setting for \fB\-translation\fR is \fBauto\fR for both
input and output.
.TP
\fBbinary\fR
No end-of-line translations are performed. This is nearly identical to
\fBlf\fP mode, except that in addition \fBbinary\fP mode also sets the
end of file character to the empty string, which disables it.
See the description of
\fB\-eofchar\fP for more information.
.TP
\fBcr\fR
The end of a line in the underlying file or device is represented
by a single carriage return character.
As the input translation mode, \fBcr\fP mode converts carriage returns
to newline characters.
As the output translation mode, \fBcr\fP mode
translates newline characters to carriage returns.
This mode is typically used on Macintosh platforms.
.TP
\fBcrlf\fR
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, \fBcrlf\fP mode converts
carriage-return-linefeed sequences
to newline characters.
As the output translation mode, \fBcrlf\fP mode
translates newline characters to
carriage-return-linefeed sequences.
This mode is typically used on Windows platforms and for network
connections.
.TP
\fBlf\fR
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.
.RE
.PP
.SH "SEE ALSO"
close(n), flush(n), gets(n), puts(n), read(n), socket(n)
.SH KEYWORDS
blocking, buffering, carriage return, end of line, flushing, linemode,
newline, nonblocking, platform, translation

217
contrib/tcl/doc/file.n Normal file
View File

@ -0,0 +1,217 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) file.n 1.13 96/04/11 17:03:13
'\"
.so man.macros
.TH file n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
file \- Manipulate file names and attributes
.SH SYNOPSIS
\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
.VS
This command provides several operations on a file's name or attributes.
\fIName\fR is the name of a file;
if it starts with a tilde, then tilde substitution is done before
executing the command (see the manual entry for \fBfilename\fR
for details).
.VE
\fIOption\fR indicates what to do with the file name. Any unique
abbreviation for \fIoption\fR is acceptable. The valid options are:
.TP
\fBfile atime \fIname\fR
Returns a decimal string giving the time at which file \fIname\fR
was last accessed. 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 access time cannot be queried then an
error is generated.
.TP
\fBfile dirname \fIname\fR
.VS
Returns a name comprised of all of the path components in \fIname\fR
excluding the last element. If \fIname\fR is a relative file name and
only contains one path element, then returns ``\fB.\fR'' (or ``\fB:\fR''
on the Macintosh). If \fIname\fR refers to a root directory, then the
root directory is returned. For example,
.RS
.CS
\fBfile dirname c:/\fR
.CE
returns \fBc:/\fR.
.PP
Note that tilde substitution will only be
performed if it is necessary to complete the command. For example,
.CS
\fBfile dirname ~/src/foo.c\fR
.CE
returns \fB~/src\fR, whereas
.CS
\fBfile dirname ~\fR
.CE
returns \fB/home\fR (or something similar).
.RE
.VE
.TP
\fBfile executable \fIname\fR
Returns \fB1\fR if file \fIname\fR is executable by
the current user, \fB0\fR otherwise.
Under UNIX this command uses the real user and group identifiers,
not the effective ones.
.TP
\fBfile exists \fIname\fR
Returns \fB1\fR if file \fIname\fR exists and the current user has
search privileges for the directories leading to it, \fB0\fR otherwise.
.TP
\fBfile extension \fIname\fR
Returns all of the characters in \fIname\fR after and including the
last dot in the last element of \fIname\fR. If there is no dot in
the last element of \fIname\fR then returns
the empty string.
.TP
\fBfile isdirectory \fIname\fR
Returns \fB1\fR if file \fIname\fR is a directory,
\fB0\fR otherwise.
.TP
\fBfile isfile \fIname\fR
Returns \fB1\fR if file \fIname\fR is a regular file,
\fB0\fR otherwise.
.VS br
.TP
\fBfile join \fIname\fR ?\fIname ...\fR?
Takes one or more file names and combines them, using the correct
path separator for the current platform. If a particular \fIname\fR is
relative, then it will be joined to the previous file name argument.
Otherwise, any earlier arguments will be discarded, and joining will
proceed from the current argument. For example,
.RS
.CS
\fBfile join a b /foo bar\fR
.CE
returns \fB/foo/bar\fR.
.PP
Note that any of the names can contain separators, and that the result
is always canonical for the current platform: \fB/\fR for Unix and
Windows, and \fB:\fR for Macintosh.
.RE
.VE
.TP
\fBfile lstat \fIname varName\fR
Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
kernel call instead of \fIstat\fR. This means that if \fIname\fR
refers to a symbolic link the information returned in \fIvarName\fR
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 \fBstat\fR option.
.TP
\fBfile mtime \fIname\fR
Returns a decimal string giving the time at which file \fIname\fR
was last modified. 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 then an
error is generated.
.TP
\fBfile owned \fIname\fR
Returns \fB1\fR if file \fIname\fR is owned by the current user,
\fB0\fR otherwise.
.VS br
.TP
\fBfile pathtype \fIname\fR
Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If
\fIname\fR refers to a specific file on a specific volume, the path type
will be \fBabsolute\fR. If \fIname\fR refers to a file relative to the
current working directory, then the path type will be \fBrelative\fR. If
\fIname\fR refers to a file relative to the current working directory on
a specified volume, or to a specific file on the current working volume, then
the file type is \fBvolumerelative\fR.
.VE
.TP
\fBfile readable \fIname\fR
Returns \fB1\fR if file \fIname\fR is readable by
the current user, \fB0\fR otherwise.
Under UNIX this command uses the real user and group identifiers,
not the effective ones.
.TP
\fBfile readlink \fIname\fR
Returns the value of the symbolic link given by \fIname\fR (i.e. the
name of the file it points to). If
\fIname\fR 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 undefined.
.TP
\fBfile rootname \fIname\fR
Returns all of the characters in \fIname\fR up to but not including
the last ``.'' character in the last component of name. If the last
component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.
.TP
\fBfile size \fIname\fR
Returns a decimal string giving the size of file \fIname\fR in bytes.
If the file doesn't exist or its size cannot be queried then an
error is generated.
.VS br
.TP
\fBfile split \fIname\fR
Returns a list whose elements are the path components in \fIname\fR. The
first element of the list will have the same path type as \fIname\fR.
All other elements will be relative. Path separators will be discarded
unless they are needed ensure that an element is unambiguously relative.
For example, under Unix
.RS
.CS
\fBfile split /foo/~bar/baz\fR
.CE
returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands
that use the third component do not attempt to perform tilde
substitution.
.RE
.VE
.TP
\fBfile stat \fIname varName\fR
Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the
variable given by \fIvarName\fR to hold information returned from
the kernel call.
\fIVarName\fR is treated as an array variable,
and the following elements of that variable are set: \fBatime\fR,
\fBctime\fR, \fBdev\fR, \fBgid\fR, \fBino\fR, \fBmode\fR, \fBmtime\fR,
\fBnlink\fR, \fBsize\fR, \fBtype\fR, \fBuid\fR.
Each element except \fBtype\fR is a decimal string with the value of
the corresponding field from the \fBstat\fR return structure; see the
manual entry for \fBstat\fR for details on the meanings of the values.
The \fBtype\fR element gives the type of the file in the same form
returned by the command \fBfile type\fR.
This command returns an empty string.
.TP
\fBfile tail \fIname\fR
.VS
Returns all of the characters in \fIname\fR after the last directory
separator. If \fIname\fR contains no separators then returns
\fIname\fR.
.VE
.TP
\fBfile type \fIname\fR
Returns a string giving the type of file \fIname\fR, which will be
one of \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR,
\fBblockSpecial\fR, \fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
.TP
\fBfile writable \fIname\fR
Returns \fB1\fR if file \fIname\fR is writable by
the current user, \fB0\fR otherwise.
Under UNIX this command uses the real user and group identifiers,
not the effective ones.
.VS
.SH "SEE ALSO"
filename
.VE
.SH KEYWORDS
attributes, directory, file, name, stat

109
contrib/tcl/doc/fileevent.n Normal file
View File

@ -0,0 +1,109 @@
'\"
'\" Copyright (c) 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.
'\"
'\" SCCS: @(#) fileevent.n 1.6 96/02/23 13:46:29
'\"
.so man.macros
.TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
fileevent \- Execute a script when a channel becomes readable or writable
.SH SYNOPSIS
\fBfileevent \fIchannelId \fBreadable \fR?\fIscript\fR?
.sp
\fBfileevent \fIchannelId \fBwritable \fR?\fIscript\fR?
.BE
.SH DESCRIPTION
.PP
This command is used to create \fIfile event handlers\fR. 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 \fBgets\fR or \fBread\fR 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 \fBfileevent\fR, the process can
tell when data is present and only invoke \fBgets\fR or \fBread\fR when
they won't block.
.PP
The \fIchannelId\fR argument to \fBfileevent\fR refers to an open channel,
such as the return value from a previous \fBopen\fR or \fBsocket\fR
command.
If the \fIscript\fR argument is specified, then \fBfileevent\fR
creates a new event handler: \fIscript\fR will be evaluated
whenever the channel becomes readable or writable (depending on the
second argument to \fBfileevent\fR).
In this case \fBfileevent\fR returns an empty string.
The \fBreadable\fR and \fBwritable\fR event handlers for a file
are independent, and may be created and deleted separately.
However, there may be at most one \fBreadable\fR and one \fBwritable\fR
handler for a file at a given time in a given interpreter.
If \fBfileevent\fR is called when the specified handler already
exists in the invoking interpreter, the new script replaces the old one.
.PP
If the \fIscript\fR argument is not specified, \fBfileevent\fR
returns the current script for \fIchannelId\fR, or an empty string
if there is none.
If the \fIscript\fR 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.
.PP
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 \fBgets\fR
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 considered to be readable if an end of file or
error condition is present on the underlying file or device.
It is important for \fIscript\fR 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 \fIscript\fR
reads no data, returns, and is immediately invoked again.
.PP
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 present on the underlying file or device.
.PP
Event-driven I/O works best for channels that have been
placed into nonblocking mode with the \fBfconfigure\fR command.
In blocking mode, a \fBputs\fR command may block if you give it
more data than the underlying file or device can accept, and a
\fBgets\fR or \fBread\fR 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 \fBputs\fR, \fBread\fR, and \fBgets\fR never block.
See the documentation for the individual commands for information
on how they handle blocking and nonblocking channels.
.PP
The script for a file event is executed at global level (outside the
context of any Tcl procedure) in the interpreter in which the
\fBfileevent\fR command was invoked.
If an error occurs while executing the script then the
\fBbgerror\fR 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.
.SH CREDITS
.PP
\fBfileevent\fR is based on the \fBaddinput\fR command created
by Mark Diekhans.
.SH "SEE ALSO"
bgerror, fconfigure, gets, puts, read
.SH KEYWORDS
asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
script, writable.

197
contrib/tcl/doc/filename.n Normal file
View File

@ -0,0 +1,197 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) filename.n 1.7 96/04/11 17:03:14
'\"
.so man.macros
.TH filename n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
filename \- File name conventions supported by Tcl commands
.BE
.SH INTRODUCTION
.PP
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 platform, Tcl supports file names in the
standard forms(s) for that platform. In addition, on all platforms,
Tcl supports 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 particular form for file names.
Instead, portable scripts must use the \fBfile split\fR and \fBfile
join\fR commands to manipulate file names (see the \fBfile\fR manual
entry for more details).
.SH PATH TYPES
.PP
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 relative 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. Volume-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 specified
volume. The \fBfile pathtype\fR command can be used to determine the
type of a given path.
.SH PATH SYNTAX
.PP
The rules for native names depend on the value reported in the Tcl
array element \fBtcl_platform(platform)\fR:
.TP 10
\fBmac\fR
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 \fB::\fR refers to the
parent of the current directory, \fB:::\fR refers to the parent of the
parent, and so forth.
.RS
.PP
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 separator. The file name
\fB\&.\fR refers to the current directory, and \fB\&..\fR refers to the
parent of the current directory. However, some names like \fB/\fR or
\fB/..\fR have no mapping, and are interpreted as Macintosh names. In
general, commands that generate file names will return Macintosh style
names, but commands that accept file names will take both Macintosh
and Unix-style names.
.PP
The following examples illustrate various forms of path names:
.TP 15
\fB:\fR
Relative path to the current folder.
.TP 15
\fBMyFile\fR
Relative path to a file named \fBMyFile\fR in the current folder.
.TP 15
\fBMyDisk:MyFile\fR
Absolute path to a file named \fBMyFile\fR on the device named \fBMyDisk\fR.
.TP 15
\fB:MyDir:MyFile\fR
Relative path to a file name \fBMyFile\fR in a folder named
\fBMyDir\fR in the current folder.
.TP 15
\fB::MyFile\fR
Relative path to a file named \fBMyFile\fR in the folder above the
current folder.
.TP 15
\fB:::MyFile\fR
Relative path to a file named \fBMyFile\fR in the folder two levels above the
current folder.
.TP 15
\fB/MyDisk/MyFile\fR
Absolute path to a file named \fBMyFile\fR on the device named
\fBMyDisk\fR.
.TP 15
\fB\&../MyFile\fR
Relative path to a file named \fBMyFile\fR in the folder above the
current folder.
.RE
.TP
\fBunix\fR
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
\fB\&.\fR and \fB\&..\fR 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:
.RS
.TP 15
\fB/\fR
Absolute path to the root directory.
.TP 15
\fB/etc/passwd\fR
Absolute path to the file named \fBpasswd\fR in the directory
\fBetc\fR in the root directory.
.TP 15
\fB\&.\fR
Relative path to the current directory.
.TP 15
\fBfoo\fR
Relative path to the file \fBfoo\fR in the current directory.
.TP 15
\fBfoo/bar\fR
Relative path to the file \fBbar\fR in the directory \fBfoo\fR in the
current directory.
.TP 15
\fB\&../foo\fR
Relative path to the file \fBfoo\fR in the directory above the current
directory.
.RE
.TP
\fBwindows\fR
On Microsoft Windows platforms, Tcl supports both drive-relative and UNC
style names. Both \fB/\fR and \fB\e\fR may be used as directory separators
in either type of name. Drive-relative names consist of an optional drive
specifier followed by an absolute or relative path. UNC paths follow the
general form \fB\e\eservername\esharename\epath\efile\fR. In both forms,
the file names \fB.\fR and \fB..\fR are special and refer to the current
directory and the parent of the current directory respectively. The
following examples illustrate various forms of path names:
.RS
.TP 15
\fB\&\e\eHost\eshare/file\fR
Absolute UNC path to a file called \fBfile\fR in the root directory of
the export point \fBshare\fR on the host \fBHost\fR.
.TP 15
\fBc:foo\fR
Volume-relative path to a file \fBfoo\fR in the current directory on drive
\fBc\fR.
.TP 15
\fBc:/foo\fR
Absolute path to a file \fBfoo\fR in the root directory of drive
\fBc\fR.
.TP 15
\fBfoo\ebar\fR
Relative path to a file \fBbar\fR in the \fBfoo\fR directory in the current
directory on the current volume.
.TP 15
\fB\&\efoo\fR
Volume-relative path to a file \fBfoo\fR in the root directory of the current
volume.
.RE
.SH TILDE SUBSTITUTION
.PP
In addition to the file name rules described above, Tcl also supports
\fIcsh\fR-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
\fB$HOME\fR 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.
.PP
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. File
names that have a tilde without a user name will be substituted using
the \fB$HOME\fR environment variable, just like for Unix.
.SH PORTABILITY ISSUES
.PP
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:
\fB<>:"/\e|\fR. 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 characters and an extension of no
more than 3 characters.
.SH KEYWORDS
current directory, absolute file name, relative file name,
volume-relative file name, portability

37
contrib/tcl/doc/flush.n Normal file
View File

@ -0,0 +1,37 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) flush.n 1.9 96/02/15 20:02:05
'\"
.so man.macros
.TH flush n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
flush \- Flush buffered output for a channel
.SH SYNOPSIS
\fBflush \fIchannelId\fR
.BE
.SH DESCRIPTION
.PP
Flushes any output that has been buffered for \fIchannelId\fR.
\fIChannelId\fR must be a channel identifier such as returned by a previous
\fBopen\fR or \fBsocket\fR command, and it must have been opened for writing.
.VS
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.
.VE
.SH "SEE ALSO"
open(n), socket(n)
.SH KEYWORDS
blocking, buffer, channel, flush, nonblocking, output

44
contrib/tcl/doc/for.n Normal file
View File

@ -0,0 +1,44 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) for.n 1.5 96/03/25 20:15:01
'\"
.so man.macros
.TH for n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
for \- ``For'' loop
.SH SYNOPSIS
\fBfor \fIstart test next body\fR
.BE
.SH DESCRIPTION
.PP
\fBFor\fR is a looping command, similar in structure to the C
\fBfor\fR statement. The \fIstart\fR, \fInext\fR, and
\fIbody\fR arguments must be Tcl command strings, and \fItest\fR
is an expression string.
The \fBfor\fR command first invokes the Tcl interpreter to
execute \fIstart\fR. Then it repeatedly evaluates \fItest\fR as
an expression; if the result is non-zero it invokes the Tcl
interpreter on \fIbody\fR, then invokes the Tcl interpreter on \fInext\fR,
then repeats the loop. The command terminates when \fItest\fR evaluates
to 0. If a \fBcontinue\fR command is invoked within \fIbody\fR then
any remaining commands in the current execution of \fIbody\fR are skipped;
processing continues by invoking the Tcl interpreter on \fInext\fR, then
evaluating \fItest\fR, and so on. If a \fBbreak\fR command is invoked
within \fIbody\fR
or \fInext\fR,
then the \fBfor\fR command will
return immediately.
The operation of \fBbreak\fR and \fBcontinue\fR are similar to the
corresponding statements in C.
\fBFor\fR returns an empty string.
.SH KEYWORDS
for, iteration, looping

86
contrib/tcl/doc/foreach.n Normal file
View File

@ -0,0 +1,86 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) foreach.n 1.6 96/03/25 20:15:14
'\"
.so man.macros
.TH foreach n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
foreach \- Iterate over all elements in one or more lists
.SH SYNOPSIS
\fBforeach \fIvarname list body\fR
.br
\fBforeach \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR
.BE
.SH DESCRIPTION
.PP
The \fBforeach\fR command implements a loop where the loop
variable(s) take on values from one or more lists.
In the simplest case there is one loop variable, \fIvarname\fR,
and one list, \fIlist\fR, that is a list of values to assign to \fIvarname\fR.
The \fIbody\fR argument is a Tcl script.
For each element of \fIlist\fR (in order
from first to last), \fBforeach\fR assigns the contents of the
element to \fIvarname\fR as if the \fBlindex\fR command had been used
to extract the element, then calls the Tcl interpreter to execute
\fIbody\fR.
.PP
In the general case there can be more than one value list
(e.g., \fIlist1\fR and \fIlist2\fR),
and each value list can be associated with a list of loop variables
(e.g., \fIvarlist1\fR and \fIvarlist2\fR).
During each iteration of the loop
the variables of each \fIvarlist\fP are assigned
consecutive values from the corresponding \fIlist\fP.
Values in each \fIlist\fP 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.
.PP
The \fBbreak\fR and \fBcontinue\fR statements may be
invoked inside \fIbody\fR, with the same effect as in the \fBfor\fR
command. \fBForeach\fR returns an empty string.
.SH EXAMPLES
.PP
The following loop uses i and j as loop variables to iterate over
pairs of elements of a single list.
.DS
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.
.DE
.PP
The next loop uses i and j to iterate over two lists in parallel.
.DS
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.
.DE
.PP
The two forms are combined in the following example.
.DS
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.
.DE
.SH KEYWORDS
foreach, iteration, list, looping

220
contrib/tcl/doc/format.n Normal file
View File

@ -0,0 +1,220 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) format.n 1.10 96/03/25 20:15:25
'\"
.so man.macros
.TH format n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
format \- Format a string in the style of sprintf
.SH SYNOPSIS
\fBformat \fIformatString \fR?\fIarg arg ...\fR?
.BE
.SH INTRODUCTION
.PP
This command generates a formatted string in the same way as the
ANSI C \fBsprintf\fR procedure (it uses \fBsprintf\fR in its
implementation).
\fIFormatString\fR indicates how to format the result, using
\fB%\fR conversion specifiers as in \fBsprintf\fR, and the additional
arguments, if any, provide values to be substituted into the result.
The return value from \fBformat\fR is the formatted string.
.SH "DETAILS ON FORMATTING"
.PP
The command operates by scanning \fIformatString\fR 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 \fB%\fR then it is not copied to the result string.
Instead, the characters following the \fB%\fR character are treated as
a conversion specifier.
The conversion specifier controls the conversion of the next successive
\fIarg\fR 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 additional \fIarg\fR.
The \fBformat\fR command must be given enough \fIarg\fRs to meet the needs
of all of the conversion specifiers in \fIformatString\fR.
.PP
Each conversion specifier may contain up to six different parts:
.VS
an XPG3 position specifier,
.VE
a set of flags, a minimum 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 paragraphs below discuss each of these fields in turn.
.PP
.VS
If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in
``\fB%2$d\fR'', 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 \fIarg\fR.
If the conversion specifier requires multiple arguments because
of \fB*\fR characters in the specifier then
successive arguments are used, starting with the argument
given by the number.
This follows the XPG3 conventions for positional specifiers.
If there are any positional specifiers in \fIformatString\fR
then all of the specifiers must be positional.
.VE
.PP
The second portion of a conversion specifier may contain any of the
following flag characters, in any order:
.TP 10
\fB\-\fR
Specifies that the converted argument should be left-justified
in its field (numbers are normally right-justified with leading
spaces if needed).
.TP 10
\fB+\fR
Specifies that a number should always be printed with a sign,
even if positive.
.TP 10
\fIspace\fR
Specifies that a space should be added to the beginning of the
number if the first character isn't a sign.
.TP 10
\fB0\fR
Specifies that the number should be padded on the left with
zeroes instead of spaces.
.TP 10
\fB#\fR
Requests an alternate output form. For \fBo\fR and \fBO\fR
conversions it guarantees that the first digit is always \fB0\fR.
For \fBx\fR or \fBX\fR conversions, \fB0x\fR or \fB0X\fR (respectively)
will be added to the beginning of the result unless it is zero.
For all floating-point conversions (\fBe\fR, \fBE\fR, \fBf\fR,
\fBg\fR, and \fBG\fR) it guarantees that the result always
has a decimal point.
For \fBg\fR and \fBG\fR conversions it specifies that
trailing zeroes should not be removed.
.PP
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 printouts.
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 \fB0\fR and \fB\-\fR 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 \fB*\fR rather than
a number, then the next argument to the \fBformat\fR command
determines the minimum field width; it must be a numeric string.
.PP
The fourth portion of a conversion specifier is a precision,
which consists of a period followed by a number.
The number is used in different ways for different conversions.
For \fBe\fR, \fBE\fR, and \fBf\fR conversions it specifies the number
of digits to appear to the right of the decimal point.
For \fBg\fR and \fBG\fR 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 \fB#\fR flag has been specified).
For integer conversions, it specifies a minimum number of digits
to print (leading zeroes will be added if necessary).
For \fBs\fR 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 \fB*\fR rather than a number
then the next argument to the \fBformat\fR command determines the precision;
it must be a numeric string.
.PP
The fifth part of a conversion specifier is a length modifier,
which must be \fBh\fR or \fBl\fR.
If it is \fBh\fR it specifies that the numeric value should be
truncated to a 16-bit value before converting.
This option is rarely useful.
The \fBl\fR modifier is ignored.
.PP
The last thing in a conversion specifier is an alphabetic character
that determines what kind of conversion to perform.
The following conversion characters are currently supported:
.TP 10
\fBd\fR
Convert integer to signed decimal string.
.TP 10
\fBu\fR
Convert integer to unsigned decimal string.
.TP 10
\fBi\fR
Convert integer to signed decimal string; the integer may either be
in decimal, in octal (with a leading \fB0\fR) or in hexadecimal
(with a leading \fB0x\fR).
.TP 10
\fBo\fR
Convert integer to unsigned octal string.
.TP 10
\fBx\fR or \fBX\fR
Convert integer to unsigned hexadecimal string, using digits
``0123456789abcdef'' for \fBx\fR and ``0123456789ABCDEF'' for \fBX\fR).
.TP 10
\fBc\fR
Convert integer to the 8-bit character it represents.
.TP 10
\fBs\fR
No conversion; just insert string.
.TP 10
\fBf\fR
Convert floating-point number to signed decimal string of
the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by
the precision (default: 6).
If the precision is 0 then no decimal point is output.
.TP 10
\fBe\fR or \fBe\fR
Convert floating-point number to scientific notation in the
form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined
by the precision (default: 6).
If the precision is 0 then no decimal point is output.
If the \fBE\fR form is used then \fBE\fR is
printed instead of \fBe\fR.
.TP 10
\fBg\fR or \fBG\fR
If the exponent is less than \-4 or greater than or equal to the
precision, then convert floating-point number as for \fB%e\fR or
\fB%E\fR.
Otherwise convert as for \fB%f\fR.
Trailing zeroes and a trailing decimal point are omitted.
.TP 10
\fB%\fR
No conversion: just insert \fB%\fR.
.LP
For the numerical conversions the argument being converted must
be an integer or floating-point string; format converts the argument
to binary and then converts it back to a string according to
the conversion specifier.
.SH "DIFFERENCES FROM ANSI SPRINTF"
.PP
.VS
The behavior of the format command is the same as the
ANSI C \fBsprintf\fR procedure except for the following
differences:
.IP [1]
\fB%p\fR and \fB%n\fR specifiers are not currently supported.
.VE
.IP [2]
For \fB%c\fR conversions the argument must be a decimal string,
which will then be converted to the corresponding character value.
.IP [3]
.VS
The \fBl\fR modifier is ignored; integer values are always converted
as if there were no modifier present and real values are always
converted as if the \fBl\fR modifier were present (i.e. type
\fBdouble\fR is used for the internal representation).
If the \fBh\fR modifier is specified then integer values are truncated
to \fBshort\fR before conversion.
.VE
.SH KEYWORDS
conversion specifier, format, sprintf, string, substitution

52
contrib/tcl/doc/gets.n Normal file
View File

@ -0,0 +1,52 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) gets.n 1.12 96/02/15 20:02:08
'\"
.so man.macros
.TH gets n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
gets \- Read a line from a channel
.SH SYNOPSIS
\fBgets \fIchannelId\fR ?\fIvarName\fR?
.BE
.SH DESCRIPTION
.PP
This command reads the next line from \fIchannelId\fR, returns everything
in the line up to (but not including) the end-of-line character(s), and
discards the end-of-line character(s).
If \fIvarName\fR is omitted the line is returned as the result of the
command.
If \fIvarName\fR 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.
.PP
.VS
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 \fIchannelId\fR 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 \fIvarName\fR is specified and an empty string is returned in
\fIvarName\fR because of end-of-file or because of insufficient
data in nonblocking mode, then the return count is -1.
Note that if \fIvarName\fR 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 \fBeof\fR and \fBfblocked\fR commands can be used to distinguish
these three cases.
.VE
.SH "SEE ALSO"
eof(n), fblocked(n)
.SH KEYWORDS
blocking, channel, end of file, end of line, line, nonblocking, read

88
contrib/tcl/doc/glob.n Normal file
View File

@ -0,0 +1,88 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) glob.n 1.10 96/03/25 20:15:48
'\"
.so man.macros
.TH glob n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
glob \- Return names of files that match patterns
.SH SYNOPSIS
\fBglob \fR?\fIswitches\fR? \fIpattern \fR?\fIpattern ...\fR?
.BE
.SH DESCRIPTION
.PP
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 \fIpattern\fR arguments.
.LP
If the initial arguments to \fBglob\fR start with \fB\-\fR then
.VS
they are treated as switches. The following switches are
currently supported:
.TP 15
\fB\-nocomplain\fR
Allows an empty list to be returned without error; without this
switch an error is returned if the result list would be empty.
.TP 15
\fB\-\|\-\fR
Marks the end of switches. The argument following this one will
be treated as a \fIpattern\fR even if it starts with a \fB\-\fR.
.VE
.PP
The \fIpattern\fR arguments may contain any of the following
special characters:
.TP 10
\fB?\fR
Matches any single character.
.TP 10
\fB*\fR
Matches any sequence of zero or more characters.
.TP 10
\fB[\fIchars\fB]\fR
Matches any single character in \fIchars\fR. If \fIchars\fR
contains a sequence of the form \fIa\fB\-\fIb\fR then any
character between \fIa\fR and \fIb\fR (inclusive) will match.
.TP 10
\fB\e\fIx\fR
Matches the character \fIx\fR.
.TP 10
\fB{\fIa\fB,\fIb\fB,\fI...\fR}
Matches any of the strings \fIa\fR, \fIb\fR, etc.
.LP
As with csh, a ``.'' at the beginning of a file's name or just
after a ``/'' must be matched explicitly or with a {} construct.
In addition, all ``/'' characters must be matched explicitly.
.LP
If the first character in a \fIpattern\fR is ``~'' then it refers
to the home directory for the user whose name follows the ``~''.
If the ``~'' is followed immediately by ``/'' then the value of
the HOME environment variable is used.
.LP
The \fBglob\fR command differs from csh globbing in two ways.
First, it does not sort its result list (use the \fBlsort\fR
command if you want the list sorted).
.VS
Second, \fBglob\fR only returns the names of files that actually
exist; in csh no check for existence is made unless a pattern
contains a ?, *, or [] construct.
.SH PORTABILITY ISSUES
.PP
Unlike other Tcl commands that will accept both network and native
style names (see the \fBfilename\fR manual entry for details on how
native and network names are specified), the \fBglob\fR command only
accepts native names. Also, for Windows UNC names, the servername and
sharename components of the path may not contain ?, *, or []
constructs.
.VE
.SH KEYWORDS
exist, file, glob, pattern

30
contrib/tcl/doc/global.n Normal file
View File

@ -0,0 +1,30 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) global.n 1.5 96/03/25 20:16:10
'\"
.so man.macros
.TH global n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
global \- Access global variables
.SH SYNOPSIS
\fBglobal \fIvarname \fR?\fIvarname ...\fR?
.BE
.SH DESCRIPTION
.PP
This command is ignored unless a Tcl procedure is being interpreted.
If so then it declares the given \fIvarname\fR's to be global variables
rather than local ones. For the duration of the current procedure
(and only while executing in the current procedure), any reference to
any of the \fIvarname\fRs will refer to the global variable by the same
name.
.SH KEYWORDS
global, procedure, variable

168
contrib/tcl/doc/history.n Normal file
View File

@ -0,0 +1,168 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) history.n 1.6 96/03/25 20:16:25
'\"
.so man.macros
.TH history n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
history \- Manipulate the history list
.SH SYNOPSIS
\fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
The \fBhistory\fR command performs one of several operations related to
recently-executed commands recorded in a history list. Each of
these recorded commands is referred to as an ``event''. When
specifying an event to the \fBhistory\fR command, the following
forms may be used:
.IP [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
(\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and
so on).
.IP [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 \fBstring match\fR command.
.PP
The \fBhistory\fR command can take any of the following forms:
.TP
\fBhistory\fR
Same
as \fBhistory info\fR, described below.
.TP
\fBhistory add\fI command \fR?\fBexec\fR?
Adds the \fIcommand\fR argument to the history list as a new event. If
\fBexec\fR is specified (or abbreviated) then the command is also
executed and its result is returned. If \fBexec\fR isn't specified
then an empty string is returned as result.
.TP
\fBhistory change\fI newValue\fR ?\fIevent\fR?
Replaces the value recorded for an event with \fInewValue\fR. \fIEvent\fR
specifies the event to replace, and
defaults to the \fIcurrent\fR event (not event \fB\-1\fR). This command
is intended for use in commands that implement new forms of history
substitution and wish to replace the current event (which invokes the
substitution) with the command created through substitution. The return
value is an empty string.
.TP
\fBhistory event\fR ?\fIevent\fR?
Returns the value of the event given by \fIevent\fR. \fIEvent\fR
defaults to \fB\-1\fR. This command causes history revision to occur:
see below for details.
.TP
\fBhistory info \fR?\fIcount\fR?
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 current event. If \fIcount\fR is specified
then only the most recent \fIcount\fR events are returned.
.TP
\fBhistory keep \fIcount\fR
This command may be used to change the size of the history list to
\fIcount\fR events. Initially, 20 events are retained in the history
list. This command returns an empty string.
.TP
\fBhistory nextid\fR
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.
.TP
\fBhistory redo \fR?\fIevent\fR?
Re-executes the command indicated by \fIevent\fR and return its result.
\fIEvent\fR defaults to \fB\-1\fR. This command results in history
revision: see below for details.
.TP
\fBhistory substitute \fIold new \fR?\fIevent\fR?
Retrieves the command given by \fIevent\fR
(\fB\-1\fR by default), replace any occurrences of \fIold\fR by
\fInew\fR in the command (only simple character equality is supported;
no wild cards), execute the resulting command, and return the result
of that execution. This command results in history
revision: see below for details.
.TP
\fBhistory words \fIselector\fR ?\fIevent\fR?
Retrieves from the command given by \fIevent\fR (\fB\-1\fR by default)
the words given by \fIselector\fR, and return those words in a string
separated by spaces. The \fBselector\fR argument has three forms.
If it is a single number then it selects the word given by that
number (\fB0\fR for the command name, \fB1\fR for its first argument,
and so on). If it consists of two numbers separated by a dash,
then it selects all the arguments between those two. Otherwise
\fBselector\fR is treated as a pattern; all words matching that
pattern (in the sense of \fBstring match\fR) are returned. In
the numeric forms \fB$\fR may be used
to select the last word of a command.
For example, suppose the most recent command in the history list is
.RS
.CS
\fBformat {%s is %d years old} Alice [expr $ageInMonths/12]\fR
.CE
Below are some history commands and the results they would produce:
.DS
.ta 4c
.fi
.UL Command " "
.UL Result
.nf
\fBhistory words $ [expr $ageInMonths/12]\fR
\fBhistory words 1-2 {%s is %d years old} Alice\fR
\fBhistory words *a*o* {%s is %d years old} [expr $ageInMonths/12]\fR
.DE
\fBHistory words\fR results in history revision: see below for details.
.RE
.SH "HISTORY REVISION"
.PP
The history options \fBevent\fR, \fBredo\fR, \fBsubstitute\fR,
and \fBwords\fR result in ``history revision''.
When one of these options is invoked then the current event
is modified to eliminate the history command and replace it with
the result of the history command.
For example, suppose that the most recent command in the history
list is
.CS
\fBset a [expr $b+2]\fR
.CE
and suppose that the next command invoked is one of the ones on
the left side of the table below. The command actually recorded in
the history event will be the corresponding one on the right side
of the table.
.ne 1.5c
.DS
.ta 4c
.fi
.UL "Command Typed" " "
.UL "Command Recorded"
.nf
\fBhistory redo set a [expr $b+2]\fR
\fBhistory s a b set b [expr $b+2]\fR
\fBset c [history w 2] set c [expr $b+2]\fR
.DE
History revision is needed because event specifiers like \fB\-1\fR
are only valid at a particular time: once more events have been
added to the history list a different event specifier would be
needed.
History revision occurs even when \fBhistory\fR is invoked
indirectly from the current event (e.g. a user types a command
that invokes a Tcl procedure that invokes \fBhistory\fR): the
top-level command whose execution eventually resulted in a
\fBhistory\fR command is replaced.
If you wish to invoke commands like \fBhistory words\fR without
history revision, you can use \fBhistory event\fR to save the
current history event and then use \fBhistory change\fR to
restore it later.
.SH KEYWORDS
event, history, record, revision

45
contrib/tcl/doc/if.n Normal file
View File

@ -0,0 +1,45 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) if.n 1.6 96/03/25 20:16:42
'\"
.so man.macros
.TH if n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
if \- Execute scripts conditionally
.SH SYNOPSIS
\fBif \fIexpr1 \fR?\fBthen\fR? \fIbody1 \fBelseif \fIexpr2 \fR?\fBthen\fR? \fIbody2\fR \fBelseif\fR ... ?\fBelse\fR? ?\fIbodyN\fR?
.BE
.SH DESCRIPTION
.PP
The \fIif\fR command evaluates \fIexpr1\fR as an expression (in the
same way that \fBexpr\fR evaluates its argument). The value of the
expression must be a boolean
.VS
(a numeric value, where 0 is false and
anything is true, or a string value such as \fBtrue\fR or \fByes\fR
for true and \fBfalse\fR or \fBno\fR for false);
.VE
if it is true then \fIbody1\fR is executed by passing it to the
Tcl interpreter.
Otherwise \fIexpr2\fR is evaluated as an expression and if it is true
then \fBbody2\fR is executed, and so on.
If none of the expressions evaluates to true then \fIbodyN\fR is
executed.
The \fBthen\fR and \fBelse\fR arguments are optional
``noise words'' to make the command easier to read.
There may be any number of \fBelseif\fR clauses, including zero.
\fIBodyN\fR may also be omitted as long as \fBelse\fR 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 \fIbodyN\fR.
.SH KEYWORDS
boolean, conditional, else, false, if, true

31
contrib/tcl/doc/incr.n Normal file
View File

@ -0,0 +1,31 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) incr.n 1.5 96/03/25 20:16:58
'\"
.so man.macros
.TH incr n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
incr \- Increment the value of a variable
.SH SYNOPSIS
\fBincr \fIvarName \fR?\fIincrement\fR?
.BE
.SH DESCRIPTION
.PP
Increments the value stored in the variable whose name is \fIvarName\fR.
The value of the variable must be an integer.
If \fIincrement\fR is supplied then its value (which must be an
integer) is added to the value of variable \fIvarName\fR; otherwise
1 is added to \fIvarName\fR.
The new value is stored as a decimal string in variable \fIvarName\fR
and also returned as result.
.SH KEYWORDS
add, increment, variable, value

168
contrib/tcl/doc/info.n Normal file
View File

@ -0,0 +1,168 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) info.n 1.12 96/03/25 20:17:12
'\"
.so man.macros
.TH info n 7.5 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 SYNOPSIS
\fBinfo \fIoption \fR?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
This command provides information about various internals of the Tcl
interpreter.
The legal \fIoption\fR's (which may be abbreviated) are:
.TP
\fBinfo args \fIprocname\fR
Returns a list containing the names of the arguments to procedure
\fIprocname\fR, in order. \fIProcname\fR must be the name of a
Tcl command procedure.
.TP
\fBinfo body \fIprocname\fR
Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be
the name of a Tcl command procedure.
.TP
\fBinfo cmdcount\fR
Returns a count of the total number of commands that have been invoked
in this interpreter.
.TP
\fBinfo commands \fR?\fIpattern\fR?
If \fIpattern\fR isn't specified, returns a list of names of all the
Tcl commands, including both the built-in commands written in C and
the command procedures defined using the \fBproc\fR command.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
are returned. Matching is determined using the same rules as for
\fBstring match\fR.
.TP
\fBinfo complete \fIcommand\fR
Returns 1 if \fIcommand\fR 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 commands 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.
.TP
\fBinfo default \fIprocname arg varname\fR
\fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR
must be the name of an argument to that procedure. If \fIarg\fR
doesn't have a default value then the command returns \fB0\fR.
Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
into variable \fIvarname\fR.
.TP
\fBinfo exists \fIvarName\fR
Returns \fB1\fR if the variable named \fIvarName\fR exists in the
current context (either as a global or local variable), returns \fB0\fR
otherwise.
.TP
\fBinfo globals \fR?\fIpattern\fR?
If \fIpattern\fR isn't specified, returns a list of all the names
of currently-defined global variables.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
are returned. Matching is determined using the same rules as for
\fBstring match\fR.
.VS br
.TP
\fBinfo hostname\fR
Returns the name of the computer on which this invocation is being
executed.
.VE
.TP
\fBinfo level\fR ?\fInumber\fR?
If \fInumber\fR is not specified, this command returns a number
giving the stack level of the invoking procedure, or 0 if the
command is invoked at top-level. If \fInumber\fR is specified,
then the result is a list consisting of the name and arguments for the
procedure call at level \fInumber\fR on the stack. If \fInumber\fR
is positive then it selects a particular stack level (1 refers
to the top-most active procedure, 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 \fBuplevel\fR command for more information on what stack
levels mean.
.TP
\fBinfo library\fR
Returns the name of the library directory in which standard Tcl
scripts are stored.
.VS
This is actually the value of the \fBtcl_library\fR
variable and may be changed by setting \fBtcl_library\fR.
See the \fBtclvars\fR manual entry for more information.
.TP
\fBinfo loaded \fR?\fIinterp\fR?
Returns a list describing all of the packages that have been loaded into
\fIinterp\fR with the \fBload\fR 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.
\fIInterp\fR defaults to the current interpreter.
.VE
.TP
\fBinfo locals \fR?\fIpattern\fR?
If \fIpattern\fR 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 \fBglobal\fR and \fBupvar\fR commands
will not be returned.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
are returned. Matching is determined using the same rules as for
\fBstring match\fR.
.VS br
.TP
\fBinfo nameofexecutable\fR
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.
.TP
\fBinfo patchlevel\fR
Returns the value of the global variable \fBtcl_patchLevel\fR; see
the \fBtclvars\fR manual entry for more information.
.VE
.TP
\fBinfo procs \fR?\fIpattern\fR?
If \fIpattern\fR isn't specified, returns a list of all the
names of Tcl command procedures.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
are returned. Matching is determined using the same rules as for
\fBstring match\fR.
.TP
\fBinfo script\fR
If a Tcl script file is currently being evaluated (i.e. there is a
call to \fBTcl_EvalFile\fR active or there is an active invocation
of the \fBsource\fR command), then this command returns the name
of the innermost file being processed. Otherwise the command returns an
empty string.
.VS br
.TP
\fBinfo sharedlibextension\fR
Returns the extension used on this platform for the names of files
containing shared libraries (for example, \fB.so\fR under Solaris).
If shared libraries aren't supported on this platform then an empty
string is returned.
.TP
\fBinfo tclversion\fR
Returns the value of the global variable \fBtcl_version\fR; see
the \fBtclvars\fR manual entry for more information.
.VE
.TP
\fBinfo vars\fR ?\fIpattern\fR?
If \fIpattern\fR isn't specified,
returns a list of all the names of currently-visible variables, including
both locals and currently-visible globals.
If \fIpattern\fR is specified, only those names matching \fIpattern\fR
are returned. Matching is determined using the same rules as for
\fBstring match\fR.
.SH KEYWORDS
command, information, interpreter, level, procedure, variable

347
contrib/tcl/doc/interp.n Normal file
View File

@ -0,0 +1,347 @@
'\"
'\" Copyright (c) 1995-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.
'\"
'\" SCCS: @(#) interp.n 1.15 96/03/25 20:17:28
'\"
.so man.macros
.TH interp n 7.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
interp \- Create and manipulate Tcl interpreters
.SH SYNOPSIS
\fBinterp \fIoption \fR?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
This command makes it possible to create one or more new Tcl
interpreters that co-exist with the creating interpreter in the
same application. The creating interpreter is called the \fImaster\fR
and the new interpreter is called a \fIslave\fR.
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.
.PP
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 \fIalias\fR. An \fIalias\fR 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 \fBenv\fR variable), which are
normally shared among all interpreters in the application. Note that the
name space for files (such as the names returned by the \fBopen\fR 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.
.PP
The \fBinterp\fR command also provides support for \fIsafe\fR
interpreters. A safe interpreter is a slave whose functions have
been greatly restricted, so that it is safe to execute untrusted
scripts without fear of them damaging other interpreters or the
application's environment. For example, all IO channel creation commands
and subprocess creation commands are removed from safe interpreters.
See SAFE INTERPRETERS below for more information on what features
are present in a safe interpreter. The alias mechanism can be
used for protected communication (analogous to a kernel call)
between a slave interpreter and its master.
.PP
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 \fIa\fR is a slave of
the current interpreter and it has a slave \fIa1\fR, which in turn has a
slave \fIa11\fR, the qualified name of \fIa11\fR in \fIa\fR is the list
\fI{a1 a11}\fR.
.PP
The \fBinterp\fR command, described below, accepts qualified interpreter
names as arguments; the interpreter in which the command is being evaluated
can always be referred to as \fI{}\fR (the empty list or string). Note that
it is impossible 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 interpreter created in an application.
Both restrictions are motivated by safety concerns.
.PP
The \fBinterp\fR command is used to create, delete, and manipulate
slave interpreters. It can have any of several forms, depending on
the \fIoption\fR argument:
.TP
\fBinterp \fBalias \fIsrcPath \fIsrcCmd\fR
Returns a Tcl list whose elements are the \fItargetCmd\fR and
\fIarg\fRs associated with the alias named \fIsrcCmd\fR
(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 \fIsrcCmd\fR if it was renamed).
.TP
\fBinterp \fBalias \fIsrcPath \fIsrcCmd\fR \fB{}\fR
Deletes the alias for \fIsrcCmd\fR in the slave interpreter identified by
\fIsrcPath\fR.
\fIsrcCmd\fR refers to the name under which the alias
was created; if the source command has been renamed, the renamed
command will be deleted.
.TP
\fBinterp \fBalias \fIsrcPath \fIsrcCmd\fR \fItargetPath \fItargetCmd \fR?\fIarg arg ...\fR?
This command creates an alias between one slave and another (see the
\fBalias\fR slave command below for creating 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.
\fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias.
\fISrcPath\fR is a Tcl list whose elements select a particular
interpreter. For example, ``\fBa b\fR'' identifies an interpreter
\fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave
of the invoking interpreter. An empty list specifies the interpreter
invoking the command. \fIsrcCmd\fR gives the name of a new
command, which will be created in the source interpreter.
\fITargetPath\fR and \fItargetCmd\fR specify a target interpreter
and command, and the \fIarg\fR arguments, if any, specify additional
arguments to \fItargetCmd\fR which are prepended to any arguments specified
in the invocation of \fIsrcCmd\fR.
\fITargetCmd\fR 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 command is
invoked in the source interpreter. See ALIAS INVOCATION below for
more details.
.TP
\fBinterp \fBaliases \fR?\fIpath\fR?
This command returns a Tcl list of the names of all the source commands for
aliases defined in the interpreter identified by \fIpath\fR.
.TP
\fBinterp \fBcreate \fR?\fB\-safe\fR? ?\fB\-\|\-\fR? ?\fIpath\fR?
Creates a slave interpreter identified by \fIpath\fR and a new command,
called a \fIslave command\fR. The name of the slave command is the last
component of \fIpath\fR. The new slave interpreter and the slave command
are created in the interpreter identified by the path obtained by removing
the last component from \fIpath\fR. For example, if \fIpath is ``\fBa b
c\fR'' then a new slave interpreter and slave command named ``\fBc\fR'' are
created in the interpreter identified by the path ``\fBa b\fR''.
The slave command may be used to manipulate the new interpreter as
described below. If \fIpath\fR is omitted, Tcl creates a unique name of the
form \fBinterp\fIx\fR, where \fIx\fR is an integer, and uses it for the
interpreter and the slave command. If the \fB\-safe\fR 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
functionality; otherwise the slave will include the full set of Tcl
built-in commands and variables. The \fB\-\|\-\fR switch can be used to
mark the end of switches; it may be needed if \fIpath\fR is an unusual
value such as \fB\-safe\fR. 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.
.TP
\fBinterp \fBdelete \fR?\fIpath ...?\fR
Deletes zero or more interpreters given by the optional \fIpath\fR
arguments, and for each interpreter, it also deletes its slaves. The
command also deletes the slave command for each interpreter deleted.
For each \fIpath\fR argument, if no interpreter by that name
exists, the command raises an error.
.TP
\fBinterp \fBeval \fIpath arg \fR?\fIarg ...\fR?
This command concatenates all of the \fIarg\fR arguments in the same
fashion as the \fBconcat\fR command, then evaluates the resulting string as
a Tcl script in the slave interpreter identified by \fIpath\fR. The result
of this evaluation (including error information such as the \fBerrorInfo\fR
and \fBerrorCode\fR variables, if an error occurs) is returned to the
invoking interpreter.
.TP
\fBinterp \fBexists \fIpath\fR
Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR
exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the
invoking interpreter is used.
.TP
\fBinterp \fBissafe\fR ?\fIpath\fR?
Returns \fB1\fR if the interpreter identified by the specified \fIpath\fR
is safe, \fB0\fR otherwise.
.TP
\fBinterp \fBshare\fR \fIsrcPath channelId destPath\fR
Causes the IO channel identified by \fIchannelId\fR to become shared
between the interpreter identified by \fIsrcPath\fR and the interpreter
identified by \fIdestPath\fR. Both interpreters have the same permissions
on the IO channel.
Both interpreters must close it to close the underlying IO channel; IO
channels accessible in an interpreter are automatically closed when an
interpreter is destroyed.
.TP
\fBinterp \fBslaves\fR ?\fIpath\fR?
Returns a Tcl list of the names of all the slave interpreters associated
with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted,
the invoking interpreter is used.
.TP
\fBinterp \fBtarget \fIpath alias\fR
Returns a Tcl list describing the target interpreter for an alias. The
alias is specified with an interpreter path and source command name, just
as in \fBinterp alias\fR above. The name of the target interpreter is
returned as an interpreter path, relative to the invoking interpreter.
If the target interpreter for the alias is the invoking interpreter then an
empty list is returned. If the target interpreter for the alias is not the
invoking 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.
.TP
\fBinterp \fBtransfer\fR \fIsrcPath channelId destPath\fR
Causes the IO channel identified by \fIchannelId\fR to become available in
the interpreter identified by \fIdestPath\fR and unavailable in the
interpreter identified by \fIsrcPath\fR.
.SH "SLAVE COMMAND"
.PP
For each slave interpreter created with the \fBinterp\fR command, a
new Tcl command is created in the master interpreter 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:
.CS
\fIslave command \fR?\fIarg arg ...\fR?
.CE
\fISlave\fR is the name of the interpreter, and \fIcommand\fR
and the \fIarg\fRs determine the exact behavior of the command.
The valid forms of this command are:
.TP
\fIslave \fBaliases\fR
Returns a Tcl list whose elements are the names of all the
aliases in \fIslave\fR. The names returned are the \fIsrcCmd\fR
values used when the aliases were created (which may not be the same
as the current names of the commands, if they have been
renamed).
.TP
\fIslave \fBalias \fIsrcCmd\fR
Returns a Tcl list whose elements are the \fItargetCmd\fR and
\fIarg\fRs associated with the alias named \fIsrcCmd\fR
(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 \fIsrcCmd\fR if it was renamed).
.TP
\fIslave \fBalias \fIsrcCmd \fB{}\fR
Deletes the alias for \fIsrcCmd\fR in the slave interpreter.
\fIsrcCmd\fR refers to the name under which the alias
was created; if the source command has been renamed, the renamed
command will be deleted.
.TP
\fIslave \fBalias \fIsrcCmd targetCmd \fR?\fIarg ..\fR?
Creates an alias such that whenever \fIsrcCmd\fR is invoked
in \fIslave\fR, \fItargetCmd\fR is invoked in the master.
The \fIarg\fR arguments will be passed to \fItargetCmd\fR as additional
arguments, prepended before any arguments passed in the invocation of
\fIsrcCmd\fR.
See ALIAS INVOCATION below for details.
.TP
\fIslave \fBeval \fIarg \fR?\fIarg ..\fR?
This command concatenates all of the \fIarg\fR arguments in
the same fashion as the \fBconcat\fR command, then evaluates
the resulting string as a Tcl script in \fIslave\fR.
The result of this evaluation (including error information
such as the \fBerrorInfo\fR and \fBerrorCode\fR variables, if an
error occurs) is returned to the invoking interpreter.
.TP
\fIslave \fBissafe\fR
Returns \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise.
.SH "ALIAS INVOCATION"
.PP
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.
.PP
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 carried 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 arguments
and merges them with the \fItargetCmd\fR and \fIarg\fRs for the
alias to create a new array of arguments. If the words
of \fIsrcCmd\fR were ``\fIsrcCmd arg1 arg2 ... argN\fR'',
the new set of words will be
``\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR'',
where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the
alias was created. \fITargetCmd\fR 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 \fItargetCmd\fR in the target interpreter.
No additional substitutions 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:
\fItargetCmd\fR and \fIargs\fR were substituted when parsing the command
that created the alias, and \fIarg1 - argN\fR are substituted when
the alias's source command is parsed in the source interpreter.
.PP
When writing the \fItargetCmd\fRs for aliases in safe interpreters,
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 interpreter could execute arbitrary
code in the master. This in turn would compromise the security
of the system.
.SH "SAFE INTERPRETERS"
.PP
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 environment. 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
\fBexec\fR 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 carefully
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.
.PP
A safe interpreter is created by specifying the \fB\-safe\fR switch
to the \fBinterp create\fR command. Furthermore, any slave created
by a safe interpreter will also be safe.
.PP
A safe interpreter is created with exactly the following set of
built-in commands:
.DS
.ta 1.2i 2.4i 3.6i
\fBappend array break case
catch clock close concat
continue eof error eval
expr fblocked flush for
foreach format gets global
history if incr info
interp join lappend lindex
list llength lrange lreplace
pid proc puts read
regexp regsub rename return
scan set seek split
string switch tell trace\fR
.DE
All commands not on this list are removed from the interpreter by
the \fBinterp create\fR command. Of course, the missing commands
can be recreated later as Tcl procedures or aliases.
.PP
In addition, the \fBenv\fR variable is not present in a safe interpreter,
so it cannot share environment variables with other interpreters. The
\fBenv\fR variable poses a security risk, because users can store
sensitive information in an environment variable. For example, the PGP
manual recommends storing the PGP private key protection password in
the environment variable \fIPGPPASS\fR. Making this variable available
to untrusted code executing in a safe interpreter would incur a
security risk.
.PP
If extensions are loaded into a safe interpreter, they may also restrict
their own functionality to eliminate unsafe commands. The management of
extensions for safety will be explained in the manual entries for the
\fBpackage\fR and \fBload\fR Tcl commands.
.SH CREDITS
.PP
This mechanism is based on the Safe-Tcl prototype implemented
by Nathaniel Borenstein and Marshall Rose.
.SH "SEE ALSO"
load(n), package(n) Tcl_CreateSlave(3)
.SH KEYWORDS
alias, master interpreter, safe interpreter, slave interpreter

29
contrib/tcl/doc/join.n Normal file
View File

@ -0,0 +1,29 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) join.n 1.5 96/03/25 20:17:46
'\"
.so man.macros
.TH join n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
join \- Create a string by joining together list elements
.SH SYNOPSIS
\fBjoin \fIlist \fR?\fIjoinString\fR?
.BE
.SH DESCRIPTION
.PP
The \fIlist\fR argument must be a valid Tcl list.
This command returns the string
formed by joining all of the elements of \fIlist\fR together with
\fIjoinString\fR separating each adjacent pair of elements.
The \fIjoinString\fR argument defaults to a space character.
.SH KEYWORDS
element, join, list, separator

35
contrib/tcl/doc/lappend.n Normal file
View File

@ -0,0 +1,35 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) lappend.n 1.6 96/03/25 20:18:03
'\"
.so man.macros
.TH lappend n "" Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
lappend \- Append list elements onto a variable
.SH SYNOPSIS
\fBlappend \fIvarName \fR?\fIvalue value value ...\fR?
.BE
.SH DESCRIPTION
.PP
This command treats the variable given by \fIvarName\fR as a list
and appends each of the \fIvalue\fR arguments to that list as a separate
element, with spaces between elements.
If \fIvarName\fR doesn't exist, it is created as a list with elements
given by the \fIvalue\fR arguments.
\fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs
are appended as list elements rather than raw text.
This command provides a relatively efficient way to build up
large lists. For example, ``\fBlappend a $b\fR'' is much
more efficient than ``\fBset a [concat $a [list $b]]\fR'' when
\fB$a\fR is long.
.SH KEYWORDS
append, element, list, variable

188
contrib/tcl/doc/library.n Normal file
View File

@ -0,0 +1,188 @@
'\"
'\" Copyright (c) 1991-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.
'\"
'\" SCCS: @(#) library.n 1.20 96/03/25 20:18:29
.so man.macros
.TH library n "" Tcl "Tcl Built-In Commands"
.BS
.SH NAME
library \- standard library of Tcl procedures
.SH SYNOPSIS
.nf
\fBauto_execok \fIcmd\fR
\fBauto_load \fIcmd\fR
\fBauto_mkindex \fIdir pattern pattern ...\fR
\fBauto_reset\fR
\fBparray \fIarrayName\fR
.BE
.SH INTRODUCTION
.PP
Tcl includes a library of Tcl procedures for commonly-needed functions.
The procedures defined in the Tcl library are generic ones suitable
for use by many different applications.
The location of the Tcl library is returned by the \fBinfo library\fR
command.
In addition to the Tcl library, each application will normally have
its own library of support procedures as well; the location of this
library is normally given by the value of the \fB$\fIapp\fB_library\fR
global variable, where \fIapp\fR is the name of the application.
For example, the location of the Tk library is kept in the variable
\fB$tk_library\fR.
.PP
To access the procedures in the Tcl library, an application should
source the file \fBinit.tcl\fR in the library, for example with
the Tcl command
.CS
\fBsource [info library]/init.tcl\fR
.CE
If the library procedure \fBTcl_Init\fR is invoked from an application's
\fBTcl_AppInit\fR procedure, this happens automatically.
The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure
and arrange for the other procedures to be loaded on-demand using
the auto-load mechanism defined below.
.SH "COMMAND PROCEDURES"
.PP
The following procedures are provided in the Tcl library:
.TP
\fBauto_execok \fIcmd\fR
Determines whether there is an executable file by the name \fIcmd\fR.
This command examines the directories in the current search path
(given by the PATH environment variable) to see if there is an
executable file named \fIcmd\fR in any of those directories.
If so, it returns 1; if not it returns 0. \fBAuto_exec\fR
remembers information about previous searches in an array
named \fBauto_execs\fR; this avoids the path search in
future calls for the same \fIcmd\fR. The command \fBauto_reset\fR
may be used to force \fBauto_execok\fR to forget its cached
information.
.TP
\fBauto_load \fIcmd\fR
This command attempts to load the definition for a Tcl command named
\fIcmd\fR.
To do this, it searches an \fIauto-load path\fR, which is a list of
one or more directories.
The auto-load path is given by the global variable \fB$auto_path\fR
if it exists.
If there is no \fB$auto_path\fR variable, then the TCLLIBPATH environment
variable is used, if it exists.
Otherwise the auto-load path consists of just the Tcl library directory.
Within each directory in the auto-load path there must be a file
\fBtclIndex\fR that describes one
.VS
or more commands defined in that directory
and a script to evaluate to load each of the commands.
The \fBtclIndex\fR file should be generated with the
\fBauto_mkindex\fR command.
If \fIcmd\fR is found in an index file, then the appropriate
script is evaluated to create the command.
.VE
The \fBauto_load\fR command returns 1 if \fIcmd\fR was successfully
created.
The command returns 0 if there was no index entry for \fIcmd\fR
or if the script didn't actually define \fIcmd\fR (e.g. because
index information is out of date).
If an error occurs while processing the script, then that error
is returned.
\fBAuto_load\fR only reads the index information once and saves it
in the array \fBauto_index\fR; future calls to \fBauto_load\fR
check for \fIcmd\fR in the array rather than re-reading the index
files.
The cached index information may be deleted with the command
\fBauto_reset\fR.
This will force the next \fBauto_load\fR command to reload the
index database from disk.
.TP
\fBauto_mkindex \fIdir pattern pattern ...\fR
.VS
Generates an index suitable for use by \fBauto_load\fR.
The command searches \fIdir\fR for all files whose names match
any of the \fIpattern\fR arguments
.VE
(matching is done with the \fBglob\fR command),
generates an index of all the Tcl command
procedures defined in all the matching files, and stores the
index information in a file named \fBtclIndex\fR in \fIdir\fR.
If no pattern is given a pattern of \fB*.tcl\fR will be assumed.
For example, the command
.RS
.CS
\fBauto_mkindex foo *.tcl\fR
.CE
.LP
will read all the \fB.tcl\fR files in subdirectory \fBfoo\fR
and generate a new index file \fBfoo/tclIndex\fR.
.PP
\fBAuto_mkindex\fR parses the Tcl scripts in a relatively
unsophisticated way: if any line contains the word \fBproc\fR
as its first characters then it is assumed to be a procedure
definition and the next word of the line is taken as the
procedure's name.
Procedure definitions that don't appear in this way (e.g. they
have spaces before the \fBproc\fR) will not be indexed.
.RE
.TP
\fBauto_reset\fR
Destroys all the information cached by \fBauto_execok\fR and
\fBauto_load\fR.
This information will be re-read from disk the next time it is
needed.
\fBAuto_reset\fR also deletes any procedures listed in the auto-load
index, so that fresh copies of them will be loaded the next time
that they're used.
.TP
\fBparray \fIarrayName\fR
Prints on standard output the names and values of all the elements
in the array \fIarrayName\fR.
\fBArrayName\fR must be an array accessible to the caller of \fBparray\fR.
It may be either local or global.
.SH "VARIABLES"
.PP
The following global variables are defined or used by the procedures in
the Tcl library:
.TP
\fBauto_execs\fR
Used by \fBauto_execok\fR to record information about whether
particular commands exist as executable files.
.TP
\fBauto_index\fR
Used by \fBauto_load\fR to save the index information read from
disk.
.TP
\fBauto_noexec\fR
If set to any value, then \fBunknown\fR will not attempt to auto-exec
any commands.
.TP
\fBauto_noload\fR
If set to any value, then \fBunknown\fR will not attempt to auto-load
any commands.
.TP
\fBauto_path\fR
If set, then it must contain a valid Tcl list giving directories to
search during auto-load operations.
.TP
\fBenv(TCL_LIBRARY)\fR
If set, then it specifies the location of the directory containing
library scripts (the value of this variable will be returned by
the command \fBinfo library\fR). If this variable isn't set then
a default value is used.
.TP
\fBenv(TCLLIBPATH)\fR
If set, then it must contain a valid Tcl list giving directories to
search during auto-load operations.
This variable is only used if \fBauto_path\fR is not defined.
.TP
\fBunknown_active\fR
This variable is set by \fBunknown\fR to indicate that it is active.
It is used to detect errors where \fBunknown\fR recurses on itself
infinitely.
The variable is unset before \fBunknown\fR returns.
.SH KEYWORDS
auto-exec, auto-load, library, unknown

32
contrib/tcl/doc/license.terms Normal file
View File

@ -0,0 +1,32 @@
This software is copyrighted by the Regents of the University of
California, Sun Microsystems, Inc., and other parties. The following
terms apply to all files associated with the software unless explicitly
disclaimed in individual files.
The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose, provided
that existing copyright notices are retained in all copies and that this
notice is included verbatim in any distributions. No written agreement,
license, or royalty fee is required for any of the authorized uses.
Modifications to this software may be copyrighted by their authors
and need not follow the licensing terms described here, provided that
the new terms are clearly indicated on the first page of each file where
they apply.
IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE
IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS.
RESTRICTED RIGHTS: Use, duplication or disclosure by the government
is subject to the restrictions as set forth in subparagraph (c) (1) (ii)
of the Rights in Technical Data and Computer Software Clause as DFARS
252.227-7013 and FAR 52.227-19.

37
contrib/tcl/doc/lindex.n Normal file
View File

@ -0,0 +1,37 @@
'\"
'\" 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.
'\"
'\" SCCS: @(#) lindex.n 1.7 96/03/25 20:18:43
'\"
.so man.macros
.TH lindex n 7.4 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
lindex \- Retrieve an element from a list
.SH SYNOPSIS
\fBlindex \fIlist index\fR
.BE
.SH DESCRIPTION
.PP
This command treats \fIlist\fR as a Tcl list and returns the
\fIindex\fR'th element from it (0 refers to the first element of the list).
In extracting the element, \fIlindex\fR 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 \fIindex\fR is negative or greater than or equal to the number
of elements in \fIvalue\fR, then an empty
string is returned.
.VS
If \fIindex\fR has the value \fBend\fR, it refers to the last element
in the list.
.VE
.SH KEYWORDS
element, index, list

Some files were not shown because too many files have changed in this diff Show More