upstream/opnsense-src
1
0
Fork 0
mirror of https://github.com/opnsense/src.git synced 2026-03-17 16:14:58 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Remove tcl from src/contrib.

Browse source
This commit is contained in:
Satoshi Asami 1998-09-05 12:33:01 +00:00
parent ff5fcc93d4
commit 140a040ae3
395 changed files with 0 additions and 173953 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
contrib/tcl/FREEBSD-upgrade
View file

@ -1,28 +0,0 @@
Tcl 7.5
originals can be found at: ftp://ftp.smli.com/pub/tcl
removed subdirectories "win", "mac", "compat"
phk@FreeBSD.org
Tcl 7.5 update 1
Imported with the commands:
tar zxvf tcl7.5p1.tar.gz
cd tcl7.5
rm -rf win mac compat
cvs import src/contrib/tcl TCL tcl7_5_p1
Tcl 8.0 beta 2
Imported with the commands:
tar zxvf tcl8.0b2.tar.gz
cd tcl8.0b2
rm -rf win mac compat
cvs import src/contrib/tcl TCL tcl8_0_b2
Tcl 8.0 patch 2
Imported with the commands:
tar zxvf tcl8.0p2.tar.gz
cd tcl8.0p2
rm -rf win mac compat
cvs import src/contrib/tcl TCL tcl8_0_p2

381
contrib/tcl/README
View file

@ -1,381 +0,0 @@
Tcl
SCCS: @(#) README 1.52 97/11/20 12:43:16
1. Introduction
---------------
This directory and its descendants contain the sources and documentation
for Tcl, an embeddable scripting language. The information here
corresponds to release 8.0p2, which is the second patch update for Tcl
8.0. Tcl 8.0 is a major new release that replaces the core of the
interpreter with an on-the-fly bytecode compiler to improve execution
speed. It also includes several other new features such as namespaces
and binary I/O, plus many bug fixes. The compiler introduces a few
incompatibilities that may affect existing Tcl scripts; the
incompatibilities are relatively obscure but may require modifications
to some old scripts before they can run with this version. The compiler
introduces many new C-level APIs, but the old APIs are still supported.
See below for more details. This patch release fixes various bugs in
Tcl 8.0; there are no feature changes relative to Tcl 8.0.
2. Documentation
----------------
The best way to get started with Tcl is to read one of the introductory
books on Tcl:
Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch,
Prentice-Hall, 1997, ISBN 0-13-616830-2
Tcl and the Tk Toolkit, by John Ousterhout,
Addison-Wesley, 1994, ISBN 0-201-63337-X
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://sunscript.sun.com
These Web pages include information about the latest releases, products
related to Tcl and Tk, 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, Macintoshes, and several 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 SunScript
(http://sunscript.sun.com) under "Tech Corner". Also, check in
the FTP directory from which you retrieved the base
distribution. Some of the binary releases are available freely,
while others are for sale.
(b) Make sure you have the most recent patch release. Look in the
FTP directory from which you retrieved this distribution to see
if it has been updated with patches. Patch releases fix bugs
without changing any features, so you should normally use the
latest patch release for the version of Tcl that you want.
Patch releases are available in two forms. A file like
tcl8.0p2.tar.Z is a complete release for patch level 2 of Tcl
version 8.0. If there is a file with a higher patch level than
this release, just fetch the file with the highest patch level
and use it.
Patches are also available in the form of patch files that just
contain the changes from one patch level to another. These
files will have names like tcl8.0p1.patch, tcl8.0p2.patch, etc. They
may also have .gz or .Z extensions to indicate compression. To
use one of these files, you apply it to an existing release with
the "patch" program. Patches must be applied in order:
tcl8.0p1.patch must be applied to an unpatched Tcl 8.0 release
to produce a Tcl 8.0p1 release; tcl8.0p2.patch can then be
applied to Tcl8.0p1 to produce Tcl 8.0p2, and so on. To apply an
uncompressed patch file such as tcl8.0p1.patch, invoke a shell
command like the following from the directory containing this
file:
patch -p < tcl8.0p1.patch
If the patch file has a .gz extension, invoke a command like the
following:
gunzip -c tcl8.0p1.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 tcl8.0p1.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 8.0
--------------------------------
Here are the most significant changes in Tcl 8.0. In addition to these
changes, there are several smaller changes and bug fixes. See the file
"changes" for a complete list of all changes.
1. Bytecode compiler. The core of the Tcl interpreter has been
replaced with an on-the-fly compiler that translates Tcl scripts to
byte codes; a new interpreter then executes the byte codes. In
earlier versions of Tcl, strings were used as a universal
representation; in Tcl 8.0 strings are replaced with Tcl_Obj
structures ("objects") that can hold both a string value and an
internal form such as a binary integer or compiled bytecodes. The
new objects make it possible to store information in efficient
internal forms and avoid the constant translations to and from
strings that occurred with the old interpreter. We have not yet
converted all of Tcl to take full advantage of the compiler and
objects and have not converted any of Tk yet, but even so you
should see speedups of 2-3x on many programs and you may see
speedups as much as 10-20x in some cases (such as code that
manipulates long lists). Future releases should achieve even
greater speedups. The compiler introduces only a few minor changes
at the level of Tcl scripts, but it introduces many new C APIs for
managing objects. See, for example, the manual entries doc/*Obj*.3.
2. Namespaces. There is a new namespace mechanism based on the
namespace implementation by Michael McLennan of Lucent Technologies.
This includes new "namespace" and "variable" commands. There are
many new C APIs associated with namespaces, but they will not be
exported until Tcl 8.1. Note: the syntax of the namespace command
has been changed slightly since the b1 release. See the changes
file for details.
3. Binary I/O. The new object system in Tcl 8.0 supports binary
strings (internally, strings are counted in addition to being null
terminated). There is a new "binary" command for inserting and
extracting data to/from binary strings. Commands such as "puts",
"gets", and "read" commands now operate correctly on binary data.
There is a new variable tcl_platform(byteOrder) to identify the
native byte order for the current host.
4. Random numbers. The "expr" command now contains a random number
generator, which can be accessed via the "rand()" and "srand()" math
functions.
5. Safe-Tcl enhancements. There is a new "hidden command"
mechanism, implemented with the Tcl commands "interp hide", "interp
expose", "interp invokehidden", and "interp hidden" and the C APIs
Tcl_HideCommand and Tcl_ExposeCommand. There is now support for
safe packages and extension loading, including new library
procedures such as safe::interpCreate (see the manual entry safe.n
for details).
6. There is a new package "registry" available under Windows for
accessing the Windows registry.
7. There is a new command "file attributes" for getting and setting
things like permissions and owner. There is also a new command
"file nativename" for getting back the platform-specific name for a
particular file.
8. There is a new "fcopy" command to copy data between channels.
This replaces and improves upon the not-so-secret unsupported old
command "unsupported0".
9. There is a new package "http" for doing GET, POST, and HEAD
requests via the HTTP/1.0 protocol. See the manual entry http.n
for details.
10. There are new library procedures for finding word breaks in
strings. See the manual entry library.n for details.
11. There are new C APIs Tcl_Finalize (for cleaning up before
unloading the Tcl DLL) and Tcl_Ungets for pushing bytes back into a
channel's input buffer.
12. Tcl now supports serial I/O devices on Windows and Unix, with a
new fconfigure -mode option. The Windows driver does not yet
support event-driven I/O.
13. The lsort command has new options -dictionary and -index. The
-index option allows for very rapid sorting based on an element
of a list.
14. The event notifier has been completely rewritten (again). It
should now allow Tcl to use an external event loop (like Motif's)
when it is embedded in other applications. No script-level
interfaces have changed, but many of the C APIs have.
Tcl 8.0 introduces the following incompatibilities that may affect Tcl
scripts that worked under Tcl 7.6 and earlier releases:
1. Variable and command names may not include the character sequence
"::" anymore: this sequence is now used as a namespace separator.
2. The semantics of some Tcl commands have been changed slightly to
maximize performance under the compiler. These incompatibilities
are documented on the Web so that we can keep the list up-to-date.
See the URL http://www.sunlabs.com/research/tcl/compiler.html.
3. 2-digit years are now parsed differently by the "clock" command
to handle year 2000 issues better (years 00-38 are treated as
2000-2038 instead of 1900-1938).
4. The old Macintosh commands "cp", "mkdir", "mv", "rm", and "rmdir"
are no longer supported; all of these features are now available on
all platforms via the "file" command.
5. The variable tcl_precision is now shared between interpreters
and defaults to 12 digits instead of 6; safe interpreters cannot
modify tcl_precision. The new object system in Tcl 8.0 causes
floating-to-string conversions (and the associated rounding) to
occur much less often than in Tcl 7.6, which can sometimes cause
behavioral changes.
6. The C APIs associated with the notifier have changed substantially.
7. The procedures Tcl_CreateModalTimeout and Tcl_DeleteModalTimeout
have been removed.
8. Tcl_CreateFileHandler and Tcl_DeleteFileHandler now take Unix
fd's and are only supported on the Unix platform
9. The C APIs for creating channel drivers have changed as part of
the new notifier implementation. The Tcl_File interfaces have been
removed. Tcl_GetChannelFile has been replaced with
Tcl_GetChannelHandle. Tcl_MakeFileChannel now takes a platform-
specific file handle. Tcl_DriverGetOptionProc procedures now take
an additional interp argument.
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. Mailing lists
----------------
A couple of Mailing List have been set up to discuss Macintosh or
Windows related Tcl issues. In order to use these Mailing Lists you
must have access to the internet. If you have access to the WWW the
home pages for these mailing lists are located at the following URLs:
http://www.sunlabs.com/research/tcl/lists/mactcl-list.html
-and-
http://www.sunlabs.com/research/tcl/lists/wintcl-list.html
The home pages contain information about the lists and an HTML archive
of all the past messages on the list. To subscribe send a message to:
listserv@sunlabs.sun.com
In the body of the message (the subject will be ignored) put:
subscribe mactcl Joe Blow
Replacing Joe Blow with your real name, of course. (Use wintcl
instead of mactcl if your interested in the Windows list.) If you
would just like to receive more information about the list without
subscribing put the line:
information mactcl
in the body instead (or wintcl).
8. 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
comp.lang.tcl may be able to offer a solution. The normal turn-around
time for bugs is 3-6 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).
9. 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.
Patch releases have a suffix such as p1 or p2. These releases contain
bug fixes only. A patch release (e.g Tcl 7.6p2) should be completely
compatible with the base release from which it is derived (e.g. Tcl
7.6), and you should normally use the highest available patch release.

3453
contrib/tcl/changes
View file

File diff suppressed because it is too large Load diff

166
contrib/tcl/doc/AddErrInfo.3
View file

@ -1,166 +0,0 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) AddErrInfo.3 1.28 97/06/12 13:39:53
'\"
.so man.macros
.TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
.sp
\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
.sp
\fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\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
For \fBTcl_AddObjErrorInfo\fR,
this points to the first byte of an array of bytes
containing a string to record in the \fBerrorInfo\fR variable.
This byte array may contain embedded null bytes
unless \fIlength\fR is negative.
For \fBTcl_AddErrorInfo\fR,
this is a conventional C string to record in the \fBerrorInfo\fR variable.
.AP int length in
The number of bytes to copy from \fImessage\fR when
setting the \fBerrorInfo\fR variable.
If negative, all bytes up to the first null byte are used.
.AP Tcl_Obj *errorObjPtr in
This variable \fBerrorCode\fR will be set to this value.
.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
error that occurred
(e.g. POSIX means an error occurred in 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_EvalObj\fR
(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObj\fR)
it calls the procedure \fBTcl_AddObjErrorInfo\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_EvalObj\fR.
\fBTcl_AddObjErrorInfo\fR may be used for this purpose:
its \fImessage\fR and \fIlength\fR arguments describe an additional
string to be appended to \fBerrorInfo\fR.
For example, the \fBsource\fR command calls \fBTcl_AddObjErrorInfo\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_AddObjErrorInfo\fR is just after
\fBTcl_EvalObj\fR has returned \fBTCL_ERROR\fR.
In calling \fBTcl_AddObjErrorInfo\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
\fBTcl_AddErrorInfo\fR resembles \fBTcl_AddObjErrorInfo\fR
but differs in initializing \fBerrorInfo\fR from the string
value of the interpreter's result
if the error is just starting to be logged.
It does not use the result as a Tcl object
so any embedded null characters in the result
will cause information to be lost.
It also takes a conventional C string in \fImessage\fR
instead of \fBTcl_AddObjErrorInfo\fR's counted string.
.PP
The procedure \fBTcl_SetObjErrorCode\fR is used to set the
\fBerrorCode\fR variable. \fIerrorObjPtr\fR contains a list object
built up by the caller. \fBerrorCode\fR is set to this
value. \fBTcl_SetObjErrorCode\fR is typically invoked just
before returning an error in an object command. If an error is
returned without calling \fBTcl_SetObjErrorCode\fR or
\fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
\fBerrorCode\fR to \fBNONE\fR.
.PP
The procedure \fBTcl_SetErrorCode\fR is also used to set the
\fBerrorCode\fR variable. However, it takes one or more strings to
record instead of an object. Otherwise, it is similar to
\fBTcl_SetObjErrorCode\fR in behavior.
.PP
\fBTcl_PosixError\fR
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 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
the interpreter's result.
.PP
It is important to call the procedures described here rather than
setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
\fBTcl_ObjSetVar2\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_AddObjErrorInfo\fR is called
for an error, it clears the existing value of \fBerrorInfo\fR
and adds the error message in the interpreter's result 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\fR
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_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
.SH KEYWORDS
error, object, object result, stack, trace, variable

52
contrib/tcl/doc/Alloc.3
View file

@ -1,52 +0,0 @@
'\"
'\" 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: @(#) Alloc.3 1.2 96/06/05 18:00:19
'\"
.so man.macros
.TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Alloc, Tcl_Free, Tcl_Realloc \- allocate or free heap memory
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
char *
\fBTcl_Alloc\fR(\fIsize\fR)
.sp
\fBTcl_Free\fR(\fIptr\fR)
.sp
char *
\fBTcl_Realloc\fR(\fIptr, size\fR)
.SH ARGUMENTS
.AS char *size
.AP int size in
Size in bytes of the memory block to allocate.
.AP char *ptr in
Pointer to memory block to free or realloc.
.BE
.SH DESCRIPTION
.PP
These procedures provide a platform and compiler independent interface
for memory allocation. Programs that need to transfer ownership of
memory blocks between Tcl and other modules should use these routines
rather than the native \fBmalloc()\fR and \fBfree()\fR routines
provided by the C run-time library.
.PP
\fBTcl_Alloc\fR returns a pointer to a block of at least \fIsize\fR
bytes suitably aligned for any use.
.PP
\fBTcl_Free\fR makes the space referred to by \fIptr\fR available for
further allocation.
.PP
\fBTcl_Realloc\fR changes the size of the block pointed to by
\fIptr\fR to \fIsize\fR bytes and returns a pointer to the new block.
The contents will be unchanged up to the lesser of the new and old
sizes. The returned location may be different from \fIptr\fR.
.SH KEYWORDS
alloc, allocation, free, malloc, memory, realloc

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

@ -1,42 +0,0 @@
'\"
'\" 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

73
contrib/tcl/doc/AppInit.3
View file

@ -1,73 +0,0 @@
'\"
'\" 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.10 96/08/26 12:59:40
'\"
.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
\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.
.SH KEYWORDS
application, argument, command, initialization, interpreter

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

@ -1,89 +0,0 @@
'\"
'\" 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

156
contrib/tcl/doc/Async.3
View file

@ -1,156 +0,0 @@
'\"
'\" 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.14 96/08/26 12:59:41
'\"
.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)
.sp
int
\fBTcl_AsyncReady\fR()
.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.
The procedure \fBTcl_AsyncReady\fR will return non-zero whenever any
asynchronous handlers are ready; it can be checked to avoid calls
to \fBTcl_AsyncInvoke\fR when there are no ready handlers.
Tcl calls \fBTcl_AsyncReady\fR after each command is evaluated
and calls \fBTcl_AsyncInvoke\fR if needed.
Applications may also call \fBTcl_AsyncInvoke\fR at interesting
times for that application.
For example, Tcl's event handler calls \fBTcl_AsyncReady\fR
after each event and calls \fBTcl_AsyncInvoke\fR if needed.
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
View file

@ -1,58 +0,0 @@
'\"
'\" 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
View file

@ -1,45 +0,0 @@
'\"
'\" 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

83
contrib/tcl/doc/BoolObj.3
View file

@ -1,83 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) @(#) BoolObj.3 1.7 97/05/08 19:50:57
'\"
.so man.macros
.TH Tcl_BooleanObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- manipulate Tcl objects as boolean values
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewBooleanObj\fR(\fIboolValue\fR)
.sp
\fBTcl_SetBooleanObj\fR(\fIobjPtr, boolValue\fR)
.sp
int
\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP int boolValue in
Integer value used to initialize or set a boolean object.
If the integer is nonzero, the boolean object is set to 1;
otherwise the boolean object is set to 0.
.AP Tcl_Obj *objPtr in/out
For \fBTcl_SetBooleanObj\fR, this points to the object to be converted
to boolean type.
For \fBTcl_GetBooleanFromObj\fR, this refers to the object
from which to get a boolean value;
if \fIobjPtr\fR does not already point to a boolean object,
an attempt will be made to convert it to one.
.AP Tcl_Interp *interp in/out
If an error occurs during conversion,
an error message is left in the interpreter's result object
unless \fIinterp\fR is NULL.
.AP int *boolPtr out
Points to place where \fBTcl_GetBooleanFromObj\fR
stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
.BE
.SH DESCRIPTION
.PP
These procedures are used to create, modify, and read
boolean Tcl objects from C code.
\fBTcl_NewBooleanObj\fR and \fBTcl_SetBooleanObj\fR
will create a new object of boolean type
or modify an existing object to have boolean type.
Both of these procedures set the object to have the
boolean value (0 or 1) specified by \fIboolValue\fR;
if \fIboolValue\fR is nonzero, the object is set to 1,
otherwise to 0.
\fBTcl_NewBooleanObj\fR returns a pointer to a newly created object
with reference count zero.
Both procedures set the object's type to be boolean
and assign the boolean value to the object's internal representation
\fIlongValue\fR member.
\fBTcl_SetBooleanObj\fR invalidates any old string representation
and, if the object is not already a boolean object,
frees any old internal representation.
.PP
\fBTcl_GetBooleanFromObj\fR attempts to return a boolean value
from the Tcl object \fIobjPtr\fR.
If the object is not already a boolean object,
it will attempt to convert it to one.
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
unless \fIinterp\fR is NULL.
Otherwise, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR
and stores the boolean value in the address given by \fIboolPtr\fR.
If the object is not already a boolean object,
the conversion will free any old internal representation.
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
.SH KEYWORDS
boolean, boolean object, boolean type, internal representation, object, object type, string representation

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

@ -1,63 +0,0 @@
'\"
'\" 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
View file

@ -1,36 +0,0 @@
'\"
'\" 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

55
contrib/tcl/doc/Concat.3
View file

@ -1,55 +0,0 @@
'\"
'\" 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.12 97/06/11 17:54:12
'\"
.so man.macros
.TH Tcl_Concat 3 7.5 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
.VS
The result string is dynamically allocated
using \fBTcl_Alloc\fR; the caller must eventually release the space
by calling \fBTcl_Free\fR.
.VE
.VS
.SH "SEE ALSO"
Tcl_ConcatObj
.SH KEYWORDS
concatenate, strings

571
contrib/tcl/doc/CrtChannel.3
View file

@ -1,571 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) CrtChannel.3 1.29 97/06/20 13:37:45
.so man.macros
.TH Tcl_CreateChannel 3 8.0 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_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetDefaultTranslation, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- procedures for creating and manipulating channels
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Channel
\fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
.sp
ClientData
\fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
.sp
Tcl_ChannelType *
\fBTcl_GetChannelType\fR(\fIchannel\fR)
.sp
char *
\fBTcl_GetChannelName\fR(\fIchannel\fR)
.VS
.sp
int
\fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
.VE
.sp
int
\fBTcl_GetChannelFlags\fR(\fIchannel\fR)
.sp
\fBTcl_SetDefaultTranslation\fR(\fIchannel, transMode\fR)
.sp
int
\fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
.sp
\fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR)
.sp
.VS
\fBTcl_NotifyChannel\fR(\fIchannel, mask\fR)
.sp
int
\fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
.VE
.sp
.SH ARGUMENTS
.AS Tcl_EolTranslation *channelName 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 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 int mask in
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
whether a channel is readable and writable.
.AP Tcl_Channel channel in
The channel to operate on.
.VS
.AP int direction in
\fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
means the output handle is wanted.
.AP ClientData *handlePtr out
Points to the location where the desired OS-specific handle should be
stored.
.VE
.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.
.VS
.AP int mask in
An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
this channel.
.AP Tcl_Interp *interp in
Current interpreter. (can be NULL)
.AP char *optionName in
Name of the invalid option.
.AP char *optionList in
Specific options list (space separated words, without "-")
to append to the standard generic options list.
Can be NULL for generic options error message only.
.VE
.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 device supported on each platform. This manual entry describes the
C APIs used to communicate between the generic layer and the
type-specific channel drivers. 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 file and command 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 file 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 and \fIinstanceData\fR with it. The channel is opened in the
mode indicated by \fImask\fR.
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
.VS
\fBTcl_GetChannelHandle\fR places the OS-specific device handle
associated with \fIchannel\fR for the given \fIdirection\fR in the
location specified by \fIhandlePtr\fR and returns \fBTCL_OK\fR. If
the channel does not have a device handle for the specified direction,
then \fBTCL_ERROR\fR is returned instead. Different channel drivers
will return different types of handle. Refer to the manual entries
for each driver to determine what type of handle is returned.
.VE
.PP
\fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR
and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
and output.
.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.
.PP
.VS
\fBTcl_NotifyChannel\fR is called by a channel driver to indicate to
the generic layer that the events specified by \fImask\fR have
occurred on the channel. Channel drivers are responsible for invoking
this function whenever the channel handlers need to be called for the
channel. See \fBWATCHPROC\fR below for more details.
.VE
.PP
.VS
\fBTcl_BadChannelOption\fR is called from driver specific set or get option
procs to generate a complete error message.
.VE
.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
.VS
.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_DriverWatchProc *\fIwatchProc\fR;
Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
} Tcl_ChannelType;
.CE
.VE
.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,
int \fImode\fR);
.CE
.PP
The \fIinstanceData\fR is the same as the value 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 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);
.CE
.PP
The \fIinstanceData\fR argument is the same as the value 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 encapsulated by this channel. 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,
char *\fIbuf\fR,
int \fIbufSize\fR,
int *\fIerrorCodePtr\fR);
.CE
.PP
\fIInstanceData\fR is the same as the value 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 encapsulated by the
channel and store it at \fIbuf\fR. On success, the function should return
a nonnegative 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,
char *\fIbuf\fR,
int \fItoWrite\fR,
int *\fIerrorCodePtr\fR);
.CE
.PP
\fIInstanceData\fR is the same as the value 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
encapsulated by the channel. On success, the function should return a
nonnegative 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,
long \fIoffset\fR,
int \fIseekMode\fR,
int *\fIerrorCodePtr\fR);
.CE
.PP
The \fIinstanceData\fR argument is the same as the value 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.
.VS
It should call \fBTcl_BadChannelOption\fR which itself returns
\fBTCL_ERROR\fR if the \fIoptionName\fR is
unrecognized.
.VE
If \fIoptionValue\fR specifies a value for the option that
is not supported or if a system call error occurs,
the function should leave 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,
.VS
Tcl_Interp *\fIinterp\fR,
.VE
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.
.VS
It should call \fBTcl_BadChannelOption\fR which itself returns
\fBTCL_ERROR\fR if the \fIoptionName\fR is
unrecognized. If a system call error occurs,
the function should leave 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.
.VE
.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 WATCHPROC
.VS
.PP
The \fIwatchProc\fR field contains the address of a function called
by the generic layer to initialize the event notification mechanism to
notice events of interest on this channel.
\fIWatchProc\fR should match the following prototype:
.PP
.CS
typedef void Tcl_DriverWatchProc(
ClientData \fIinstanceData\fR,
int \fImask\fR);
.CE
.VE
.PP
The \fIinstanceData\fR is the same as the value passed to
\fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR
argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in
noticing on this channel.
.PP
.VS
The function should initialize device type specific mechanisms to
notice when an event of interest is present on the channel. When one
or more of the designated events occurs on the channel, the channel
driver is responsible for calling \fBTcl_NotifyChannel\fR to inform
the generic channel module. The driver should take care not to starve
other channel drivers or sources of callbacks by invoking
Tcl_NotifyChannel too frequently. Fairness can be insured by using
the Tcl event queue to allow the channel event to be scheduled in sequence
with other events. See the description of \fBTcl_QueueEvent\fR for
details on how to queue an event.
.SH GETHANDLEPROC
.PP
The \fIgetHandleProc\fR field contains the address of a function called by
the generic layer to retrieve a device-specific handle from the channel.
\fIGetHandleProc\fR should match the following prototype:
.PP
.CS
typedef int Tcl_DriverGetHandleProc(
ClientData \fIinstanceData\fR,
int \fIdirection\fR,
ClientData *\fIhandlePtr\fR);
.CE
.PP
\fIInstanceData is the same as the value passed to
\fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR
argument is either \fBTCL_READABLE\fR to retrieve the handle used
for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for
output.
.PP
If the channel implementation has device-specific handles, the
function should retrieve the appropriate handle associated with the
channel, according the \fIdirection\fR argument. The handle should be
stored in the location referred to by \fIhandlePtr\fR, and
\fBTCL_OK\fR should be returned. If the channel is not open for the
specified direction, or if the channel implementation does not use
device handles, the function should return \fBTCL_ERROR\fR.
.VE
.VS
.SH TCL_BADCHANNELOPTION
.PP
This procedure generates a "bad option" error message in an
(optional) interpreter. It is used by channel drivers when
a invalid Set/Get option is requested. Its purpose is to concatenate
the generic options list to the specific ones and factorize
the generic options error message string.
.PP
It always return \fBTCL_ERROR\fR
.PP
An error message is generated in interp's result object to
indicate that a command was invoked with the a bad option
The message has the form
.CS
bad option "blah": should be one of
<...generic options...>+<...specific options...>
so you get for instance:
bad option "-blah": should be one of -blocking,
-buffering, -buffersize, -eofchar, -translation,
-peername, or -sockname
when called with optionList="peername sockname"
.CE
"blah" is the optionName argument and "<specific options>"
is a space separated list of specific option words.
The function takes good care of inserting minus signs before
each option, commas after, and an "or" before the last option.
.VE
.SH "SEE ALSO"
Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3)
.SH KEYWORDS
blocking, channel driver, channel registration, channel type, nonblocking

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

@ -1,92 +0,0 @@
'\"
'\" 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
View file

@ -1,59 +0,0 @@
'\"
'\" 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

138
contrib/tcl/doc/CrtCommand.3
View file

@ -1,138 +0,0 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) CrtCommand.3 1.29 97/06/04 17:23:53
'\"
.so man.macros
.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateCommand \- implement new commands in C
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Command
\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
.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.
.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.
It differs from \fBTcl_CreateObjCommand\fR in that a new string-based
command is defined;
that is, a command procedure is defined that takes an array of
argument strings instead of objects.
The object-based command procedures registered by \fBTcl_CreateObjCommand\fR
can execute significantly faster than the string-based command procedures
defined by \fBTcl_CreateCommand\fR.
This is because they take Tcl objects as arguments
and those objects can retain an internal representation that
can be manipulated more efficiently.
Also, Tcl's interpreter now uses objects internally.
In order to invoke a string-based command procedure
registered by \fBTcl_CreateCommand\fR,
it must generate and fetch a string representation
from each argument object before the call
and create a new Tcl object to hold the string result returned by the
string-based command procedure.
New commands should be defined using \fBTcl_CreateObjCommand\fR.
We support \fBTcl_CreateCommand\fR for backwards compatibility.
.PP
The procedures \fBTcl_DeleteCommand\fR, \fBTcl_GetCommandInfo\fR,
and \fBTcl_SetCommandInfo\fR are used in conjunction with
\fBTcl_CreateCommand\fR.
.PP
\fBTcl_CreateCommand\fR will delete an existing command \fIcmdName\fR,
if one is already associated with the interpreter.
It returns a token that may be used to refer
to the command in subsequent calls to \fBTcl_GetCommandName\fR.
If \fIcmdName\fR contains any \fB::\fR namespace qualifiers,
then the command is added to the specified namespace;
otherwise the command is added to the global namespace.
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.
\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
the interpreter result 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 the interpreter result
field is managed, see the \fBTcl_Interp\fR man page.
Before invoking a command procedure,
\fBTcl_Eval\fR sets the interpreter result to point to an empty string,
so simple commands can return an empty result by doing nothing at all.
.PP
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 the interpreter result 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.
.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
.SH "SEE ALSO"
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
.SH KEYWORDS
bind, command, create, delete, interpreter, namespace

100
contrib/tcl/doc/CrtFileHdlr.3
View file

@ -1,100 +0,0 @@
'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) CrtFileHdlr.3 1.7 97/04/23 16:11:17
'\"
.so man.macros
.TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only)
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.VS
.sp
\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
.sp
\fBTcl_DeleteFileHandler\fR(\fIfd\fR)
.VE
.SH ARGUMENTS
.AS Tcl_FileProc clientData
.VS
.AP int fd in
Unix file descriptor for an open file or device.
.VE
.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
.VS
\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 \fIfd\fR, and the conditions of interest
.VE
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 \fIfd\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 \fIfd\fR; if no handler exists for the
file given by \fIfd\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.
.PP
.VS
Note that these interfaces are only supported by the Unix
implementation of the Tcl notifier.
.VE
.SH KEYWORDS
callback, file, handler

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

@ -1,131 +0,0 @@
'\"
'\" 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.17 97/10/31 13:05:51
'\"
.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\fR to test if some other
code already called \fBTcl_DeleteInterp\fR; if not, call
\fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR 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)

93
contrib/tcl/doc/CrtMathFnc.3
View file

@ -1,93 +0,0 @@
'\"
'\" 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.9 96/08/26 12:59:43
'\"
.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;
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
View file

@ -1,71 +0,0 @@
'\"
'\" 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

248
contrib/tcl/doc/CrtObjCmd.3
View file

@ -1,248 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) @(#) CrtObjCmd.3 1.10 97/07/31 14:10:38
'\"
.so man.macros
.TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName \- implement new commands in C
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Command
\fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
.sp
int
\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
.sp
int
\fBTcl_DeleteCommandFromToken\fR(\fIinterp, token\fR)
.sp
int
\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
.sp
int
\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
.sp
char *
\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
.SH ARGUMENTS
.AS Tcl_ObjCmdProc *deleteProc in/out
.AP Tcl_Interp *interp in
Interpreter in which to create a new command or that contains a command.
.AP char *cmdName in
Name of command.
.AP Tcl_ObjCmdProc *proc in
Implementation of the 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_Command token in
Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.
The command must not have been deleted.
.AP Tcl_CmdInfo *infoPtr in/out
Pointer to structure containing various information about a
Tcl command.
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
and associates it with procedure \fIproc\fR
such that whenever \fIname\fR is
invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObj\fR)
the Tcl interpreter will call \fIproc\fR to process the command.
.PP
\fBTcl_CreateObjCommand\fR will delete any command \fIname\fR
already associated with the interpreter.
It returns a token that may be used to refer
to the command in subsequent calls to \fBTcl_GetCommandName\fR.
If \fIname\fR contains any \fB::\fR namespace qualifiers,
then the command is added to the specified namespace;
otherwise the command is added to the global namespace.
If \fBTcl_CreateObjCommand\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.
\fIproc\fR should have arguments and result that match the type
\fBTcl_ObjCmdProc\fR:
.CS
typedef int Tcl_ObjCmdProc(
ClientData \fIclientData\fR,
Tcl_Interp *\fIinterp\fR,
int \fIobjc\fR,
.VS
Tcl_Obj *CONST \fIobjv\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_CreateObjCommand\fR. Typically, \fIclientData\fR points to an
application-specific data structure that describes what to do when the
command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the
arguments to the command, \fIobjc\fR giving the number of argument objects
(including the command name) and \fIobjv\fR giving the values of the
arguments. The \fIobjv\fR array will contain \fIobjc\fR values, pointing to
the argument objects. Unlike \fIargv\fR[\fIargv\fR] used in a
string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL.
.PP
Additionally, when \fIproc\fR is invoked, it must not modify the contents
of the \fIobjv\fR array by assigning new pointer values to any element of the
array (for example, \fIobjv\fR[\fB2\fR] = \fBNULL\fR) because this will
cause memory to be lost and the runtime stack to be corrupted. The
\fBCONST\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
compilers to report any such attempted assignment as an error. However,
it is acceptable to modify the internal representation of any individual
object argument. For instance, the user may call
\fBTcl_GetIntFromObject\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
representation of that object; that call may change the type of the object
that \fIobjv\fR[\fB2\fR] points at, but will not change where
\fIobjv\fR[\fB2\fR] points.
.VE
.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, if \fIproc\fR needs to return a non-empty result,
it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
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 this gives an error message.
Before invoking a command procedure,
\fBTcl_EvalObj\fR sets interpreter's result to
point to an object representing an empty string, so simple
commands can return an empty result by doing nothing at all.
.PP
The contents of the \fIobjv\fR array belong to Tcl and are not
guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
not modify them.
Call \fBTcl_SetObjResult\fR if you want
to return something from the \fIobjv\fR array.
.PP
\fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.
This can occur through a call to \fBTcl_DeleteCommand\fR,
\fBTcl_DeleteCommandFromToken\fR, or \fBTcl_DeleteInterp\fR,
or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\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_CreateObjCommand\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.
If \fIname\fR contains any \fB::\fR namespace qualifiers,
the command is deleted from the specified namespace.
.PP
Given a token returned by \fBTcl_CreateObjCommand\fR,
\fBTcl_DeleteCommandFromToken\fR deletes the command
from a command interpreter.
It will delete a command even if that command has been renamed.
Once the call completes, attempts to invoke the command in
\fIinterp\fR will result in errors.
If the command corresponding to \fItoken\fR
has already been deleted from \fIinterp\fR then
\fBTcl_DeleteCommand\fR does nothing and returns -1;
otherwise it returns 0.
.PP
\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
exists as a command in \fIinterp\fR.
\fIcmdName\fR may include \fB::\fR namespace qualifiers
to identify a command in a particular namespace.
If the command is not found, then it returns 0.
Otherwise it places information about the command
in the \fBTcl_CmdInfo\fR structure
pointed to by \fIinfoPtr\fR and returns 1.
A \fBTcl_CmdInfo\fR structure has the following fields:
.CS
typedef struct Tcl_CmdInfo {
int isNativeObjectProc;
Tcl_ObjCmdProc *objProc;
ClientData objClientData;
Tcl_CmdProc *proc;
ClientData clientData;
Tcl_CmdDeleteProc *deleteProc;
ClientData deleteData;
Tcl_Namespace *namespacePtr;
} Tcl_CmdInfo;
.CE
The \fIisNativeObjectProc\fR field has the value 1
if \fBTcl_CreateObjCommand\fR was called to register the command;
it is 0 if only \fBTcl_CreateCommand\fR was called.
It allows a program to determine whether it is faster to
call \fIobjProc\fR or \fIproc\fR:
\fIobjProc\fR is normally faster
if \fIisNativeObjectProc\fR has the value 1.
The fields \fIobjProc\fR and \fIobjClientData\fR
have the same meaning as the \fIproc\fR and \fIclientData\fR
arguments to \fBTcl_CreateObjCommand\fR;
they hold information about the object-based command procedure
that the Tcl interpreter calls to implement the command.
The fields \fIproc\fR and \fIclientData\fR
hold information about the string-based command procedure
that implements the command.
If \fBTcl_CreateCommand\fR was called for this command,
this is the procedure passed to it;
otherwise, this is a compatibility procedure
registered by \fBTcl_CreateObjCommand\fR
that simply calls the command's
object-based procedure after converting its string arguments to Tcl objects.
The field \fIdeleteData\fR 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.
The field \fInamespacePtr\fR holds a pointer to the
Tcl_Namespace that contains the command.
.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.
\fIcmdName\fR may include \fB::\fR namespace qualifiers
to identify a command in a particular namespace.
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.
Note that \fBTcl_SetCmdInfo\fR will not change a command's namespace;
you must use \fBTcl_RenameCommand\fR to do that.
.PP
\fBTcl_GetCommandName\fR provides a mechanism for tracking commands
that have been renamed.
Given a token returned by \fBTcl_CreateObjCommand\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.
This name does not include any \fB::\fR namespace qualifiers.
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.
.PP
.SH "SEE ALSO"
Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
.SH KEYWORDS
bind, command, create, delete, namespace, object

230
contrib/tcl/doc/CrtSlave.3
View file

@ -1,230 +0,0 @@
'\"
'\" 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.26 97/07/31 18:00:14
'\"
.so man.macros
.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands.
.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
.VS
int
\fBTcl_CreateAlias\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, argc, argv\fR)
.sp
int
\fBTcl_CreateAliasObj\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, objc, objv\fR)
.VE
.sp
int
\fBTcl_GetAlias\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)
.sp
.VS
int
\fBTcl_GetAliasObj\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr\fR)
.sp
int
\fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
.sp
int
\fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
.SH ARGUMENTS
.AS Tcl_InterpDeleteProc **hiddenCmdName
.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
If non-zero, a ``safe'' slave that is suitable for running untrusted code
is created, otherwise a trusted slave is created.
.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 int objc in
Count of additional object arguments to pass to the alias object command.
.AP Tcl_Object **objv in
Vector of Tcl_Obj structures, the additional object arguments to pass to
the alias object 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.
.AP int *objcPtr out
Pointer to location to store count of additional object arguments to be
passed to the alias. The location is in storage owned by the caller.
.AP Tcl_Obj ***objvPtr out
Pointer to location to store a vector of Tcl_Obj structures, the additional
arguments to pass to an object alias command. The location is in storage
owned by the caller, the vector of Tcl_Obj structures is owned by the
called function.
.VS
.AP char *cmdName in
Name of an exposed command to hide or create.
.AP char *hiddenCmdName in
Name under which a hidden command is stored and with which it can be
exposed or invoked.
.VE
.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 \fIinterp\fR.
It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
allows \fIinterp\fR to manipulate the new slave.
If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
code has access to all the Tcl commands.
If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code
has access only to set of Tcl commands defined as ``Safe Tcl''; see the
manual entry for the Tcl \fBinterp\fR command for details.
If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
.PP
\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created
with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
\fB0\fR otherwise.
.PP
\fBTcl_MakeSafe\fR makes \fIinterp\fR ``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.
.PP
\fBTcl_GetSlave\fR returns a pointer to a slave interpreter of
\fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR.
If no such slave interpreter exists, \fBNULL\fR is returned.
.PP
\fBTcl_GetMaster\fR returns a pointer to the master interpreter of
\fIinterp\fR. If \fIinterp\fR 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
.VS
\fBTcl_CreateAlias\fR creates an object command named \fIsrcCmd\fR in
\fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
to be invoked in \fItargetInterp\fR. The arguments specified by the strings
contained in \fIargv\fR are always prepended to any arguments supplied in the
invocation of \fIsrcCmd\fR and passed to \fItargetCmd\fR.
This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
it fails; in that case, an error message is left in the object result
of \fIslaveInterp\fR.
Note that there are no restrictions on the ancestry relationship (as
created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
\fItargetInterp\fR. Any two interpreters can be used, without any
restrictions on how they are related.
.PP
\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAliasObj\fR except
that it takes a vector of objects to pass as additional arguments instead
of a vector of strings.
.VE
.PP
\fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
in \fIinterp\fR. 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.
.VS
.PP
\fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
returns a pointer to a vector of Tcl_Obj structures instead of a vector of
strings.
.PP
\fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
the set of hidden commands to the set of exposed commands, putting
it under the name
\fIcmdName\fR.
\fIHiddenCmdName\fR must be the name of an existing hidden
command, or the operation will return \fBTCL_ERROR\fR and leave an error
message in the \fIresult\fR field in \fIinterp\fR.
If an exposed command named \fIcmdName\fR already exists,
the operation returns \fBTCL_ERROR\fR and leaves an error message in the
object result of \fIinterp\fR.
If the operation succeeds, it returns \fBTCL_OK\fR.
After executing this command, attempts to use \fIcmdName\fR in a call to
\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
.PP
\fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
exposed commands to the set of hidden commands, under the name
\fIhiddenCmdName\fR.
\fICmdName\fR must be the name of an existing exposed
command, or the operation will return \fBTCL_ERROR\fR and leave an error
message in the object result of \fIinterp\fR.
Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
leave an error message in the object result of \fIinterp\fR.
The \fICmdName\fR will be looked up in the global namespace, and not
relative to the current namespace, even if the current namespace is not the
global one.
If a hidden command whose name is \fIhiddenCmdName\fR already
exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
field in \fIinterp\fR contains an error message.
If the operation succeeds, it returns \fBTCL_OK\fR.
After executing this command, attempts to use \fIcmdName\fR in a call to
\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
.PP
.SH "SEE ALSO"
For a description of the Tcl interface to multiple interpreters, see
\fIinterp(n)\fR.
.SH KEYWORDS
alias, command, exposed commands, hidden commands, interpreter, invoke,
master, slave,

76
contrib/tcl/doc/CrtTimerHdlr.3
View file

@ -1,76 +0,0 @@
'\"
'\" 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.4 96/09/17 10:54:58
'\"
.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.
The tokens returned by \fBTcl_CreateTimerHandler\fR never have
a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR
then the procedure does nothing.
.SH KEYWORDS
callback, clock, handler, timer

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

@ -1,106 +0,0 @@
'\"
'\" 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

145
contrib/tcl/doc/DString.3
View file

@ -1,145 +0,0 @@
'\"
'\" 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.20 96/08/26 12:59:44
'\"
.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
\fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
.sp
\fBTcl_DStringFree\fR(\fIdsPtr\fR)
.sp
\fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
.sp
\fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
.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
.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.
.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
\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.
.SH KEYWORDS
append, dynamic string, free, result

62
contrib/tcl/doc/DetachPids.3
View file

@ -1,62 +0,0 @@
'\"
'\" 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.15 96/08/26 12:59:44
'\"
.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
\fBTcl_ReapDetachedProcs\fR()
.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
\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.
.SH KEYWORDS
background, child, detach, process, wait

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

@ -1,108 +0,0 @@
'\"
'\" 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.6 97/05/09 18:12: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
new 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

86
contrib/tcl/doc/DoWhenIdle.3
View file

@ -1,86 +0,0 @@
'\"
'\" 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.6 97/05/09 18:18:33
'\"
.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

79
contrib/tcl/doc/DoubleObj.3
View file

@ -1,79 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) @(#) DoubleObj.3 1.6 97/05/08 19:50:07
'\"
.so man.macros
.TH Tcl_DoubleObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl objects as floating-point values
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewDoubleObj\fR(\fIdoubleValue\fR)
.sp
\fBTcl_SetDoubleObj\fR(\fIobjPtr, doubleValue\fR)
.sp
int
\fBTcl_GetDoubleFromObj\fR(\fIinterp, objPtr, doublePtr\fR)
.SH ARGUMENTS
.AS Tcl_Interp doubleValue in/out
.AP double doubleValue in
A double-precision floating point value used to initialize or set a double object.
.AP Tcl_Obj *objPtr in/out
For \fBTcl_SetDoubleObj\fR, this points to the object to be converted
to double type.
For \fBTcl_GetDoubleFromObj\fR, this refers to the object
from which to get a double value;
if \fIobjPtr\fR does not already point to a double object,
an attempt will be made to convert it to one.
.AP Tcl_Interp *interp in/out
If an error occurs during conversion,
an error message is left in the interpreter's result object
unless \fIinterp\fR is NULL.
.AP double *doublePtr out
Points to place to store the double value
obtained from \fIobjPtr\fR.
.BE
.SH DESCRIPTION
.PP
These procedures are used to create, modify, and read
double Tcl objects from C code.
\fBTcl_NewDoubleObj\fR and \fBTcl_SetDoubleObj\fR
will create a new object of double type
or modify an existing object to have double type.
Both of these procedures set the object to have the
double-precision floating point value given by \fIdoubleValue\fR;
\fBTcl_NewDoubleObj\fR returns a pointer to a newly created object
with reference count zero.
Both procedures set the object's type to be double
and assign the double value to the object's internal representation
\fIdoubleValue\fR member.
\fBTcl_SetDoubleObj\fR invalidates any old string representation
and, if the object is not already a double object,
frees any old internal representation.
.PP
\fBTcl_GetDoubleFromObj\fR attempts to return a double value
from the Tcl object \fIobjPtr\fR.
If the object is not already a double object,
it will attempt to convert it to one.
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
unless \fIinterp\fR is NULL.
Otherwise, it returns \fBTCL_OK\fR and stores the double value
in the address given by \fIdoublePtr\fR.
If the object is not already a double object,
the conversion will free any old internal representation.
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
.SH KEYWORDS
double, double object, double type, internal representation, object, object type, string representation

114
contrib/tcl/doc/Eval.3
View file

@ -1,114 +0,0 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) Eval.3 1.21 97/01/22 14:22:03
'\"
.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
\fBTcl_Eval\fR(\fIinterp, cmd\fR)
.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.
A 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 and is used by all the others.
It executes the commands in the script held by \fIcmd\fR
until either an error occurs or it reaches the end of the script.
.PP
Note that \fBTcl_Eval\fR and \fBTcl_GlobalEval\fR
have been largely replaced by the
object-based procedures \fBTcl_EvalObj\fR and \fBTcl_GlobalEvalObj\fR.
Those object-based procedures evaluate a script held in a Tcl object
instead of a string.
The object argument can retain the bytecode instructions for the script
and so avoid reparsing the script each time it is executed.
\fBTcl_Eval\fR is implemented using \fBTcl_EvalObj\fR
but is slower because it must reparse the script each time
since there is no object to retain the bytecode instructions.
.PP
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 (a result value or error message).
If an error occurs during compilation, this return information
describes the error.
Otherwise, 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
During the processing of a Tcl command it is legal to make nested
calls to evaluate other commands (this is how procedures and
some control structures 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 \fBTcl_Eval\fR
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,
it 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 "SEE ALSO"
Tcl_EvalObj, Tcl_GlobalEvalObj
.SH KEYWORDS
command, execute, file, global, object, object result, variable

91
contrib/tcl/doc/EvalObj.3
View file

@ -1,91 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) EvalObj.3 1.4 97/01/22 15:18:44
'\"
.so man.macros
.TH Tcl_EvalObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_EvalObj, Tcl_GlobalEvalObj \- execute Tcl commands
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_EvalObj\fR(\fIinterp, objPtr\fR)
.sp
int
\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
.SH ARGUMENTS
.AS Tcl_Interp **termPtr;
.AP Tcl_Interp *interp in
Interpreter in which to execute the command.
The command's result will be stored in the interpreter's result object
and can be retrieved using \fBTcl_GetObjResult\fR.
.AP Tcl_Obj *objPtr in
A Tcl object containing a command string
(or sequence of commands in a string) to execute.
.BE
.SH DESCRIPTION
.PP
These two procedures execute Tcl commands.
\fBTcl_EvalObj\fR is the core procedure
and is used by \fBTcl_GlobalEvalObj\fR.
It executes the commands in the script held by \fIobjPtr\fR
until either an error occurs or it reaches the end of the script.
If this is the first time \fIobjPtr\fR has been executed,
its commands are compiled into bytecode instructions
that are then executed if there are no compilation errors.
.PP
The return value from \fBTcl_EvalObj\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 a result object containing additional information
(a result value or error message)
that can be retrieved using \fBTcl_GetObjResult\fR.
If an error occurs during compilation, this return information
describes the error.
Otherwise, this return information corresponds to the last command
executed from \fIobjPtr\fR.
.PP
\fBTcl_GlobalEvalObj\fR is similar to \fBTcl_EvalObj\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 procedures and
some control structures are implemented).
If a code other than \fBTCL_OK\fR is returned
from a nested \fBTcl_EvalObj\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_EvalObj\fR keeps track of how many nested \fBTcl_EvalObj\fR
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_EvalObj\fR
invocation for \fIinterp\fR,
it converts the return code to \fBTCL_ERROR\fR
and sets the interpreter's result object
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_EvalObj\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
.SH "SEE ALSO"
Tcl_GetObjResult, Tcl_SetObjResult
.SH KEYWORDS
command, execute, file, global, object, object result, variable

103
contrib/tcl/doc/Exit.3
View file

@ -1,103 +0,0 @@
'\"
'\" 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.8 96/12/10 07:37:23
'\"
.so man.macros
.TH Tcl_Exit 3 7.7 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Exit, Tcl_Finalize, 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_Finalize\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, any nonzero value
usually 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
The procedures described here provide a graceful mechanism to end the
execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the
application's state before ending the execution of \fBTcl\fR code.
.PP
Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this
process. This procedure is invoked by the \fBexit\fR command, and can be
invoked anyplace else to terminate the application.
No-one should ever invoke the \fBexit\fR system procedure directly; always
invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers.
Note that if other code invokes \fBexit\fR system procedure directly, or
otherwise causes the application to terminate without calling
\fBTcl_Exit\fR, the exit handlers will not be run.
\fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
returns control to its caller.
.PP
.VS
\fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
exit from the current process.
It is useful for cleaning up when a process is finished using \fBTcl\fR but
wishes to continue executing, and when \fBTcl\fR is used in a dynamically
loaded extension that is about to be unloaded.
On some systems \fBTcl\fR is automatically notified when it is being
unloaded, and it calls \fBTcl_Finalize\fR internally; on these systems it
not necessary for the caller to explicitly call \fBTcl_Finalize\fR.
However, to ensure portability, your code should always invoke
\fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the
code will work on all platforms. \fBTcl_Finalize\fR can be safely called
more than once.
.VE
.PP
\fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
This provides a hook for cleanup operations such as flushing buffers
and freeing global memory.
\fIProc\fR should 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.
.PP
.VS
.PP
\fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
in reverse order from the order in which they were registered.
This matches the natural order in which extensions are loaded and unloaded;
if extension \fBA\fR loads extension \fBB\fR, it usually
unloads \fBB\fR before it itself is unloaded.
If extension \fBA\fR registers its exit handlers before loading extension
\fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
before the exit handlers for \fBA\fR.
.VE
.SH KEYWORDS
callback, cleanup, dynamic loading, end application, exit, unloading

114
contrib/tcl/doc/ExprLong.3
View file

@ -1,114 +0,0 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) ExprLong.3 1.26 97/06/26 13:42:47
'\"
.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 or \fIobjPtr\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 the expression
given by the \fIstring\fR argument
and return the result in one of four different forms.
The expression can have any of the forms accepted by the \fBexpr\fR command.
Note that these procedures have been largely replaced by the
object-based procedures \fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
\fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprStringObj\fR.
Those object-based procedures evaluate an expression held in a Tcl object
instead of a string.
The object argument can retain an internal representation
that is more efficient to execute.
.PP
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 they 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 they store 0 at \fI*booleanPtr\fR if
the value was zero and 1 otherwise.
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.
.PP
\fBTcl_ExprString\fR returns the value of the expression as a
string stored in \fIinterp->result\fR.
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.
.SH "SEE ALSO"
Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj
.SH KEYWORDS
boolean, double, evaluate, expression, integer, object, string

104
contrib/tcl/doc/ExprLongObj.3
View file

@ -1,104 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) ExprLongObj.3 1.6 97/06/26 13:41:12
'\"
.so man.macros
.TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj \- evaluate an expression
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_ExprLongObj\fR(\fIinterp, objPtr, longPtr\fR)
.sp
int
\fBTcl_ExprDoubleObj\fR(\fIinterp, objPtr, doublePtr\fR)
.sp
int
\fBTcl_ExprBooleanObj\fR(\fIinterp, objPtr, booleanPtr\fR)
.sp
int
\fBTcl_ExprObj\fR(\fIinterp, objPtr, resultPtrPtr\fR)
.SH ARGUMENTS
.AS Tcl_Interp *resultPtrPtr out
.AP Tcl_Interp *interp in
Interpreter in whose context to evaluate \fIstring\fR or \fIobjPtr\fR.
.AP Tcl_Obj *objPtr in
Pointer to an object containing the expression to evaluate.
.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.
.AP Tcl_Obj *resultPtrPtr out
Pointer to location in which to store a pointer to the object
that is the result 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 \fIobjPtr\fR argument, and it
can have any of the forms accepted by the \fBexpr\fR command.
.PP
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.
.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 a message describing the error
can be retrieved using \fBTcl_GetObjResult\fR.
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_ExprLongObj\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_ExprDoubleObj\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_ExprBooleanObj\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 they store 0 at \fI*booleanPtr\fR if
the value was zero and 1 otherwise.
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.
.PP
If \fBTcl_ExprObj\fR successfully evaluates the expression,
it stores a pointer to the Tcl object
containing the expression's value at \fI*resultPtrPtr\fR.
In this case, the caller is responsible for calling
\fBTcl_DecrRefCount\fR to decrement the object's reference count
when it is finished with the object.
.SH "SEE ALSO"
Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult
.SH KEYWORDS
boolean, double, evaluate, expression, integer, object, string

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

@ -1,46 +0,0 @@
'\"
'\" 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.4 96/10/09 08:29:29
'\"
.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, it 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
View file

@ -1,130 +0,0 @@
'\"
'\" 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

77
contrib/tcl/doc/GetIndex.3
View file

@ -1,77 +0,0 @@
'\"
'\" Copyright (c) 1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) @(#) GetIndex.3 1.3 97/07/30 16:21:05
'\"
.so man.macros
.TH Tcl_GetIndexFromObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_GetIndexFromObj \- lookup string in table of keywords
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags, indexPtr\fR)
.SH ARGUMENTS
.AS Tcl_Interp **tablePtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting; if NULL, then no message is
provided on errors.
.AP Tcl_Obj *objPtr in/out
The string value of this object is used to search through \fItablePtr\fR.
The internal representation is modified to hold the index of the matching
table entry.
.AP char **tablePtr in
An array of null-terminated strings. The end of the array is marked
by a NULL string pointer.
.AP char *msg in
Null-terminated string describing what is being looked up, such as
\fBoption\fR. This string is included in error messages.
.AP int flags in
OR-ed combination of bits providing additional information for
operation. The only bit that is currently defined is \fBTCL_EXACT\fR.
.AP int *indexPtr out
The index of the string in \fItablePtr\fR that matches the value of
\fIobjPtr\fR is returned here.
.BE
.SH DESCRIPTION
.PP
This procedure provides an efficient way for looking up keywords,
switch names, option names, and similar things where the value of
an object must be one of a predefined set of values.
\fIObjPtr\fR is compared against each of
the strings in \fItablePtr\fR to find a match. A match occurs if
\fIobjPtr\fR's string value is identical to one of the strings in
\fItablePtr\fR, or if it is a unique abbreviation
for exactly one of the strings in \fItablePtr\fR and the
\fBTCL_EXACT\fR flag was not specified; in either case
the index of the matching entry is stored at \fI*indexPtr\fR
and TCL_OK is returned.
.PP
If there is no matching entry,
TCL_ERROR is returned and an error message is left in \fIinterp\fR's
result if \fIinterp\fR isn't NULL. \fIMsg\fR is included in the
error message to indicate what was being looked up. For example,
if \fImsg\fR is \fBoption\fR the error message will have a form like
\fBbad option "firt": must be first, second, or third\fR.
.PP
If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
internal representation of \fIobjPtr\fR to hold the address of
the table and the index of the matching entry. If \fBTcl_GetIndexFromObj\fR
is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR
arguments (e.g. during a reinvocation of a Tcl command), it returns
the matching index immediately without having to redo the lookup
operation. Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
in \fItablePtr\fR are static: they must not change between invocations.
.SH "SEE ALSO"
Tcl_WrongNumArgs
.SH KEYWORDS
index, object, table lookup

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

@ -1,81 +0,0 @@
'\"
'\" 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

61
contrib/tcl/doc/GetOpnFl.3
View file

@ -1,61 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) GetOpnFl.3 1.3 97/04/23 16:14:43
.so man.macros
.TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_GetOpenFile \- Get a standard IO File * handle from a channel. (Unix only)
.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.
.VS
.PP
Note that this interface is only supported on the Unix platform.
.VE
.SH KEYWORDS
channel, file handle, permissions, pipeline, read, write

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

@ -1,73 +0,0 @@
'\"
'\" 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
View file

@ -1,208 +0,0 @@
'\"
'\" 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

104
contrib/tcl/doc/IntObj.3
View file

@ -1,104 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) @(#) IntObj.3 1.7 97/05/08 19:49:22
'\"
.so man.macros
.TH Tcl_IntObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewIntObj, Tcl_NewLongObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj \- manipulate Tcl objects as integers
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewIntObj\fR(\fIintValue\fR)
.sp
Tcl_Obj *
\fBTcl_NewLongObj\fR(\fIlongValue\fR)
.sp
\fBTcl_SetIntObj\fR(\fIobjPtr, intValue\fR)
.sp
\fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR)
.sp
int
\fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
.sp
int
\fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP int intValue in
Integer value used to initialize or set an integer object.
.AP long longValue in
Long integer value used to initialize or set an integer object.
.AP Tcl_Obj *objPtr in/out
For \fBTcl_SetIntObj\fR and \fBTcl_SetLongObj\fR,
this points to the object to be converted to integer type.
For \fBTcl_GetIntFromObj\fR and \fBTcl_GetLongFromObj\fR,
this refers to the object
from which to get an integer or long integer value;
if \fIobjPtr\fR does not already point to an integer object,
an attempt will be made to convert it to one.
.AP Tcl_Interp *interp in/out
If an error occurs during conversion,
an error message is left in the interpreter's result object
unless \fIinterp\fR is NULL.
.AP int *intPtr out
Points to place to store the integer value
obtained by \fBTcl_GetIntFromObj\fR from \fIobjPtr\fR.
.AP long *longPtr out
Points to place to store the long integer value
obtained by \fBTcl_GetLongFromObj\fR from \fIobjPtr\fR.
.BE
.SH DESCRIPTION
.PP
These procedures are used to create, modify, and read
integer Tcl objects from C code.
\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR,
\fBTcl_SetIntObj\fR, and \fBTcl_SetLongObj\fR
create a new object of integer type
or modify an existing object to have integer type.
\fBTcl_NewIntObj\fR and \fBTcl_SetIntObj\fR set the object to have the
integer value given by \fIintValue\fR,
while \fBTcl_NewLongObj\fR and \fBTcl_SetLongObj\fR
set the object to have the
long integer value given by \fIlongValue\fR.
\fBTcl_NewIntObj\fR and \fBTcl_NewLongObj\fR
return a pointer to a newly created object with reference count zero.
These procedures set the object's type to be integer
and assign the integer value to the object's internal representation
\fIlongValue\fR member.
\fBTcl_SetIntObj\fR and \fBTcl_SetLongObj\fR
invalidate any old string representation and,
if the object is not already an integer object,
free any old internal representation.
.PP
\fBTcl_GetIntFromObj\fR and \fBTcl_GetLongFromObj\fR
attempt to return an integer value from the Tcl object \fIobjPtr\fR.
If the object is not already an integer object,
they will attempt to convert it to one.
If an error occurs during conversion, they return \fBTCL_ERROR\fR
and leave an error message in the interpreter's result object
unless \fIinterp\fR is NULL.
Also, if the long integer held in the object's internal representation
\fIlongValue\fR member can not be represented in a (non-long) integer,
\fBTcl_GetIntFromObj\fR returns \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
unless \fIinterp\fR is NULL.
Otherwise, both procedures return \fBTCL_OK\fR and
store the integer or the long integer value
in the address given by \fIintPtr\fR and \fIlongPtr\fR respectively.
If the object is not already an integer object,
the conversion will free any old internal representation.
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
.SH KEYWORDS
integer, integer object, integer type, internal representation, object, object type, string representation

125
contrib/tcl/doc/Interp.3
View file

@ -1,125 +0,0 @@
'\"
'\" 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.16 96/06/06 13:48:02
'\"
.so man.macros
.TH Tcl_Interp 3 7.5 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.
.VS
In this case, the \fIfreeProc\fR field must be zero.
Alternatively, a command procedure may dynamically
allocate its return value (e.g. using \fBTcl_Alloc\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, or \fBTCL_DYNAMIC\fR
if the storage was allocated directly by Tcl or by a call to
\fBTcl_Alloc\fR.
.VE
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.
.VS
In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
used for \fIfreeProc\fR.
.VE
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

115
contrib/tcl/doc/LinkVar.3
View file

@ -1,115 +0,0 @@
'\"
'\" 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.15 96/09/05 17:16:57
'\"
.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
\fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
.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. Must be in writable memory: Tcl may make
temporary modifications to it while parsing the variable name.
.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.
.VS
If its value is not null then it must be a pointer to a string
allocated with \fBTcl_Alloc\fR.
.VE
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
\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.
.SH KEYWORDS
boolean, integer, link, read-only, real, string, traces, variable

249
contrib/tcl/doc/ListObj.3
View file

@ -1,249 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) @(#) ListObj.3 1.10 97/10/08 11:36:58
'\"
.so man.macros
.TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl objects as lists
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_ListObjAppendList\fR(\fIinterp, listPtr, elemListPtr\fR)
.sp
int
\fBTcl_ListObjAppendElement\fR(\fIinterp, listPtr, objPtr\fR)
.sp
Tcl_Obj *
\fBTcl_NewListObj\fR(\fIobjc, objv\fR)
.sp
\fBTcl_SetListObj\fR(\fIobjPtr, objc, objv\fR)
.sp
int
\fBTcl_ListObjGetElements\fR(\fIinterp, listPtr, objcPtr, objvPtr\fR)
.sp
int
\fBTcl_ListObjLength\fR(\fIinterp, listPtr, intPtr\fR)
.sp
int
\fBTcl_ListObjIndex\fR(\fIinterp, listPtr, index, objPtrPtr\fR)
.sp
int
\fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR)
.SH ARGUMENTS
.AS Tcl_Interp "*CONST objv[]" out
.AP Tcl_Interp *interp in
If an error occurs while converting an object to be a list object,
an error message is left in the interpreter's result object
unless \fIinterp\fR is NULL.
.AP Tcl_Obj *listPtr in/out
Points to the list object to be manipulated.
If \fIlistPtr\fR does not already point to a list object,
an attempt will be made to convert it to one.
.AP Tcl_Obj *elemListPtr in/out
For \fBTcl_ListObjAppendList\fR, this points to a list object
containing elements to be appended onto \fIlistPtr\fR.
Each element of *\fIelemListPtr\fR will
become a new element of \fIlistPtr\fR.
If *\fIelemListPtr\fR is not NULL and
does not already point to a list object,
an attempt will be made to convert it to one.
.AP Tcl_Obj *objPtr in
For \fBTcl_ListObjAppendElement\fR,
points to the Tcl object that will be appended to \fIlistPtr\fR.
For \fBTcl_SetListObj\fR,
this points to the Tcl object that will be converted to a list object
containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR.
.AP int *objcPtr in
Points to location where \fBTcl_ListObjGetElements\fR
stores the number of element objects in \fIlistPtr\fR.
.AP Tcl_Obj ***objvPtr out
A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array
of pointers to the element objects of \fIlistPtr\fR.
.AP int objc in
The number of Tcl objects that \fBTcl_NewListObj\fR
will insert into a new list object,
and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR.
For \fBTcl_SetListObj\fR,
the number of Tcl objects to insert into \fIobjPtr\fR.
.VS
.TP
Tcl_Obj *CONST \fIobjv\fR[] (in)
.
An array of pointers to objects.
\fBTcl_NewListObj\fR will insert these objects into a new list object
and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR.
Each object will become a separate list element.
.VE
.AP int *intPtr out
Points to location where \fBTcl_ListObjLength\fR
stores the length of the list.
.AP int index in
Index of the list element that \fBTcl_ListObjIndex\fR
is to return.
The first element has index 0.
.AP Tcl_Obj **objPtrPtr out
Points to place where \fBTcl_ListObjIndex\fR is to store
a pointer to the resulting list element object.
.AP int first in
Index of the starting list element that \fBTcl_ListObjReplace\fR
is to replace.
The list's first element has index 0.
.AP int count in
The number of elements that \fBTcl_ListObjReplace\fR
is to replace.
.BE
.SH DESCRIPTION
.PP
Tcl list objects have an internal representation that supports
the efficient indexing and appending.
The procedures described in this man page are used to
create, modify, index, and append to Tcl list objects from C code.
.PP
\fBTcl_ListObjAppendList\fR and \fBTcl_ListObjAppendElement\fR
both add one or more objects
to the end of the list object referenced by \fIlistPtr\fR.
\fBTcl_ListObjAppendList\fR appends each element of the list object
referenced by \fIelemListPtr\fR while
\fBTcl_ListObjAppendElement\fR appends the single object
referenced by \fIobjPtr\fR.
Both procedures will convert the object referenced by \fIlistPtr\fR
to a list object if necessary.
If an error occurs during conversion,
both procedures return \fBTCL_ERROR\fR and leave an error message
in the interpreter's result object if \fIinterp\fR is not NULL.
Similarly, if \fIelemListPtr\fR does not already refer to a list object,
\fBTcl_ListObjAppendList\fR will attempt to convert it to one
and if an error occurs during conversion,
will return \fBTCL_ERROR\fR
and leave an error message in the interpreter's result object
if interp is not NULL.
Both procedures invalidate any old string representation of \fIlistPtr\fR
and, if it was converted to a list object,
free any old internal representation.
Similarly, \fBTcl_ListObjAppendList\fR frees any old internal representation
of \fIelemListPtr\fR if it converts it to a list object.
After appending each element in \fIelemListPtr\fR,
\fBTcl_ListObjAppendList\fR increments the element's reference count
since \fIlistPtr\fR now also refers to it.
For the same reason, \fBTcl_ListObjAppendElement\fR
increments \fIobjPtr\fR's reference count.
If no error occurs,
the two procedures return \fBTCL_OK\fR after appending the objects.
.PP
\fBTcl_NewListObj\fR and \fBTcl_SetListObj\fR
create a new object or modify an existing object to hold
the \fIobjc\fR elements of the array referenced by \fIobjv\fR
where each element is a pointer to a Tcl object.
If \fIobjc\fR is less than or equal to zero,
they return an empty object.
The new object's string representation is left invalid.
The two procedures increment the reference counts
of the elements in \fIobjc\fR since the list object now refers to them.
The new list object returned by \fBTcl_NewListObj\fR
has reference count zero.
.PP
\fBTcl_ListObjGetElements\fR returns a count and
a pointer to an array of the elements in a list object.
It returns the count by storing it in the address \fIobjcPtr\fR.
Similarly, it returns the array pointer by storing it
in the address \fIobjvPtr\fR.
If \fIlistPtr\fR is not already a list object,
\fBTcl_ListObjGetElements\fR will attempt to convert it to one;
if the conversion fails, it returns \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
if \fIinterp\fR is not NULL.
Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer.
.PP
\fBTcl_ListObjLength\fR returns the number of elements in the list object
referenced by \fIlistPtr\fR.
It returns this count by storing an integer in the address \fIintPtr\fR.
If the object is not already a list object,
\fBTcl_ListObjLength\fR will attempt to convert it to one;
if the conversion fails, it returns \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
if \fIinterp\fR is not NULL.
Otherwise it returns \fBTCL_OK\fR after storing the list's length.
.PP
The procedure \fBTcl_ListObjIndex\fR returns a pointer to the object
at element \fIindex\fR in the list referenced by \fIlistPtr\fR.
It returns this object by storing a pointer to it
in the address \fIobjPtrPtr\fR.
If \fIlistPtr\fR does not already refer to a list object,
\fBTcl_ListObjIndex\fR will attempt to convert it to one;
if the conversion fails, it returns \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
if \fIinterp\fR is not NULL.
If the index is out of range,
that is, \fIindex\fR is negative or
greater than or equal to the number of elements in the list,
\fBTcl_ListObjIndex\fR stores a NULL in \fIobjPtrPtr\fR
and returns \fBTCL_OK\fR.
Otherwise it returns \fBTCL_OK\fR after storing the element's
object pointer.
The reference count for the list element is not incremented;
the caller must do that if it needs to retain a pointer to the element.
.PP
\fBTcl_ListObjReplace\fR replaces zero or more elements
of the list referenced by \fIlistPtr\fR
with the \fIobjc\fR objects in the array referenced by \fIobjv\fR.
If \fIlistPtr\fR does not point to a list object,
\fBTcl_ListObjReplace\fR will attempt to convert it to one;
if the conversion fails, it returns \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
if \fIinterp\fR is not NULL.
Otherwise, it returns \fBTCL_OK\fR after replacing the objects.
If \fIobjv\fR is NULL, no new elements are added.
If the argument \fIfirst\fR is zero or negative,
it refers to the first element.
If \fIfirst\fR is greater than or equal to the
number of elements in the list, then no elements are deleted;
the new elements are appended to the list.
\fIcount\fR gives the number of elements to replace.
If \fIcount\fR is zero or negative then no elements are deleted;
the new elements are simply inserted before the one
designated by \fIfirst\fR.
\fBTcl_ListObjReplace\fR invalidates \fIlistPtr\fR's
old string representation.
The reference counts of any elements inserted from \fIobjv\fR
are incremented since the resulting list now refers to them.
Similarly, the reference counts for any replaced objects are decremented.
.PP
Because \fBTcl_ListObjReplace\fR combines
both element insertion and deletion,
it can be used to implement a number of list operations.
For example, the following code inserts the \fIobjc\fR objects
referenced by the array of object pointers \fIobjv\fR
just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR:
.CS
result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv);
.CE
Similarly, the following code appends the \fIobjc\fR objects
referenced by the array \fIobjv\fR
to the end of the list \fIlistPtr\fR:
.CS
result = Tcl_ListObjLength(interp, listPtr, &length);
if (result == TCL_OK) {
result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv);
}
.CE
The \fIcount\fR list elements starting at \fIfirst\fR can be deleted
by simply calling \fBTcl_ListObjReplace\fR
with a NULL \fIobjvPtr\fR:
.CS
result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL);
.CE
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
.SH KEYWORDS
append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation

537
contrib/tcl/doc/Notifier.3
View file

@ -1,537 +0,0 @@
'\"
'\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) Notifier.3 1.16 97/05/17 17:03:17
'\"
.so man.macros
.TH Notifier 3 8.0 Tcl "Tcl Library Procedures"
.BS
.VS
.SH NAME
Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_WaitForEvent, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
.sp
\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
.sp
\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fB)\fR
.sp
\fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
.VS
.sp
\fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
.sp
int
\fBTcl_WaitForEvent\fR(\fItimePtr\fR)
.sp
\fBTcl_SetTimer\fR(\fItimePtr\fR)
.sp
int
\fBTcl_ServiceAll\fR()
.sp
int
\fBTcl_ServiceEvent\fR(\fIflags\fR)
.sp
int
\fBTcl_GetServiceMode\fR()
.sp
int
\fBTcl_SetServiceMode\fR(\fImode\fR)
.VE
.SH ARGUMENTS
.AS Tcl_EventDeleteProc milliseconds
.AS Tcl_EventSetupProc *setupProc
.AP Tcl_EventSetupProc *setupProc in
Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
.AP Tcl_EventCheckProc *checkProc in
Procedure for \fBTcl_DoOneEvent\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, \fIcheckProc\fR, or
\fIdeleteProc\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 \fBTcl_Alloc\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
What types of events to service. These flags are the same as those
passed to \fBTcl_DoOneEvent\fR.
.AP Tcl_EventDeleteProc *deleteProc in
Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
.VS
.AP int mode in
Inidicates whether events should be serviced by \fBTcl_ServiceAll\fR.
Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
.VE
.BE
.SH INTRODUCTION
.PP
.VS
The interfaces described here are used to customize the Tcl event
loop. The two most common customizations are to add new sources of
events and to merge Tcl's event loop with some other event loop, such
as one provided by an application in which Tcl is embedded. Each of
these tasks is described in a separate section below.
.VE
.PP
The procedures in this manual entry 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 on Unix systems. 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. The procedures
\fBTcl_CreateEventSource\fR, \fBTcl_DeleteEventSource\fR,
and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
\fBTcl_DeleteEvents\fR are used primarily by event sources.
.IP [2]
The event queue: there is a single queue for the whole application,
containing events that have been detected but not yet serviced. Event
sources place events onto the queue so that they may be processed in
order at appropriate times during the event loop. 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.
.VS
\fBTcl_QueueEvent\fR is used (primarily
by event sources) to add events to the event queue and
\fBTcl_DeleteEvents\fR is used to remove events from the queue without
processing them.
.IP [3]
The event loop: in order to detect and process events, the application
enters a loop that waits for events to occur, places them on the event
queue, and then processes them. Most applications will do this by
calling the procedure \fBTcl_DoOneEvent\fR, which is described in a
separate manual entry.
.PP
Most Tcl applications need not worry about any of the internals of
the Tcl notifier. However, the notifier now has enough flexibility
to be retargeted either for a new platform or to use an external event
loop (such as the Motif event loop, when Tcl is embedded in a Motif
application). The procedures \fBTcl_WaitForEvent\fR and
\fBTcl_SetTimer\fR are normally implemented by Tcl, but may be
replaced with new versions to retarget the notifier (the \fBTcl_Sleep\fR,
\fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must
also be replaced; see CREATING A NEW NOTIFIER below for details).
The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
\fBTcl_GetServiceMode\fR, and \fBTcl_SetServiceMode\fR are provided
to help connect Tcl's event loop to an external event loop such as
Motif's.
.SH "NOTIFIER BASICS"
.VE
.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
.VS
from the queue, and return. It does this by calling
\fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
.VE
.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 perform event-source specific initialization and
.VS
possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
.VE
\fBTcl_WaitForEvent\fR will block if no new events occur.
.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. 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.
.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
be 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 make sure that the application wakes up
when events of the desired type occur. This is typically done in a
platform-dependent fashion. For example, under Unix an event source
might call \fBTcl_CreateFileHandler\fR; under Windows it might
request notification with a Windows event. For timer-driven event
sources such as timer events or any polled event, the event source
can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
up after a specified time even if no events have occurred.
.VS
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. If an event source knows that it already has events ready to
report, it can request a zero maximum block time. For example, the
setup procedure for the X event source looks to see if there are
events already queued. If there are, it calls
\fBTcl_SetMaxBlockTime\fR with a 0 block time so that
\fBTcl_WaitForEvent\fR does not block if there is no new data on the X
connection.
.VE
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
.VS
Information provided to \fBTcl_SetMaxBlockTime\fR
is only used for the next call to \fBTcl_WaitForEvent\fR; it is
discarded after \fBTcl_WaitForEvent\fR returns.
.VE
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
.VS
If the application uses an external event loop rather than
\fBTcl_DoOneEvent\fR, the event sources may need to call
\fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event
handler is registered that needs to poll for events, the event source
may call \fBTcl_SetMaxBlockTime\fR to set the block time to zero to
force the external event loop to call Tcl. In this case,
\fBTcl_SetMaxBlockTime\fR invokes \fBTcl_SetTimer\fR with the shortest
interval seen since the last call to \fBTcl_DoOneEvent\fR or
\fBTcl_ServiceAll\fR.
.PP
In addition to the generic procedure \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. For example, on Unix systems
the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events.
.VE
.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.
.PP
If an event source's check procedure detects an interesting event, 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
.VS
When it is time to handle an event from the queue (steps 1 and 4
above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
.VE
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
.VS
current call to \fBTcl_ServiceEvent\fR; this is used by the event source
.VE
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
.VS
should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR
.VE
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
.VS
When \fIproc\fR returns 1, \fBTcl_ServiceEvent\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 \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
before calling \fBTcl_QueueEvent\fR, but it
will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
.PP
\fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
for each event in the queue, deleting those for with the procedure
returns 1. Events for which the procedure returns 0 are left in the
queue. \fIProc\fR should match the following prototype:
.CS
typedef int Tcl_EventDeleteProc(
Tcl_Event *\fIevPtr\fR,
ClientData \fIclientData\fR);
.CE
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
private information managed by the event source. The \fIevPtr\fR will
point to the next event in the queue.
.VE
.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, which are
.VS
available on all platforms, and \fBTcl_CreateFileHandler\fR and
\fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these
procedures are generic, in that they are the same for all notifiers.
However, five of the procedures are notifier-dependent:
\fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR. To
support a new platform or to integrate Tcl with an
application-specific event loop, you must write new versions of these
procedures.
.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 \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).
.PP
Ideally, \fBTcl_WaitForEvent\fR should only wait for an event
to occur; it should not actually process the event in any way.
Later on, the
event sources will process the raw events and create Tcl_Events on
the event queue in their \fIcheckProc\fR procedures.
However, on some platforms (such as Windows) this isn't possible;
events may be processed in \fBTcl_WaitForEvent\fR, including queuing
Tcl_Events and more (for example, callbacks for native widgets may be
invoked). The return value from \fBTcl_WaitForEvent\fR must be either
0, 1, or \-1. On platforms such as Windows where events get processed in
\fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
events still pending that haven't been processed. This is a sign to the
caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
pending events to be processed. A 0 return value means that calling
\fBTcl_WaitForEvent\fR again will not have any effect: either this is a
platform where \fBTcl_WaitForEvent\fR only waits without doing any event
processing, or \fBTcl_WaitForEvent\fR knows for sure that there are no
additional events to process (e.g. it returned because the time
elapsed). Finally, a return value of \-1 means that the event loop is
no longer operational and the application should probably unwind and
terminate. Under Windows this happens when a WM_QUIT message is received;
under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
forever because there were no active event sources and the timeout was
infinite.
.PP
If the notifier will be used with an external event loop, then it must
also support the \fBTcl_SetTimer\fR interface. \fBTcl_SetTimer\fR is
invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
time has been reduced. \fBTcl_SetTimer\fR should arrange for the
external event loop to invoke \fBTcl_ServiceAll\fR after the specified
interval even if no events have occurred. This interface is needed
because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
event loop. If the
notifier will only be used from \fBTcl_DoOneEvent\fR, then
\fBTcl_SetTimer\fR need not do anything.
.PP
On Unix systems, the file event source also needs support from the
notifier. The file event source consists of the
\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
procedures, which are described elsewhere.
.PP
The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described
elsewhere.
.PP
The easiest way to create a new notifier is to look at the code
for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
.SH "EXTERNAL EVENT LOOPS"
.PP
The notifier interfaces are designed so that Tcl can be embedded into
applications that have their own private event loops. In this case,
the application does not call \fBTcl_DoOneEvent\fR except in the case
of recursive event loops such as calls to the Tcl commands \fBupdate\fR
or \fBvwait\fR. Most of the time is spent in the external event loop
of the application. In this case the notifier must arrange for the
external event loop to call back into Tcl when something
happens on the various Tcl event sources. These callbacks should
arrange for appropriate Tcl events to be placed on the Tcl event queue.
.PP
Because the external event loop is not calling \fBTcl_DoOneEvent\fR on
a regular basis, it is up to the notifier to arrange for
\fBTcl_ServiceEvent\fR to be called whenever events are pending on the
Tcl event queue. The easiest way to do this is to invoke
\fBTcl_ServiceAll\fR at the end of each callback from the external
event loop. This will ensure that all of the event sources are
polled, any queued events are serviced, and any pending idle handlers
are processed before returning control to the application. In
addition, event sources that need to poll for events can call
\fBTcl_SetMaxBlockTime\fR to force the external event loop to call
Tcl even if no events are available on the system event queue.
.PP
As a side effect of processing events detected in the main external
event loop, Tcl may invoke \fBTcl_DoOneEvent\fR to start a recursive event
loop in commands like \fBvwait\fR. \fBTcl_DoOneEvent\fR will invoke
the external event loop, which will result in callbacks as described
in the preceding paragraph, which will result in calls to
\fBTcl_ServiceAll\fR. However, in these cases it is undesirable to
service events in \fBTcl_ServiceAll\fR. Servicing events there is
unnecessary because control will immediately return to the
external event loop and hence to \fBTcl_DoOneEvent\fR, which can
service the events itself. Furthermore, \fBTcl_DoOneEvent\fR is
supposed to service only a single event, whereas \fBTcl_ServiceAll\fR
normally services all pending events. To handle this situation,
\fBTcl_DoOneEvent\fR sets a flag for \fBTcl_ServiceAll\fR
that causes it to return without servicing any events.
This flag is called the \fIservice mode\fR;
\fBTcl_DoOneEvent\fR restores it to its previous value before it returns.
.PP
In some cases, however, it may be necessary for \fBTcl_ServiceAll\fR
to service events
even when it has been invoked from \fBTcl_DoOneEvent\fR. This happens
when there is yet another recursive event loop invoked via an
event handler called by \fBTcl_DoOneEvent\fR (such as one that is
part of a native widget). In this case, \fBTcl_DoOneEvent\fR may not
have a chance to service events so \fBTcl_ServiceAll\fR must service
them all. Any recursive event loop that calls an external event
loop rather than \fBTcl_DoOneEvent\fR must reset the service mode so
that all events get processed in \fBTcl_ServiceAll\fR. This is done
by invoking the \fBTcl_SetServiceMode\fR procedure. If
\fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_NONE\fR, then calls
to \fBTcl_ServiceAll\fR will return immediately without processing any
events. If \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_ALL\fR,
then calls to \fBTcl_ServiceAll\fR will behave normally.
\fBTcl_SetServiceMode\fR returns the previous value of the service
mode, which should be restored when the recursive loop exits.
\fBTcl_GetServiceMode\fR returns the current value of the service
mode.
.VE
.SH KEYWORDS
event, notifier, event queue, event sources, file events, timer, idle, service mode

162
contrib/tcl/doc/ObjSetVar.3
View file

@ -1,162 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) ObjSetVar.3 1.6 97/05/19 17:35:44
'\"
.so man.macros
.TH Tcl_ObjSetVar2 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_ObjSetVar2, Tcl_ObjGetVar2 \- manipulate Tcl variables
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR)
.sp
Tcl_Obj *
\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR)
.SH ARGUMENTS
.AS Tcl_Interp *newValuePtr
.AP Tcl_Interp *interp in
Interpreter containing variable.
.AP Tcl_Obj *part1Ptr in
Points to a Tcl object containing the variable's name.
The name may include a series of \fB::\fR namespace qualifiers
to specify a variable in a particular namespace.
May refer to a scalar variable or an element of an array variable.
.AP Tcl_Obj *part2Ptr in
If non-NULL, points to an object containing the name of an element
within an array and \fIpart1Ptr\fR must refer to an array variable.
.AP Tcl_Obj *newValuePtr in
Points to a Tcl object containing the new value for the variable.
.AP int flags in
OR-ed combination of bits providing additional information for
operation. See below for valid values.
.BE
.SH DESCRIPTION
.PP
These two procedures may be used to read and modify
Tcl variables from C code.
\fBTcl_ObjSetVar2\fR will create a new variable or modify an existing one.
It sets the specified variable to
the object referenced by \fInewValuePtr\fR
and returns a pointer to the object which is the variable's new value.
The returned object may not be the same one
referenced by \fInewValuePtr\fR;
this might happen because variable traces may modify the variable's value.
The reference count for the variable's old value is decremented
and the reference count for its new value is incremented.
If the new value for the variable
is not the same one referenced by \fInewValuePtr\fR
(perhaps as a result of a variable trace),
then \fInewValuePtr\fR's reference count is left unchanged.
The reference count for the returned object is not incremented
to reflect the returned reference.
If the caller needs to keep a reference to the object,
say in a data structure,
it must increment its reference count using \fBTcl_IncrRefCount\fR.
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 variable name specified to \fBTcl_ObjSetVar2\fR consists of two parts.
\fIpart1Ptr\fR contains the name of a scalar or array variable.
If \fIpart2Ptr\fR is NULL, the variable must be a scalar.
If \fIpart2Ptr\fR is not NULL,
it contains the name of an element in the array named by \fIpart2Ptr\fR.
As a special case, if the flag TCL_PARSE_PART1 is specified,
\fIpart1Ptr\fR may contain both an array and an element name:
if the name contains an open parenthesis and ends with a
close parenthesis, then the value between the parentheses is
treated as an element name (which can have any string value) and
the characters before the first open
parenthesis are treated as the name of an array variable.
If the flag TCL_PARSE_PART1 is given,
\fIpart2Ptr\fR should be NULL since the array and element names
are taken from \fIpart2Ptr\fR.
.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 as follows:
If a procedure call is active in \fIinterp\fR,
a variable is looked up at the current level of procedure call.
Otherwise, a variable is looked up first in the current namespace,
then in the global namespace.
However, if this bit is set in \fIflags\fR then the variable
is looked up only in the global namespace
even if there is a procedure call active.
If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
\fBTCL_GLOBAL_ONLY\fR is ignored.
.TP
\fBTCL_NAMESPACE_ONLY\fR
Under normal circumstances the procedures look up variables as follows:
If a procedure call is active in \fIinterp\fR,
a variable is looked up at the current level of procedure call.
Otherwise, a variable is looked up first in the current namespace,
then in the global namespace.
However, if this bit is set in \fIflags\fR then the variable
is looked up only in the current namespace
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 the interpreter's result,
where it can be retrieved with \fBTcl_GetObjResult\fR
or \fBTcl_GetStringResult\fR.
If this flag bit isn't set then no error message is left
and the interpreter's result will not be modified.
.TP
\fBTCL_APPEND_VALUE\fR
If this bit is set then \fInewValuePtr\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 \fInewValuePtr\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
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 `` }'').
.TP
\fBTCL_PARSE_PART1\fR
If this bit is set,
then \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR
will parse \fIpart1Ptr\fR
to obtain both an array name and an element name.
If the name in \fIpart1Ptr\fR contains an open parenthesis
and ends with a close parenthesis,
the name is treated as the name of an element of an array;
otherwise, the name in \fIpart1Ptr\fR
is interpreted as the name of a scalar variable.
When this bit is set,
\fIpart2Ptr\fR is ignored.
.PP
\fBTcl_ObjGetVar2\fR returns the value of the specified variable.
Its arguments are treated the same way as those for \fBTcl_ObjSetVar2\fR.
It returns a pointer to the object which is the variable's value.
The reference count for the returned object is not incremented.
If the caller needs to keep a reference to the object,
say in a data structure,
it must increment the reference count using \fBTcl_IncrRefCount\fR.
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.
.SH "SEE ALSO"
Tcl_GetObjResult, Tcl_GetStringResult, Tcl_GetVar, Tcl_GetVar2, Tcl_SetVar, Tcl_SetVar2, Tcl_TraceVar, Tcl_UnsetVar, Tcl_UnsetVar2
.SH KEYWORDS
array, interpreter, object, scalar, set, unset, variable

336
contrib/tcl/doc/Object.3
View file

@ -1,336 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) @(#) Object.3 1.10 97/07/22 11:40:10
'\"
.so man.macros
.TH Tcl_Obj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared \- manipulate Tcl objects
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewObj\fR()
.sp
Tcl_Obj *
\fBTcl_DuplicateObj\fR(\fIobjPtr\fR)
.sp
\fBTcl_IncrRefCount\fR(\fIobjPtr\fR)
.sp
\fBTcl_DecrRefCount\fR(\fIobjPtr\fR)
.sp
int
\fBTcl_IsShared\fR(\fIobjPtr\fR)
.sp
\fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR)
.SH ARGUMENTS
.AS Tcl_Obj *objPtr in
.AP Tcl_Obj *objPtr in
Points to an object;
must have been the result of a previous call to \fBTcl_NewObj\fR.
.BE
.SH INTRODUCTION
.PP
This man page presents an overview of Tcl objects and how they are used.
It also describes generic procedures for managing Tcl objects.
These procedures are used to create and copy objects,
and increment and decrement the count of references (pointers) to objects.
The procedures are used in conjunction with ones
that operate on specific types of objects such as
\fBTcl_GetIntFromObj\fR and \fBTcl_ListObjAppendElement\fR.
The individual procedures are described along with the data structures
they manipulate.
.PP
Tcl's \fIdual-ported\fR objects provide a general-purpose mechanism
for storing and exchanging Tcl values.
They largely replace the use of strings in Tcl.
For example, they are used to store variable values,
command arguments, command results, and scripts.
Tcl objects behave like strings but also hold an internal representation
that can be manipulated more efficiently.
For example, a Tcl list is now represented as an object
that holds the list's string representation
as well as an array of pointers to the objects for each list element.
Dual-ported objects avoid most runtime type conversions.
They also improve the speed of many operations
since an appropriate representation is immediately available.
The compiler itself uses Tcl objects to
cache the instruction bytecodes resulting from compiling scripts.
.PP
The two representations are a cache of each other and are computed lazily.
That is, each representation is only computed when necessary,
it is computed from the other representation,
and, once computed, it is saved.
In addition, a change in one representation invalidates the other one.
As an example, a Tcl program doing integer calculations can
operate directly on a variable's internal machine integer
representation without having to constantly convert
between integers and strings.
Only when it needs a string representing the variable's value,
say to print it,
will the program regenerate the string representation from the integer.
Although objects contain an internal representation,
their semantics are defined in terms of strings:
an up-to-date string can always be obtained,
and any change to the object will be reflected in that string
when the object's string representation is fetched.
Because of this representation invalidation and regeneration,
it is dangerous for extension writers to access
\fBTcl_Obj\fR fields directly.
It is better to access Tcl_Obj information using
procedures like \fBTcl_GetStringFromObj\fR.
.PP
Objects are allocated on the heap
and are referenced using a pointer to their \fBTcl_Obj\fR structure.
Objects are shared as much as possible.
This significantly reduces storage requirements
because some objects such as long lists are very large.
Also, most Tcl values are only read and never modified.
This is especially true for procedure arguments,
which can be shared between the caller and the called procedure.
Assignment and argument binding is done by
simply assigning a pointer to the value.
Reference counting is used to determine when it is safe to
reclaim an object's storage.
.PP
Tcl objects are typed.
An object's internal representation is controlled by its type.
Seven types are predefined in the Tcl core
including integer, double, list, and bytecode.
Extension writers can extend the set of types
by using the procedure \fBTcl_RegisterObjType\fR .
.SH "THE TCL_OBJ STRUCTURE"
.PP
Each Tcl object is represented by a \fBTcl_Obj\fR structure
which is defined as follows.
.CS
typedef struct Tcl_Obj {
int \fIrefCount\fR;
char *\fIbytes\fR;
int \fIlength\fR;
Tcl_ObjType *\fItypePtr\fR;
union {
long \fIlongValue\fR;
double \fIdoubleValue\fR;
VOID *\fIotherValuePtr\fR;
struct {
VOID *\fIptr1\fR;
VOID *\fIptr2\fR;
} \fItwoPtrValue\fR;
} \fIinternalRep\fR;
} Tcl_Obj;
.CE
The \fIbytes\fR and the \fIlength\fR members together hold
an object's string representation,
which is a \fIcounted\fR or \fIbinary string\fR
that may contain binary data with embedded null bytes.
\fIbytes\fR points to the first byte of the string representation.
The \fIlength\fR member gives the number of bytes.
The byte array must always have a null after the last byte,
at offset \fIlength\fR;
this allows string representations that do not contain nulls
to be treated as conventional null-terminated C strings.
C programs use \fBTcl_GetStringFromObj\fR to get
an object's string representation.
If \fIbytes\fR is NULL,
the string representation is invalid.
.PP
An object's type manages its internal representation.
The member \fItypePtr\fR points to the Tcl_ObjType structure
that describes the type.
If \fItypePtr\fR is NULL,
the internal representation is invalid.
.PP
The \fIinternalRep\fR union member holds
an object's internal representation.
This is either a (long) integer, a double-precision floating point number,
a pointer to a value containing additional information
needed by the object's type to represent the object,
or two arbitrary pointers.
.PP
The \fIrefCount\fR member is used to tell when it is safe to free
an object's storage.
It holds the count of active references to the object.
Maintaining the correct reference count is a key responsibility
of extension writers.
Reference counting is discussed below
in the section \fBSTORAGE MANAGEMENT OF OBJECTS\fR.
.PP
Although extension writers can directly access
the members of a Tcl_Obj structure,
it is much better to use the appropriate procedures and macros.
For example, extension writers should never
read or update \fIrefCount\fR directly;
they should use macros such as
\fBTcl_IncrRefCount\fR and \fBTcl_IsShared\fR instead.
.PP
A key property of Tcl objects is that they hold two representations.
An object typically starts out containing only a string representation:
it is untyped and has a NULL \fItypePtr\fR.
An object containing an empty string or a copy of a specified string
is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively.
An object's string value is gotten with \fBTcl_GetStringFromObj\fR
and changed with \fBTcl_SetStringObj\fR.
If the object is later passed to a procedure like \fBTcl_GetIntFromObj\fR
that requires a specific internal representation,
the procedure will create one and set the object's \fItypePtr\fR.
The internal representation is computed from the string representation.
An object's two representations are duals of each other:
changes made to one are reflected in the other.
For example, \fBTcl_ListObjReplace\fR will modify an object's
internal representation and the next call to \fBTcl_GetStringFromObj\fR
will reflect that change.
.PP
Representations are recomputed lazily for efficiency.
A change to one representation made by a procedure
such as \fBTcl_ListObjReplace\fR is not reflected immediately
in the other representation.
Instead, the other representation is marked invalid
so that it is only regenerated if it is needed later.
Most C programmers never have to be concerned with how this is done
and simply use procedures such as \fBTcl_GetBooleanFromObj\fR or
\fBTcl_ListObjIndex\fR.
Programmers that implement their own object types
must check for invalid representations
and mark representations invalid when necessary.
The procedure \fBTcl_InvalidateStringRep\fR is used
to mark an object's string representation invalid and to
free any storage associated with the old string representation.
.PP
Objects usually remain one type over their life,
but occasionally an object must be converted from one type to another.
For example, a C program might build up a string in an object
with repeated calls to \fBTcl_StringObjAppend\fR,
and then call \fBTcl_ListObjIndex\fR to extract a list element from
the object.
The same object holding the same string value
can have several different internal representations
at different times.
Extension writers can also force an object to be converted from one type
to another using the \fBTcl_ConvertToType\fR procedure.
Only programmers that create new object types need to be concerned
about how this is done.
A procedure defined as part of the object type's implementation
creates a new internal representation for an object
and changes its \fItypePtr\fR.
See the man page for \fBTcl_RegisterObjType\fR
to see how to create a new object type.
.SH "EXAMPLE OF THE LIFETIME OF AN OBJECT"
.PP
As an example of the lifetime of an object,
consider the following sequence of commands:
.CS
\fBset x 123\fR
.CE
This assigns to \fIx\fR an untyped object whose
\fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3.
The object's \fItypePtr\fR member is NULL.
.CS
\fBputs "x is $x"\fR
.CE
\fIx\fR's string representation is valid (since \fIbytes\fR is non-NULL)
and is fetched for the command.
.CS
\fBincr x\fR
.CE
The \fBincr\fR command first gets an integer from \fIx\fR's object
by calling \fBTcl_GetIntFromObj\fR.
This procedure checks whether the object is already an integer object.
Since it is not, it converts the object
by setting the object's \fIinternalRep.longValue\fR member
to the integer \fB123\fR
and setting the object's \fItypePtr\fR
to point to the integer Tcl_ObjType structure.
Both representations are now valid.
\fBincr\fR increments the object's integer internal representation
then invalidates its string representation
(by calling \fBTcl_InvalidateStringRep\fR)
since the string representation
no longer corresponds to the internal representation.
.CS
\fBputs "x is now $x"\fR
.CE
The string representation of \fIx\fR's object is needed
and is recomputed.
The string representation is now \fB124\fR.
and both representations are again valid.
.SH "STORAGE MANAGEMENT OF OBJECTS"
.PP
Tcl objects are allocated on the heap and are shared as much as possible
to reduce storage requirements.
Reference counting is used to determine when an object is
no longer needed and can safely be freed.
An object just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR
has \fIrefCount\fR 0.
The macro \fBTcl_IncrRefCount\fR increments the reference count
when a new reference to the object is created.
The macro \fBTcl_DecrRefCount\fR decrements the count
when a reference is no longer needed and,
if the object's reference count drops to zero, frees its storage.
An object shared by different code or data structures has
\fIrefCount\fR greater than 1.
Incrementing an object's reference count ensures that
it won't be freed too early or have its value change accidently.
.PP
As an example, the bytecode interpreter shares argument objects
between calling and called Tcl procedures to avoid having to copy objects.
It assigns the call's argument objects to the procedure's
formal parameter variables.
In doing so, it calls \fBTcl_IncrRefCount\fR to increment
the reference count of each argument since there is now a new
reference to it from the formal parameter.
When the called procedure returns,
the interpreter calls \fBTcl_DecrRefCount\fR to decrement
each argument's reference count.
When an object's reference count drops to zero,
\fBTcl_DecrRefCount\fR reclaims its storage.
Most command procedures do not have to be concerned about
reference counting since they use an object's value immediately
and don't retain a pointer to the object after they return.
However, if they do retain a pointer to an object in a data structure,
they must be careful to increment its reference count
since the retained pointer is a new reference.
.PP
Command procedures that directly modify objects
such as those for \fBlappend\fR and \fBlinsert\fR must be careful to
copy a shared object before changing it.
They must first check whether the object is shared
by calling \fBTcl_IsShared\fR.
If the object is shared they must copy the object
by using \fBTcl_DuplicateObj\fR;
this returns a new duplicate of the original object
that has \fIrefCount\fR 0.
If the object is not shared,
the command procedure "owns" the object and can safely modify it directly.
For example, the following code appears in the command procedure
that implements \fBlinsert\fR.
This procedure modifies the list object passed to it in \fIobjv[1]\fR
by inserting \fIobjc-3\fR new elements before \fIindex\fR.
.CS
listPtr = objv[1];
if (Tcl_IsShared(listPtr)) {
listPtr = Tcl_DuplicateObj(listPtr);
}
result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3]));
.CE
As another example, \fBincr\fR's command procedure
must check whether the variable's object is shared before
incrementing the integer in its internal representation.
If it is shared, it needs to duplicate the object
in order to avoid accidently changing values in other data structures.
.SH "SEE ALSO"
Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType
.SH KEYWORDS
internal representation, object, object creation, object type, reference counting, string representation, type conversion

198
contrib/tcl/doc/ObjectType.3
View file

@ -1,198 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) ObjectType.3 1.8 97/04/30 15:42:29
'\"
.so man.macros
.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl object types
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_RegisterObjType\fR(\fItypePtr\fR)
.sp
Tcl_ObjType *
\fBTcl_GetObjType\fR(\fItypeName\fR)
.sp
int
\fBTcl_AppendAllObjTypes\fR(\fIinterp, objPtr\fR)
.sp
int
\fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
.SH ARGUMENTS
.AS Tcl_ObjType *typeName in
.AP Tcl_ObjType *typePtr in
Points to the structure containing information about the Tcl object type.
This storage must must live forever,
typically by being statically allocated.
.AP char *typeName in
The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tcl_Obj *objPtr in
For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which
it appends the name of each object type as a list element.
For \fBTcl_ConvertToType\fR, this points to an object that
must have been the result of a previous call to \fBTcl_NewObj\fR.
.BE
.SH DESCRIPTION
.PP
The procedures in this man page manage Tcl object types.
The are used to register new object types,
look up types,
and force conversions from one type to another.
.PP
\fBTcl_RegisterObjType\fR registers a new Tcl object type
in the table of all object types supported by Tcl.
The argument \fItypePtr\fR points to a Tcl_ObjType structure that
describes the new type by giving its name
and by supplying pointers to four procedures
that implement the type.
If the type table already contains a type
with the same name as in \fItypePtr\fR,
it is replaced with the new type.
The Tcl_ObjType structure is described
in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
.PP
\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
with name \fItypeName\fR.
It returns NULL if no type with that name is registered.
.PP
\fBTcl_AppendAllObjTypes\fR appends the name of each object type
as a list element onto the Tcl object referenced by \fIobjPtr\fR.
The return value is \fBTCL_OK\fR unless there was an error
converting \fIobjPtr\fR to a list object;
in that case \fBTCL_ERROR\fR is returned.
.PP
\fBTcl_ConvertToType\fR converts an object from one type to another
if possible.
It creates a new internal representation for \fIobjPtr\fR
appropriate for the target type \fItypePtr\fR
and sets its \fItypePtr\fR member to that type.
Any internal representation for \fIobjPtr\fR's old type is freed.
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
and leaves an error message in the result object for \fIinterp\fR
unless \fIinterp\fR is NULL.
Otherwise, it returns \fBTCL_OK\fR.
Passing a NULL \fIinterp\fR allows this procedure to be used
as a test whether the conversion can be done (and in fact was done).
.SH "THE TCL_OBJTYPE STRUCTURE"
.PP
Extension writers can define new object types by defining four
procedures,
initializing a Tcl_ObjType structure to describe the type,
and calling \fBTcl_RegisterObjType\fR.
The \fBTcl_ObjType\fR structure is defined as follows:
.CS
typedef struct Tcl_ObjType {
char *\fIname\fR;
Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
Tcl_UpdateStringProc *\fIupdateStringProc\fR;
Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
} Tcl_ObjType;
.CE
.PP
The \fIname\fR member describes the name of the type, e.g. \fBint\fR.
Extension writers can look up an object type using its name
with the \fBTcl_GetObjType\fR procedure.
The remaining four members are pointers to procedures
called by the generic Tcl object code:
.PP
The \fIsetFromAnyProc\fR member contains the address of a function
called to create a valid internal representation
from an object's string representation.
.CS
typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR);
.CE
If an internal representation can't be created from the string,
it returns \fBTCL_ERROR\fR and puts a message
describing the error in the result object for \fIinterp\fR
unless \fIinterp\fR is NULL.
If \fIsetFromAnyProc\fR is successful,
it stores the new internal representation,
sets \fIobjPtr\fR's \fItypePtr\fR member to point to
\fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR.
Before setting the new internal representation,
the \fIsetFromAnyProc\fR must free any internal representation
of \fIobjPtr\fR's old type;
it does this by calling the old type's \fIfreeIntRepProc\fR
if it is not NULL.
As an example, the \fIsetFromAnyProc\fR for the builtin Tcl integer type
gets an up-to-date string representation for \fIobjPtr\fR
by calling \fBTcl_GetStringFromObj\fR.
It parses the string to obtain an integer and,
if this succeeds,
stores the integer in \fIobjPtr\fR's internal representation
and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's
Tcl_ObjType structure.
.PP
The \fIupdateStringProc\fR member contains the address of a function
called to create a valid string representation
from an object's internal representation.
.CS
typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR);
.CE
\fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
It must always set \fIbytes\fR non-NULL before returning.
We require the string representation's byte array
to have a null after the last byte, at offset \fIlength\fR;
this allows string representations that do not contain null bytes
to be treated as conventional null character-terminated C strings.
Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR.
Note that \fIupdateStringProc\fRs must allocate
enough storage for the string's bytes and the terminating null byte.
The \fIupdateStringProc\fR for Tcl's builtin list type, for example,
builds an array of strings for each element object
and then calls \fBTcl_Merge\fR
to construct a string with proper Tcl list structure.
It stores this string as the list object's string representation.
.PP
The \fIdupIntRepProc\fR member contains the address of a function
called to copy an internal representation from one object to another.
.CS
typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR);
.CE
\fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
internal representation.
Before the call,
\fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
\fIsrcPtr\fR's object type determines what
copying its internal representation means.
For example, the \fIdupIntRepProc\fR for the Tcl integer type
simply copies an integer.
The builtin list type's \fIdupIntRepProc\fR
allocates a new array that points at the original element objects;
the elements are shared between the two lists
(and their reference counts are incremented to reflect the new references).
.PP
The \fIfreeIntRepProc\fR member contains the address of a function
that is called when an object is freed.
.CS
typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
.CE
The \fIfreeIntRepProc\fR function can deallocate the storage
for the object's internal representation
and do other type-specific processing necessary when an object is freed.
For example, Tcl list objects have an \fIinternalRep.otherValuePtr\fR
that points to an array of pointers to each element in the list.
The list type's \fIfreeIntRepProc\fR decrements
the reference count for each element object
(since the list will no longer refer to those objects),
then deallocates the storage for the array of pointers.
The \fIfreeIntRepProc\fR member can be set to NULL
to indicate that the internal representation does not require freeing.
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
.SH KEYWORDS
internal representation, object, object type, string representation, type conversion

499
contrib/tcl/doc/OpenFileChnl.3
View file

@ -1,499 +0,0 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) OpenFileChnl.3 1.40 97/09/29 11:22:49
.so man.macros
.TH Tcl_OpenFileChannel 3 8.0 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, 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)
.VS
.sp
Tcl_Channel
\fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR)
.VE
.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_GetsObj\fR(\fIchannel, lineObjPtr\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(\fIinterp, channel, 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.
.VS
.AP ClientData handle in
Operating system specific handle for I/O to a file. For Unix this is a
file descriptor, for Windows it is a HANDLE.
.AP int readOrWrite in
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
what operations are valid on \fIhandle\fR.
.VE
.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 len in
The length of the input or output.
.AP int atEnd in
If nonzero, store the input at the end of the input queue, otherwise store
it at the head of the input queue.
.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. The line read
will be appended to any data already in the dynamic string.
.AP Tcl_Obj *linePtrObj in
A pointer to a Tcl object in which to store the line read from the
channel. The line read will be appended to the current value of the
object.
.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.
.PP
The newly created channel is not registered in the supplied interpreter; to
register it, use \fBTcl_RegisterChannel\fR, described below.
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it as a
replacement for the standard channel.
.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.
.PP
The newly created channel is not registered in the supplied interpreter; to
register it, use \fBTcl_RegisterChannel\fR, described below.
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it as a
replacement for the standard channel.
.SH TCL_MAKEFILECHANNEL
.PP
\fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
platform-specific, file handle.
The newly created channel is not registered in the supplied interpreter; to
register it, use \fBTcl_RegisterChannel\fR, described below.
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it as a
replacement for the standard channel.
.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, and the caller should
not call \fBTcl_Close\fR for the channel; the channel will be closed
automatically when it is unregistered from the interpreter.
.PP
Code executing outside of any Tcl interpreter can call
\fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it
wishes to hold a reference to this channel. Subsequently, the channel can
be registered in a Tcl interpreter and it will only be closed when the
matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
This allows code executing outside of any interpreter to safely hold a
reference to a channel that is also registered in a Tcl 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.
.PP
Code not associated with a Tcl interpreter can call
\fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
that it no longer holds a reference to that channel. If this is the last
reference to the channel, it will now be closed.
.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. 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 using \fBTcl_RegisterChannel\fR; see the documentation for
\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been
given as the \fBchan\fR argument in a call to \fBTcl_RegisterChannel\fR,
you should instead use \fBTcl_UnregisterChannel\fR, which will internally
call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been
matched by corresponding calls to \fBTcl_UnregisterChannel\fR.
.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 AND TCL_GETSOBJ
.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.
.PP
\fBTcl_GetsObj\fR is the same as \fBTcl_Gets\fR except the resulting
characters are appended to a Tcl object \fBlineObjPtr\fR rather than a
dynamic string.
.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.
.VS
.SH "PLATFORM ISSUES"
.PP
The handles returned from \fBTcl_GetChannelHandle\fR depend on the
platform and the channel type. On Unix platforms, the handle is
always a Unix file descriptor as returned from the \fBopen\fR system
call. On Windows platforms, the handle is a file \fBHANDLE\fR when
the channel was created with \fBTcl_OpenFileChannel\fR,
\fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other
channel types may return a different type of handle on Windows
platforms. On the Macintosh platform, the handle is a file reference
number as returned from \fBHOpenDF\fR.
.VE
.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

179
contrib/tcl/doc/OpenTcp.3
View file

@ -1,179 +0,0 @@
'\"
'\" Copyright (c) 1996-7 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.19 97/06/25 14:44:00
.so man.macros
.TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, 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.
.PP
The newly created channel is not registered in the supplied interpreter; to
register it, use \fBTcl_RegisterChannel\fR.
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it as a
replacement for the standard channel.
.SH TCL_MAKETCPCLIENTCHANNEL
.PP
\fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an
existing, platform specific, handle for a client TCP socket.
.PP
The newly created channel is not registered in the supplied interpreter; to
register it, use \fBTcl_RegisterChannel\fR.
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it as a
replacement for the standard channel.
.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.
.PP
The newly created channel is not registered in the supplied interpreter; to
register it, use \fBTcl_RegisterChannel\fR.
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it as a
replacement for the standard channel.
.VS
.SH "PLATFORM ISSUES"
.PP
On Unix platforms, the socket handle is a Unix file descriptor as
returned by the \fBsocket\fR system call. On the Windows platform, the
socket handle is a \fBSOCKET\fR as defined in the WinSock API. On the
Macintosh platform, the socket handle is a \fBStreamPtr\fR.
.VE
.SH "SEE ALSO"
Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)
.SH KEYWORDS
client, server, TCP

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

@ -1,59 +0,0 @@
'\"
'\" 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

103
contrib/tcl/doc/Preserve.3
View file

@ -1,103 +0,0 @@
'\"
'\" 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.13 96/05/28 09:26:12
'\"
.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(char *\fIblockPtr\fR);
.CE
The \fIblockPtr\fR argument to \fIfreeProc\fR will be the
same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR.
The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the
\fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical
reasons, but the value is the same.
.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

47
contrib/tcl/doc/PrintDbl.3
View file

@ -1,47 +0,0 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) PrintDbl.3 1.9 97/08/22 13:30:22
'\"
.so man.macros
.TH Tcl_PrintDouble 3 8.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
.VS
Before Tcl 8.0, the \fBtcl_precision\fR variable in this interpreter
controlled the conversion. As of Tcl 8.0, this argument is ignored and
the conversion is controlled by the \fBtcl_precision\fR variable
that is now shared by all interpreters.
.VE
.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 \fB%g\fR format to generate the string, with one
special twist: the string is guaranteed to contain either
a ``.'' or an ``e'' so that it doesn't look like an integer. Where
\fB%g\fR would generate an integer with no decimal point, \fBTcl_PrintDouble\fR
adds ``.0''.
.SH KEYWORDS
conversion, double-precision, floating-point, string

55
contrib/tcl/doc/RecEvalObj.3
View file

@ -1,55 +0,0 @@
'\"
'\" Copyright (c) 1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: SCCS: @(#) RecEvalObj.3 1.1 97/07/29 18:31:21
'\"
.so man.macros
.TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_RecordAndEvalObj \- save command on history list before evaluating
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_RecordAndEvalObj\fR(\fIinterp, cmdPtr, flags\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp;
.AP Tcl_Interp *interp in
Tcl interpreter in which to evaluate command.
.AP Tcl_Obj *cmdPtr in
Points to a Tcl object containing a command (or sequence of commands)
to execute.
.AP int flags in
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.
.BE
.SH DESCRIPTION
.PP
\fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
on the history list and then execute it using \fBTcl_EvalObj\fR
(or \fBTcl_GlobalEvalObj\fR if the TCL_EVAL_GLOBAL bit is set
in \fIflags\fR).
It returns a completion code such as TCL_OK just like \fBTcl_EvalObj\fR,
as well as a result object containing additional information
(a result value or error message)
that can be retrieved using \fBTcl_GetObjResult\fR.
If you don't want the command recorded on the history list then
you should invoke \fBTcl_EvalObj\fR instead of \fBTcl_RecordAndEvalObj\fR.
Normally \fBTcl_RecordAndEvalObj\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 "SEE ALSO"
Tcl_EvalObj, Tcl_GetObjResult
.SH KEYWORDS
command, event, execute, history, interpreter, object, record

57
contrib/tcl/doc/RecordEval.3
View file

@ -1,57 +0,0 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) RecordEval.3 1.18 97/07/29 18:25:13
'\"
.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, flags\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
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.
.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
(or \fBTcl_GlobalEval\fR if the TCL_EVAL_GLOBAL bit is set in \fIflags\fR).
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.
.PP
Note that \fBTcl_RecordAndEval\fR has been largely replaced by the
object-based procedure \fBTcl_RecordAndEvalObj\fR.
That object-based procedure records and optionally executes
a command held in a Tcl object instead of a string.
.SH "SEE ALSO"
Tcl_RecordAndEvalObj
.SH KEYWORDS
command, event, execute, history, interpreter, record

116
contrib/tcl/doc/RegExp.3
View file

@ -1,116 +0,0 @@
'\"
'\" 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.9 96/08/26 12:59:48
'\"
.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
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)
.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
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.
.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
\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.
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.
.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.
.SH KEYWORDS
match, pattern, regular expression, string, subexpression

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

@ -1,48 +0,0 @@
'\"
'\" 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
View file

@ -1,55 +0,0 @@
'\"
'\" 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

217
contrib/tcl/doc/SetResult.3
View file

@ -1,217 +0,0 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) SetResult.3 1.23 97/06/26 14:05:57
'\"
.so man.macros
.TH Tcl_SetResult 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_SetObjResult\fR(\fIinterp, objPtr\fR)
.sp
Tcl_Obj *
\fBTcl_GetObjResult\fR(\fIinterp\fR)
.sp
\fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
.sp
char *
\fBTcl_GetStringResult\fR(\fIinterp\fR)
.sp
\fBTcl_AppendResult\fR(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
.sp
\fBTcl_AppendElement\fR(\fIinterp, string\fR)
.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 or read.
.AP Tcl_Obj *objPtr in
Object value to become result for \fIinterp\fR.
.AP char *string in
String value to become result for \fIinterp\fR or to be
appended to the 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 manipulating the
result value in a Tcl interpreter.
The interpreter result may be either a Tcl object or a string.
For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR
set the interpreter result to, respectively, an object and a string.
Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR
return the interpreter result as an object and as a string.
The procedures always keep the string and object forms
of the interpreter result consistent.
For example, if \fBTcl_SetObjResult\fR is called to set
the result to an object,
then \fBTcl_GetStringResult\fR is called,
it will return the object's string value.
.PP
\fBTcl_SetObjResult\fR
arranges for \fIobjPtr\fR to be the result for \fIinterp\fR,
replacing any existing result.
The result is left pointing to the object
referenced by \fIobjPtr\fR.
\fIobjPtr\fR's reference count is incremented
since there is now a new reference to it from \fIinterp\fR.
The reference count for any old result object
is decremented and the old result object is freed if no
references to it remain.
.PP
\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as an object.
The object's reference count is not incremented;
if the caller needs to retain a long-term pointer to the object
they should use \fBTcl_IncrRefCount\fR to increment its reference count
in order to keep it from being freed too early or accidently changed.
.PP
\fBTcl_SetResult\fR
arranges for \fIstring\fR to be the result for the current Tcl
command in \fIinterp\fR, replacing any existing result.
The \fIfreeProc\fR argument specifies how to manage the storage
for the \fIstring\fR argument;
it is discussed in the section
\fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below.
If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
and \fBTcl_SetResult\fR
re-initializes \fIinterp\fR's result to point to an empty string.
.PP
\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as an string.
If the result was set to an object by a \fBTcl_SetObjResult\fR call,
the object form will be converted to a string and returned.
If the object's string representation contains null bytes,
this conversion will lose information.
For this reason, programmers are encouraged to
write their code to use the new object API procedures
and to call \fBTcl_GetObjResult\fR instead.
.PP
\fBTcl_ResetResult\fR clears the result for \fIinterp\fR
and leaves the result in its normal empty initialized state.
If the result is an object,
its reference count is decremented and the result is left
pointing to an unshared object representing an empty string.
If the result is a dynamically allocated string, its memory is free*d
and the result is left as a empty string.
\fBTcl_ResetResult\fR also clears the error state managed by
\fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR,
and \fBTcl_SetErrorCode\fR.
.SH OLD STRING PROCEDURES
.PP
Use of the following procedures is deprecated
since they manipulate the Tcl result as a string.
Procedures such as \fBTcl_SetObjResult\fR
that manipulate the result as an object
can be significantly more efficient.
.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.
It also converts the current interpreter result from an object
to a string, if necessary, before appending the argument strings.
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.
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.
.PP
\fBTcl_FreeResult\fR performs part of the work
of \fBTcl_ResetResult\fR.
It frees up the memory associated with \fIinterp\fR's result.
It also sets \fIinterp->freeProc\fR to zero, but 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 DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED
.PP
It used to be legal for programs to
directly read and write \fIinterp->result\fR
to manipulate the interpreter result.
Direct access to \fIinterp->result\fR is now strongly deprecated
because it can make the result's string and object forms inconsistent.
Programs should always read the result
using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR,
and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR.
.SH THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT
.PP
\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
the Tcl system is to manage the storage for the \fIstring\fR argument.
If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called
at a time when \fIinterp\fR holds a string result,
they do whatever is necessary to dispose of the old string result
(see the \fBTcl_Interp\fR manual entry for details on this).
.PP
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 \fBTcl_Alloc\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 \fBTcl_Free\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
result 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.
.SH "SEE ALSO"
Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp
.SH KEYWORDS
append, command, element, list, object, result, return value, interpreter

204
contrib/tcl/doc/SetVar.3
View file

@ -1,204 +0,0 @@
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) SetVar.3 1.30 97/10/10 16:10:36
'\"
.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 include a series of \fB::\fR namespace qualifiers
to specify a variable in a particular namespace.
May refer to a scalar variable or an element of
an array variable.
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.
.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.
May include a series of \fB::\fR namespace qualifiers
to specify a variable in a particular namespace.
.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.
.PP
Note that \fBTcl_GetVar\fR and \fBTcl_SetVar\fR
have been largely replaced by the
object-based procedures \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR.
Those object-based procedures read, modify, and create
a variable whose name is held in a Tcl object instead of a string.
They also return a pointer to the object
which is the variable's value instead of returning a string.
Operations on objects can be faster since objects
hold an internal representation that can be manipulated more efficiently.
.PP
\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),
they return NULL.
.PP
The name of the variable may be specified to
\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR 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 the following bits.
Note that the flag bit TCL_PARSE_PART1 is only meaningful
for the procedures Tcl_SetVar2 and Tcl_GetVar2.
.TP
\fBTCL_GLOBAL_ONLY\fR
Under normal circumstances the procedures look up variables as follows:
If a procedure call is active in \fIinterp\fR,
a variable is looked up at the current level of procedure call.
Otherwise, a variable is looked up first in the current namespace,
then in the global namespace.
However, if this bit is set in \fIflags\fR then the variable
is looked up only in the global namespace
even if there is a procedure call active.
If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
\fBTCL_GLOBAL_ONLY\fR is ignored.
.TP
\fBTCL_NAMESPACE_ONLY\fR
Under normal circumstances the procedures look up variables as follows:
If a procedure call is active in \fIinterp\fR,
a variable is looked up at the current level of procedure call.
Otherwise, a variable is looked up first in the current namespace,
then in the global namespace.
However, if this bit is set in \fIflags\fR then the variable
is looked up only in the current namespace
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 the interpreter's result,
where it can be retrieved with \fBTcl_GetObjResult\fR
or \fBTcl_GetStringResult\fR.
If this flag bit isn't set then no error message is left
and the interpreter's result 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
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 `` }'').
.TP
\fBTCL_PARSE_PART1\fR
If this bit is set when calling \fITcl_SetVar2\fR and \fITcl_GetVar2\fR,
\fIname1\fR may contain both an array and an element name:
if the name contains an open parenthesis and ends with a
close parenthesis, then the value between the parentheses is
treated as an element name (which can have any string value) and
the characters before the first open
parenthesis are treated as the name of an array variable.
If the flag TCL_PARSE_PART1 is given,
\fIname2\fR should be NULL since the array and element names
are taken from \fIname1\fR.
.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).
\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR use the flag bits TCL_GLOBAL_ONLY
and TCL_LEAVE_ERR_MSG, both of
which have
the same meaning as for \fBTcl_SetVar\fR.
In addition, \fBTcl_GetVar2\fR uses the bit TCL_PARSE_PART1,
which has the same meaning as for \fBTcl_SetVar2\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.
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.
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_GetObjResult, Tcl_GetStringResult, Tcl_ObjGetVar2, Tcl_ObjSetVar2, Tcl_TraceVar
.SH KEYWORDS
array, interpreter, object, scalar, set, unset, variable

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

@ -1,37 +0,0 @@
'\"
'\" 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

191
contrib/tcl/doc/SplitList.3
View file

@ -1,191 +0,0 @@
'\"
'\" 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.21 97/04/29 14:07:10
'\"
.so man.macros
.TH Tcl_SplitList 3 7.5 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)
.VS
.sp
int
\fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR)
.VE
.sp
int
\fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
.VS
.sp
int
\fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR)
.VE
.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.
.VS
.AP int length in
Number of bytes in string \fIsrc\fR.
.VE
.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:
.VS
.CS
Tcl_Free((char *) argv);
.CE
.VE
.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.
.VS
The result string is dynamically allocated
using \fBTcl_Alloc\fR; the caller must eventually release the space
using \fBTcl_Free\fR.
.VE
.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.
.PP
.VS
\fBTcl_ScanCountedElement\fR and \fBTcl_ConvertCountedElement\fR are
the same as \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR, except
the length of string \fIsrc\fR is specified by the \fIlength\fR
argument, and the string may contain embedded nulls.
.VE
.SH KEYWORDS
backslash, convert, element, list, merge, split, strings

93
contrib/tcl/doc/SplitPath.3
View file

@ -1,93 +0,0 @@
'\"
'\" 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: @(#) SplitPath.3 1.4 96/08/19 14:59:35
'\"
.so man.macros
.TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType \- manipulate platform-dependent file paths
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_SplitPath\fR(\fIpath, argcPtr, argvPtr\fR)
.sp
char *
\fBTcl_JoinPath\fR(\fIargc, argv, resultPtr\fR)
.sp
Tcl_PathType
\fBTcl_GetPathType\fR(\fIpath\fR)
.SH ARGUMENTS
.AS Tcl_DString ***argvPtr
.AP char *path in
File path in a form appropriate for the current platform (see the
\fBfilename\fR manual entry for acceptable forms for path names).
.AP int *argcPtr out
Filled in with number of path elements in \fIpath\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 \fIpath\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 path elements to merge together into a single path.
.AP Tcl_DString *resultPtr in/out
A pointer to an initialized \fBTcl_DString\fR to which the result of
\fBTcl_JoinPath\fR will be appended.
.BE
.SH DESCRIPTION
.PP
These procedures may be used to disassemble and reassemble file
paths in a platform independent manner: they provide C-level access to
the same functionality as the \fBfile split\fR, \fBfile join\fR, and
\fBfile pathtype\fR commands.
.PP
\fBTcl_SplitPath\fR breaks a path into its constituent elements,
returning an array of pointers to the elements using \fIargcPtr\fR and
\fIargvPtr\fR. 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 path elements. It is the caller's
responsibility to free all of this storage.
For example, suppose that you have called \fBTcl_SplitPath\fR with the
following code:
.CS
int argc;
char *path;
char **argv;
\&...
Tcl_SplitPath(string, &argc, &argv);
.CE
Then you should eventually free the storage with a call like the
following:
.CS
Tcl_Free((char *) argv);
.CE
.PP
\fBTcl_JoinPath\fR is the inverse of \fBTcl_SplitPath\fR: it takes a
collection of path elements given by \fIargc\fR and \fIargv\fR and
generates a result string that is a properly constructed path. The
result string is appended to \fIresultPtr\fR. \fIResultPtr\fR must
refer to an initialized \fBTcl_DString\fR.
.PP
If the result of \fBTcl_SplitPath\fR is passed to \fBTcl_JoinPath\fR,
the result will refer to the same location, but may not be in the same
form. This is because \fBTcl_SplitPath\fR and \fBTcl_JoinPath\fR
eliminate duplicate path separators and return a normalized form for
each platform.
.PP
\fBTcl_GetPathType\fR returns the type of the specified \fIpath\fR,
where \fBTcl_PathType\fR is one of \fBTCL_PATH_ABSOLUTE\fR,
\fBTCL_PATH_RELATIVE\fR, or \fBTCL_PATH_VOLUME_RELATIVE\fR. See the
\fBfilename\fR manual entry for a description of the path types for
each platform.
.SH KEYWORDS
file, filename, join, path, split, type

70
contrib/tcl/doc/StaticPkg.3
View file

@ -1,70 +0,0 @@
'\"
'\" 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.4 96/09/04 11:21:26
'\"
.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.
Once \fBTcl_StaticPackage\fR has been invoked for a package, it
may be loaded into interpreters using the \fBload\fR command.
\fBTcl_StaticPackage\fR is normally invoked only by the \fBTcl_AppInit\fR
procedure for the application, not by packages for themselves
(\fBTcl_StaticPackage\fR should only be invoked for statically
loaded packages, and code in the package itself should not need
to know whether the package is dynamically or statically loaded).
.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
View file

@ -1,39 +0,0 @@
'\"
'\" 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

132
contrib/tcl/doc/StringObj.3
View file

@ -1,132 +0,0 @@
'\"
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) @(#) StringObj.3 1.13 97/06/25 13:40:25
'\"
.so man.macros
.TH Tcl_StringObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_AppendToObj, Tcl_AppendStringsToObj, Tcl_SetObjLength, TclConcatObj \- manipulate Tcl objects as strings
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewStringObj\fR(\fIbytes, length\fR)
.sp
\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
.sp
char *
\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
.sp
\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
.sp
\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
.sp
\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
.sp
Tcl_Obj *
\fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
.SH ARGUMENTS
.AS Tcl_Interp *lengthPtr out
.AP char *bytes in
Points to the first byte of an array of bytes
used to set or append to a string object.
This byte array may contain embedded null bytes
unless \fIlength\fR is negative.
.AP int length in
The number of bytes to copy from \fIbytes\fR when
initializing, setting, or appending to a string object.
If negative, all bytes up to the first null are used.
.AP Tcl_Obj *objPtr in/out
Points to an object to manipulate.
.AP int *lengthPtr out
If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
the the length of an object's string representation.
.AP char *string in
Null-terminated string value to append to \fIobjPtr\fR.
.AP int newLength in
New length for the string value of \fIobjPtr\fR, not including the
final NULL character.
.AP int objc in
The number of elements to concatenate.
.AP Tcl_Obj *objv[] in
The array of objects to concatenate.
.BE
.SH DESCRIPTION
.PP
The procedures described in this manual entry allow Tcl objects to
be manipulated as string values. They use the internal representation
of the object to store additional information to make the string
manipulations more efficient. In particular, they make a series of
append operations efficient by allocating extra storage space for the
string so that it doesn't have to be copied for each append.
.PP
\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object
or modify an existing object to hold a copy of
the string given by \fIbytes\fR and \fIlength\fR.
\fBTcl_NewStringObj\fR returns a pointer to a newly created object
with reference count zero.
Both procedures set the object to hold a copy of the specified string.
\fBTcl_SetStringObj\fR frees any old string representation
as well as any old internal representation of the object.
.PP
\fBTcl_GetStringFromObj\fR returns an object's string representation.
This is given by the returned byte pointer
and length, which is stored in \fIlengthPtr\fR if it is non-NULL.
If the object's string representation is invalid
(its byte pointer is NULL),
the string representation is regenerated from the
object's internal representation.
The storage referenced by the returned byte pointer
is owned by the object manager and should not be modified by the caller.
.PP
\fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
\fIlength\fR to the object specified by \fIobjPtr\fR. It does this
in a way that handles repeated calls relatively efficiently (it
overallocates the string space to avoid repeated reallocations
and copies of object's string value).
.PP
\fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR
except that it can be passed more than one value to append and
each value must be a null-terminated string (i.e. none of the
values may contain internal null characters). Any number of
\fIstring\fR arguments may be provided, but the last argument
must be a NULL pointer to indicate the end of the list.
.PP
The \fBTcl_SetObjLength\fR procedure changes the length of the
string value of its \fIobjPtr\fR argument. If the \fInewLength\fR
argument is greater than the space allocated for the object's
string, then the string space is reallocated and the old value
is copied to the new space; the bytes between the old length of
the string and the new length may have arbitrary values.
If the \fInewLength\fR argument is less than the current length
of the object's string, with \fIobjPtr->length\fR is reduced without
reallocating the string space; the original allocated size for the
string is recorded in the object, so that the string length can be
enlarged in a subsequent call to \fBTcl_SetObjLength\fR without
reallocating storage. In all cases \fBTcl_SetObjLength\fR leaves
a null character at \fIobjPtr->bytes[newLength]\fR.
.PP
The \fBTcl_ConcatObj\fR function returns a new string object whose
value is the space-separated concatenation of the string
representations of all of the objects in the \fIobjv\fR
array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
as it copies the string representations of the \fIobjv\fR array to the
result. If an element of the \fIobjv\fR array consists of nothing but
white space, then that object is ignored entirely. This white-space
removal was added to make the output of the \fBconcat\fR command
cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
newly-created object whose ref count is zero.
.SH "SEE ALSO"
Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
.SH KEYWORDS
append, internal representation, object, object type, string object,
string type, string representation, concat, concatenate

181
contrib/tcl/doc/Tcl.n
View file

@ -1,181 +0,0 @@
'\"
'\" 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.128 96/08/26 12:59:50
'
.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.
In all cases but those described below the backslash is dropped and
the following character is treated as an ordinary
character and included in the word.
This allows characters such as double quotes, close brackets,
and dollar signs to be included in words without triggering
special processing.
The following table lists the backslash sequences that are
handled specially, along with the value that replaces each sequence.
.RS
.TP 6
\e\fBa\fR
Audible alert (bell) (0x7).
.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
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.
.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
The hexadecimal digits \fIhh\fR give the hexadecimal value of
the character. Any number of digits may be present.
.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
View file

@ -1,61 +0,0 @@
'\"
'\" 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

348
contrib/tcl/doc/TraceVar.3
View file

@ -1,348 +0,0 @@
'\"
'\" 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.27 97/10/10 15:05:37
'\"
.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.
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.
.AP int flags in
OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and
TCL_TRACE_UNSETS, TCL_PARSE_PART1, 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 consists of 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).
As a special case, if the flag TCL_PARSE_PART1 is specified,
\fIname1\fR may contain both an array and an element name:
if the name contains an open parenthesis and ends with a
close parenthesis, then the value between the parentheses is
treated as an element name (which can have any string value) and
the characters before the first open
parenthesis are treated as the name of an array variable.
If the flag TCL_PARSE_PART1 is given,
\fIname2\fR should be NULL since the array and element names
are taken from \fIname1\fR.
.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.
However, if a variable is unset during a read or write trace then unset
traces will be invoked.
.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.
If it unsets the variable then the access will return an error
just as if the variable never existed.
.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.
If it deletes the variable then the traced access will return
an empty string.
.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.
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.
.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

66
contrib/tcl/doc/Translate.3
View file

@ -1,66 +0,0 @@
'\"
'\" 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.22 96/08/26 12:59:51
'\"
.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 *
\fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR)
.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
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.
.BE
.SH DESCRIPTION
.PP
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.
.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.
When an error occurs, \fBTcl_TranslateFileName\fR
frees the dynamic string itself so that the caller need not call
\fBTcl_DStringFree\fR.
.PP
The caller is responsible for making sure that \fIinterp->result\fR
has its default empty value when \fBTcl_TranslateFileName\fR is invoked.
.SH "SEE ALSO"
filename
.SH KEYWORDS
file name, home directory, tilde, translate, user

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

@ -1,76 +0,0 @@
'\"
'\" 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

79
contrib/tcl/doc/WrongNumArgs.3
View file

@ -1,79 +0,0 @@
'\"
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) @(#) WrongNumArgs.3 1.5 97/07/30 16:20:07
'\"
.so man.macros
.TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_WrongNumArgs \- generate standard error message for wrong number of arguments
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_WrongNumArgs\fR(\fIinterp, objc, objv, message\fR)
.SH ARGUMENTS
.AS Tcl_Interp "*CONST objv[]"
.AP Tcl_Interp interp in
Interpreter in which error will be reported: error message gets stored
in its result object.
.AP int objc in
Number of leading arguments from \fIobjv\fR to include in error
message.
.TP
Tcl_Obj *CONST \fIobjv\fR[] (in)
Arguments to command that had the wrong number of arguments.
.AP char *message in
Additional error information to print after leading arguments
from \fIobjv\fR. This typically gives the acceptable syntax
of the command. This argument may be NULL.
.BE
.SH DESCRIPTION
.PP
\fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by
command procedures when they discover that they have received the
wrong number of arguments. \fBTcl_WrongNumArgs\fR generates a
standard error message and stores it in the result object of
\fIinterp\fR. The message includes the \fIobjc\fR initial
elements of \fIobjv\fR plus \fImessage\fR. For example, if
\fIobjv\fR consists of the values \fBfoo\fR and \fBbar\fR,
\fIobjc\fR is 1, and \fImessage\fR is ``\fBfileName count\fR''
then \fIinterp\fR's result object will be set to the following
string:
.CS
wrong # args: should be "foo fileName count"
.CE
If \fIobjc\fR is 2, the result will be set to the following string:
.CS
wrong # args: should be "foo bar fileName count"
.CE
\fIObjc\fR is usually 1, but may be 2 or more for commands like
\fBstring\fR and the Tk widget commands, which use the first argument
as a subcommand.
.PP
Some of the objects in the \fIobjv\fR array may be abbreviations for
a subcommand. The command
\fBTcl_GetIndexFromObj\fR will convert the abbreviated string object
into an \fIindexObject\fR. If an error occurs in the parsing of the
subcommand we would like to use the full subcommand name rather than
the abbreviation. If the \fBTcl_WrongNumArgs\fR command finds any
\fIindexObjects\fR in the \fIobjv\fR array it will use the full subcommand
name in the error message instead of the abbreviated name that was
originally passed in. Using the above example, let us assume that
\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object
is now an indexObject becasue it was passed to
\fBTcl_GetIndexFromObj\fR. In this case the error message would be:
.CS
wrong # args: should be "foo barfly fileName count"
.CE
.SH "SEE ALSO"
Tcl_GetIndexFromObj
.SH KEYWORDS
command, error message, wrong number of arguments

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

@ -1,109 +0,0 @@
'\"
'\" 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
View file

@ -1,32 +0,0 @@
'\"
'\" 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

116
contrib/tcl/doc/array.n
View file

@ -1,116 +0,0 @@
'\"
'\" 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.9 97/10/29 14:10:13
'\"
.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
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.
.TP
\fBarray get \fIarrayName\fR ?\fIpattern\fR?
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.
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.
If \fIarrayName\fR isn't the name of an array variable, or if
the array contains no elements, then an empty list is returned.
.TP
\fBarray names \fIarrayName\fR ?\fIpattern\fR?
Returns a list containing the names of all of the elements in
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.
.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
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.
If the variable \fIarrayName\fR does not already exist
and \fIlist\fR is empty,
\fIarrayName\fR is created with an empty array value.
.TP
\fBarray size \fIarrayName\fR
Returns a decimal string giving the number of elements in the
array.
If \fIarrayName\fR isn't the name of an array then 0 is returned.
.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

68
contrib/tcl/doc/bgerror.n
View file

@ -1,68 +0,0 @@
'\"
'\" 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.5 97/08/04 17:49:35
'\"
.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 is a default
\fBbgerror\fR procedure
which posts a dialog box containing
the error message and offers the user a chance to see a stack
trace showing where the error occurred.
.SH KEYWORDS
background error, reporting

532
contrib/tcl/doc/binary.n
View file

@ -1,532 +0,0 @@
'\"
'\" Copyright (c) 1997 by Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) binary.n 1.7 97/11/11 19:08:47
'\"
.so man.macros
.TH binary n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
binary \- Insert and extract fields from binary strings
.SH SYNOPSIS
\fBbinary format \fIformatString \fR?\fIarg arg ...\fR?
.br
\fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR?
.BE
.SH DESCRIPTION
.PP
This command provides facilities for manipulating binary data. The
first form, \fBbinary format\fR, creates a binary string from normal
Tcl values. For example, given the values 16 and 22, it might produce
an 8-byte binary string consisting of two 4-byte integers, one for
each of the numbers. The second form of the command,
\fBbinary scan\fR, does the opposite: it extracts data from a binary
string and returns it as ordinary Tcl string values.
.SH "BINARY FORMAT"
.PP
The \fBbinary format\fR command generates a binary string whose layout
is specified by the \fIformatString\fR and whose contents come from
the additional arguments. The resulting binary value is returned.
.PP
The \fIformatString\fR consists of a sequence of zero or more field
specifiers separated by zero or more spaces. Each field specifier is
a single type character followed by an optional numeric \fIcount\fR.
Most field specifiers consume one argument to obtain the value to be
formatted. The type character specifies how the value is to be
formatted. The \fIcount\fR typically indicates how many items of the
specified type are taken from the value. If present, the \fIcount\fR
is a non-negative decimal integer or \fB*\fR, which normally indicates
that all of the items in the value are to be used. If the number of
arguments does not match the number of fields in the format string
that consume arguments, then an error is generated.
.PP
Each type-count pair moves an imaginary cursor through the binary
data, storing bytes at the current position and advancing the cursor
to just after the last byte stored. The cursor is initially at
position 0 at the beginning of the data. The type may be any one of
the following characters:
.IP \fBa\fR 5
Stores a character string of length \fIcount\fR in the output string.
If \fIarg\fR has fewer than \fIcount\fR bytes, then additional zero
bytes are used to pad out the field. If \fIarg\fR is longer than the
specified length, the extra characters will be ignored. If
\fIcount\fR is \fB*\fR, then all of the bytes in \fIarg\fR will be
formatted. If \fIcount\fR is omitted, then one character will be
formatted. For example,
.RS
.CS
\fBbinary format a7a*a alpha bravo charlie\fR
.CE
will return a string equivalent to \fBalpha\\000\\000bravoc\fR.
.RE
.IP \fBA\fR 5
This form is the same as \fBa\fR except that spaces are used for
padding instead of nulls. For example,
.RS
.CS
\fBbinary format A6A*A alpha bravo charlie\fR
.CE
will return \fBalpha bravoc\fR.
.RE
.IP \fBb\fR 5
Stores a string of \fIcount\fR binary digits in low-to-high order
within each byte in the output string. \fIArg\fR must contain a
sequence of \fB1\fR and \fB0\fR characters. The resulting bytes are
emitted in first to last order with the bits being formatted in
low-to-high order within each byte. If \fIarg\fR has fewer than
\fIcount\fR digits, then zeros will be used for the remaining bits.
If \fIarg\fR has more than the specified number of digits, the extra
digits will be ignored. If \fIcount\fR is \fB*\fR, then all of the
digits in \fIarg\fR will be formatted. If \fIcount\fR is omitted,
then one digit will be formatted. If the number of bits formatted
does not end at a byte boundary, the remaining bits of the last byte
will be zeros. For example,
.RS
.CS
\fBbinary format b5b* 11100 111000011010\fR
.CE
will return a string equivalent to \fB\\x07\\x87\\x05\fR.
.RE
.IP \fBB\fR 5
This form is the same as \fBb\fR except that the bits are stored in
high-to-low order within each byte. For example,
.RS
.CS
\fBbinary format B5B* 11100 111000011010\fR
.CE
will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR.
.RE
.IP \fBh\fR 5
Stores a string of \fIcount\fR hexadecimal digits in low-to-high
within each byte in the output string. \fIArg\fR must contain a
sequence of characters in the set ``0123456789abcdefABCDEF''. The
resulting bytes are emitted in first to last order with the hex digits
being formatted in low-to-high order within each byte. If \fIarg\fR
has fewer than \fIcount\fR digits, then zeros will be used for the
remaining digits. If \fIarg\fR has more than the specified number of
digits, the extra digits will be ignored. If \fIcount\fR is
\fB*\fR, then all of the digits in \fIarg\fR will be formatted. If
\fIcount\fR is omitted, then one digit will be formatted. If the
number of digits formatted does not end at a byte boundary, the
remaining bits of the last byte will be zeros. For example,
.RS
.CS
\fBbinary format h3h* AB def\fR
.CE
will return a string equivalent to \fB\\xba\\xed\\x0f\fR.
.RE
.IP \fBH\fR 5
This form is the same as \fBh\fR except that the digits are stored in
high-to-low order within each byte. For example,
.RS
.CS
\fBbinary format H3H* ab DEF\fR
.CE
will return a string equivalent to \fB\\xab\\xde\\xf0\fR.
.RE
.IP \fBc\fR 5
Stores one or more 8-bit integer values in the output string. If no
\fIcount\fR is specified, then \fIarg\fR must consist of an integer
value; otherwise \fIarg\fR must consist of a list containing at least
\fIcount\fR integer elements. The low-order 8 bits of each integer
are stored as a one-byte value at the cursor position. If \fIcount\fR
is \fB*\fR, then all of the integers in the list are formatted. If
the number of elements in the list is fewer than \fIcount\fR, then an
error is generated. If the number of elements in the list is greater
than \fIcount\fR, then the extra elements are ignored. For example,
.RS
.CS
\fBbinary format c3cc* {3 -3 128 1} 257 {2 5}\fR
.CE
will return a string equivalent to
\fB\\x03\\xfd\\x80\\x01\\x02\\x05\fR, whereas
.CS
\fBbinary format c {2 5}\fR
.CE
will generate an error.
.RE
.IP \fBs\fR 5
This form is the same as \fBc\fR except that it stores one or more
16-bit integers in little-endian byte order in the output string. The
low-order 16-bits of each integer are stored as a two-byte value at
the cursor position with the least significant byte stored first. For
example,
.RS
.CS
\fBbinary format s3 {3 -3 258 1}\fR
.CE
will return a string equivalent to
\fB\\x03\\x00\\xfd\\xff\\x02\\x01\fR.
.RE
.IP \fBS\fR 5
This form is the same as \fBs\fR except that it stores one or more
16-bit integers in big-endian byte order in the output string. For
example,
.RS
.CS
\fBbinary format S3 {3 -3 258 1}\fR
.CE
will return a string equivalent to
\fB\\x00\\x03\\xff\\xfd\\x01\\x02\fR.
.RE
.IP \fBi\fR 5
This form is the same as \fBc\fR except that it stores one or more
32-bit integers in little-endian byte order in the output string. The
low-order 32-bits of each integer are stored as a four-byte value at
the cursor position with the least significant byte stored first. For
example,
.RS
.CS
\fBbinary format i3 {3 -3 65536 1}\fR
.CE
will return a string equivalent to
\fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x10\\x00\fR.
.RE
.IP \fBI\fR 5
This form is the same as \fBi\fR except that it stores one or more one
or more 32-bit integers in big-endian byte order in the output string.
For example,
.RS
.CS
\fBbinary format I3 {3 -3 65536 1}\fR
.CE
will return a string equivalent to
\fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x10\\x00\\x00\fR.
.RE
.IP \fBf\fR 5
This form is the same as \fBc\fR except that it stores one or more one
or more single-precision floating in the machine's native
representation in the output string. This representation is not
portable across architectures, so it should not be used to communicate
floating point numbers across the network. The size of a floating
point number may vary across architectures, so the number of bytes
that are generated may vary. If the value overflows the
machine's native representation, then the value of FLT_MAX
as defined by the system will be used instead. Because Tcl uses
double-precision floating-point numbers internally, there may be some
loss of precision in the conversion to single-precision. For example,
on a Windows system running on an Intel Pentium processor,
.RS
.CS
\fBbinary format f2 {1.6 3.4}\fR
.CE
will return a string equivalent to
\fB\\xcd\\xcc\\xcc\\x3f\\x9a\\x99\\x59\\x40\fR.
.RE
.IP \fBd\fR 5
This form is the same as \fBf\fR except that it stores one or more one
or more double-precision floating in the machine's native
representation in the output string. For example, on a
Windows system running on an Intel Pentium processor,
.RS
.CS
\fBbinary format d1 {1.6}\fR
.CE
will return a string equivalent to
\fB\\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f\fR.
.RE
.IP \fBx\fR 5
Stores \fIcount\fR null bytes in the output string. If \fIcount\fR is
not specified, stores one null byte. If \fIcount\fR is \fB*\fR,
generates an error. This type does not consume an argument. For
example,
.RS
.CS
\fBbinary format a3xa3x2a3 abc def ghi\fR
.CE
will return a string equivalent to \fBabc\\000def\\000\\000ghi\fR.
.RE
.IP \fBX\fR 5
Moves the cursor back \fIcount\fR bytes in the output string. If
\fIcount\fR is \fB*\fR or is larger than the current cursor position,
then the cursor is positioned at location 0 so that the next byte
stored will be the first byte in the result string. If \fIcount\fR is
omitted then the cursor is moved back one byte. This type does not
consume an argument. For example,
.RS
.CS
\fBbinary format a3X*a3X2a3 abc def ghi\fR
.CE
will return \fBdghi\fR.
.RE
.IP \fB@\fR 5
Moves the cursor to the absolute location in the output string
specified by \fIcount\fR. Position 0 refers to the first byte in the
output string. If \fIcount\fR refers to a position beyond the last
byte stored so far, then null bytes will be placed in the unitialized
locations and the cursor will be placed at the specified location. If
\fIcount\fR is \fB*\fR, then the cursor is moved to the current end of
the output string. If \fIcount\fR is omitted, then an error will be
generated. This type does not consume an argument. For example,
.RS
.CS
\fBbinary format a5@2a1@*a3@10a1 abcde f ghi j\fR
.CE
will return \fBabfdeghi\\000\\000j\fR.
.RE
.SH "BINARY SCAN"
.PP
The \fBbinary scan\fR command parses fields from a binary string,
returning the number of conversions performed. \fIString\fR gives the
input to be parsed and \fIformatString\fR indicates how to parse it.
Each \fIvarName\fR gives the name of a variable; when a field is
scanned from \fIstring\fR the result is assigned to the corresponding
variable.
.PP
As with \fBbinary format\fR, the \fIformatString\fR consists of a
sequence of zero or more field specifiers separated by zero or more
spaces. Each field specifier is a single type character followed by
an optional numeric \fIcount\fR. Most field specifiers consume one
argument to obtain the variable into which the scanned values should
be placed. The type character specifies how the binary data is to be
interpreted. The \fIcount\fR typically indicates how many items of
the specified type are taken from the data. If present, the
\fIcount\fR is a non-negative decimal integer or \fB*\fR, which
normally indicates that all of the remaining items in the data are to
be used. If there are not enough bytes left after the current cursor
position to satisfy the current field specifier, then the
corresponding variable is left untouched and \fBbinary scan\fR returns
immediately with the number of variables that were set. If there are
not enough arguments for all of the fields in the format string that
consume arguments, then an error is generated.
.PP
Each type-count pair moves an imaginary cursor through the binary data,
reading bytes from the current position. The cursor is initially
at position 0 at the beginning of the data. The type may be any one of
the following characters:
.IP \fBa\fR 5
The data is a character string of length \fIcount\fR. If \fIcount\fR
is \fB*\fR, then all of the remaining bytes in \fIstring\fR will be
scanned into the variable. If \fIcount\fR is omitted, then one
character will be scanned. For example,
.RS
.CS
\fBbinary scan abcde\\000fghi a6a10 var1 var2\fR
.CE
will return \fB1\fR with the string equivalent to \fBabcde\\000\fR
stored in \fBvar1\fR and \fBvar2\fR left unmodified.
.RE
.IP \fBA\fR 5
This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from
the scanned value before it is stored in the variable. For example,
.RS
.CS
\fBbinary scan "abc efghi \\000" a* var1\fR
.CE
will return \fB1\fR with \fBabc efghi\fR stored in \fBvar1\fR.
.RE
.IP \fBb\fR 5
The data is turned into a string of \fIcount\fR binary digits in
low-to-high order represented as a sequence of ``1'' and ``0''
characters. The data bytes are scanned in first to last order with
the bits being taken in low-to-high order within each byte. Any extra
bits in the last byte are ignored. If \fIcount\fR is \fB*\fR, then
all of the remaining bits in \fBstring\fR will be scanned. If
\fIcount\fR is omitted, then one bit will be scanned. For example,
.RS
.CS
\fBbinary scan \\x07\\x87\\x05 b5b* var1 var2\fR
.CE
will return \fB2\fR with \fB11100\fR stored in \fBvar1\fR and
\fB1110000110100000\fR stored in \fBvar2\fR.
.RE
.IP \fBB\fR 5
This form is the same as \fBB\fR, except the bits are taken in
high-to-low order within each byte. For example,
.RS
.CS
\fBbinary scan \\x70\\x87\\x05 b5b* var1 var2\fR
.CE
will return \fB2\fR with \fB01110\fR stored in \fBvar1\fR and
\fB1000011100000101\fR stored in \fBvar2\fR.
.RE
.IP \fBh\fR 5
The data is turned into a string of \fIcount\fR hexadecimal digits in
low-to-high order represented as a sequence of characters in the set
``0123456789abcdef''. The data bytes are scanned in first to last
order with the hex digits being taken in low-to-high order within each
byte. Any extra bits in the last byte are ignored. If \fIcount\fR
is \fB*\fR, then all of the remaining hex digits in \fBstring\fR will be
scanned. If \fIcount\fR is omitted, then one hex digit will be
scanned. For example,
.RS
.CS
\fBbinary scan \\x07\\x86\\x05 h3h* var1 var2\fR
.CE
will return \fB2\fR with \fB706\fR stored in \fBvar1\fR and
\fB50\fR stored in \fBvar2\fR.
.RE
.IP \fBH\fR 5
This form is the same as \fBh\fR, except the digits are taken in
low-to-high order within each byte. For example,
.RS
.CS
\fBbinary scan \\x07\\x86\\x05 H3H* var1 var2\fR
.CE
will return \fB2\fR with \fB078\fR stored in \fBvar1\fR and
\fB05\fR stored in \fBvar2\fR.
.RE
.IP \fBc\fR 5
The data is turned into \fIcount\fR 8-bit signed integers and stored
in the corresponding variable as a list. If \fIcount\fR is \fB*\fR,
then all of the remaining bytes in \fBstring\fR will be scanned. If
\fIcount\fR is omitted, then one 8-bit integer will be scanned. For
example,
.RS
.CS
\fBbinary scan \\x07\\x86\\x05 c2c* var1 var2\fR
.CE
will return \fB2\fR with \fB7 -122\fR stored in \fBvar1\fR and \fB5\fR
stored in \fBvar2\fR. Note that the integers returned are signed, but
they can be converted to unsigned 8-bit quantities using an expression
like:
.CS
\fBexpr ( $num + 0x100 ) % 0x100\fR
.CE
.RE
.IP \fBs\fR 5
The data is interpreted as \fIcount\fR 16-bit signed integers
represented in little-endian byte order. The integers are stored in
the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then
all of the remaining bytes in \fBstring\fR will be scanned. If
\fIcount\fR is omitted, then one 16-bit integer will be scanned. For
example,
.RS
.CS
\fBbinary scan \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2\fR
.CE
will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
stored in \fBvar2\fR. Note that the integers returned are signed, but
they can be converted to unsigned 16-bit quantities using an expression
like:
.CS
\fBexpr ( $num + 0x10000 ) % 0x10000\fR
.CE
.RE
.IP \fBS\fR 5
This form is the same as \fBs\fR except that the data is interpreted
as \fIcount\fR 16-bit signed integers represented in big-endian byte
order. For example,
.RS
.CS
\fBbinary scan \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2\fR
.CE
will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
stored in \fBvar2\fR.
.RE
.IP \fBi\fR 5
The data is interpreted as \fIcount\fR 32-bit signed integers
represented in little-endian byte order. The integers are stored in
the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then
all of the remaining bytes in \fBstring\fR will be scanned. If
\fIcount\fR is omitted, then one 32-bit integer will be scanned. For
example,
.RS
.CS
\fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff i2i* var1 var2\fR
.CE
will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
stored in \fBvar2\fR. Note that the integers returned are signed and
cannot be represented by Tcl as unsigned values.
.RE
.IP \fBI\fR 5
This form is the same as \fBI\fR except that the data is interpreted
as \fIcount\fR 32-bit signed integers represented in big-endian byte
order. For example,
.RS
.CS
\fBbinary \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 I2I* var1 var2\fR
.CE
will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR
stored in \fBvar2\fR.
.RE
.IP \fBf\fR 5
The data is interpreted as \fIcount\fR single-precision floating point
numbers in the machine's native representation. The floating point
numbers are stored in the corresponding variable as a list. If
\fIcount\fR is \fB*\fR, then all of the remaining bytes in
\fBstring\fR will be scanned. If \fIcount\fR is omitted, then one
single-precision floating point number will be scanned. The size of a
floating point number may vary across architectures, so the number of
bytes that are scanned may vary. If the data does not represent a
valid floating point number, the resulting value is undefined and
compiler dependent. For example, on a Windows system running on an
Intel Pentium processor,
.RS
.CS
\fBbinary scan \\x3f\\xcc\\xcc\\xcd f var1\fR
.CE
will return \fB1\fR with \fB1.6000000238418579\fR stored in
\fBvar1\fR.
.RE
.IP \fBd\fR 5
This form is the same as \fBf\fR except that the data is interpreted
as \fIcount\fR double-precision floating point numbers in the
machine's native representation. For example, on a Windows system
running on an Intel Pentium processor,
.RS
.CS
\fBbinary scan \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1\fR
.CE
will return \fB1\fR with \fB1.6000000000000001\fR
stored in \fBvar1\fR.
.RE
.IP \fBx\fR 5
Moves the cursor forward \fIcount\fR bytes in \fIstring\fR. If
\fIcount\fR is \fB*\fR or is larger than the number of bytes after the
current cursor cursor position, then the cursor is positioned after
the last byte in \fIstring\fR. If \fIcount\fR is omitted, then the
cursor is moved forward one byte. Note that this type does not
consume an argument. For example,
.RS
.CS
\fBbinary scan \\x01\\x02\\x03\\x04 x2H* var1\fR
.CE
will return \fB1\fR with \fB0304\fR stored in \fBvar1\fR.
.RE
.IP \fBX\fR 5
Moves the cursor back \fIcount\fR bytes in \fIstring\fR. If
\fIcount\fR is \fB*\fR or is larger than the current cursor position,
then the cursor is positioned at location 0 so that the next byte
scanned will be the first byte in \fIstring\fR. If \fIcount\fR
is omitted then the cursor is moved back one byte. Note that this
type does not consume an argument. For example,
.RS
.CS
\fBbinary scan \\x01\\x02\\x03\\x04 c2XH* var1 var2\fR
.CE
will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR
stored in \fBvar2\fR.
.RE
.IP \fB@\fR 5
Moves the cursor to the absolute location in the data string specified
by \fIcount\fR. Note that position 0 refers to the first byte in
\fIstring\fR. If \fIcount\fR refers to a position beyond the end of
\fIstring\fR, then the cursor is positioned after the last byte. If
\fIcount\fR is omitted, then an error will be generated. For example,
.RS
.CS
\fBbinary scan \\x01\\x02\\x03\\x04 c2@1H* var1 var2\fR
.CE
will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR
stored in \fBvar2\fR.
.RE
.SH "PLATFORM ISSUES"
Sometimes it is desirable to format or scan integer values in the
native byte order for the machine. Refer to the \fBbyteOrder\fR
element of the \fBtcl_platform\fR array to decide which type character
to use when formatting or scanning integers.
.SH "SEE ALSO"
format, scan, tclvars
.SH KEYWORDS
binary, format, scan

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

@ -1,34 +0,0 @@
'\"
'\" 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.7 96/10/09 08:29:26
'\"
.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 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
View file

@ -1,59 +0,0 @@
'\"
'\" 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
View file

@ -1,40 +0,0 @@
'\"
'\" 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
View file

@ -1,28 +0,0 @@
'\"
'\" 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

188
contrib/tcl/doc/clock.n
View file

@ -1,188 +0,0 @@
'\"
'\" Copyright (c) 1992-1995 Karl Lehenbauer and Mark Diekhans.
'\" Copyright (c) 1995-1997 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.18 97/09/10 13:31:23
'\"
.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%c\fR
Locale specific date and time.
.IP \fB%d\fR
Day of month (01 - 31).
.IP \fB%H\fR
Hour in 24-hour format (00 - 23).
.IP \fB%I\fR
Hour in 12-hour format (00 - 12).
.IP \fB%j\fR
Day of year (001 - 366).
.IP \fB%m\fR
Month number (01 - 12).
.IP \fB%M\fR
Minute (00 - 59).
.IP \fB%p\fR
AM/PM indicator.
.IP \fB%S\fR
Seconds (00 - 59).
.IP \fB%U\fR
Week 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 of year (01 - 52), Monday is the first day of the week.
.IP \fB%x\fR
Locale specific date format.
.IP \fB%X\fR
Locale specific time format.
.IP \fB%y\fR
Year without century (00 - 99).
.IP \fB%Y\fR
Year with century (e.g. 1990)
.IP \fB%Z\fR
Time zone name.
.RE
.sp
.RS
In addition, the following field descriptors may be supported on some
systems (e.g. Unix but not Windows):
.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%n\fR
Insert a newline.
.IP \fB%r\fR
Time as %I:%M:%S %p.
.IP \fB%R\fR
Time as %H:%M.
.IP \fB%t\fR
Insert a tab.
.IP \fB%T\fR
Time as %H:%M:%S.
.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
.VS
than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
as 1969-1999. Not all platforms can represent the years 38-70, so
an error may result if these years are used.
.VE
.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 and the correct date is given when going from the end
of a long month to a short month.
.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
View file

@ -1,59 +0,0 @@
'\"
'\" 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.11 97/08/22 18:50:48
'\"
.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

40
contrib/tcl/doc/concat.n
View file

@ -1,40 +0,0 @@
'\"
'\" 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.8 96/08/26 12:59:54
'\"
.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
\fBconcat\fI \fR?\fIarg arg ...\fR?
.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
If no \fIarg\fRs are supplied, the result is an empty string.
.SH KEYWORDS
concatenate, join, lists

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

@ -1,34 +0,0 @@
'\"
'\" 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.7 96/10/09 08:29:27
'\"
.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 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
View file

@ -1,27 +0,0 @@
'\"
'\" 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
View file

@ -1,58 +0,0 @@
'\"
'\" 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
View file

@ -1,30 +0,0 @@
'\"
'\" 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

357
contrib/tcl/doc/exec.n
View file

@ -1,357 +0,0 @@
'\"
'\" 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.17 96/09/18 15:21:17
'\"
.so man.macros
.TH exec n 7.6 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
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.
.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
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'').
.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
\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.
.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
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.
.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
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.
.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.
However, if \fB\-keepnewline\fR is specified then the trailing
newline is retained.
.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.
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.
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.
.VS
.SH "PORTABILITY ISSUES"
.TP
\fBWindows\fR (all versions)
.
Reading from or writing to a socket, using the ``\fB@\0\fIfileId\fR''
notation, does not work. When reading from a socket, a 16-bit DOS
application will hang and a 32-bit application will return immediately with
end-of-file. When either type of application writes to a socket, the
information is instead sent to the console, if one is present, or is
discarded.
.sp
The Tk console text widget does not provide real standard IO capabilities.
Under Tk, when redirecting from standard input, all applications will see an
immediate end-of-file; information redirected to standard output or standard
error will be discarded.
.sp
Either forward or backward slashes are accepted as path separators for
arguments to Tcl commands. When executing an application, the path name
specified for the application may also contain forward or backward slashes
as path separators. Bear in mind, however, that most Windows applications
accept arguments with forward slashes only as option delimiters and
backslashes only in paths. Any arguments to an application that specify a
path name with forward slashes will not automatically be converted to use
the backslash character. If an argument contains forward slashes as the
path separator, it may or may not be recognized as a path name, depending on
the program.
.sp
Additionally, when calling a 16-bit DOS or Windows 3.X application, all path
names must use the short, cryptic, path format (e.g., using ``applba~1.def''
instead of ``applbakery.default'').
.sp
Two or more forward or backward slashes in a row in a path refer to a
network path. For example, a simple concatenation of the root directory
\fBc:/\fR with a subdirectory \fB/windows/system\fR will yield
\fBc://windows/system\fR (two slashes together), which refers to the
directory \fB/system\fR on the machine \fBwindows\fR (and the \fBc:/\fR is
ignored), and is not equivalent to \fBc:/windows/system\fR, which describes
a directory on the current computer.
.TP
\fBWindows NT\fR
.
When attempting to execute an application, \fBexec\fR first searches for the
name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR
are appended to the end of the specified name and it searches for
the longer name. If a directory name was not specified as part of the
application name, the following directories are automatically searched in
order when attempting to locate the application:
.sp
.RS
.RS
The directory from which the Tcl executable was loaded.
.br
The current directory.
.br
The Windows NT 32-bit system directory.
.br
The Windows NT 16-bit system directory.
.br
The Windows NT home directory.
.br
The directories listed in the path.
.RE
.sp
In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
the caller must prepend ``\fBcmd.exe /c\0\fR'' to the desired command.
.sp
.RE
.TP
\fBWindows 95\fR
.
When attempting to execute an application, \fBexec\fR first searches for the
name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR
are appended to the end of the specified name and it searches for
the longer name. If a directory name was not specified as part of the
application name, the following directories are automatically searched in
order when attempting to locate the application:
.sp
.RS
.RS
The directory from which the Tcl executable was loaded.
.br
The current directory.
.br
The Windows 95 system directory.
.br
The Windows 95 home directory.
.br
The directories listed in the path.
.RE
.sp
In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command.
.sp
Once a 16-bit DOS application has read standard input from a console and
then quit, all subsequently run 16-bit DOS applications will see the
standard input as already closed. 32-bit applications do not have this
problem and will run correctly even after a 16-bit DOS application thinks
that standard input is closed. There is no known workaround for this bug
at this time.
.sp
Redirection between the \fBNUL:\fR device and a 16-bit application does not
always work. When redirecting from \fBNUL:\fR, some applications may hang,
others will get an infinite stream of ``0x01'' bytes, and some will actually
correctly get an immediate end-of-file; the behavior seems to depend upon
something compiled into the application itself. When redirecting greater than
4K or so to \fBNUL:\fR, some applications will hang. The above problems do not
happen with 32-bit applications.
.sp
All DOS 16-bit applications are run synchronously. All standard input from
a pipe to a 16-bit DOS application is collected into a temporary file; the
other end of the pipe must be closed before the 16-bit DOS application
begins executing. All standard output or error from a 16-bit DOS
application to a pipe is collected into temporary files; the application
must terminate before the temporary files are redirected to the next stage
of the pipeline. This is due to a workaround for a Windows 95 bug in the
implementation of pipes, and is how the Windows 95 command line interpreter
handles pipes itself.
.sp
Certain applications, such as \fBcommand.com\fR, should not be executed
interactively. Applications which directly access the console window,
rather than reading from their standard input and writing to their standard
output may fail, hang Tcl, or even hang the system if their own private
console window is not available to them.
.RE
.TP
\fBWindows 3.X\fR
.
When attempting to execute an application, \fBexec\fR first searches for the
name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR
are appended to the end of the specified name and it searches for
the longer name. If a directory name was not specified as part of the
application name, the following directories are automatically searched in
order when attempting to locate the application:
.sp
.RS
.RS
The directory from which the Tcl executable was loaded.
.br
The current directory.
.br
The Windows 3.X system directory.
.br
The Windows 3.X home directory.
.br
The directories listed in the path.
.RE
.sp
In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command.
.sp
16-bit and 32-bit DOS and Windows applications may be executed. However,
redirection and piping of standard IO only works with 16-bit DOS
applications. 32-bit applications always see standard input as already
closed, and any standard output or error is discarded, no matter where in the
pipeline the application occurs or what redirection symbols are used by the
caller. Additionally, for 16-bit applications, standard error is always
sent to the same place as standard output; it cannot be redirected to a
separate location. In order to achieve pseudo-redirection for 32-bit
applications, the 32-bit application must instead be written to take command
line arguments that specify the files that it should read from and write to
and open those files itself.
.sp
All applications, both 16-bit and 32-bit, run synchronously; each application
runs to completion before the next one in the pipeline starts. Temporary files
are used to simulate piping between applications. The \fBexec\fR
command cannot be used to start an application in the background.
.sp
When standard input is redirected from an open file using the
``\fB@\0\fIfileId\fR'' notation, the open file is completely read up to its
end. This is slightly different than under Windows 95 or NT, where the child
application consumes from the open file only as much as it wants.
Redirecting to an open file is supported as normal.
.RE
.TP
\fBMacintosh\fR
The \fBexec\fR command is not implemented and does not exist under Macintosh.
.TP
\fBUnix\fR\0\0\0\0\0\0\0
The \fBexec\fR command is fully functional and works as described.
.SH "SEE ALSO"
open(n)
.VE
.SH KEYWORDS
execute, pipeline, redirection, subprocess

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

@ -1,28 +0,0 @@
'\"
'\" 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

323
contrib/tcl/doc/expr.n
View file

@ -1,323 +0,0 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) expr.n 1.28 97/09/18 18:21:30
'\"
.so man.macros
.TH expr n 8.0 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
Concatenates \fIarg\fR's (adding separator spaces between them),
evaluates the result as a Tcl expression, and returns the value.
The operators permitted in Tcl expressions are a subset of
the operators permitted in C expressions, and they have the
same meaning and precedence as the 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's instructions.
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
\fBf\fR, \fBF\fR, \fBl\fR, and \fBL\fR 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]
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.
.LP
Where substitutions occur above (e.g. inside quoted strings), they
are performed by the expression's instructions.
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
Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
may be applied to string operands, and bit-wise NOT may be
applied only to integers.
.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.
The remainder will always have the same sign as the divisor and
an absolute value smaller than the divisor.
.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 boolean and numeric (integers or floating-point) operands only.
.TP 20
\fB||\fR
Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
Valid for boolean and numeric (integers or floating-point) operands only.
.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
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 and the
generation of random 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
\fBrand()\fR
Returns a floating point number from zero to just less than one or,
in mathematical terms, the range [0,1). The seed comes from the
internal clock of the machine or may be set manual with the srand
function.
.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.
.TP
\fBsrand(\fIarg\fB)\fR
The \fIarg\fR, which must be an integer, is used to reset the seed for
the random number generator. Returns the first random number from
that seed. Each interpreter has it's own seed.
.PP
In addition to these predefined functions, applications may
define additional functions using \fBTcl_CreateMathFunc\fR().
.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.
Floating-point values are always returned with a ``\fB.\fR''
or an \fBe\fR so that they will not look like integer values. For
example,
.CS
\fBexpr 20.0/5.0\fR
.CE
returns \fB4.0\fR, not \fB4\fR.
.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 \fB18\fR.
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.
.SH "PERFORMANCE CONSIDERATIONS"
.VS
.PP
Enclose expressions in braces for the best speed and the smallest
storage requirements.
This allows the Tcl bytecode compiler to generate the best code.
.PP
As mentioned above, expressions are substituted twice:
once by the Tcl parser and once by the \fBexpr\fR command.
For example, the commands
.CS
\fBset a 3\fR
\fBset b {$a + 2}\fR
\fBexpr $b*4\fR
.CE
return 11, not a multiple of 4.
This is because the Tcl parser will first substitute \fB$a + 2\fR for
the variable \fBb\fR,
then the \fBexpr\fR command will evaluate the expression \fB$a + 2*4\fR.
.PP
Most expressions do not require a second round of substitutions.
Either they are enclosed in braces or, if not,
their variable and command substitutions yield numbers or strings
that don't themselves require substitutions.
However, because a few unbraced expressions
need two rounds of substitutions,
the bytecode compiler must emit
additional instructions to handle this situation.
The most expensive code is required for
unbraced expressions that contain command substitutions.
These expressions must be implemented by generating new code
each time the expression is executed.
.VE
.SH KEYWORDS
arithmetic, boolean, compare, expression, fuzzy comparison

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

@ -1,32 +0,0 @@
'\"
'\" 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
View file

@ -1,178 +0,0 @@
'\"
'\" 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

127
contrib/tcl/doc/fcopy.n
View file

@ -1,127 +0,0 @@
'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" SCCS: @(#) fcopy.n 1.4 97/06/19 11:10:07
'\"
.so man.macros
.TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
fcopy \- Copy data from one channel to another.
.SH SYNOPSIS
\fBfcopy \fIinchan\fR \fIoutchan\fR ?\fB\-size \fIsize\fR? ?\fB\-command \fIcallback\fR?
.BE
.SH DESCRIPTION
.PP
The \fBfcopy\fP command copies data from one I/O channel, \fIinchan\fR to another I/O channel, \fIoutchan\fR.
The \fBfcopy\fP command leverages the buffering in the Tcl I/O system to
avoid extra copies and to avoid buffering too much data in
main memory when copying large files to slow destinations like
network sockets.
.PP
The \fBfcopy\fP
command transfers data from \fIinchan\fR until end of file
or \fIsize\fP bytes have been
transferred. If no \fB\-size\fP argument is given,
then the copy goes until end of file.
All the data read from \fIinchan\fR is copied to \fIoutchan\fR.
Without the \fB\-command\fP option, \fBfcopy\fP blocks until the copy is complete
and returns the number of bytes written to \fIoutchan\fR.
.PP
The \fB\-command\fP argument makes \fBfcopy\fP work in the background.
In this case it returns immediately and the \fIcallback\fP is invoked
later when the copy completes.
The \fIcallback\fP is called with
one or two additional
arguments that indicates how many bytes were written to \fIoutchan\fR.
If an error occurred during the background copy, the second argument is the
error string associated with the error.
With a background copy,
it is not necessary to put \fIinchan\fR or \fIoutchan\fR into
non-blocking mode; the \fBfcopy\fP command takes care of that automatically.
However, it is necessary to enter the event loop by using
the \fBvwait\fP command or by using Tk.
.PP
You are not allowed to do other I/O operations with
\fIinchan\fR or \fIoutchan\fR during a background fcopy.
If either \fIinchan\fR or \fIoutchan\fR get closed
while the copy is in progress, the current copy is stopped
and the command callback is \fInot\fP made.
If \fIinchan\fR is closed,
then all data already queued for \fIoutchan\fR is written out.
.PP
Note that \fIinchan\fR can become readable during a background copy.
You should turn off any \fBfileevent\fP handlers during a background
copy so those handlers do not interfere with the copy.
Any I/O attempted by a \fBfileevent\fP handler will get a "channel busy" error.
.PP
\fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR
according to the \fB\-translation\fR option
for these channels.
See the manual entry for \fBfconfigure\fR for details on the
\fB\-translation\fR option.
The translations mean that the number of bytes read from \fIinchan\fR
can be different than the number of bytes written to \fIoutchan\fR.
Only the number of bytes written to \fIoutchan\fR is reported,
either as the return value of a synchronous \fBfcopy\fP or
as the argument to the callback for an asynchronous \fBfcopy\fP.
.SH EXAMPLE
.PP
This first example shows how the callback gets
passed the number of bytes transferred.
It also uses vwait to put the application into the event loop.
Of course, this simplified example could be done without the command
callback.
.DS
proc Cleanup {in out bytes {error {}}} {
global total
set total $bytes
close $in
close $out
if {[string length $error] != 0} {
# error occurred during the copy
}
}
set in [open $file1]
set out [socket $server $port]
fcopy $in $out -command [list Cleanup $in $out]
vwait total
.DE
.PP
The second example copies in chunks and tests for end of file
in the command callback
.DS
proc CopyMore {in out chunk bytes {error {}}} {
global total done
incr total $bytes
if {([string length $error] != 0) || [eof $in] {
set done $total
close $in
close $out
} else {
fcopy $in $out -command [list CopyMore $in $out $chunk] \\
-size $chunk
}
}
set in [open $file1]
set out [socket $server $port]
set chunk 1024
set total 0
fcopy $in $out -command [list CopyMore $in $out $chunk] -size $chunk
vwait done
.DE
.SH "SEE ALSO"
eof(n), fblocked(n), fconfigure(n)
.SH KEYWORDS
blocking, channel, end of line, end of file, nonblocking, read, translation

331
contrib/tcl/doc/file.n
View file

@ -1,331 +0,0 @@
'\"
'\" 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.23 97/04/30 11:37:10
'\"
.so man.macros
.TH file n 7.6 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
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). \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.
.VS
.TP
\fBfile attributes \fIname\fR
.br
\fBfile attributes \fIname\fR ?\fBoption\fR?
.br
\fBfile attributes \fIname\fR ?\fBoption value option value...\fR?
.RS
This subcommand returns or sets platform specific values associated
with a file. The first form returns a list of the platform specific
flags and their values. The second form returns the value for the
specific option. The third form sets one or more of the values. The
values are as follows:
.PP
On Unix, \fB-group\fR gets or sets the group name for the file. A group id can
be given to the command, but it returns a group name. \fB-owner\fR
gets or sets the user name of the owner of the file. The command
returns the owner name, but the numerical id can be passed when
setting the owner. \fB-permissions\fR sets or retrieves the octal code
that chmod(1) uses. This command does not support the symbolic
attributes for chmod(1) at this time.
.PP
On Windows, \fB-archive\fR gives the value or sets or clears the
archive attribute of the file. \fB-hidden\fR gives the value or sets
or clears the hidden attribute of the file. \fB-longname\fR will
expand each path element to its long version. This attribute cannot be
set. \fB-readonly\fR gives the value or sets or clears the readonly
attribute of the file. \fB-shortname\fR gives a string where every
path element is replaced with its short (8.3) version of the
name. This attribute cannot be set. \fB-system\fR gives or sets or
clears the value of the system attribute of the file.
.PP
On Macintosh, \fB-creator\fR gives or sets the Finder creator type of
the file. \fB-hidden\fR gives or sets or clears the hidden attribute
of the file. \fB-readonly\fR gives or sets or clears the readonly
attribute of the file. Note that directories can only be locked if
File Sharing is turned on. \fB-type\fR gives or sets the Finder file
type for the file.
.RE
.VE
.PP
\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
.br
\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
.RS
The first form makes a copy of the file or directory \fIsource\fR under
the pathname \fItarget\fR. If \fItarget\fR is an existing directory,
then the second form is used. The second form makes a copy inside
\fItargetDir\fR of each \fIsource\fR file listed. If a directory is
specified as a \fIsource\fR, then the contents of the directory will be
recursively copied into \fItargetDir\fR. Existing files will not be
overwritten unless the \fB\-force\fR option is specified. Trying to
overwrite a non-empty directory, overwrite a directory with a file, or a
file with a directory will all result in errors even if \fI\-force\fR was
specified. Arguments are processed in the order specified, halting at the
first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument
following the \fB\-\|\-\fR will be treated as a \fIsource\fR even if it
starts with a \fB\-\fR.
.RE
.TP
\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ?
.
Removes the file or directory specified by each \fIpathname\fR argument.
Non-empty directories will be removed only if the \fB\-force\fR option is
specified. Trying to delete a non-existant file is not considered an
error. Trying to delete a read-only file will cause the file to be deleted,
even if the \fB\-force\fR flags is not specified. Arguments are processed
in the order specified, halting at the first error, if any. A \fB\-\|\-\fR
marks the end of switches; the argument following the \fB\-\|\-\fR will be
treated as a \fIpathname\fR even if it starts with a \fB\-\fR.
.TP
\fBfile dirname \fIname\fR
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
.TP
\fBfile executable \fIname\fR
.
Returns \fB1\fR if file \fIname\fR is executable by the current user,
\fB0\fR otherwise.
.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.
.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
.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 mkdir \fIdir\fR ?\fIdir\fR ...?
.
Creates each directory specified. For each pathname \fIdir\fR specified,
this command will create all non-existing parent directories as
well as \fIdir\fR itself. If an existing directory is specified, then
no action is taken and no error is returned. Trying to overwrite an existing
file with a directory will result in an error. Arguments are processed in
the order specified, halting at the first error, if any.
.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.
.VS
.TP
\fBfile nativename \fIname\fR
.
Returns the platform-specific name of the file. This is useful if the
filename is needed to pass to a platform-specific call, such as exec
under Windows or AppleScript on the Macintosh.
.VE
.TP
\fBfile owned \fIname\fR
.
Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR
otherwise.
.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.
.TP
\fBfile readable \fIname\fR
.
Returns \fB1\fR if file \fIname\fR is readable by the current user,
\fB0\fR otherwise.
.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.
.PP
\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
.br
\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
.RS
The first form takes the file or directory specified by pathname
\fIsource\fR and renames it to \fItarget\fR, moving the file if the
pathname \fItarget\fR specifies a name in a different directory. If
\fItarget\fR is an existing directory, then the second form is used. The
second form moves each \fIsource\fR file or directory into the directory
\fItargetDir\fR. Existing files will not be overwritten unless the
\fB\-force\fR option is specified. Trying to overwrite a non-empty
directory, overwrite a directory with a file, or a file with a directory
will all result in errors. Arguments are processed in the order specified,
halting at the first error, if any. A \fB\-\|\-\fR marks the end of
switches; the argument following the \fB\-\|\-\fR will be treated as a
\fIsource\fR even if it starts with a \fB\-\fR.
.RE
.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.
.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
.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
.
Returns all of the characters in \fIname\fR after the last directory
separator. If \fIname\fR contains no separators then returns
\fIname\fR.
.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 volume\fR
.
Returns the absolute paths to the volumes mounted on the system, as a proper
Tcl list. On the Macintosh, this will be a list of the mounted drives,
both local and network. N.B. if two drives have the same name, they will
both appear on the volume list, but there is currently no way, from Tcl, to
access any but the first of these drives. On UNIX, the command will always return
"/", since all filesystems are locally mounted. On Windows, it will return
a list of the available local drives (e.g. {a:/ c:/}).
.TP
\fBfile writable \fIname\fR
.
Returns \fB1\fR if file \fIname\fR is writable by the current user,
\fB0\fR otherwise.
.SH "PORTABILITY ISSUES"
.TP
\fBUnix\fR\0\0\0\0\0\0\0
.
These commands always operate using the real user and group identifiers,
not the effective ones.
.SH "SEE ALSO"
filename
.SH KEYWORDS
attributes, copy files, delete files, directory, file, move files, name, rename files, stat

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

@ -1,109 +0,0 @@
'\"
'\" 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.

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