Tcl 7.5, various makefiles will be updated to use these sources as soon
as I get these back down to my machine.
This commit is contained in:
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
331
contrib/tcl/README
Normal file
331
contrib/tcl/README
Normal 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
4
contrib/tcl/README.FreeBSD
Normal 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
2031
contrib/tcl/changes
Normal file
File diff suppressed because it is too large
Load Diff
135
contrib/tcl/doc/AddErrInfo.3
Normal file
135
contrib/tcl/doc/AddErrInfo.3
Normal 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
42
contrib/tcl/doc/AllowExc.3
Normal 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
75
contrib/tcl/doc/AppInit.3
Normal 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
89
contrib/tcl/doc/AssocData.3
Normal 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
164
contrib/tcl/doc/Async.3
Normal 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
58
contrib/tcl/doc/BackgdErr.3
Normal 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
45
contrib/tcl/doc/Backslash.3
Normal 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
63
contrib/tcl/doc/CallDel.3
Normal 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
36
contrib/tcl/doc/CmdCmplt.3
Normal 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
51
contrib/tcl/doc/Concat.3
Normal 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
427
contrib/tcl/doc/CrtChannel.3
Normal 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
92
contrib/tcl/doc/CrtChnlHdlr.3
Normal 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
59
contrib/tcl/doc/CrtCloseHdlr.3
Normal 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
181
contrib/tcl/doc/CrtCommand.3
Normal 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
90
contrib/tcl/doc/CrtFileHdlr.3
Normal 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
131
contrib/tcl/doc/CrtInterp.3
Normal 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
95
contrib/tcl/doc/CrtMathFnc.3
Normal 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
71
contrib/tcl/doc/CrtModalTmt.3
Normal 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
142
contrib/tcl/doc/CrtSlave.3
Normal 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
73
contrib/tcl/doc/CrtTimerHdlr.3
Normal 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
106
contrib/tcl/doc/CrtTrace.3
Normal 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
153
contrib/tcl/doc/DString.3
Normal 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
66
contrib/tcl/doc/DetachPids.3
Normal 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
108
contrib/tcl/doc/DoOneEvent.3
Normal 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
87
contrib/tcl/doc/DoWhenIdle.3
Normal 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
106
contrib/tcl/doc/Eval.3
Normal 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
66
contrib/tcl/doc/Exit.3
Normal 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
106
contrib/tcl/doc/ExprLong.3
Normal 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
46
contrib/tcl/doc/FindExec.3
Normal 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
130
contrib/tcl/doc/GetFile.3
Normal 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
81
contrib/tcl/doc/GetInt.3
Normal 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
57
contrib/tcl/doc/GetOpnFl.3
Normal 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
73
contrib/tcl/doc/GetStdChan.3
Normal 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
208
contrib/tcl/doc/Hash.3
Normal 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
119
contrib/tcl/doc/Interp.3
Normal 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
116
contrib/tcl/doc/LinkVar.3
Normal 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
366
contrib/tcl/doc/Notifier.3
Normal 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
441
contrib/tcl/doc/OpenFileChnl.3
Normal 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
152
contrib/tcl/doc/OpenTcp.3
Normal 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
59
contrib/tcl/doc/PkgRequire.3
Normal 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
100
contrib/tcl/doc/Preserve.3
Normal 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
45
contrib/tcl/doc/PrintDbl.3
Normal 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
53
contrib/tcl/doc/RecordEval.3
Normal 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
124
contrib/tcl/doc/RegExp.3
Normal 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
48
contrib/tcl/doc/SetErrno.3
Normal 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
55
contrib/tcl/doc/SetRecLmt.3
Normal 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
145
contrib/tcl/doc/SetResult.3
Normal 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
162
contrib/tcl/doc/SetVar.3
Normal 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
37
contrib/tcl/doc/Sleep.3
Normal 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
166
contrib/tcl/doc/SplitList.3
Normal 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
67
contrib/tcl/doc/StaticPkg.3
Normal 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
39
contrib/tcl/doc/StrMatch.3
Normal 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
189
contrib/tcl/doc/Tcl.n
Normal 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
61
contrib/tcl/doc/Tcl_Main.3
Normal 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
349
contrib/tcl/doc/TraceVar.3
Normal 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
76
contrib/tcl/doc/Translate.3
Normal 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
76
contrib/tcl/doc/UpVar.3
Normal 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
109
contrib/tcl/doc/after.n
Normal 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
32
contrib/tcl/doc/append.n
Normal 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
125
contrib/tcl/doc/array.n
Normal 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
67
contrib/tcl/doc/bgerror.n
Normal 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
34
contrib/tcl/doc/break.n
Normal 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
59
contrib/tcl/doc/case.n
Normal 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
40
contrib/tcl/doc/catch.n
Normal 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
28
contrib/tcl/doc/cd.n
Normal 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
176
contrib/tcl/doc/clock.n
Normal 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
59
contrib/tcl/doc/close.n
Normal 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
44
contrib/tcl/doc/concat.n
Normal 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
34
contrib/tcl/doc/continue.n
Normal 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
27
contrib/tcl/doc/eof.n
Normal 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
58
contrib/tcl/doc/error.n
Normal 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
30
contrib/tcl/doc/eval.n
Normal 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
185
contrib/tcl/doc/exec.n
Normal 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
28
contrib/tcl/doc/exit.n
Normal 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
299
contrib/tcl/doc/expr.n
Normal 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
32
contrib/tcl/doc/fblocked.n
Normal 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
178
contrib/tcl/doc/fconfigure.n
Normal 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
217
contrib/tcl/doc/file.n
Normal 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
109
contrib/tcl/doc/fileevent.n
Normal 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
197
contrib/tcl/doc/filename.n
Normal 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
37
contrib/tcl/doc/flush.n
Normal 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
44
contrib/tcl/doc/for.n
Normal 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
86
contrib/tcl/doc/foreach.n
Normal 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
220
contrib/tcl/doc/format.n
Normal 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
52
contrib/tcl/doc/gets.n
Normal 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
88
contrib/tcl/doc/glob.n
Normal 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
30
contrib/tcl/doc/global.n
Normal 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
168
contrib/tcl/doc/history.n
Normal 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
45
contrib/tcl/doc/if.n
Normal 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
31
contrib/tcl/doc/incr.n
Normal 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
168
contrib/tcl/doc/info.n
Normal 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
347
contrib/tcl/doc/interp.n
Normal 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
29
contrib/tcl/doc/join.n
Normal 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
35
contrib/tcl/doc/lappend.n
Normal 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
188
contrib/tcl/doc/library.n
Normal 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
32
contrib/tcl/doc/license.terms
Normal 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
37
contrib/tcl/doc/lindex.n
Normal 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
Loading…
Reference in New Issue
Block a user