summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/ExprLong.34
-rw-r--r--doc/GetIndex.36
-rw-r--r--doc/Hash.34
-rw-r--r--doc/Limit.34
-rw-r--r--doc/ListObj.34
-rw-r--r--doc/Notifier.330
-rw-r--r--doc/ParseCmd.34
-rw-r--r--doc/RegExp.36
-rw-r--r--doc/SetVar.317
-rw-r--r--doc/TraceVar.36
-rw-r--r--doc/Utf.34
11 files changed, 25 insertions, 64 deletions
diff --git a/doc/ExprLong.3 b/doc/ExprLong.3
index bc70595..bb00edf 100644
--- a/doc/ExprLong.3
+++ b/doc/ExprLong.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: ExprLong.3,v 1.8 2004/10/07 15:15:37 dkf Exp $
+'\" RCS: @(#) $Id: ExprLong.3,v 1.9 2004/10/07 16:05:13 dkf Exp $
'\"
.so man.macros
.TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures"
@@ -31,9 +31,7 @@ int
.AS Tcl_Interp *booleanPtr out
.AP Tcl_Interp *interp in
Interpreter in whose context to evaluate \fIstring\fR or \fIobjPtr\fR.
-.VS 8.4
.AP "const char" *string in
-.VE
Expression to be evaluated.
.AP long *longPtr out
Pointer to location in which to store the integer value of the
diff --git a/doc/GetIndex.3 b/doc/GetIndex.3
index f54dd3c..cc3dbc7 100644
--- a/doc/GetIndex.3
+++ b/doc/GetIndex.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: GetIndex.3,v 1.15 2004/10/07 15:15:38 dkf Exp $
+'\" RCS: @(#) $Id: GetIndex.3,v 1.16 2004/10/07 16:05:13 dkf Exp $
'\"
.so man.macros
.TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures"
@@ -22,7 +22,7 @@ indexPtr\fR)
.sp
int
\fBTcl_GetIndexFromObjStruct\fR(\fIinterp, objPtr, structTablePtr, offset,
-msg, flags, indexPtr\fR)
+ msg, flags, indexPtr\fR)
.VE
.SH ARGUMENTS
.AS "const char" *structTablePtr in/out
@@ -40,11 +40,9 @@ by a NULL string pointer.
An array of arbitrary type, typically some \fBstruct\fP type.
The first member of the structure must be a null-terminated string.
The size of the structure is given by \fIoffset\fP.
-.VS
.AP int offset in
The offset to add to structTablePtr to get to the next entry.
The end of the array is marked by a NULL string pointer.
-.VE
.AP "const char" *msg in
Null-terminated string describing what is being looked up, such as
\fBoption\fR. This string is included in error messages.
diff --git a/doc/Hash.3 b/doc/Hash.3
index 98cf3b2..d21ba2b 100644
--- a/doc/Hash.3
+++ b/doc/Hash.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: Hash.3,v 1.17 2004/10/07 15:15:38 dkf Exp $
+'\" RCS: @(#) $Id: Hash.3,v 1.18 2004/10/07 16:05:14 dkf Exp $
'\"
.so man.macros
.TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
@@ -257,8 +257,8 @@ There are some things, pointers for example which don't hash well
because they do not use the lower bits. If this flag is set then the
hash table will attempt to rectify this by randomizing the bits and
then using the upper N bits as the index into the table.
-.VS 8.5 br
.IP \fBTCL_HASH_KEY_SYSTEM_HASH\fR 25
+.VS 8.5
This flag forces Tcl to use the memory allocation
procedures provided by the operating system when allocating
and freeing memory used to store the hash table data structures,
diff --git a/doc/Limit.3 b/doc/Limit.3
index ca06a7d..389c406 100644
--- a/doc/Limit.3
+++ b/doc/Limit.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: Limit.3,v 1.5 2004/10/07 14:52:43 dkf Exp $
+'\" RCS: @(#) $Id: Limit.3,v 1.6 2004/10/07 16:05:14 dkf Exp $
'\"
.so man.macros
.TH Tcl_LimitCheck 3 8.5 Tcl "Tcl Library Procedures"
@@ -65,7 +65,7 @@ void
Interpreter that the limit being managed applies to or that will have
its limits checked.
.AP int type in
-The type of limit that the operation refers to. Must be either
+The type of limit that the operation refers to. This must be either
\fBTCL_LIMIT_COMMANDS\fR or \fBTCL_LIMIT_TIME\fR.
.AP int commandLimit in
The maximum number of commands (as reported by \fBinfo cmdcount\fR)
diff --git a/doc/ListObj.3 b/doc/ListObj.3
index 8e97f43..9bbf818 100644
--- a/doc/ListObj.3
+++ b/doc/ListObj.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: ListObj.3,v 1.7 2004/10/07 15:15:38 dkf Exp $
+'\" RCS: @(#) $Id: ListObj.3,v 1.8 2004/10/07 16:05:14 dkf Exp $
'\"
.so man.macros
.TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -73,13 +73,11 @@ 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
.AP "Tcl_Obj *const" objv[] 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.
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index 2ea9195..3bf7c0f 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: Notifier.3,v 1.11 2004/10/07 15:37:44 dkf Exp $
+'\" RCS: @(#) $Id: Notifier.3,v 1.12 2004/10/07 16:05:14 dkf Exp $
'\"
.so man.macros
.TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
@@ -99,11 +99,9 @@ Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
.AP int flags in
What types of events to service. These flags are the same as those
passed to \fBTcl_DoOneEvent\fR.
-.VS 8.1
.AP int mode in
Indicates 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
@@ -137,9 +135,7 @@ 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 8.1
-Threaded applications work in a
+servicing at a future time. Threaded applications work in a
similar manner, except that there is a separate event queue for
each thread containing a Tcl interpreter.
\fBTcl_QueueEvent\fR is used (primarily
@@ -171,7 +167,6 @@ The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
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.
@@ -182,17 +177,13 @@ 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 8.1
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 8.1
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
@@ -258,7 +249,6 @@ 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 8.1
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
@@ -270,7 +260,6 @@ 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:
@@ -282,16 +271,13 @@ typedef struct Tcl_Time {
.CE
The \fIusec\fR field should be less than 1000000.
.PP
-.VS 8.1
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 8.1
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
@@ -307,7 +293,6 @@ 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
@@ -365,10 +350,8 @@ 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 8.1
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
@@ -380,9 +363,7 @@ 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 8.1
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
@@ -391,9 +372,7 @@ 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 8.1
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
@@ -404,7 +383,6 @@ Another example of deferring events happens in Tk if
\fBTk_RestrictEvents\fR has been invoked to defer certain kinds
of window events.
.PP
-.VS 8.1
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
@@ -446,13 +424,11 @@ point to the next event in the queue.
\fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those
provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted.
If no such source exists, \fBTcl_DeleteEventSource\fR has no effect.
-.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 8.1
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.
@@ -594,7 +570,7 @@ then calls to \fBTcl_ServiceAll\fR will behave normally.
mode, which should be restored when the recursive loop exits.
\fBTcl_GetServiceMode\fR returns the current value of the service
mode.
-.VE
+
.SH "SEE ALSO"
\fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR,
\fBTcl_DoOneEvent\fR, \fBThread(3)\fR
diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3
index 5f4edaf..2cbff4e 100644
--- a/doc/ParseCmd.3
+++ b/doc/ParseCmd.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: ParseCmd.3,v 1.17 2004/10/07 15:15:47 dkf Exp $
+'\" RCS: @(#) $Id: ParseCmd.3,v 1.18 2004/10/07 16:05:15 dkf Exp $
'\"
.so man.macros
.TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures"
@@ -286,9 +286,9 @@ of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens.
This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR
sub-token. The \fInumComponents\fR field is always 1.
-.VS 8.5
.TP
\fBTCL_TOKEN_EXPAND_WORD\fR
+.VS 8.5
This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
the command parser notes this word began with the expansion
prefix \fB{expand}\fR, indicating that after substitution,
diff --git a/doc/RegExp.3 b/doc/RegExp.3
index 8892a20..8de90b9 100644
--- a/doc/RegExp.3
+++ b/doc/RegExp.3
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: RegExp.3,v 1.18 2004/10/07 15:15:47 dkf Exp $
+'\" RCS: @(#) $Id: RegExp.3,v 1.19 2004/10/07 16:05:15 dkf Exp $
'\"
.so man.macros
.TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
@@ -67,11 +67,13 @@ will be allowed.
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.
-.VS 8.4
.AP "const char" **startPtr out
+.VS 8.4
The address of the first character in the range is stored here, or
NULL if there is no such range.
+.VE 8.4
.AP "const char" **endPtr out
+.VS 8.4
The address of the character just after the last one in the range
is stored here, or NULL if there is no such range.
.VE 8.4
diff --git a/doc/SetVar.3 b/doc/SetVar.3
index 465749c..dc43c54 100644
--- a/doc/SetVar.3
+++ b/doc/SetVar.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: SetVar.3,v 1.11 2004/10/07 15:15:48 dkf Exp $
+'\" RCS: @(#) $Id: SetVar.3,v 1.12 2004/10/07 16:05:15 dkf Exp $
'\"
.so man.macros
.TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures"
@@ -16,10 +16,8 @@ Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVa
.nf
\fB#include <tcl.h>\fR
.sp
-.VS 8.1
Tcl_Obj *
\fBTcl_SetVar2Ex\fR(\fIinterp, name1, name2, newValuePtr, flags\fR)
-.VE
.sp
const char *
\fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR)
@@ -30,10 +28,8 @@ const char *
Tcl_Obj *
\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR)
.sp
-.VS 8.1
Tcl_Obj *
\fBTcl_GetVar2Ex\fR(\fIinterp, name1, name2, flags\fR)
-.VE
.sp
const char *
\fBTcl_GetVar\fR(\fIinterp, varName, flags\fR)
@@ -63,9 +59,7 @@ to specify a variable in a particular namespace.
If non-NULL, gives name of element within array; in this
case \fIname1\fR must refer to an array variable.
.AP Tcl_Obj *newValuePtr in
-.VS 8.1
Points to a Tcl object containing the new value for the variable.
-.VE
.AP int flags in
OR-ed combination of bits providing additional information. See below
for valid values.
@@ -93,7 +87,6 @@ within an array and \fIpart1Ptr\fR must refer to an array variable.
These procedures are used to create, modify, read, and delete
Tcl variables from C code.
.PP
-.VS 8.1
\fBTcl_SetVar2Ex\fR, \fBTcl_SetVar\fR, \fBTcl_SetVar2\fR, and
\fBTcl_ObjSetVar2\fR
will create a new variable or modify an existing one.
@@ -107,14 +100,12 @@ a pointer to a Tcl_Obj. \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR
take the new value as a string and return a string; they are
usually less efficient than \fBTcl_ObjSetVar2\fR. Note that the
return value may be different than the \fInewValuePtr\fR or
-.VE
\fInewValue\fR argument, due to modifications made by write traces.
If an error occurs in setting the variable (e.g. an array
variable is referenced without giving an index into the array)
NULL is returned and an error message is left in \fIinterp\fR's
result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR bit is set.
.PP
-.VS 8.1
\fBTcl_GetVar2Ex\fR, \fBTcl_GetVar\fR, \fBTcl_GetVar2\fR, and
\fBTcl_ObjGetVar2\fR
return the current value of a variable.
@@ -127,7 +118,6 @@ returned as a pointer to a Tcl_Obj. For \fBTcl_GetVar\fR and
\fBTcl_GetVar2\fR the value is returned as a string; this is
usually less efficient, so \fBTcl_GetVar2Ex\fR or \fBTcl_ObjGetVar2\fR
are preferred.
-.VE
If an error occurs while reading the variable (e.g. the variable
doesn't exist or an array element is specified for a scalar
variable), then NULL is returned and an error message is left
@@ -167,16 +157,13 @@ If the \fIname1\fR and \fIname2\fR arguments are provided and
\fIname2\fR is non-NULL, then an array element is specified and
the array name and index have
already been separated by the caller: \fIname1\fR contains the
-name and \fIname2\fR contains the index.
-.VS 8.1
-An error is generated
+name and \fIname2\fR contains the index. An error is generated
if \fIname1\fR contains an open parenthesis and ends with a
close parenthesis (array element) and \fIname2\fR is non-NULL.
.IP [3]
If \fIname2\fR is NULL, \fIname1\fR is treated just like
\fIvarName\fR in case [1] above (it can be either a scalar or an array
element variable name).
-.VE
.PP
The \fIflags\fR argument may be used to specify any of several
options to the procedures.
diff --git a/doc/TraceVar.3 b/doc/TraceVar.3
index be4d994..dfd488d 100644
--- a/doc/TraceVar.3
+++ b/doc/TraceVar.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: TraceVar.3,v 1.12 2004/10/07 15:15:48 dkf Exp $
+'\" RCS: @(#) $Id: TraceVar.3,v 1.13 2004/10/07 16:05:15 dkf Exp $
'\"
.so man.macros
.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
@@ -106,15 +106,17 @@ Invoke \fIproc\fR whenever the array command is invoked.
This gives the trace procedure a chance to update the array before
array names or array get is called. Note that this is called
before an array set, but that will trigger write traces.
-.VS 8.4
.TP
\fBTCL_TRACE_RESULT_DYNAMIC\fR
+.VS 8.4
The result of invoking the \fIproc\fR is a dynamically allocated
string that will be released by the Tcl library via a call to
\fBckfree\fR. Must not be specified at the same time as
\fBTCL_TRACE_RESULT_OBJECT\fR.
+.VE 8.4
.TP
\fBTCL_TRACE_RESULT_OBJECT\fR
+.VS 8.4
The result of invoking the \fIproc\fR is a Tcl_Obj* (cast to a char*)
with a reference count of at least one. The ownership of that
reference will be transferred to the Tcl core for release (when the
diff --git a/doc/Utf.3 b/doc/Utf.3
index d9f26d6..a1a9a4d 100644
--- a/doc/Utf.3
+++ b/doc/Utf.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: Utf.3,v 1.19 2004/10/07 15:15:48 dkf Exp $
+'\" RCS: @(#) $Id: Utf.3,v 1.20 2004/10/07 16:05:15 dkf Exp $
'\"
.so man.macros
.TH Utf 3 "8.1" Tcl "Tcl Library Procedures"
@@ -116,8 +116,8 @@ including the backslash character.
.AP char *dst out
Buffer in which the bytes represented by the backslash sequence are stored.
At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
-.VS 8.4
.AP int nocase in
+.VS 8.4
Specifies whether the match should be done case-sensitive (0) or
case-insensitive (1).
.VE 8.4