diff options
Diffstat (limited to 'doc')
105 files changed, 587 insertions, 1425 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 53f134a..3968820 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options +Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -30,8 +30,6 @@ int .sp \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR) .sp -\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR) -.sp \fBTcl_GetErrorLine\fR(\fIinterp\fR) .sp \fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR) @@ -56,14 +54,14 @@ For \fBTcl_AddObjErrorInfo\fR, this points to the first byte of an array of \fIlength\fR bytes containing a string to append to the \fB\-errorinfo\fR return option. This byte array may contain embedded null bytes -unless \fIlength\fR is negative. +unless \fIlength\fR is TCL_INDEX_NONE. .AP Tcl_Obj *objPtr in A message to be appended to the \fB\-errorinfo\fR return option in the form of a Tcl_Obj value. -.AP int length in +.AP size_t length in The number of bytes to copy from \fImessage\fR when appending to the \fB\-errorinfo\fR return option. -If negative, all bytes up to the first null byte are used. +If TCL_INDEX_NONE, all bytes up to the first null byte are used. .AP Tcl_Obj *errorObjPtr in The \fB\-errorcode\fR return option will be set to this value. .AP "const char" *element in @@ -78,8 +76,8 @@ The line number of a script where an error occurred. Pointer to first character in script containing command (must be <= command) .AP "const char" *command in Pointer to first character in command that generated the error -.AP int commandLength in -Number of bytes in command; -1 means use all bytes up to first null byte +.AP size_t commandLength in +Number of bytes in command; TCL_INDEX_NONE means use all bytes up to first null byte .BE .SH DESCRIPTION .PP @@ -229,7 +227,7 @@ embedded null bytes. This is essentially never a good idea. If the \fImessage\fR needs to contain the null character \fBU+0000\fR, Tcl's usual internal encoding rules should be used to avoid the need for a null byte. If the \fBTcl_AddObjErrorInfo\fR -interface is used at all, it should be with a negative \fIlength\fR value. +interface is used at all, it should be with a TCL_INDEX_NONE \fIlength\fR value. .PP The procedure \fBTcl_SetObjErrorCode\fR is used to set the \fB\-errorcode\fR return option to the list value \fIerrorObjPtr\fR @@ -245,12 +243,6 @@ The procedure \fBTcl_SetErrorCode\fR is also used to set the record instead of a value. Otherwise, it is similar to \fBTcl_SetObjErrorCode\fR in behavior. .PP -\fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that -instead of taking a variable number of arguments it takes an argument list. -Interfaces using argument lists have been found to be nonportable in practice. -This function is deprecated and will be removed in Tcl 9.0. - -.PP The procedure \fBTcl_GetErrorLine\fR is used to read the integer value of the \fB\-errorline\fR return option without the overhead of a full call to \fBTcl_GetReturnOptions\fR. Likewise, \fBTcl_SetErrorLine\fR diff --git a/doc/Alloc.3 b/doc/Alloc.3 index 70b0f7d..c0fd0cd 100644 --- a/doc/Alloc.3 +++ b/doc/Alloc.3 @@ -4,11 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures" +.TH Tcl_Alloc 3 9.0 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME -Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory +Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo \- allocate or free heap memory .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -19,32 +19,17 @@ char * void \fBTcl_Free\fR(\fIptr\fR) .sp -char * +void * \fBTcl_Realloc\fR(\fIptr, size\fR) .sp -char * +void * \fBTcl_AttemptAlloc\fR(\fIsize\fR) .sp -char * +void * \fBTcl_AttemptRealloc\fR(\fIptr, size\fR) .sp void \fBTcl_GetMemoryInfo\fR(\fIdsPtr\fR) -.sp -char * -\fBckalloc\fR(\fIsize\fR) -.sp -void -\fBckfree\fR(\fIptr\fR) -.sp -char * -\fBckrealloc\fR(\fIptr, size\fR) -.sp -char * -\fBattemptckalloc\fR(\fIsize\fR) -.sp -char * -\fBattemptckrealloc\fR(\fIptr, size\fR) .SH ARGUMENTS .AS char *size .AP "unsigned int" size in @@ -84,18 +69,17 @@ allocation fails, these functions will return NULL. Note that on some platforms, but not all, attempting to allocate a zero-sized block of memory will also cause these functions to return NULL. .PP -The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR, -\fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented -as macros. Normally, they are synonyms for the corresponding -procedures documented on this page. When Tcl and all modules -calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however, -these macros are redefined to be special debugging versions -of these procedures. To support Tcl's memory debugging within a -module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc. +When a module or Tcl itself is compiled with \fBTCL_MEM_DEBUG\fR defined, +the procedures \fBTcl_Alloc\fR, \fBTcl_Free\fR, \fBTcl_Realloc\fR, +\fBTcl_AttemptAlloc\fR, and \fBTcl_AttempRealloc\fR are implemented +as macros, redefined to be special debugging versions of these procedures. \fBTcl_GetMemoryInfo\fR appends a list-of-lists of memory stats to the provided DString. This function cannot be used in stub-enabled extensions, -and it is only available if Tcl is compiled with the threaded memory allocator. +and it is only available if Tcl is compiled with the threaded memory allocator +When used in stub-enabled embedders, the stubs table must be first initialized +using one of \fBTcl_InitSubsystems\fR, \fBTcl_SetPanicProc\fR, +\fBTcl_FindExecutable\fR or \fBTclZipfs_AppHook\fR. .SH KEYWORDS alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG diff --git a/doc/AllowExc.3 b/doc/AllowExc.3 index 172bb30..29e31be 100644 --- a/doc/AllowExc.3 +++ b/doc/AllowExc.3 @@ -30,8 +30,7 @@ or \fBTCL_RETURN\fR, then Tcl normally converts this into a \fBTCL_ERROR\fR return with an appropriate message. The particular script evaluation procedures of Tcl that act in the manner are \fBTcl_EvalObjEx\fR, \fBTcl_EvalObjv\fR, \fBTcl_Eval\fR, \fBTcl_EvalEx\fR, -\fBTcl_GlobalEval\fR, \fBTcl_GlobalEvalObj\fR, \fBTcl_VarEval\fR and -\fBTcl_VarEvalVA\fR. +\fBTcl_GlobalEval\fR, \fBTcl_GlobalEvalObj\fR and \fBTcl_VarEval\fR. .PP However, if \fBTcl_AllowExceptions\fR is invoked immediately before calling one of those a procedures, then arbitrary completion diff --git a/doc/AssocData.3 b/doc/AssocData.3 index d4fa3d7..e95c26b 100644 --- a/doc/AssocData.3 +++ b/doc/AssocData.3 @@ -13,7 +13,7 @@ Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations o .nf \fB#include <tcl.h>\fR .sp -ClientData +void * \fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR) .sp \fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR) @@ -31,7 +31,7 @@ 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 +.AP void *clientData in Arbitrary one-word value associated with the given key in this interpreter. This data is owned by the caller. .BE @@ -64,7 +64,7 @@ the type \fBTcl_InterpDeleteProc\fR: .PP .CS typedef void \fBTcl_InterpDeleteProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR); .CE .PP diff --git a/doc/Async.3 b/doc/Async.3 index e6ec5f8..a8d7da0 100644 --- a/doc/Async.3 +++ b/doc/Async.3 @@ -35,7 +35,7 @@ int .AS Tcl_AsyncHandler clientData .AP Tcl_AsyncProc *proc in Procedure to invoke to handle an asynchronous event. -.AP ClientData clientData in +.AP void *clientData in One-word value to pass to \fIproc\fR. .AP Tcl_AsyncHandler async in Token for asynchronous event handler. @@ -95,7 +95,7 @@ type \fBTcl_AsyncProc\fR: .PP .CS typedef int \fBTcl_AsyncProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIcode\fR); .CE diff --git a/doc/Backslash.3 b/doc/Backslash.3 deleted file mode 100644 index 1a807f6..0000000 --- a/doc/Backslash.3 +++ /dev/null @@ -1,47 +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. -'\" -.TH Tcl_Backslash 3 "8.1" Tcl "Tcl Library Procedures" -.so man.macros -.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 out -.AP "const char" *src in -Pointer to a string starting with a backslash. -.AP int *countPtr out -If \fIcountPtr\fR is not NULL, \fI*countPtr\fR gets filled -in with number of characters in the backslash sequence, including -the backslash character. -.BE - -.SH DESCRIPTION -.PP -The use of \fBTcl_Backslash\fR is deprecated in favor of -\fBTcl_UtfBackslash\fR. -.PP -This is a utility procedure provided for backwards compatibility with -non-internationalized Tcl extensions. It parses a backslash sequence and -returns the low byte of the Unicode 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 "SEE ALSO" -Tcl(n), Tcl_UtfBackslash(3) - -.SH KEYWORDS -backslash, parse diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3 index fd7f245..69f55d6 100644 --- a/doc/ByteArrObj.3 +++ b/doc/ByteArrObj.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. '\" -.TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures" +.TH Tcl_ByteArrayObj 3 9.0 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -34,8 +34,8 @@ unsigned char * .AP "const unsigned char" *bytes in The array of bytes used to initialize or set a byte-array value. May be NULL even if \fInumBytes\fR is non-zero. -.AP int numBytes in -The number of bytes in the array. It must be >= 0. +.AP size_t numBytes in +The number of bytes in the array. .AP Tcl_Obj *objPtr in/out For \fBTcl_SetByteArrayObj\fR, this points to an unshared value to be overwritten by a byte-array value. For \fBTcl_GetBytesFromObj\fR, @@ -43,7 +43,7 @@ overwritten by a byte-array value. For \fBTcl_GetBytesFromObj\fR, to the value from which to extract an array of bytes. .AP Tcl_Interp *interp in Interpreter to use for error reporting. -.AP "size_t | int" *numBytesPtr out +.AP "size_t \&| int" *numBytesPtr out Points to space where the number of bytes in the array may be written. Caller may pass NULL when it does not need this information. .BE @@ -92,11 +92,6 @@ returns a pointer to the created value with a reference count of zero. of the unshared \fIobjPtr\fR as appropriate, and keeps its reference count (0 or 1) unchanged. The value produced by these routines has no string representation. Any memory allocation failure may cause a panic. -Note that the type of the \fInumBytes\fR argument is \fBint\fR; consequently -the largest byte-array value that can be produced by these routines is one -holding \fBINT_MAX\fR bytes. Note also that the string representation of -any Tcl value is limited to \fBINT_MAX\fR bytes, so caution should be -taken with any byte-array of more than \fBINT_MAX / 2\fR bytes. .PP \fBTcl_GetBytesFromObj\fR performs the opposite function of \fBTcl_SetByteArrayObj\fR, providing access to read a byte-array from @@ -121,29 +116,14 @@ failure, nothing will be written to \fInumBytesPtr\fR, and if the \fIinterp\fR argument is non-NULL, then error messages and codes are left in it recording the error. .PP -\fBTcl_GetByteArrayFromObj\fR performs nearly the same function as -\fBTcl_GetBytesFromObj\fR. They differ only in the circumstance when -a byte-array internal value must be created by transformation of -a string representation, and that string representation contains a -character with codepoint greater than U+00FF. Instead of failing -the conversion, \fBTcl_GetByteArrayFromObj\fR will use the 8 least -significant bits of each codepoint to produce a valid byte value -from any character codepoint value. In any other circumstance, -\fBTcl_GetByteArrayFromObj\fR performs just as \fBTcl_GetBytesFromObj\fR -does. Since the conversion cannot fail, \fBTcl_GetByteArrayFromObj\fR -has no need for an \fIinterp\fR argument to record any errors and -the caller can assume \fBTcl_GetByteArrayFromObj\fR does not return NULL. +\fBTcl_GetByteArrayFromObj\fR performs exactly the same function as +\fBTcl_GetBytesFromObj\fR does when called with the \fIinterp\fR +argument passed the value NULL. This is incompatible with the +way \fBTcl_GetByteArrayFromObj\fR functioned in Tcl 8. +\fBTcl_GetBytesFromObj\fR is the more capable interface and should +usually be favored for use over \fBTcl_GetByteArrayFromObj\fR. .PP -\fBTcl_GetByteArrayFromObj\fR must be used with caution. Because of the -truncation on conversion, the byte-array made available to the caller -cannot reliably complete a round-trip back to the original string -representation. This creates opportunities for bugs due to blindness -to differences in values. This routine exists in this form primarily -for compatibility with codebases written for earlier releases of Tcl. -It is expected this routine will incompatibly change in Tcl 9 so that -it also signals failed conversions with a NULL return. -.PP -On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR +On success, both \fBTcl_GetByteFromObj\fR and \fBTcl_GetByteArrayFromObj\fR return a pointer into the internal representation of a \fBTcl_Obj\fR. That pointer must not be freed by the caller, and should not be retained for use beyond the known time the internal representation of the value @@ -154,10 +134,14 @@ and any string representation is invalidated. On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR write the number of bytes in the byte-array value of \fIobjPtr\fR to the space pointed to by \fInumBytesPtr\fR. This space may be of type -\fBsize_t\fR or of type \fBint\fR. In Tcl 8, the largest number of -bytes possible is \fBINT_MAX\fR, so either type can receive the value. -In codebases meant to migrate to Tcl 9, the option to write to a space -of type \fBsize_t\fR may aid in the migration. +\fBsize_t\fR or of type \fBint\fR. It is recommended that callers provide +a \fBsize_t\fR space for this purpose. If the caller provides only +an \fBint\fR space and the number of bytes in the byte-array value of +\fIobjPtr\fR is greater than \fBINT_MAX\fR, the routine will fail due +to being unable to correctly report the byte-array size to the caller. +The ability to provide an \fBint\fR space is best considered a migration +aid for codebases constrained to continue operating with Tcl releases +older than 8.7. .PP \fBTcl_SetByteArrayLength\fR enables a caller to change the size of a byte-array in the internal representation of an unshared \fIobjPtr\fR to @@ -170,8 +154,9 @@ changes the internal representation, \fBTcl_SetByteArrayLength\fR also invalidates any string representation in \fIobjPtr\fR. If resizing grows the byte-array, the new byte values are undefined. If \fIobjPtr\fR does not already possess an internal byte-array, one is produced in the -same way that \fBTcl_GetByteArrayFromObj\fR does, with all the cautions -that go along with that. +same way that \fBTcl_GetBytesFromObj\fR does, also returning NULL +when any characters of the value in \fIobjPtr\fR (up to +\fInumBytes\fR of them) are not valid bytes. .SH "REFERENCE COUNT MANAGEMENT" .PP \fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much diff --git a/doc/CallDel.3 b/doc/CallDel.3 index 33b8afc..00763b6 100644 --- a/doc/CallDel.3 +++ b/doc/CallDel.3 @@ -23,7 +23,7 @@ Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interp Interpreter with which to associated callback. .AP Tcl_InterpDeleteProc *proc in Procedure to call when \fIinterp\fR is deleted. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -38,7 +38,7 @@ type \fBTcl_InterpDeleteProc\fR: .PP .CS typedef void \fBTcl_InterpDeleteProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR); .CE .PP diff --git a/doc/Cancel.3 b/doc/Cancel.3 index 73edaf6..4f727b3 100644 --- a/doc/Cancel.3 +++ b/doc/Cancel.3 @@ -30,7 +30,7 @@ ORed combination of flag bits that specify additional options. For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently supported. For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and \fBTCL_CANCEL_UNWIND\fR are currently supported. -.AP ClientData clientData in +.AP void *clientData in Currently reserved for future use. It should be set to NULL. .BE diff --git a/doc/ChnlStack.3 b/doc/ChnlStack.3 index b046cd2..9233a88 100644 --- a/doc/ChnlStack.3 +++ b/doc/ChnlStack.3 @@ -32,7 +32,7 @@ Tcl_Channel Interpreter for error reporting. .AP "const Tcl_ChannelType" *typePtr in The new channel I/O procedures to use for \fIchannel\fR. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to channel I/O procedures. .AP int mask in Conditions under which \fIchannel\fR will be used: OR-ed combination of @@ -49,11 +49,8 @@ I/O channels. Examples include compression and encryption modules. These functions transparently stack and unstack a new channel on top of an existing one. Any number of channels can be stacked together. .PP -The implementation of the Tcl channel code was rewritten in 8.3.2 to -correct some problems with the previous implementation with regard to -stacked channels. Anyone using stacked channels or creating stacked -channel drivers should update to the new \fBTCL_CHANNEL_VERSION_2\fR -\fBTcl_ChannelType\fR structure. See \fBTcl_CreateChannel\fR for details. +The \fBTcl_ChannelType\fR version currently supported is +\fBTCL_CHANNEL_VERSION_5\fR. See \fBTcl_CreateChannel\fR for details. .PP \fBTcl_StackChannel\fR stacks a new \fIchannel\fR on an existing channel with the same name that was registered for \fIchannel\fR by diff --git a/doc/Class.3 b/doc/Class.3 index c89c5f4..c029595 100644 --- a/doc/Class.3 +++ b/doc/Class.3 @@ -41,12 +41,12 @@ Tcl_Object int \fBTcl_ObjectDeleted\fR(\fIobject\fR) .sp -ClientData +void * \fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR) .sp \fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR) .sp -ClientData +void * \fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR) .sp \fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR) @@ -64,7 +64,7 @@ Tcl_Obj * \fBTcl_GetObjectClassName\fR(\fIinterp\fR, \fIobject\fR) .VE "TIP 605" .SH ARGUMENTS -.AS ClientData metadata in/out +.AS void *metadata in/out .AP Tcl_Interp *interp in/out Interpreter providing the context for looking up or creating an object, and into whose result error messages will be written on failure. @@ -81,11 +81,11 @@ automatically selected. The name of the namespace to create for the object's private use, or NULL if a new unused name is to be automatically selected. The namespace must not already exist. -.AP int objc in +.AP size_t objc in The number of elements in the \fIobjv\fR array. .AP "Tcl_Obj *const" *objv in The arguments to the command to create the instance of the class. -.AP int skip in +.AP size_t skip in The number of arguments at the start of the argument array, \fIobjv\fR, that are not arguments to any constructors. This allows the generation of correct error messages even when complicated calling patterns are used (e.g., via the @@ -93,7 +93,7 @@ error messages even when complicated calling patterns are used (e.g., via the .AP Tcl_ObjectMetadataType *metaTypePtr in The type of \fImetadata\fR being set with \fBTcl_ClassSetMetadata\fR or retrieved with \fBTcl_ClassGetMetadata\fR. -.AP ClientData metadata in +.AP void *metadata in An item of metadata to attach to the class, or NULL to remove the metadata associated with a particular \fImetaTypePtr\fR. .AP "Tcl_ObjectMapMethodNameProc" "methodNameMapper" in @@ -200,7 +200,7 @@ a class or object. .PP .CS typedef void \fBTcl_ObjectMetadataDeleteProc\fR( - ClientData \fImetadata\fR); + void *\fImetadata\fR); .CE .PP The \fImetadata\fR argument gives the address of the metadata to be @@ -213,8 +213,8 @@ associated with a class or object. .CS typedef int \fBTcl_CloneProc\fR( Tcl_Interp *\fIinterp\fR, - ClientData \fIsrcMetadata\fR, - ClientData *\fIdstMetadataPtr\fR); + void *\fIsrcMetadata\fR, + void **\fIdstMetadataPtr\fR); .CE .PP The \fIinterp\fR argument gives a place to write an error message when the diff --git a/doc/Concat.3 b/doc/Concat.3 index e853fc3..10b4a10 100644 --- a/doc/Concat.3 +++ b/doc/Concat.3 @@ -18,7 +18,7 @@ const char * \fBTcl_Concat\fR(\fIargc, argv\fR) .SH ARGUMENTS .AS "const char *const" argv[] -.AP int argc in +.AP size_t argc in Number of strings. .AP "const char *const" argv[] in Array of strings to concatenate. Must have \fIargc\fR entries. diff --git a/doc/CrtAlias.3 b/doc/CrtAlias.3 index 77a3bc2..12494bf 100644 --- a/doc/CrtAlias.3 +++ b/doc/CrtAlias.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands +Tcl_IsSafe, Tcl_CreateChild, Tcl_GetChild, Tcl_GetParent, 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 @@ -16,25 +16,13 @@ Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_Ge int \fBTcl_IsSafe\fR(\fIinterp\fR) .sp -int -\fBTcl_MakeSafe\fR(\fIinterp\fR) -.sp Tcl_Interp * \fBTcl_CreateChild\fR(\fIinterp, name, isSafe\fR) .sp Tcl_Interp * -\fBTcl_CreateSlave\fR(\fIinterp, name, isSafe\fR) -.sp -Tcl_Interp * -\fBTcl_GetSlave\fR(\fIinterp, name\fR) -.sp -Tcl_Interp * \fBTcl_GetChild\fR(\fIinterp, name\fR) .sp Tcl_Interp * -\fBTcl_GetMaster\fR(\fIinterp\fR) -.sp -Tcl_Interp * \fBTcl_GetParent\fR(\fIinterp\fR) .sp int @@ -81,12 +69,12 @@ Name of source command for alias. Interpreter that contains the target command for an alias. .AP "const char" *targetCmd in Name of target command for alias in \fItargetInterp\fR. -.AP int argc in +.AP size_t argc in Count of additional arguments to pass to the alias command. .AP "const char *const" *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 +.AP size_t objc in Count of additional value arguments to pass to the aliased command. .AP Tcl_Obj **objv in Vector of Tcl_Obj structures, the additional value arguments to pass to @@ -142,38 +130,19 @@ child in which Tcl code has access only to set of Tcl commands defined as see the manual entry for the Tcl \fBinterp\fR command for details. If the creation of the new child interpreter failed, \fBNULL\fR is returned. .PP -\fBTcl_CreateSlave\fR is a synonym for \fBTcl_CreateChild\fR. -.PP \fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is .QW safe (was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified), \fB0\fR otherwise. .PP -\fBTcl_MakeSafe\fR marks \fIinterp\fR as -.QW safe , -so that future -calls to \fBTcl_IsSafe\fR will return 1. It also removes all known -potentially-unsafe core functionality (both commands and variables) -from \fIinterp\fR. However, it cannot know what parts of an extension -or application are safe and does not make any attempt to remove those -parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR. -Callers will want to take care with their use of \fBTcl_MakeSafe\fR -to avoid false claims of safety. For many situations, \fBTcl_CreateChild\fR -may be a better choice, since it creates interpreters in a known-safe state. -\fBTcl_MakeSafe\fR is deprecated and will be removed in Tcl 9.0. -.PP \fBTcl_GetChild\fR returns a pointer to a child interpreter of \fIinterp\fR. The child interpreter is identified by \fIname\fR. If no such child interpreter exists, \fBNULL\fR is returned. .PP -\fBTcl_GetSlave\fR is a synonym for \fBTcl_GetChild\fR. -.PP \fBTcl_GetParent\fR returns a pointer to the parent interpreter of \fIinterp\fR. If \fIinterp\fR has no parent (it is a top-level interpreter) then \fBNULL\fR is returned. .PP -\fBTcl_GetMaster\fR is a synonym for \fBTcl_GetParent\fR. -.PP \fBTcl_GetInterpPath\fR stores in the result of \fIinterp\fR the relative path between \fIinterp\fR and \fIchildInterp\fR; \fIchildInterp\fR must be a child of \fIinterp\fR. If the computation diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 1496631..f04fbff 100644 --- a/doc/CrtChannel.3 +++ b/doc/CrtChannel.3 @@ -9,7 +9,7 @@ .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_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels +Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -17,7 +17,7 @@ Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChanne Tcl_Channel \fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR) .sp -ClientData +void * \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR) .sp const Tcl_ChannelType * @@ -80,9 +80,6 @@ Tcl_ChannelTypeVersion Tcl_DriverBlockModeProc * \fBTcl_ChannelBlockModeProc\fR(\fItypePtr\fR) .sp -Tcl_DriverCloseProc * -\fBTcl_ChannelCloseProc\fR(\fItypePtr\fR) -.sp Tcl_DriverClose2Proc * \fBTcl_ChannelClose2Proc\fR(\fItypePtr\fR) .sp @@ -92,9 +89,6 @@ Tcl_DriverInputProc * Tcl_DriverOutputProc * \fBTcl_ChannelOutputProc\fR(\fItypePtr\fR) .sp -Tcl_DriverSeekProc * -\fBTcl_ChannelSeekProc\fR(\fItypePtr\fR) -.sp Tcl_DriverWideSeekProc * \fBTcl_ChannelWideSeekProc\fR(\fItypePtr\fR) .sp @@ -133,7 +127,7 @@ by any other channel. Can be NULL, in which case the channel is created without a name. If the created channel is assigned to one of the standard channels (\fBstdin\fR, \fBstdout\fR or \fBstderr\fR), the assigned channel name will be the name of the standard channel. -.AP ClientData instanceData in +.AP void *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 @@ -144,10 +138,10 @@ The channel to operate on. .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 +.AP void **handlePtr out Points to the location where the desired OS-specific handle should be stored. -.AP int size in +.AP size_t size in The size, in bytes, of buffers to allocate in this channel. .AP int mask in An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR @@ -302,16 +296,13 @@ name is registered in the (thread)-global list of all channels (result (thread)global list of all channels (of the current thread). Application to a channel still registered in some interpreter is not allowed. -Also notifies the driver if the \fBTcl_ChannelType\fR version is -\fBTCL_CHANNEL_VERSION_4\fR (or higher), and +Also notifies the driver if \fBTcl_DriverThreadActionProc\fR is defined for it. .PP \fBTcl_SpliceChannel\fR adds the specified \fIchannel\fR to the (thread)global list of all channels (of the current thread). Application to a channel registered in some interpreter is not allowed. -Also notifies the driver if the \fBTcl_ChannelType\fR version is -\fBTCL_CHANNEL_VERSION_4\fR (or higher), and -\fBTcl_DriverThreadActionProc\fR is defined for it. +Also notifies the driver if \fBTcl_DriverThreadActionProc\fR is defined for it. .PP \fBTcl_ClearChannelHandlers\fR removes all channel handlers and event scripts associated with the specified \fIchannel\fR, thus shutting @@ -331,10 +322,10 @@ The \fBTcl_ChannelType\fR structure contains the following fields: typedef struct Tcl_ChannelType { const char *\fItypeName\fR; Tcl_ChannelTypeVersion \fIversion\fR; - Tcl_DriverCloseProc *\fIcloseProc\fR; + void *\fIcloseProc\fR; /* Not used any more*/ Tcl_DriverInputProc *\fIinputProc\fR; Tcl_DriverOutputProc *\fIoutputProc\fR; - Tcl_DriverSeekProc *\fIseekProc\fR; + void *\fIseekProc\fR; /* Not used any more */ Tcl_DriverSetOptionProc *\fIsetOptionProc\fR; Tcl_DriverGetOptionProc *\fIgetOptionProc\fR; Tcl_DriverWatchProc *\fIwatchProc\fR; @@ -363,9 +354,8 @@ The user should only use the above structure for \fBTcl_ChannelType\fR instantiation. When referencing fields in a \fBTcl_ChannelType\fR structure, the following functions should be used to obtain the values: \fBTcl_ChannelName\fR, \fBTcl_ChannelVersion\fR, -\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelCloseProc\fR, -\fBTcl_ChannelClose2Proc\fR, \fBTcl_ChannelInputProc\fR, -\fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelSeekProc\fR, +\fBTcl_ChannelBlockModeProc\fR, \fBTcl_ChannelClose2Proc\fR, +\fBTcl_ChannelInputProc\fR, \fBTcl_ChannelOutputProc\fR, \fBTcl_ChannelWideSeekProc\fR, \fBTcl_ChannelThreadActionProc\fR, \fBTcl_ChannelTruncateProc\fR, \fBTcl_ChannelSetOptionProc\fR, \fBTcl_ChannelGetOptionProc\fR, @@ -388,25 +378,9 @@ a pointer to the string. .PP The \fIversion\fR field should be set to the version of the structure -that you require. \fBTCL_CHANNEL_VERSION_2\fR is the minimum recommended. -\fBTCL_CHANNEL_VERSION_3\fR must be set to specify the \fIwideSeekProc\fR member. -\fBTCL_CHANNEL_VERSION_4\fR must be set to specify the \fIthreadActionProc\fR member -(includes \fIwideSeekProc\fR). -\fBTCL_CHANNEL_VERSION_5\fR must be set to specify the -\fItruncateProc\fR members (includes -\fIwideSeekProc\fR and \fIthreadActionProc\fR). -If it is not set to any of these, then this -\fBTcl_ChannelType\fR is assumed to have the original structure. See -\fBOLD CHANNEL TYPES\fR for more details. While Tcl will recognize -and function with either structures, stacked channels must be of at -least \fBTCL_CHANNEL_VERSION_2\fR to function correctly. -.PP -This value can be retrieved with \fBTcl_ChannelVersion\fR, which returns -one of -\fBTCL_CHANNEL_VERSION_5\fR, -\fBTCL_CHANNEL_VERSION_4\fR, -\fBTCL_CHANNEL_VERSION_3\fR, -\fBTCL_CHANNEL_VERSION_2\fR or \fBTCL_CHANNEL_VERSION_1\fR. +that you require. \fBTCL_CHANNEL_VERSION_5\fR is the minimum supported. +.PP +This value can be retrieved with \fBTcl_ChannelVersion\fR. .SS BLOCKMODEPROC .PP The \fIblockModeProc\fR field contains the address of a function called by @@ -415,7 +389,7 @@ the generic layer to set blocking and nonblocking mode on the device. .PP .CS typedef int \fBTcl_DriverBlockModeProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, int \fImode\fR); .CE .PP @@ -442,22 +416,23 @@ blocking mode is acceptable to it, and should this also document for the user so that the blocking mode of the channel is not changed to an unacceptable value. Any confusion here may lead the interpreter into a (spurious and difficult to find) deadlock. -.SS "CLOSEPROC AND CLOSE2PROC" +.SS "CLOSE2PROC" .PP -The \fIcloseProc\fR field contains the address of a function called by the +The \fIclose2Proc\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: +closed. \fIClose2Proc\fR must match the following prototype: .PP .CS -typedef int \fBTcl_DriverCloseProc\fR( - ClientData \fIinstanceData\fR, - Tcl_Interp *\fIinterp\fR); +typedef int \fBTcl_DriverClose2Proc\fR( + void *\fIinstanceData\fR, + Tcl_Interp *\fIinterp\fR, + int \fIflags\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 +If \fIflags\fR is 0, 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 @@ -466,35 +441,20 @@ error code. In addition, if an error occurs and \fIinterp\fR is not NULL, the procedure should store an error message in the interpreter's result. .PP Alternatively, channels that support closing the read and write sides -independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set -\fIclose2Proc\fR to the address of a function that matches the -following prototype: -.PP -.CS -typedef int \fBTcl_DriverClose2Proc\fR( - ClientData \fIinstanceData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIflags\fR); -.CE -.PP -The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed +independently may accept other flag values than 0. +Then \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to indicate that the driver should close the read and/or write side of the channel. The channel driver may be invoked to perform additional operations on the channel after \fIclose2Proc\fR is -called to close one or both sides of the channel. If \fIflags\fR is -\fB0\fR (zero), the driver should close the channel in the manner -described above for \fIcloseProc\fR. No further operations will be -invoked on this instance after \fIclose2Proc\fR is called with all -flags cleared. In all cases, the \fIclose2Proc\fR function should -return zero if the close operation was successful; 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 the interpreter's result. -.PP -The \fIcloseProc\fR and \fIclose2Proc\fR values can be retrieved with -\fBTcl_ChannelCloseProc\fR or \fBTcl_ChannelClose2Proc\fR, which -return a pointer to the respective function. +called to close one or both sides of the channel. In all cases, the +\fIclose2Proc\fR function should return zero if the close operation was +successful; 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 the interpreter's result. +.PP +The \fIclose2Proc\fR value can be retrieved with \fBTcl_ChannelClose2Proc\fR, +which returns a pointer to the function. .SS INPUTPROC .PP The \fIinputProc\fR field contains the address of a function called by the @@ -503,7 +463,7 @@ internal buffer. \fIInputProc\fR must match the following prototype: .PP .CS typedef int \fBTcl_DriverInputProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, char *\fIbuf\fR, int \fIbufSize\fR, int *\fIerrorCodePtr\fR); @@ -547,7 +507,7 @@ generic layer to transfer data from an internal buffer to the output device. .PP .CS typedef int \fBTcl_DriverOutputProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, const char *\fIbuf\fR, int \fItoWrite\fR, int *\fIerrorCodePtr\fR); @@ -577,17 +537,17 @@ without writing any data. .PP This value can be retrieved with \fBTcl_ChannelOutputProc\fR, which returns a pointer to the function. -.SS "SEEKPROC AND WIDESEEKPROC" +.SS "WIDESEEKPROC" .PP -The \fIseekProc\fR field contains the address of a function called by the +The \fIwideSeekProc\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 +operations will be applied. \fIWideSeekProc\fR must match the following prototype: .PP .CS -typedef int \fBTcl_DriverSeekProc\fR( - ClientData \fIinstanceData\fR, - long \fIoffset\fR, +typedef long long \fBTcl_DriverWideSeekProc\fR( + void *\fIinstanceData\fR, + long long \fIoffset\fR, int \fIseekMode\fR, int *\fIerrorCodePtr\fR); .CE @@ -606,30 +566,8 @@ does not implement seeking. 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. .PP -If there is a non-NULL \fIseekProc\fR field, the \fIwideSeekProc\fR -field may contain the address of an alternative function to use which -handles wide (i.e. larger than 32-bit) offsets, so allowing seeks -within files larger than 2GB. The \fIwideSeekProc\fR will be called -in preference to the \fIseekProc\fR, but both must be defined if the -\fIwideSeekProc\fR is defined. \fIWideSeekProc\fR must match the -following prototype: -.PP -.CS -typedef long long \fBTcl_DriverWideSeekProc\fR( - ClientData \fIinstanceData\fR, - long long \fIoffset\fR, - int \fIseekMode\fR, - int *\fIerrorCodePtr\fR); -.CE -.PP -The arguments and return values mean the same thing as with -\fIseekProc\fR above, except that the type of offsets and the return -type are different. -.PP -The \fIseekProc\fR value can be retrieved with -\fBTcl_ChannelSeekProc\fR, which returns a pointer to the function, -and similarly the \fIwideSeekProc\fR can be retrieved with -\fBTcl_ChannelWideSeekProc\fR. +The \fIwideSseekProc\fR value can be retrieved with +\fBTcl_ChannelWideSeekProc\fR, which returns a pointer to the function. .SS SETOPTIONPROC .PP The \fIsetOptionProc\fR field contains the address of a function called by @@ -638,7 +576,7 @@ the generic layer to set a channel type specific option on a channel. .PP .CS typedef int \fBTcl_DriverSetOptionProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, Tcl_Interp *\fIinterp\fR, const char *\fIoptionName\fR, const char *\fInewValue\fR); @@ -679,7 +617,7 @@ channel. \fIgetOptionProc\fR must match the following prototype: .PP .CS typedef int \fBTcl_DriverGetOptionProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, Tcl_Interp *\fIinterp\fR, const char *\fIoptionName\fR, Tcl_DString *\fIoptionValue\fR); @@ -717,7 +655,7 @@ notice events of interest on this channel. .PP .CS typedef void \fBTcl_DriverWatchProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, int \fImask\fR); .CE .PP @@ -748,9 +686,9 @@ the generic layer to retrieve a device-specific handle from the channel. .PP .CS typedef int \fBTcl_DriverGetHandleProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, int \fIdirection\fR, - ClientData *\fIhandlePtr\fR); + void **\fIhandlePtr\fR); .CE .PP \fIInstanceData\fR is the same as the value passed to @@ -777,7 +715,7 @@ It should be set to NULL. .PP .CS typedef int \fBTcl_DriverFlushProc\fR( - ClientData \fIinstanceData\fR); + void *\fIinstanceData\fR); .CE .PP This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns @@ -792,7 +730,7 @@ that occur on the underlying (stacked) channel. .PP .CS typedef int \fBTcl_DriverHandlerProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, int \fIinterestMask\fR); .CE .PP @@ -821,7 +759,7 @@ might be maintaining using the calling thread as the associate. See .PP .CS typedef void \fBTcl_DriverThreadActionProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, int \fIaction\fR); .CE .PP @@ -838,7 +776,7 @@ length. It can be NULL. .PP .CS typedef int \fBTcl_DriverTruncateProc\fR( - ClientData \fIinstanceData\fR, + void *\fIinstanceData\fR, long long \fIlength\fR); .CE .PP @@ -886,58 +824,6 @@ The function takes good care of inserting minus signs before each option, commas after, and an .QW or before the last option. -.SH "OLD CHANNEL TYPES" -The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains -the following fields: -.PP -.CS -typedef struct Tcl_ChannelType { - const 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_DriverClose2Proc *\fIclose2Proc\fR; -} \fBTcl_ChannelType\fR; -.CE -.PP -It is still possible to create channel with the above structure. The -internal channel code will determine the version. It is imperative to use -the new \fBTcl_ChannelType\fR structure if you are creating a stacked -channel driver, due to problems with the earlier stacked channel -implementation (in 8.2.0 to 8.3.1). -.PP -Prior to 8.4.0 (i.e. during the later releases of 8.3 and early part -of the 8.4 development cycle) the \fBTcl_ChannelType\fR structure -contained the following fields: -.PP -.CS -typedef struct Tcl_ChannelType { - const char *\fItypeName\fR; - Tcl_ChannelTypeVersion \fIversion\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_DriverClose2Proc *\fIclose2Proc\fR; - Tcl_DriverBlockModeProc *\fIblockModeProc\fR; - Tcl_DriverFlushProc *\fIflushProc\fR; - Tcl_DriverHandlerProc *\fIhandlerProc\fR; - Tcl_DriverTruncateProc *\fItruncateProc\fR; -} \fBTcl_ChannelType\fR; -.CE -.PP -When the above structure is registered as a channel type, the -\fIversion\fR field should always be \fBTCL_CHANNEL_VERSION_2\fR. .SH "SEE ALSO" Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3) .SH KEYWORDS diff --git a/doc/CrtChnlHdlr.3 b/doc/CrtChnlHdlr.3 index 0ecd3c9..ee8b411 100644 --- a/doc/CrtChnlHdlr.3 +++ b/doc/CrtChnlHdlr.3 @@ -29,10 +29,10 @@ Tcl channel such as returned by \fBTcl_CreateChannel\fR. 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 +.AP Tcl_ChannelProc *proc in Procedure to invoke whenever the channel indicated by \fIchannel\fR meets the conditions specified by \fImask\fR. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -48,7 +48,7 @@ what it means for a channel to be readable or writable. .PP .CS typedef void \fBTcl_ChannelProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, int \fImask\fR); .CE .PP diff --git a/doc/CrtCloseHdlr.3 b/doc/CrtCloseHdlr.3 index bac2431..1046ea3 100644 --- a/doc/CrtCloseHdlr.3 +++ b/doc/CrtCloseHdlr.3 @@ -26,7 +26,7 @@ void 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 +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -38,7 +38,7 @@ Arbitrary one-word value to pass to \fIproc\fR. .PP .CS typedef void \fBTcl_CloseProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR is the same as the value provided in the call to diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3 index bf76d48..50baa6f 100644 --- a/doc/CrtCommand.3 +++ b/doc/CrtCommand.3 @@ -25,7 +25,7 @@ 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 +.AP voie *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; @@ -75,7 +75,7 @@ and it returns NULL. .PP .CS typedef int \fBTcl_CmdProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIargc\fR, const char *\fIargv\fR[]); @@ -131,7 +131,7 @@ result that match the type \fBTcl_CmdDeleteProc\fR: .PP .CS typedef void \fBTcl_CmdDeleteProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR argument will be the same as the \fIclientData\fR diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3 index f1b8df7..0dfb429 100644 --- a/doc/CrtFileHdlr.3 +++ b/doc/CrtFileHdlr.3 @@ -29,7 +29,7 @@ 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 +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -51,7 +51,7 @@ type \fBTcl_FileProc\fR: .PP .CS typedef void \fBTcl_FileProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, int \fImask\fR); .CE .PP diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3 deleted file mode 100644 index bb96fc9..0000000 --- a/doc/CrtMathFnc.3 +++ /dev/null @@ -1,166 +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. -'\" -.TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures" -.so man.macros -.BS -.SH NAME -Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and enumerate math functions for expressions -.SH "NOTICE OF EVENTUAL DEPRECATION" -.PP -The \fBTcl_CreateMathFunc\fR and \fBTcl_GetMathFuncInfo\fR functions -are rendered somewhat obsolete by the ability to create functions for -expressions by placing commands in the \fBtcl::mathfunc\fR namespace, -as described in the \fBmathfunc\fR manual page; the API described on -this page is not expected to be maintained indefinitely. -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -void -\fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR) -.sp -int -\fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr, - clientDataPtr\fR) -.sp -Tcl_Obj * -\fBTcl_ListMathFuncs\fR(\fIinterp, pattern\fR) -.SH ARGUMENTS -.AS Tcl_ValueType *clientDataPtr out -.AP Tcl_Interp *interp in -Interpreter in which new function will be defined. -.AP "const 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. -.AP int *numArgsPtr out -Points to a variable that will be set to contain the number of -arguments to the function. -.AP Tcl_ValueType **argTypesPtr out -Points to a variable that will be set to contain a pointer to an array -giving the permissible types for each argument to the function which -will need to be freed up using \fITcl_Free\fR. -.AP Tcl_MathProc **procPtr out -Points to a variable that will be set to contain a pointer to the -implementation code for the function (or NULL if the function is -implemented directly in bytecode). -.AP ClientData *clientDataPtr out -Points to a variable that will be set to contain the clientData -argument passed to \fITcl_CreateMathFunc\fR when the function was -created if the function is not implemented directly in bytecode. -.AP "const char" *pattern in -Pattern to match against function names so as to filter them (by -passing to \fITcl_StringMatch\fR), or NULL to not apply any filter. -.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. -These functions are represented by commands in the namespace, -\fBtcl::mathfunc\fR. The \fBTcl_CreateMathFunc\fR function is -an obsolete way for applications to add additional functions -to those already provided by Tcl or to replace existing functions. -It should not be used by new applications, which should create -math functions using \fBTcl_CreateObjCommand\fR to create a command -in the \fBtcl::mathfunc\fR namespace. -.PP -In the \fBTcl_CreateMathFunc\fR interface, -\fIName\fR is the name of the function as it will appear in expressions. -If \fIname\fR does not already exist in the \fB::tcl::mathfunc\fR -namespace, then a new command is created in that namespace. -If \fIname\fR 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 -one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR, \fBTCL_WIDE_INT\fR, -or \fBTCL_EITHER\fR to indicate whether the corresponding argument must be an -integer, a double-precision floating value, a wide (64-bit) integer, -or any, 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: -.PP -.CS -typedef int \fBTcl_MathProc\fR( - 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: -.PP -.CS -typedef struct Tcl_Value { - Tcl_ValueType \fItype\fR; - long \fIintValue\fR; - double \fIdoubleValue\fR; - Tcl_WideInt \fIwideValue\fR; -} \fBTcl_Value\fR; -.CE -.PP -The \fItype\fR field indicates the type of the argument and is -one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR. -It will match the \fIargTypes\fR value specified for the function unless -the \fIargTypes\fR value was \fBTCL_EITHER\fR. 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, -\fIdoubleValue\fR or \fIwideValue\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 one of -\fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR -to indicate which value was set. -Under normal circumstances \fIproc\fR should return \fBTCL_OK\fR. -If an error occurs while executing the function, \fIproc\fR should -return \fBTCL_ERROR\fR and leave an error message in the interpreter's result. -.PP -\fBTcl_GetMathFuncInfo\fR retrieves the values associated with -function \fIname\fR that were passed to a preceding -\fBTcl_CreateMathFunc\fR call. Normally, the return code is -\fBTCL_OK\fR but if the named function does not exist, \fBTCL_ERROR\fR -is returned and an error message is placed in the interpreter's -result. -.PP -If an error did not occur, the array reference placed in the variable -pointed to by \fIargTypesPtr\fR is newly allocated, and should be -released by passing it to \fBTcl_Free\fR. Some functions (the -standard set implemented in the core, and those defined by placing -commands in the \fBtcl::mathfunc\fR namespace) do not have -argument type information; attempting to retrieve values for -them causes a NULL to be stored in the variable pointed to by -\fIprocPtr\fR and the variable pointed to by \fIclientDataPtr\fR -will not be modified. The variable pointed to by \fInumArgsPointer\fR -will contain -1, and no argument types will be stored in the variable -pointed to by \fIargTypesPointer\fR. -.PP -\fBTcl_ListMathFuncs\fR returns a Tcl value containing a list of all -the math functions defined in the interpreter whose name matches -\fIpattern\fR. The returned value has a reference count of zero. -.SH "REFERENCE COUNT MANAGEMENT" -.PP -\fBTcl_ListMathFuncs\fR always returns a zero-reference object, much -like \fBTcl_NewObj\fR. -.SH "SEE ALSO" -expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3) -.SH KEYWORDS -expression, mathematical function diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index 0490bd7..ffd9e27 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -58,7 +58,7 @@ Implementation of the new command: \fIproc\fR will be called whenever .AP Tcl_ObjCmdProc2 *proc2 in Implementation of the new command: \fIproc2\fR will be called whenever \fIcmdName\fR is invoked as a command. -.AP ClientData clientData in +.AP void *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; @@ -101,7 +101,7 @@ and it returns NULL. .PP .CS typedef int \fBTcl_ObjCmdProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[]); @@ -174,7 +174,7 @@ result that match the type \fBTcl_CmdDeleteProc\fR: .PP .CS typedef void \fBTcl_CmdDeleteProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR argument will be the same as the \fIclientData\fR @@ -185,7 +185,7 @@ except its \fIproc2\fR argument is of type \fBTcl_ObjCmdProc2\fR. .PP .CS typedef int \fBTcl_ObjCmdProc2\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, size_t \fIobjc\fR, Tcl_Obj *const \fIobjv\fR[]); @@ -224,24 +224,29 @@ pointed to by \fIinfoPtr\fR and returns 1. A \fBTcl_CmdInfo\fR structure has the following fields: .PP .CS -typedef struct Tcl_CmdInfo { +typedef struct { int \fIisNativeObjectProc\fR; Tcl_ObjCmdProc *\fIobjProc\fR; - ClientData \fIobjClientData\fR; + void *\fIobjClientData\fR; Tcl_CmdProc *\fIproc\fR; - ClientData \fIclientData\fR; + void *\fIclientData\fR; Tcl_CmdDeleteProc *\fIdeleteProc\fR; - ClientData \fIdeleteData\fR; + void *\fIdeleteData\fR; Tcl_Namespace *\fInamespacePtr\fR; + Tcl_ObjCmdProc2 *\fIobjProc2\fR; + void *\fIobjClientData2\fR; } \fBTcl_CmdInfo\fR; .CE .PP -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. +The \fIisNativeObjectProc\fR field has the value 2 if +\fBTcl_CreateObjCommand2\fR was called to register the command; +it 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 +call \fIobjProc2\fR, \fIobjProc\fR or \fIproc\fR: +\fIobjProc2\fR/\fIobjProc\fR is normally faster +if \fIisNativeObjectProc\fR has the value 2; +\fIobjProc\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 @@ -257,7 +262,7 @@ otherwise, this is a compatibility procedure registered by \fBTcl_CreateObjCommand\fR that simply calls the command's value-based procedure after converting its string arguments to Tcl values. -The field \fIdeleteData\fR is the ClientData value +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. @@ -271,7 +276,7 @@ from \fBTcl_CreateObjCommand\fR in place of the command name. If the and fills in the structure designated by \fIinfoPtr\fR. .PP \fBTcl_SetCommandInfo\fR is used to modify the procedures and -ClientData values associated with a command. +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. @@ -287,9 +292,9 @@ copies the information from \fI*infoPtr\fR to Tcl's internal structure for the command and returns 1. .PP Note that \fBTcl_SetCommandInfo\fR and -\fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a +\fBTcl_SetCommandInfoFromToken\fR both allow the clientData for a command's deletion procedure to be given a different value than the -ClientData for its command procedure. +clientData for its command procedure. .PP Note that neither \fBTcl_SetCommandInfo\fR nor \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace. diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3 index c229a23..1190417 100644 --- a/doc/CrtTimerHdlr.3 +++ b/doc/CrtTimerHdlr.3 @@ -24,7 +24,7 @@ Tcl_TimerToken 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 +.AP void *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 @@ -51,7 +51,7 @@ the type \fBTcl_TimerProc\fR: .PP .CS typedef void \fBTcl_TimerProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR parameter to \fIproc\fR is a diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3 index 723a392..e4d1a43 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -29,7 +29,7 @@ Tcl_Trace .AS Tcl_CmdObjTraceDeleteProc *deleteProc .AP Tcl_Interp *interp in Interpreter containing command to be traced or untraced. -.AP int level in +.AP size_t level in Only commands at or below this nesting level will be traced unless 0 is specified. 1 means top-level commands only, 2 means top-level commands or those that are @@ -97,7 +97,7 @@ typedef int \fBTcl_CmdObjTraceProc2\fR( .PP 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 +\fIclientData\fR typically points to an application-specific data structure that describes what to do when \fIobjProc\fR is invoked. The \fIlevel\fR parameter gives the nesting level of the command (1 for top-level commands passed to \fBTcl_Eval\fR by the application, 2 for diff --git a/doc/DString.3 b/doc/DString.3 index 66323a7..5c4d8f4 100644 --- a/doc/DString.3 +++ b/doc/DString.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings +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 @@ -26,7 +26,7 @@ char * .sp \fBTcl_DStringEndSublist\fR(\fIdsPtr\fR) .sp -int +size_t \fBTcl_DStringLength\fR(\fIdsPtr\fR) .sp char * @@ -34,8 +34,6 @@ char * .sp \fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR) .sp -\fBTcl_DStringTrunc\fR(\fIdsPtr, newLength\fR) -.sp \fBTcl_DStringFree\fR(\fIdsPtr\fR) .sp \fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR) @@ -53,10 +51,10 @@ Pointer to structure that is used to manage a dynamic string. Pointer to characters to append to dynamic string. .AP "const char" *element in Pointer to characters to append as list element to dynamic string. -.AP int length in -Number of bytes from \fIbytes\fR to add to dynamic string. If -1, +.AP size_t length in +Number of bytes from \fIbytes\fR to add to dynamic string. If TCL_INDEX_NONE, add all characters up to null terminating character. -.AP int newLength in +.AP size_t newLength in New length for dynamic string, not including null terminating character. .AP Tcl_Interp *interp in/out @@ -132,10 +130,6 @@ caller to fill in the new space. even if the string is truncated to zero length, so \fBTcl_DStringFree\fR will still need to be called. .PP -\fBTcl_DStringTrunc\fR changes the length of a dynamic string. -This procedure is now deprecated. \fBTcl_DStringSetLength\fR should -be used instead. -.PP \fBTcl_DStringFree\fR should be called when you are 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. diff --git a/doc/DetachPids.3 b/doc/DetachPids.3 index 26075c3..c4d6fa7 100644 --- a/doc/DetachPids.3 +++ b/doc/DetachPids.3 @@ -22,7 +22,7 @@ Tcl_Pid \fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR) .SH ARGUMENTS .AS Tcl_Pid *statusPtr out -.AP int numPids in +.AP size_t 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. diff --git a/doc/DictObj.3 b/doc/DictObj.3 index 0b4c1ca..ebff7bf 100644 --- a/doc/DictObj.3 +++ b/doc/DictObj.3 @@ -70,7 +70,7 @@ Points to a variable that will have the value from a key/value pair placed within it. For \fBTcl_DictObjFirst\fR and \fBTcl_DictObjNext\fR, this may be NULL to indicate that the caller is not interested in the value. -.AP int *sizePtr out +.AP "size_t \&| int" *sizePtr out Points to a variable that will have the number of key/value pairs contained within the dictionary placed within it. .AP Tcl_DictSearch *searchPtr in/out @@ -84,7 +84,7 @@ returned, the search record \fImust\fR be passed to Points to a variable that will have a non-zero value written into it when the enumeration of the key/value pairs in a dictionary has completed, and a zero otherwise. -.AP int keyc in +.AP size_t keyc in Indicates the number of keys that will be supplied in the \fIkeyv\fR array. .AP "Tcl_Obj *const" *keyv in @@ -138,7 +138,8 @@ converted to a dictionary. \fBTcl_DictObjSize\fR updates the given variable with the number of key/value pairs currently in the given dictionary. The result of this procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be -converted to a dictionary. +converted to a dictionary or if \fIsizePtr\fR points to a variable of type +\fBint\fR and the dict contains more than 2**31 key/value pairs. .PP \fBTcl_DictObjFirst\fR commences an iteration across all the key/value pairs in the given dictionary, placing the key and value in the diff --git a/doc/DoWhenIdle.3 b/doc/DoWhenIdle.3 index cfdbff9..1a252cc 100644 --- a/doc/DoWhenIdle.3 +++ b/doc/DoWhenIdle.3 @@ -21,7 +21,7 @@ Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pendi .AS Tcl_IdleProc clientData .AP Tcl_IdleProc *proc in Procedure to invoke. -.AP ClientData clientData in +.AP coid *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -43,7 +43,7 @@ type \fBTcl_IdleProc\fR: .PP .CS typedef void \fBTcl_IdleProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR diff --git a/doc/DumpActiveMemory.3 b/doc/DumpActiveMemory.3 index 226209a..0e162bb 100644 --- a/doc/DumpActiveMemory.3 +++ b/doc/DumpActiveMemory.3 @@ -43,7 +43,7 @@ is not defined, these functions are all no-ops. \fBTcl_DumpActiveMemory\fR will output a list of all currently allocated memory to the specified file. The information output for each allocated block of memory is: starting and ending addresses -(excluding guard zone), size, source file where \fBckalloc\fR was +(excluding guard zone), size, source file where \fBTcl_Alloc\fR was called to allocate the block and line number in that file. It is especially useful to call \fBTcl_DumpActiveMemory\fR after the Tcl interpreter has been deleted. @@ -55,8 +55,8 @@ by \fBTcl_Main\fR. \fBTcl_ValidateAllMemory\fR forces a validation of the guard zones of all currently allocated blocks of memory. Normally validation of a block occurs when its freed, unless full validation is enabled, in -which case validation of all blocks occurs when \fBckalloc\fR and -\fBckfree\fR are called. This function forces the validation to occur +which case validation of all blocks occurs when \fBTcl_Alloc\fR and +\fBTcl_Free\fR are called. This function forces the validation to occur at any point. .SH "SEE ALSO" diff --git a/doc/Encoding.3 b/doc/Encoding.3 index 9b88c11..7b5e9d4 100644 --- a/doc/Encoding.3 +++ b/doc/Encoding.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings +Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath \- procedures for creating and using encodings .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -25,13 +25,13 @@ int char * \fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR) .sp -int +size_t \fBTcl_ExternalToUtfDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR) .sp char * \fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR) .sp -int +size_t \fBTcl_UtfToExternalDStringEx\fR(\fIencoding, src, srcLen, flags, dstPtr\fR) .sp int @@ -42,16 +42,10 @@ int \fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR) .sp -char * -\fBTcl_WinTCharToUtf\fR(\fItsrc, srcLen, dstPtr\fR) -.sp -TCHAR * -\fBTcl_WinUtfToTChar\fR(\fIsrc, srcLen, dstPtr\fR) -.sp const char * \fBTcl_GetEncodingName\fR(\fIencoding\fR) .sp -int +size_t \fBTcl_GetEncodingNulLength\fR(\fIencoding\fR) .sp int @@ -71,12 +65,6 @@ Tcl_Obj * .sp int \fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR) -.sp -const char * -\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR) -.sp -void -\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR) .SH ARGUMENTS .AS "const Tcl_EncodingType" *dstWrotePtr in/out .AP Tcl_Interp *interp in @@ -94,11 +82,11 @@ Points to storage where encoding token is to be written. .AP "const char" *src in For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the specified encoding that are to be converted to UTF-8. For the -\fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of +\fBTcl_UtfToExternal\fR function, an array of UTF-8 characters to be converted to the specified encoding. .AP "const TCHAR" *tsrc in An array of Windows TCHAR characters to convert to UTF-8. -.AP int srcLen in +.AP size_t srcLen in Length of \fIsrc\fR or \fItsrc\fR in bytes. If the length is negative, the encoding-specific length of the string is used. .AP Tcl_DString *dstPtr out @@ -114,15 +102,15 @@ converted. \fBTCL_ENCODING_END\fR signifies that the source buffer is the last block in a (potentially multi-block) input stream, telling the conversion routine to perform any finalization that needs to occur after the last byte is converted and then to reset to an initial state. -\fBTCL_ENCODING_STOPONERROR\fR signifies that the conversion routine should -return immediately upon reading a source character that does not exist in -the target encoding; otherwise a default fallback character will -automatically be substituted. The flag \fBTCL_ENCODING_STRICT\fR makes the +\fBTCL_ENCODING_NOCOMPLAIN\fR signifies that the conversion routine should +not return immediately upon reading a source character that does not exist in +the target encoding, but it will substitute a default fallback character for +all of such characters. The flag \fBTCL_ENCODING_STOPONERROR\fR has no effect, +it only has meaning in Tcl 8.x. The flag \fBTCL_ENCODING_STRICT\fR makes the encoder/decoder more strict in what it considers to be an invalid byte -sequence. The flag \fBTCL_ENCODING_NOCOMPLAIN\fR has -no effect, it is reserved for Tcl 9.0. The flag \fBTCL_ENCODING_MODIFIED\fR makes -\fBTcl_UtfToExternalDStringEx\fR and \fBTcl_UtfToExternal\fR produce the -byte sequence \exC0\ex80 in stead of \ex00, for the utf-8/cesu-8 encoders. +sequence. The flag \fBTCL_ENCODING_MODIFIED\fR makes +\fBTcl_UtfToExternalDStringEx\fR and \fBTcl_UtfToExternal\fR produce the byte +sequence \exC0\ex80 in stead of \ex00, for the utf-8/cesu-8 encoders. .AP Tcl_EncodingState *statePtr in/out Used when converting a (generally long or indefinite length) byte stream in a piece-by-piece fashion. The conversion routine stores its current @@ -253,7 +241,7 @@ if the input stream has been damaged or if the input encoding method was misidentified. .IP \fBTCL_CONVERT_UNKNOWN\fR 29 The source buffer contained a character that could not be represented in -the target encoding and \fBTCL_ENCODING_STOPONERROR\fR was specified. +the target encoding and \fBTCL_ENCODING_NOCOMPLAIN\fR was not specified. .RE .LP \fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from UTF-8 @@ -279,18 +267,6 @@ is filled with the corresponding number of bytes that were stored in \fIdst\fR. The return values are the same as the return values for \fBTcl_ExternalToUtf\fR. .PP -\fBTcl_WinUtfToTChar\fR and \fBTcl_WinTCharToUtf\fR are Windows-only -convenience functions for converting between UTF-8 and Windows strings -based on the TCHAR type which is by convention a Unicode character on -Windows NT. Those functions are deprecated. You can use -\fBTcl_UtfToWCharDString\fR resp. \fBTcl_WCharToUtfDString\fR as replacement. -If you want compatibility with earlier Tcl releases than 8.7, use -\fBTcl_UtfToUniCharDString\fR resp. \fBTcl_UniCharToUtfDString\fR as -replacement, and make sure you compile your extension with -DTCL_UTF_MAX=3. -Beware: Those replacement functions don't initialize their Tcl_DString (you'll -have to do that yourself), and \fBTcl_UniCharToUtfDString\fR from Tcl 8.6 -doesn't accept -1 as length parameter. -.PP \fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR. Given an \fIencoding\fR, the return value is the \fIname\fR argument that was used to create the encoding. The string returned by @@ -320,7 +296,7 @@ the encoding name to it. The \fBTcl_DStringValue\fR is returned. \fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list consisting of the names of all the encodings that are currently defined or can be dynamically loaded, searching the encoding path specified by -\fBTcl_SetDefaultEncodingDir\fR. This procedure does not ensure that the +\fBTcl_SetEncodingSearchPath\fR. This procedure does not ensure that the dynamically-loadable encoding files contain valid data, but merely that they exist. .PP @@ -348,7 +324,7 @@ typedef struct Tcl_EncodingType { Tcl_EncodingConvertProc *\fIfromUtfProc\fR; Tcl_EncodingFreeProc *\fIfreeProc\fR; void *\fIclientData\fR; - int \fInullSize\fR; + size_t \fInullSize\fR; } \fBTcl_EncodingType\fR; .CE .PP @@ -435,15 +411,6 @@ are not verified as existing readable filesystem directories. When searching for encoding data files takes place, and non-existent or non-readable filesystem directories on the \fIsearchPath\fR are silently ignored. -.PP -\fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR -are obsolete interfaces best replaced with calls to -\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR. -They are called to access and set the first element of the \fIsearchPath\fR -list. Since Tcl searches \fIsearchPath\fR for encoding data files in -list order, these routines establish the -.QW default -directory in which to find encoding data files. .SH "ENCODING FILES" Space would prohibit precompiling into Tcl every possible encoding algorithm, so many encodings are stored on disk as dynamically-loadable @@ -10,7 +10,7 @@ .so man.macros .BS .SH NAME -Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts +Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval \- execute Tcl scripts .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -38,9 +38,6 @@ int .sp int \fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *) NULL\fR) -.sp -int -\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR) .SH ARGUMENTS .AS Tcl_Interp **termPtr .AP Tcl_Interp *interp in @@ -53,7 +50,7 @@ ORed combination of flag bits that specify additional options. \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported. .AP "const char" *fileName in Name of a file containing a Tcl script. -.AP int objc in +.AP size_t objc in The number of values in the array pointed to by \fIobjv\fR; this is also the number of words in the command. .AP Tcl_Obj **objv in @@ -67,9 +64,6 @@ first null byte are used. Points to first byte of script to execute (null-terminated and UTF-8). .AP "const char" *part in String forming part of a Tcl script. -.AP va_list argList in -An argument list which must have been initialized using -\fBva_start\fR, and cleared using \fBva_end\fR. .BE .SH DESCRIPTION @@ -126,16 +120,10 @@ might be a UTF-8 special code. The string is parsed and executed directly bytecodes. In situations where it is known that the script will never be executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR. \fBTcl_Eval\fR returns a completion code and result just like -\fBTcl_EvalObjEx\fR. Note: for backward compatibility with versions before -Tcl 8.0, \fBTcl_Eval\fR copies the value result in \fIinterp\fR to -\fIinterp->result\fR (use is deprecated) where it can be accessed directly. - This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which -does not do the copy. +\fBTcl_EvalObjEx\fR. .PP \fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes -additional arguments \fInumBytes\fR and \fIflags\fR. For the -efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred -over \fBTcl_Eval\fR. +additional arguments \fInumBytes\fR and \fIflags\fR. .PP \fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures that are now deprecated. They are similar to \fBTcl_EvalEx\fR and @@ -151,11 +139,6 @@ It returns the result of the command and also modifies the interpreter result in the same way as \fBTcl_Eval\fR. The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end of arguments. \fBTcl_VarEval\fR is now deprecated. -.PP -\fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that -instead of taking a variable number of arguments it takes an argument -list. Interfaces using argument lists have been found to be nonportable -in practice. This function is deprecated and will be removed in Tcl 9.0. .SH "FLAG BITS" .PP @@ -42,7 +42,7 @@ usually means that an error occurred. Procedure to invoke before exiting application, or (for \fBTcl_SetExitProc\fR) NULL to uninstall the current application exit procedure. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE @@ -64,7 +64,7 @@ otherwise causes the application to terminate without calling returns control to its caller. If an application exit handler has been installed (see \fBTcl_SetExitProc\fR), that handler is invoked with an argument -consisting of the exit status (cast to ClientData); the application +consisting of the exit status (cast to void *); the application exit handler should not return control to Tcl. .PP \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not @@ -93,7 +93,7 @@ and freeing global memory. .PP .CS typedef void \fBTcl_ExitProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR parameter to \fIproc\fR is a @@ -133,10 +133,9 @@ installed, that exit handler takes over complete responsibility for finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an appropriate time. The argument passed to \fIproc\fR when it is invoked will be the exit status code (as passed to \fBTcl_Exit\fR) -cast to a ClientData value. +cast to a void *value. .PP -\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions. Its symbol -entry in the stub table is deprecated and it will be removed in Tcl 9.0. +\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions. .SH "SEE ALSO" exit(n) .SH KEYWORDS diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index e7cc4ab..469af22 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -20,7 +20,7 @@ int int \fBTcl_FSUnregister\fR(\fIfsPtr\fR) .sp -ClientData +void * \fBTcl_FSData\fR(\fIfsPtr\fR) .sp void @@ -123,7 +123,7 @@ Tcl_Obj * int \fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR) .sp -ClientData +void * \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR) .sp Tcl_Obj * @@ -210,7 +210,7 @@ this structure will be returned. This parameter may be NULL. .AP Tcl_Interp *interp in Interpreter to use either for results, evaluation, or reporting error messages. -.AP ClientData clientData in +.AP void *clientData in The native description of the path value to create. .AP Tcl_Obj *firstPtr in The first of two path values to compare. The value may be converted @@ -220,9 +220,9 @@ The second of two path values to compare. The value may be converted to \fBpath\fR type. .AP Tcl_Obj *listObj in The list of path elements to operate on with a \fBjoin\fR operation. -.AP int elements in -If non-negative, the number of elements in the \fIlistObj\fR which should -be joined together. If negative, then all elements are joined. +.AP size_t elements in +The number of elements in the \fIlistObj\fR which should +be joined together. If TCL_INDEX_NONE, then all elements are joined. .AP Tcl_Obj **errorPtr out In the case of an error, filled with a value containing the name of the file which caused an error in the various copy/rename operations. @@ -251,7 +251,7 @@ Name of a procedure to look up in the file's symbol table Filled with the init function for this code. .AP Tcl_LibraryInitProc **proc2Ptr out Filled with the safe-init function for this code. -.AP ClientData *clientDataPtr out +.AP void **clientDataPtr out Filled with the clientData value to pass to this code's unload function when it is called. .AP Tcl_LoadHandle *loadHandlePtr out @@ -269,11 +269,11 @@ allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. .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 *lenPtr out +.AP "size_t \&| int" *lenPtr out If non-NULL, filled with the number of elements in the split path. .AP Tcl_Obj *basePtr in The base path on to which to join the given elements. May be NULL. -.AP int objc in +.AP size_t objc in The number of elements in \fIobjv\fR. .AP "Tcl_Obj *const" objv[] in The elements to join to the given base path. @@ -720,7 +720,7 @@ better functions to use for most purposes. \fBTcl_FSGetTranslatedStringPath\fR does the same as \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL. The string returned is dynamically allocated and owned by the caller, -which must store it or call \fBckfree\fR to ensure it is freed. Again, +which must store it or call \fBTcl_Free\fR to ensure it is freed. Again, \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually better functions to use for most purposes. .PP @@ -787,7 +787,7 @@ It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or .SS "PORTABLE STAT RESULT API" .PP \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system heap (which -may be deallocated by being passed to \fBckfree\fR). This allows extensions to +may be deallocated by being passed to \fBTcl_Free\fR). This allows extensions to invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the size of the buffer. That in turn depends on the flags used to build Tcl. .PP @@ -835,7 +835,7 @@ general that is not a good thing to do). \fBTCL_OK\fR will be returned. the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If the filesystem is not currently registered, \fBTCL_ERROR\fR is returned. .PP -\fBTcl_FSData\fR will return the ClientData associated with the given +\fBTcl_FSData\fR will return the clientData associated with the given filesystem, if that filesystem is registered. Otherwise it will return NULL. .PP @@ -850,7 +850,7 @@ The \fBTcl_Filesystem\fR structure contains the following fields: .CS typedef struct Tcl_Filesystem { const char *\fItypeName\fR; - int \fIstructureLength\fR; + size_t \fIstructureLength\fR; Tcl_FSVersion \fIversion\fR; Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR; Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR; @@ -1012,7 +1012,7 @@ Tcl's internal list of known filesystems. .CS typedef int \fBTcl_FSPathInFilesystemProc\fR( Tcl_Obj *\fIpathPtr\fR, - ClientData *\fIclientDataPtr\fR); + void **\fIclientDataPtr\fR); .CE .SS DUPINTERNALREPPROC .PP @@ -1022,8 +1022,8 @@ simply not copy the internal representation, which may then need to be regenerated later. .PP .CS -typedef ClientData \fBTcl_FSDupInternalRepProc\fR( - ClientData \fIclientData\fR); +typedef void *\fBTcl_FSDupInternalRepProc\fR( + void *\fIclientData\fR); .CE .SS FREEINTERNALREPPROC Free the internal representation. This must be implemented if internal @@ -1032,7 +1032,7 @@ internal representation is generated), but may otherwise be NULL. .PP .CS typedef void \fBTcl_FSFreeInternalRepProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .SS INTERNALTONORMALIZEDPROC .PP @@ -1043,7 +1043,7 @@ representation is the normalized path. .PP .CS typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .SS CREATEINTERNALREPPROC .PP @@ -1054,7 +1054,7 @@ the \fITcl_FSPathInFilesystemProc\fR for this filesystem always immediately creates an internal representation for paths it accepts. .PP .CS -typedef ClientData \fBTcl_FSCreateInternalRepProc\fR( +typedef void *\fBTcl_FSCreateInternalRepProc\fR( Tcl_Obj *\fIpathPtr\fR); .CE .SS NORMALIZEPATHPROC diff --git a/doc/FindExec.3 b/doc/FindExec.3 index 7f8c8a4..eed296c 100644 --- a/doc/FindExec.3 +++ b/doc/FindExec.3 @@ -35,8 +35,8 @@ 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 -The result of \fBTcl_FindExecutable\fR is the full Tcl version (e.g., -\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR). +The result of \fBTcl_FindExecutable\fR is the full Tcl version with +build information (e.g., \fB9.0.0+abcdef...abcdef.gcc-1002\fR). .PP On UNIX platforms this procedure is typically invoked as the very first thing in the application's main program; it must be passed @@ -62,7 +62,6 @@ equivalent to the \fBinfo nameofexecutable\fR command. NULL is returned if the internal full path name has not been computed or unknown. .PP -\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions. Its symbol -entry in the stub table is deprecated and it will be removed in Tcl 9.0. +\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions. .SH KEYWORDS binary, executable file diff --git a/doc/GetInt.3 b/doc/GetInt.3 index f15c12d..1e8cd61 100644 --- a/doc/GetInt.3 +++ b/doc/GetInt.3 @@ -71,12 +71,9 @@ if the first such characters are then \fIsrc\fR is expected to be in octal form; otherwise, if the first such characters are .QW \fB0b\fR -then \fIsrc\fR is expected to be in binary form; otherwise, -if the first such character is -.QW \fB0\fR then \fIsrc\fR -is expected to be in octal form; otherwise, \fIsrc\fR -is expected to be in decimal form. +is expected to be in binary form; otherwise, \fIsrc\fR is +expected to be in decimal form. .PP \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point number, which is: white space; a sign; a sequence of digits; a diff --git a/doc/GetOpnFl.3 b/doc/GetOpnFl.3 index a450b02..5ac5391 100644 --- a/doc/GetOpnFl.3 +++ b/doc/GetOpnFl.3 @@ -28,7 +28,7 @@ be used for reading. .AP int checkUsage in If non-zero, then an error will be generated if the file was not opened for the access indicated by \fIwrite\fR. -.AP ClientData *filePtr out +.AP void **filePtr out Points to word in which to store pointer to FILE structure for the file given by \fIchanID\fR. .BE diff --git a/doc/GetTime.3 b/doc/GetTime.3 index 9dc4056..4aa8442 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -27,13 +27,13 @@ Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS. .AP Tcl_ScaleTimeProc scaleProc in Pointer to handler function for the conversion of time delays in the virtual domain to real-time. -.AP ClientData clientData in +.AP void *clientData in Value passed through to the two handler functions. .AP Tcl_GetTimeProc *getProcPtr out Pointer to place the currently registered get handler function into. .AP Tcl_ScaleTimeProc *scaleProcPtr out Pointer to place the currently registered scale handler function into. -.AP ClientData *clientDataPtr out +.AP void **clientDataPtr out Pointer to place the currently registered pass-through value into. .BE .SH DESCRIPTION @@ -83,10 +83,10 @@ The signatures of the handler functions are as follows: .CS typedef void \fBTcl_GetTimeProc\fR( Tcl_Time *\fItimebuf\fR, - ClientData \fIclientData\fR); + void *\fIclientData\fR); typedef void \fBTcl_ScaleTimeProc\fR( Tcl_Time *\fItimebuf\fR, - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fItimebuf\fR fields contain the time to manipulate, and the diff --git a/doc/GetVersion.3 b/doc/GetVersion.3 index 3672382..b973044 100644 --- a/doc/GetVersion.3 +++ b/doc/GetVersion.3 @@ -15,14 +15,13 @@ Tcl_GetVersion \- get the version of the library at runtime .sp \fBTcl_GetVersion\fR(\fImajor, minor, patchLevel, type\fR) .SH ARGUMENTS -.AS Tcl_ReleaseType *patchLevel out .AP int *major out Major version number of the Tcl library. .AP int *minor out Minor version number of the Tcl library. .AP int *patchLevel out The patch level of the Tcl library (or alpha or beta number). -.AP Tcl_ReleaseType *type out +.AP int *type out The type of release, also indicates the type of patch level. Can be one of \fBTCL_ALPHA_RELEASE\fR, \fBTCL_BETA_RELEASE\fR, or \fBTCL_FINAL_RELEASE\fR. @@ -30,7 +30,7 @@ Tcl_HashEntry * Tcl_HashEntry * \fBTcl_FindHashEntry\fR(\fItablePtr, key\fR) .sp -ClientData +void * \fBTcl_GetHashValue\fR(\fIentryPtr\fR) .sp \fBTcl_SetHashValue\fR(\fIentryPtr, value\fR) @@ -66,9 +66,8 @@ 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 void *value in +New value to assign to hash table entry. .AP Tcl_HashSearch *searchPtr in Pointer to record to use to keep track of progress in enumerating all the entries in a hash table. @@ -186,11 +185,6 @@ 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 -.QW 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 @@ -229,7 +223,7 @@ 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 \fBckfree\fR. +by passing it to \fBTcl_Free\fR. .PP The header file \fBtcl.h\fR defines the actual data structures used to implement hash tables. @@ -2,7 +2,7 @@ '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" -.TH Tcl_Init 3 8.7 Tcl "Tcl Library Procedures" +.TH Tcl_Init 3 9.0 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -39,6 +39,10 @@ The pre-initialization script is executed by \fBTcl_Init\fR before accessing the file system. The purpose is to typically prepare a custom file system (like an embedded zip-file) to be activated before the search. +When used in stub-enabled embedders, the stubs table must be first initialized +using one of \fBTcl_InitSubsystems\fR, \fBTcl_SetPanicProc\fR, \fBTcl_FindExecutable\fR +or \fBTclZipfs_AppHook\fR before \fBTcl_SetPreInitScript\fR may be called. + .SH "SEE ALSO" Tcl_AppInit, Tcl_Main diff --git a/doc/InitStubs.3 b/doc/InitStubs.3 index 4423666..20105fe 100644 --- a/doc/InitStubs.3 +++ b/doc/InitStubs.3 @@ -63,9 +63,9 @@ Define the \fBUSE_TCL_STUBS\fR symbol. Typically, you would include the \fB\-DUSE_TCL_STUBS\fR flag when compiling the extension. .IP 3) 5 Link the extension with the Tcl stubs library instead of the standard -Tcl library. For example, to use the Tcl 8.6 ABI on Unix platforms, -the library name is \fIlibtclstub8.6.a\fR; on Windows platforms, the -library name is \fItclstub86.lib\fR. +Tcl library. For example, to use the Tcl 9.0 ABI on Unix platforms, +the library name is \fIlibtclstub9.0.a\fR; on Windows platforms, the +library name is \fItclstub90.lib\fR. .PP If the extension also requires the Tk API, it must also call \fBTk_InitStubs\fR to initialize the Tk stubs interface and link diff --git a/doc/InitSubSyst.3 b/doc/InitSubSyst.3 index 89f2b88..b7962c6 100644 --- a/doc/InitSubSyst.3 +++ b/doc/InitSubSyst.3 @@ -21,14 +21,14 @@ The \fBTcl_InitSubsystems\fR procedure initializes the Tcl library. This procedure is typically invoked as the very first thing in the application's main program. .PP -The result of \fBTcl_InitSubsystems\fR is the full Tcl version (e.g., -\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR). +The result of \fBTcl_InitSubsystems\fR is the full Tcl version with +build information (e.g., \fB9.0.0+abcdef...abcdef.gcc-1002\fR). .PP \fBTcl_InitSubsystems\fR is very similar in use to \fBTcl_FindExecutable\fR. It can be used when Tcl is -used as utility library, no other encodings than utf8, +used as utility library, no other encodings than utf-8, iso8859-1 or utf-16 are used, and no interest exists in the value of \fBinfo nameofexecutable\fR. The system encoding will not -be extracted from the environment, but falls back to iso8859-1. +be extracted from the environment, but falls back to utf-8. .SH KEYWORDS binary, executable file diff --git a/doc/IntObj.3 b/doc/IntObj.3 index 18d867e..d2954c8 100644 --- a/doc/IntObj.3 +++ b/doc/IntObj.3 @@ -32,7 +32,7 @@ int \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR) .sp int -\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR) +\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, indexPtr\fR) .sp int \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR) @@ -61,7 +61,7 @@ int \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR) .SH ARGUMENTS .AS Tcl_WideInt doubleValue in/out -.AP int endValue in +.AP size_t endValue in \fBTcl_GetIntForIndex\fR will return this when the input value is "end". .AP int intValue in Integer value used to initialize or set a Tcl value. @@ -83,6 +83,8 @@ retrieval fails. Points to place to store the integer value retrieved from \fIobjPtr\fR. .AP long *longPtr out Points to place to store the long integer value retrieved from \fIobjPtr\fR. +.AP size_t *indexPtr out +Points to place to store the size_t value retrieved from \fIobjPtr\fR. .AP Tcl_WideInt *widePtr out Points to place to store the wide integer value retrieved from \fIobjPtr\fR. .AP Tcl_WideUInt *uwidePtr out diff --git a/doc/Interp.3 b/doc/Interp.3 deleted file mode 100644 index c1b9803..0000000 --- a/doc/Interp.3 +++ /dev/null @@ -1,41 +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. -'\" -.TH Tcl_Interp 3 8.7 Tcl "Tcl Library Procedures" -.so man.macros -.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; /* NO LONGER AVAILABLE */ - Tcl_FreeProc *\fIfreeProc\fR; /* NO LONGER AVAILABLE */ - int \fIerrorLine\fR; /* NO LONGER AVAILABLE */ -} \fBTcl_Interp\fR; - -typedef void \fBTcl_FreeProc\fR( - char *\fIblockPtr\fR); -.BE -.SH DESCRIPTION -.PP -The \fBTcl_CreateInterp\fR procedure returns a pointer to a \fBTcl_Interp\fR -structure. Callers of \fBTcl_CreateInterp\fR should use this pointer -as an opaque token, suitable for nothing other than passing back to -other routines in the Tcl interface from the same thread that called -\fBTcl_CreateInterp\fR. The \fBTcl_Interp\fR struct no longer has any -supported client-visible fields. Supported public routines such as -\fBTcl_SetResult\fR, \fBTcl_GetResult\fR, \fBTcl_SetErrorLine\fR, -\fBTcl_GetErrorLine\fR must be used instead. -.PP -Any legacy programs and extensions trying to access the fields above -in their source code will need conversion to compile for Tcl 8.7 and later. - -.SH KEYWORDS -interpreter, result diff --git a/doc/Limit.3 b/doc/Limit.3 index 3d202fc..43e92f0 100644 --- a/doc/Limit.3 +++ b/doc/Limit.3 @@ -65,7 +65,7 @@ its limits checked. .AP int type in 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 +.AP size_t commandLimit in The maximum number of commands (as reported by \fBinfo cmdcount\fR) that may be executed in the interpreter. .AP Tcl_Time *timeLimitPtr in/out @@ -83,7 +83,7 @@ the handler returns. Many handlers may be attached to the same interpreter limit; their order of execution is not defined, and they must be identified by \fIhandlerProc\fR and \fIclientData\fR when they are deleted. -.AP ClientData clientData in +.AP void *clientData in Arbitrary pointer-sized word used to pass some context to the \fIhandlerProc\fR function. .AP Tcl_LimitHandlerDeleteProc *deleteProc in @@ -162,7 +162,7 @@ following prototype: .PP .CS typedef void \fBTcl_LimitHandlerProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR); .CE .PP @@ -179,7 +179,7 @@ following prototype: .PP .CS typedef void \fBTcl_LimitHandlerDeleteProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the diff --git a/doc/LinkVar.3 b/doc/LinkVar.3 index f5e97b4..f7ce3a3 100644 --- a/doc/LinkVar.3 +++ b/doc/LinkVar.3 @@ -59,7 +59,7 @@ In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and All the above for both functions may be optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl variable read-only. -.AP int size in +.AP size_t size in .VS "TIP 312" The number of elements in the C array. Must be greater than zero. .VE "TIP 312" @@ -263,7 +263,7 @@ Tcl errors. . The C variable is of type \fBchar *\fR. If its value is not NULL then it must be a pointer to a string -allocated with \fBTcl_Alloc\fR or \fBckalloc\fR. +allocated with \fBTcl_Alloc\fR. Whenever the Tcl variable is modified the current C string will be freed and new memory will be allocated to hold a copy of the variable's new value. diff --git a/doc/ListObj.3 b/doc/ListObj.3 index c5c1dc7..a0ed5c9 100644 --- a/doc/ListObj.3 +++ b/doc/ListObj.3 @@ -59,13 +59,13 @@ points to the Tcl value that will be appended to \fIlistPtr\fR. For \fBTcl_SetListObj\fR, this points to the Tcl value that will be converted to a list value containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR. -.AP int *objcPtr in +.AP "size_t \&| int" *objcPtr in Points to location where \fBTcl_ListObjGetElements\fR stores the number of element values 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 values of \fIlistPtr\fR. -.AP int objc in +.AP size_t objc in The number of Tcl values that \fBTcl_NewListObj\fR will insert into a new list value, and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR. @@ -76,21 +76,21 @@ An array of pointers to values. \fBTcl_NewListObj\fR will insert these values into a new list value and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR. Each value will become a separate list element. -.AP int *lengthPtr out +.AP "size_t \&| int" *lengthPtr out Points to location where \fBTcl_ListObjLength\fR stores the length of the list. -.AP int index in +.AP size_t 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 value. -.AP int first in +.AP size_t 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 +.AP size_t count in The number of elements that \fBTcl_ListObjReplace\fR is to replace. .BE @@ -153,7 +153,9 @@ address \fIobjcPtr\fR. Similarly, it returns the array pointer by storing it in the address \fIobjvPtr\fR. The memory pointed to is managed by Tcl and should not be freed or written to by the caller. If the list is empty, 0 is stored at \fIobjcPtr\fR -and NULL at \fIobjvPtr\fR. +and NULL at \fIobjvPtr\fR. If \fIobjcPtr\fR points to a variable +of type \fBint\fR and the list contains more than 2**31 elements, the +function returns \fBTCL_ERROR\fR. If \fIlistPtr\fR is not already a list value, \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 @@ -162,7 +164,9 @@ 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 value referenced by \fIlistPtr\fR. -It returns this count by storing an integer in the address \fIlengthPtr\fR. +It returns this count by storing a value in the address \fIlengthPtr\fR. +If \fIlengthPtr\fR points to a variable of type \fBint\fR and the list +contains more than 2**31 elements, the function returns \fBTCL_ERROR\fR. If the value is not already a list value, \fBTcl_ListObjLength\fR will attempt to convert it to one; if the conversion fails, it returns \fBTCL_ERROR\fR @@ -180,7 +184,7 @@ if the conversion fails, it returns \fBTCL_ERROR\fR and leaves an error message in the interpreter's result value if \fIinterp\fR is not NULL. If the index is out of range, -that is, \fIindex\fR is negative or +that is, \fIindex\fR is TCL_INDEX_NONE 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. @@ -199,13 +203,13 @@ and leaves an error message in the interpreter's result value if \fIinterp\fR is not NULL. Otherwise, it returns \fBTCL_OK\fR after replacing the values. If \fIobjv\fR is NULL, no new elements are added. -If the argument \fIfirst\fR is zero or negative, +If the argument \fIfirst\fR is zero or TCL_INDEX_NONE, 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; +If \fIcount\fR is zero or TCL_INDEX_NONE 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 diff --git a/doc/Method.3 b/doc/Method.3 index 577cd54..c3a6b64 100644 --- a/doc/Method.3 +++ b/doc/Method.3 @@ -58,10 +58,10 @@ Tcl_Method Tcl_Object \fBTcl_ObjectContextObject\fR(\fIcontext\fR) .sp -int +size_t \fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR) .SH ARGUMENTS -.AS ClientData clientData in +.AS void *clientData in .AP Tcl_Interp *interp in/out The interpreter holding the object or class to create or update a method in. .AP Tcl_Object object in @@ -83,10 +83,10 @@ and \fBTCL_OO_METHOD_PRIVATE\fR for a private method. .AP Tcl_MethodType *methodTypePtr in A description of the type of the method to create, or the type of method to compare against. -.AP ClientData clientData in +.AP void *clientData in A piece of data that is passed to the implementation of the method without interpretation. -.AP ClientData *clientDataPtr out +.AP void **clientDataPtr out A pointer to a variable in which to write the \fIclientData\fR value supplied when the method was created. If NULL, the \fIclientData\fR value will not be retrieved. @@ -95,11 +95,11 @@ A reference to a method to query. .AP Tcl_ObjectContext context in A reference to a method-call context. Note that client code \fImust not\fR retain a reference to a context. -.AP int objc in +.AP size_t objc in The number of arguments to pass to the method implementation. .AP "Tcl_Obj *const" *objv in An array of arguments to pass to the method implementation. -.AP int skip in +.AP size_t skip in The number of arguments passed to the method implementation that do not represent "real" arguments. .BE @@ -213,7 +213,7 @@ Functions matching this signature are called when the method is invoked. .PP .CS typedef int \fBTcl_MethodCallProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, Tcl_ObjectContext \fIobjectContext\fR, int \fIobjc\fR, @@ -234,7 +234,7 @@ through a new method being created or because the object or class is deleted. .PP .CS typedef void \fBTcl_MethodDeleteProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as @@ -248,8 +248,8 @@ class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR). .CS typedef int \fBTcl_CloneProc\fR( Tcl_Interp *\fIinterp\fR, - ClientData \fIoldClientData\fR, - ClientData *\fInewClientDataPtr\fR); + void *\fIoldClientData\fR, + void **\fInewClientDataPtr\fR); .CE .PP The \fIinterp\fR argument gives a place to write an error message when the @@ -63,13 +63,13 @@ in the same way as the \fIproc2\fR argument to \fBTcl_CreateObjCommand2\fR(3) Called instead of \fIproc\fR when a trampoline is already in use. .AP Tcl_ObjCmdProc2 *nreProc2 in Called instead of \fIproc2\fR when a trampoline is already in use. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR and \fIobjProc\fR. .AP Tcl_CmdDeleteProc *deleteProc in/out Called before \fIcmdName\fR is deleted from the interpreter, allowing for command-specific cleanup. May be NULL. -.AP int objc in +.AP size_t objc in Number of items in \fIobjv\fR. .AP Tcl_Obj **objv in Words in the command. @@ -86,10 +86,10 @@ Pointer to an unshared Tcl_Obj where the result of the evaluation is stored if the return code is TCL_OK. .AP Tcl_NRPostProc *postProcPtr in A function to push. -.AP ClientData data0 in -.AP ClientData data1 in -.AP ClientData data2 in -.AP ClientData data3 in +.AP void *data0 in +.AP void *data1 in +.AP void *data2 in +.AP void *data3 in \fIdata0\fR through \fIdata3\fR are four one-word values that will be passed to the function designated by \fIpostProcPtr\fR when it is invoked. .BE @@ -147,7 +147,7 @@ a message as the interpreter's result. .CS typedef int \fBTcl_NRPostProc\fR( - \fBClientData\fR \fIdata\fR[], + \fBvoid *\fR \fIdata\fR[], \fBTcl_Interp\fR *\fIinterp\fR, int \fIresult\fR); .CE @@ -163,7 +163,7 @@ stack, to evalute a script: .CS int \fITheCmdOldObjProc\fR( - ClientData clientData, + void *clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) @@ -194,7 +194,7 @@ call \fITheCmdNRObjProc\fR: .CS int \fITheCmdOldObjProc\fR( - ClientData clientData, + void *clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) @@ -207,7 +207,7 @@ int .CS int \fITheCmdNRObjProc\fR - ClientData clientData, + void *clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) @@ -228,7 +228,7 @@ int .CS int \fITheCmdNRPostProc\fR( - ClientData data[], + void *data[], Tcl_Interp *interp, int result) { diff --git a/doc/Namespace.3 b/doc/Namespace.3 index 49b772c..c4c893a 100644 --- a/doc/Namespace.3 +++ b/doc/Namespace.3 @@ -57,7 +57,7 @@ The interpreter in which the namespace exists and where name lookups are performed. Also where error result messages are written. .AP "const char" *name in The name of the namespace or command to be created or accessed. -.AP ClientData clientData in +.AP void *clientData in A context pointer by the creator of the namespace. Not interpreted by Tcl at all. .AP Tcl_NamespaceDeleteProc *deleteProc in @@ -117,7 +117,7 @@ the global namespace.) .PP .CS typedef void \fBTcl_NamespaceDeleteProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP \fBTcl_DeleteNamespace\fR deletes a namespace, calling the diff --git a/doc/Notifier.3 b/doc/Notifier.3 index 7cb02f6..e01abc4 100644 --- a/doc/Notifier.3 +++ b/doc/Notifier.3 @@ -38,7 +38,7 @@ Tcl_ThreadId void \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR) .sp -ClientData +void * \fBTcl_InitNotifier\fR() .sp void @@ -78,7 +78,7 @@ Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR. 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 +.AP void *clientData in Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or \fIdeleteProc\fR. .AP "const Tcl_Time" *timePtr in @@ -89,7 +89,7 @@ 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. +have been allocated by the caller using \fBTcl_Alloc\fR. .AP int position in Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, \fBTCL_QUEUE_HEAD\fR, \fBTCL_QUEUE_MARK\fR, and whether to do @@ -226,7 +226,7 @@ the event source. .PP .CS typedef void \fBTcl_EventSetupProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, int \fIflags\fR); .CE .PP @@ -304,7 +304,7 @@ following prototype: .PP .CS typedef void \fBTcl_EventCheckProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, int \fIflags\fR); .CE .PP @@ -399,7 +399,7 @@ of window events. 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) +the event source (using \fBTcl_Alloc\fR) before calling \fBTcl_QueueEvent\fR, but it will be freed by \fBTcl_ServiceEvent\fR, not by the event source. .PP @@ -424,7 +424,7 @@ queue. \fIProc\fR should match the following prototype: .CS typedef int \fBTcl_EventDeleteProc\fR( Tcl_Event *\fIevPtr\fR, - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .PP The \fIclientData\fR argument will be the same as the \fIclientData\fR diff --git a/doc/Object.3 b/doc/Object.3 index 2099552..91ee397 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -111,9 +111,9 @@ which is defined as follows. .PP .CS typedef struct Tcl_Obj { - int \fIrefCount\fR; + size_t \fIrefCount\fR; char *\fIbytes\fR; - int \fIlength\fR; + size_t \fIlength\fR; const Tcl_ObjType *\fItypePtr\fR; union { long \fIlongValue\fR; diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index 7e3cc12..3e6d0c2 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.3 @@ -109,6 +109,7 @@ typedef struct Tcl_ObjType { Tcl_DupInternalRepProc *\fIdupIntRepProc\fR; Tcl_UpdateStringProc *\fIupdateStringProc\fR; Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR; + size_t \fIversion\fR; } \fBTcl_ObjType\fR; .CE .SS "THE NAME FIELD" @@ -184,8 +185,8 @@ to be treated as conventional null character-terminated C strings. These restrictions are easily met by using Tcl's internal UTF encoding for the string representation, same as one would do for other Tcl routines accepting string values as arguments. -Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR -or \fBckalloc\fR. Note that \fIupdateStringProc\fRs must allocate +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. .PP The \fIupdateStringProc\fR for Tcl's built-in double type, for example, @@ -253,6 +254,10 @@ Note that if a subsidiary value has its reference count reduced to zero during the running of a \fIfreeIntRepProc\fR, that value may be not freed immediately, in order to limit stack usage. However, the value will be freed before the outermost current \fBTcl_DecrRefCount\fR returns. +.SS "THE VERSION FIELD" +.PP +The \fIversion\fR member provides for future extensibility of the structure +and should be set to \fITCL_OBJTYPE_V0\fR. .SH "REFERENCE COUNT MANAGEMENT" .PP The \fIobjPtr\fR argument to \fBTcl_AppendAllObjTypes\fR should be an unshared diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index e8ed521..1b9d5d3 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -53,28 +53,28 @@ int int \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR) .sp -int +size_t \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) .sp -int +size_t \fBTcl_Gets\fR(\fIchannel, lineRead\fR) .sp -int +size_t \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR) .sp -int +size_t \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR) .sp -int +size_t \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR) .sp -int +size_t \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR) .sp -int +size_t \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR) .sp -int +size_t \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR) .sp int @@ -119,7 +119,7 @@ allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. .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 +.AP size_t argc in The number of elements in \fIargv\fR. .AP "const char" **argv in Arguments for constructing a command pipeline. These values have the same @@ -134,7 +134,7 @@ input of the invoking process; likewise for \fBTCL_STDOUT\fR and redirect stdio handles to override the stdio handles for which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. If it is set, then such redirections cause an error. -.AP ClientData handle in +.AP void *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 @@ -154,7 +154,7 @@ from a procedure such as \fBTcl_OpenFileChannel\fR. .AP Tcl_Obj *readObjPtr in/out A pointer to a Tcl value in which to store the characters read from the channel. -.AP int charsToRead in +.AP size_t charsToRead in The number of characters to read from the channel. If the channel's encoding is \fBbinary\fR, this is equivalent to the number of bytes to read from the channel. @@ -163,7 +163,7 @@ If non-zero, data read from the channel will be appended to the value. Otherwise, the data will replace the existing contents of the value. .AP char *readBuf out A buffer in which to store the bytes read from the channel. -.AP int bytesToRead in +.AP size_t bytesToRead in The number of bytes to read from the channel. The buffer \fIreadBuf\fR must be large enough to hold this many bytes. .AP Tcl_Obj *lineObjPtr in/out @@ -176,7 +176,7 @@ channel. Must have been initialized by the caller. The line read will be appended to any data already in the dynamic string. .AP "const char" *input in The input to add to a channel buffer. -.AP int inputLen in +.AP size_t inputLen in Length of the input .AP int addAtEnd in Flag indicating whether the input should be added to the end or @@ -187,7 +187,7 @@ A pointer to a Tcl value whose contents will be output to the channel. A buffer containing the characters to output to the channel. .AP "const char" *byteBuf in A buffer containing the bytes to output to the channel. -.AP int bytesToWrite in +.AP size_t bytesToWrite in The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and output to the channel. .AP "long long" offset in diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3 index ca26b59..5a0f559 100644 --- a/doc/OpenTcp.3 +++ b/doc/OpenTcp.3 @@ -52,12 +52,12 @@ Length of OS listen backlog queue. Use -1 for default value. .AP "unsigned int" flags in ORed combination of \fBTCL_TCPSERVER\fR flags that specify additional informations about the socket being created. -.AP ClientData sock in +.AP void *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 +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -129,7 +129,7 @@ the channel. \fIProc\fR must match the following prototype: .PP .CS typedef void \fBTcl_TcpAcceptProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Channel \fIchannel\fR, char *\fIhostName\fR, int \fIport\fR); diff --git a/doc/Panic.3 b/doc/Panic.3 index bd019db..e8a5cb8 100644 --- a/doc/Panic.3 +++ b/doc/Panic.3 @@ -7,7 +7,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort +Tcl_Panic, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -15,9 +15,6 @@ Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error void \fBTcl_Panic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR) .sp -void -\fBTcl_PanicVA\fR(\fIformat\fR, \fIargList\fR) -.sp const char * \fBTcl_SetPanicProc\fR(\fIpanicProc\fR) .sp @@ -82,15 +79,14 @@ making calls into the Tcl library, or into other libraries that may call the Tcl library, since the original call to \fBTcl_Panic\fR indicates the Tcl library is not in a state of reliable operation. .PP -The result of \fBTcl_SetPanicProc\fR is the full Tcl version (e.g., -\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR). +The result of \fBTcl_SetPanicProc\fR is the full Tcl version with build +information (e.g., \fB9.0.0+abcdef...abcdef.gcc-1002\fR). .PP The typical use of \fBTcl_SetPanicProc\fR arranges for the error message to be displayed or reported in a manner more suitable for the application or the platform. .PP -\fBTcl_SetPanicProc\fR can not be used in stub-enabled extensions. Its symbol -entry in the stub table is deprecated and it will be removed in Tcl 9.0. +\fBTcl_SetPanicProc\fR can not be used in stub-enabled extensions. .PP Although the primary callers of \fBTcl_Panic\fR are the procedures of the Tcl library, \fBTcl_Panic\fR is a public function and may be called @@ -98,10 +94,6 @@ by any extension or application that wishes to abort the process and have a panic message displayed the same way that panic messages from Tcl will be displayed. .PP -\fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of -taking a variable number of arguments it takes an argument list. Interfaces -using argument lists have been found to be nonportable in practice. This -function is deprecated and will be removed in Tcl 9.0. .SH "SEE ALSO" abort(3), printf(3), exec(n), format(n) .SH KEYWORDS diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3 index f29f161..6a5184f 100644 --- a/doc/ParseArgs.3 +++ b/doc/ParseArgs.3 @@ -21,7 +21,7 @@ int Where to store error messages. .AP "const Tcl_ArgvInfo" *argTable in Pointer to array of option descriptors. -.AP int *objcPtr in/out +.AP "size_t \&| int" *objcPtr in/out A pointer to variable holding number of arguments in \fIobjv\fR. Will be modified to hold number of arguments left in the unprocessed argument list stored in \fIremObjv\fR. @@ -31,7 +31,7 @@ The array of arguments to be parsed. Pointer to a variable that will hold the array of unprocessed arguments. Should be NULL if no return of unprocessed arguments is required. If \fIobjcPtr\fR is updated to a non-zero value, the array returned through this -must be deallocated using \fBckfree\fR. +must be deallocated using \fBTcl_Free\fR. .BE .SH DESCRIPTION .PP @@ -84,7 +84,7 @@ typedef struct { void *\fIsrcPtr\fR; void *\fIdstPtr\fR; const char *\fIhelpStr\fR; - ClientData \fIclientData\fR; + void *\fIclientData\fR; } \fBTcl_ArgvInfo\fR; .CE .PP @@ -127,7 +127,7 @@ have the following signature: .PP .CS typedef int (\fBTcl_ArgvFuncProc\fR)( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Obj *\fIobjPtr\fR, void *\fIdstPtr\fR); .CE @@ -149,7 +149,7 @@ function will have the following signature: .PP .CS typedef int (\fBTcl_ArgvGenFuncProc\fR)( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIobjc\fR, Tcl_Obj *const *\fIobjv\fR, diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index 03b97f7..5235325 100644 --- a/doc/ParseCmd.3 +++ b/doc/ParseCmd.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokens, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions +Tcl_ParseCommand, Tcl_ParseExpr, Tcl_ParseBraces, Tcl_ParseQuotedString, Tcl_ParseVarName, Tcl_ParseVar, Tcl_FreeParse, Tcl_EvalTokensStandard \- parse Tcl scripts and expressions .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -33,23 +33,19 @@ const char * .sp \fBTcl_FreeParse\fR(\fIusedParsePtr\fR) .sp -Tcl_Obj * -\fBTcl_EvalTokens\fR(\fIinterp, tokenPtr, numTokens\fR) -.sp int \fBTcl_EvalTokensStandard\fR(\fIinterp, tokenPtr, numTokens\fR) .SH ARGUMENTS .AS Tcl_Interp *usedParsePtr out .AP Tcl_Interp *interp out -For procedures other than \fBTcl_FreeParse\fR, \fBTcl_EvalTokens\fR -and \fBTcl_EvalTokensStandard\fR, used only for error reporting; +For procedures other than \fBTcl_FreeParse\fR and +\fBTcl_EvalTokensStandard\fR, used only for error reporting; if NULL, then no error messages are left after errors. -For \fBTcl_EvalTokens\fR and \fBTcl_EvalTokensStandard\fR, -determines the context for evaluating the -script and also is used for error reporting; must not be NULL. +For \fBTcl_EvalTokensStandard\fR, determines the context for evaluating +the script and also is used for error reporting; must not be NULL. .AP "const char" *start in Pointer to first character in string to parse. -.AP int numBytes in +.AP size_t numBytes in Number of bytes in string to parse, not including any terminating null character. If less than 0 then the script consists of all characters following \fIstart\fR up to the first null character. @@ -191,17 +187,6 @@ code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, some other integer value originating in an extension. In addition, a result value or error message is left in \fIinterp\fR's result; it can be retrieved using \fBTcl_GetObjResult\fR. -.SS "DEPRECATED FUNCTIONS" -.PP -\fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in -the return convention used: it returns the result in a new Tcl_Obj. -The reference count of the value returned as result has been -incremented, so the caller must -invoke \fBTcl_DecrRefCount\fR when it is finished with the value. -If an error or other exception occurs while evaluating the tokens -(such as a reference to a non-existent variable) then the return value -is NULL and an error message is left in \fIinterp\fR's result. The use -of \fBTcl_EvalTokens\fR is deprecated. .SH "TCL_PARSE STRUCTURE" .PP \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, @@ -211,20 +196,20 @@ return parse information in two data structures, Tcl_Parse and Tcl_Token: .CS typedef struct Tcl_Parse { const char *\fIcommentStart\fR; - int \fIcommentSize\fR; + size_t \fIcommentSize\fR; const char *\fIcommandStart\fR; - int \fIcommandSize\fR; - int \fInumWords\fR; + size_t \fIcommandSize\fR; + size_t \fInumWords\fR; Tcl_Token *\fItokenPtr\fR; - int \fInumTokens\fR; + size_t \fInumTokens\fR; ... } \fBTcl_Parse\fR; typedef struct Tcl_Token { int \fItype\fR; const char *\fIstart\fR; - int \fIsize\fR; - int \fInumComponents\fR; + size_t \fIsize\fR; + size_t \fInumComponents\fR; } \fBTcl_Token\fR; .CE .PP @@ -464,12 +449,5 @@ There are additional fields in the Tcl_Parse structure after the \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR, \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be referenced by code outside of these procedures. -.SH "REFERENCE COUNT MANAGEMENT" -.PP -The result of \fBTcl_EvalTokens\fR is an unshared value with a reference count -of 1; the caller of that function should call \fBTcl_DecrRefCount\fR on the -result value to dispose of it. (The equivalent with -\fBTcl_EvalTokenStandard\fR is just the interpreter result, which can be -retrieved with \fBTcl_GetObjResult\fR.) .SH KEYWORDS backslash substitution, braces, command, expression, parse, token, variable substitution diff --git a/doc/PkgRequire.3 b/doc/PkgRequire.3 index 77e73f1..8932135 100644 --- a/doc/PkgRequire.3 +++ b/doc/PkgRequire.3 @@ -55,7 +55,7 @@ Pointer to place to store the value associated with the matching package. It is only changed if the pointer is not NULL and the function completed successfully. The storage can be any pointer type with the same size as a void pointer. -.AP int objc in +.AP size_t objc in Number of requirements. .AP Tcl_Obj* objv[] in Array of requirements. diff --git a/doc/Preserve.3 b/doc/Preserve.3 index c8f34a2..eb50a5f 100644 --- a/doc/Preserve.3 +++ b/doc/Preserve.3 @@ -21,7 +21,7 @@ Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it \fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR) .SH ARGUMENTS .AS Tcl_FreeProc clientData -.AP ClientData clientData in +.AP void *clientData in Token describing structure to be freed or reallocated. Usually a pointer to memory for structure. .AP Tcl_FreeProc *freeProc in @@ -91,7 +91,7 @@ reasons, but the value is the same. .PP When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR refers to storage allocated and returned by a prior call to -\fBTcl_Alloc\fR, \fBckalloc\fR, or another function of the Tcl library, +\fBTcl_Alloc\fR or another function of the Tcl library, then the \fIfreeProc\fR argument should be given the special value of \fBTCL_DYNAMIC\fR. .PP diff --git a/doc/PrintDbl.3 b/doc/PrintDbl.3 index 896b6eb..42b258c 100644 --- a/doc/PrintDbl.3 +++ b/doc/PrintDbl.3 @@ -18,10 +18,7 @@ Tcl_PrintDouble \- Convert floating value to string .SH ARGUMENTS .AS Tcl_Interp *interp out .AP Tcl_Interp *interp in -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. +This argument is ignored. .AP double value in Floating-point value to be converted. .AP char *dst out @@ -41,9 +38,7 @@ so that it does not look like an integer. Where \fB%g\fR would generate an integer with no decimal point, \fBTcl_PrintDouble\fR adds .QW .0 . .PP -If the \fBtcl_precision\fR value is non-zero, the result will have -precisely that many digits of significance. If the value is zero -(the default), the result will have the fewest digits needed to +The result will have the fewest digits needed to represent the number in such a way that \fBTcl_NewDoubleObj\fR will generate the same number when presented with the given string. IEEE semantics of rounding to even apply to the conversion. diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3 index e68f4b5..0835904 100644 --- a/doc/RecEvalObj.3 +++ b/doc/RecEvalObj.3 @@ -31,7 +31,7 @@ the command at global level instead of the current stack level. .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_EvalObjEx\fR +on the history list and then execute it using \fBTcl_EvalObjEx\fR. It returns a completion code such as \fBTCL_OK\fR just like \fBTcl_EvalObjEx\fR, as well as a result value containing additional information (a result value or error message) diff --git a/doc/RegExp.3 b/doc/RegExp.3 index 40429c9..86c3a55 100644 --- a/doc/RegExp.3 +++ b/doc/RegExp.3 @@ -64,7 +64,7 @@ identifies the beginning of the larger string. If it is not the same as \fItext\fR, then no .QW \fB^\fR matches will be allowed. -.AP int index in +.AP size_t 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. @@ -80,14 +80,14 @@ OR-ed combination of the compilation flags \fBTCL_REG_ADVANCED\fR, \fBTCL_REG_QUOTE\fR, \fBTCL_REG_NOCASE\fR, \fBTCL_REG_NEWLINE\fR, \fBTCL_REG_NLSTOP\fR, \fBTCL_REG_NLANCH\fR, \fBTCL_REG_NOSUB\fR, and \fBTCL_REG_CANMATCH\fR. See below for more information. -.AP int offset in +.AP size_t offset in The character offset into the text where matching should begin. The value of the offset has no impact on \fB^\fR matches. This behavior is controlled by \fIeflags\fR. -.AP int nmatches in +.AP size_t nmatches in The number of matching subexpressions that should be remembered for later use. If this value is 0, then no subexpression match -information will be computed. If the value is \-1, then +information will be computed. If the value is TCL_INDEX_NONE, then all of the matching subexpressions will be remembered. Any other value will be taken as the maximum number of subexpressions to remember. @@ -337,9 +337,9 @@ defined as follows: .PP .CS typedef struct Tcl_RegExpInfo { - int \fInsubs\fR; + size_t \fInsubs\fR; Tcl_RegExpIndices *\fImatches\fR; - long \fIextendStart\fR; + size_t \fIextendStart\fR; } \fBTcl_RegExpInfo\fR; .CE .PP @@ -355,8 +355,8 @@ follows: .PP .CS typedef struct Tcl_RegExpIndices { - long \fIstart\fR; - long \fIend\fR; + size_t \fIstart\fR; + size_t \fIend\fR; } \fBTcl_RegExpIndices\fR; .CE .PP diff --git a/doc/SaveInterpState.3 b/doc/SaveInterpState.3 index 804f9ec..da70c4d 100644 --- a/doc/SaveInterpState.3 +++ b/doc/SaveInterpState.3 @@ -6,12 +6,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures" +.TH Tcl_SaveInterpState 3 8.1 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME -Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, -Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- Save and restore the +Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState \- Save and restore the state of an an interpreter. .SH SYNOPSIS .nf @@ -24,12 +23,6 @@ int \fBTcl_RestoreInterpState\fR(\fIinterp, state\fR) .sp \fBTcl_DiscardInterpState\fR(\fIstate\fR) -.sp -\fBTcl_SaveResult\fR(\fIinterp, savedPtr\fR) -.sp -\fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR) -.sp -\fBTcl_DiscardResult\fR(\fIsavedPtr\fR) .SH ARGUMENTS .AS Tcl_InterpState savedPtr .AP Tcl_Interp *interp in @@ -38,8 +31,6 @@ The interpreter for the operation. The return code for the state. .AP Tcl_InterpState state in A token for saved state. -.AP Tcl_SavedResult *savedPtr in -A pointer to storage for saved state. .BE .SH DESCRIPTION .PP @@ -59,27 +50,5 @@ returns the \fIstatus\fR originally passed in the corresponding call to If a saved state is not restored, \fBTcl_DiscardInterpState\fR must be called to release it. A token used to discard or restore state must not be used again. -.PP -\fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, and \fBTcl_DiscardResult\fR are -deprecated. Instead use \fBTcl_SaveInterpState\fR, -\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR, which are more -capable. -.PP -\fBTcl_SaveResult\fR moves the result of \fIinterp\fR to the location -\fIstatePtr\fR points to and returns the interpreter result to its initial -state. It does not save options such as \fB\-errorcode\fR or -\fB\-errorinfo\fR. -.PP -\fBTcl_RestoreResult\fR clears any existing result or error in \fIinterp\fR and -moves the result from \fIstatePtr\fR back to \fIinterp\fR. \fIstatePtr\fR is -then in an undefined state and must not be used until passed again to -\fBTcl_SaveResult\fR. -.PP -\fBTcl_DiscardResult\fR releases the state stored at \fBstatePtr\fR, which is -then in an undefined state and must not be used until passed again to -\fBTcl_SaveResult\fR. -.PP -If a saved result is not restored, \fBTcl_DiscardResult\fR must be called to -release it. .SH KEYWORDS result, state, interp diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3 index 473b61c..72157c6 100644 --- a/doc/SetChanErr.3 +++ b/doc/SetChanErr.3 @@ -87,14 +87,10 @@ the value. Which functions of a channel driver are allowed to use which bypass function is listed below, as is which functions of the public channel API may leave a messages in the bypass areas. -.IP \fBTcl_DriverCloseProc\fR -May use \fBTcl_SetChannelErrorInterp\fR, and only this function. .IP \fBTcl_DriverInputProc\fR May use \fBTcl_SetChannelError\fR, and only this function. .IP \fBTcl_DriverOutputProc\fR May use \fBTcl_SetChannelError\fR, and only this function. -.IP \fBTcl_DriverSeekProc\fR -May use \fBTcl_SetChannelError\fR, and only this function. .IP \fBTcl_DriverWideSeekProc\fR May use \fBTcl_SetChannelError\fR, and only this function. .IP \fBTcl_DriverSetOptionProc\fR diff --git a/doc/SetRecLmt.3 b/doc/SetRecLmt.3 index ec55794..0358cc9 100644 --- a/doc/SetRecLmt.3 +++ b/doc/SetRecLmt.3 @@ -14,14 +14,14 @@ Tcl_SetRecursionLimit \- set maximum allowable nesting depth in interpreter .nf \fB#include <tcl.h>\fR .sp -int +size_t \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 +.AP size_t depth in New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR. .BE @@ -29,7 +29,7 @@ New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR. .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. +such as \fBTcl_EvalEx\fR. Any call to \fBTcl_Eval\fR that exceeds this depth is aborted with an error. By default the recursion limit is 1000. diff --git a/doc/SetResult.3 b/doc/SetResult.3 index 04a4b7f..42e3ce0 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result +Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult \- manipulate Tcl result .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -26,15 +26,11 @@ const char * .sp \fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *) NULL\fR) .sp -\fBTcl_AppendResultVA\fR(\fIinterp, argList\fR) -.sp \fBTcl_ResetResult\fR(\fIinterp\fR) .sp \fBTcl_TransferResult\fR(\fIsourceInterp, code, targetInterp\fR) .sp \fBTcl_AppendElement\fR(\fIinterp, element\fR) -.sp -\fBTcl_FreeResult\fR(\fIinterp\fR) .SH ARGUMENTS .AS Tcl_FreeProc sourceInterp out .AP Tcl_Interp *interp out @@ -143,11 +139,6 @@ extensions. Any number of \fIresult\fR arguments may be passed in a single call; the last argument in the list must be a NULL pointer. .PP -\fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that -instead of taking a variable number of arguments it takes an argument list. -Interfaces using argument lists have been found to be nonportable in practice. -This function is deprecated and will be removed in Tcl 9.0. -.PP \fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR to \fItargetInterp\fR. The two interpreters must have been created in the same thread. If \fIsourceInterp\fR and \fItargetInterp\fR are the same, @@ -184,22 +175,6 @@ single character or ends in the characters .QW " {" ) 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 does not -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. -.SS "DIRECT ACCESS TO INTERP->RESULT" -.PP -It used to be legal for programs to -directly read and write \fIinterp->result\fR -to manipulate the interpreter result. The Tcl headers no longer -permit this access. C code still doing this must -be updated to use supported routines \fBTcl_GetObjResult\fR, -\fBTcl_GetStringResult\fR, \fBTcl_SetObjResult\fR, and \fBTcl_SetResult\fR. .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT" .PP \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how diff --git a/doc/SplitList.3 b/doc/SplitList.3 index 863e322..6d9a9aa 100644 --- a/doc/SplitList.3 +++ b/doc/SplitList.3 @@ -20,16 +20,16 @@ int char * \fBTcl_Merge\fR(\fIargc, argv\fR) .sp -int +size_t \fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR) .sp -int +size_t \fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR) .sp -int +size_t \fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR) .sp -int +size_t \fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR) .SH ARGUMENTS .AS "const char *const" ***argvPtr out @@ -38,14 +38,14 @@ Interpreter to use for error reporting. If NULL, then no error message is left. .AP "const char" *list in Pointer to a string with proper list structure. -.AP int *argcPtr out +.AP "size_t \&| int" *argcPtr out Filled in with number of elements in \fIlist\fR. .AP "const 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 +.AP size_t argc in Number of elements in \fIargv\fR. .AP "const char *const" *argv in Array of strings to merge together into a single list. @@ -55,7 +55,7 @@ String that is to become an element of a list. .AP int *flagsPtr in Pointer to word to fill in with information about \fIsrc\fR. The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR. -.AP int length in +.AP size_t length in Number of bytes in string \fIsrc\fR. .AP char *dst in Place to copy converted list element. Must contain enough characters @@ -81,7 +81,8 @@ For example, suppose that you have called \fBTcl_SplitList\fR with the following code: .PP .CS -int argc, code; +size_t argc; +int code; char *string; char **argv; \&... @@ -92,12 +93,13 @@ Then you should eventually free the storage with a call like the following: .PP .CS -Tcl_Free((char *) argv); +Tcl_Free(argv); .CE .PP \fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was -successfully parsed. -If there was a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned +successfully parsed. If \fIsizePtr\fR points to a variable of type +\fBint\fR and the list contains more than 2**31 key/value pairs, or there was +a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned and the interpreter's result will point to an error message describing the problem (if \fIinterp\fR was not NULL). If \fBTCL_ERROR\fR is returned then no memory is allocated and \fI*argvPtr\fR diff --git a/doc/SplitPath.3 b/doc/SplitPath.3 index c011194..10e84f5 100644 --- a/doc/SplitPath.3 +++ b/doc/SplitPath.3 @@ -25,14 +25,14 @@ Tcl_PathType .AP "const 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 +.AP "size_t \&| int" *argcPtr out Filled in with number of path elements in \fIpath\fR. .AP "const 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 +.AP size_t argc in Number of elements in \fIargv\fR. .AP "const char *const" *argv in Array of path elements to merge together into a single path. @@ -61,7 +61,7 @@ For example, suppose that you have called \fBTcl_SplitPath\fR with the following code: .PP .CS -int argc; +size_t argc; char *path; char **argv; \&... @@ -72,7 +72,7 @@ Then you should eventually free the storage with a call like the following: .PP .CS -Tcl_Free((char *) argv); +Tcl_Free(argv); .CE .PP \fBTcl_JoinPath\fR is the inverse of \fBTcl_SplitPath\fR: it takes a diff --git a/doc/StaticLibrary.3 b/doc/StaticLibrary.3 index 9a77ab7..c5bd364 100644 --- a/doc/StaticLibrary.3 +++ b/doc/StaticLibrary.3 @@ -24,8 +24,8 @@ already been incorporated (i.e., the caller has already invoked the appropriate initialization procedure). NULL means the library has not yet been incorporated into any interpreter. .AP "const char" *prefix in -Prefix for library initialization function; should be properly -capitalized (first letter upper-case, all others lower-case). +Prefix for library initialization function. Normally in titlecase (first +letter upper-case, all others lower-case), but this is no longer required. .AP Tcl_LibraryInitProc *initProc in Procedure to invoke to incorporate this library into a trusted interpreter. @@ -70,8 +70,7 @@ initialization procedure to be invoked. \fBTcl_StaticLibrary\fR was named \fBTcl_StaticPackage\fR in Tcl 8.6 and earlier, but the old name is deprecated now. .PP -\fBTcl_StaticLibrary\fR can not be used in stub-enabled extensions. Its symbol -entry in the stub table is deprecated and it will be removed in Tcl 9.0. +\fBTcl_StaticLibrary\fR can not be used in stub-enabled extensions. .SH KEYWORDS initialization procedure, package, static linking .SH "SEE ALSO" diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 6118a2d..2d41018 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings +Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -40,7 +40,7 @@ Tcl_UniChar * int \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR) .sp -int +size_t \fBTcl_GetCharLength\fR(\fIobjPtr\fR) .sp Tcl_Obj * @@ -59,9 +59,6 @@ void \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR) .sp void -\fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR) -.sp -void \fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR) .sp Tcl_Obj * @@ -90,38 +87,38 @@ Tcl_Obj * Points to the first byte of an array of UTF-8-encoded bytes used to set or append to a string value. This byte array may contain embedded null characters -unless \fInumChars\fR is negative. (Applications needing null bytes +unless \fInumChars\fR is \fBTCL_INDEX_NONE\fR. (Applications needing null bytes should represent them as the two-byte sequence \fI\e300\e200\fR, use \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if the string is a collection of uninterpreted bytes.) -.AP int length in +.AP size_t length in The number of bytes to copy from \fIbytes\fR when initializing, setting, or appending to a string value. -If negative, all bytes up to the first null are used. +If \fBTCL_INDEX_NONE\fR, all bytes up to the first null are used. .AP "const Tcl_UniChar" *unicode in Points to the first byte of an array of Unicode characters used to set or append to a string value. This byte array may contain embedded null characters -unless \fInumChars\fR is negative. -.AP int numChars in +unless \fInumChars\fR is \fBTCL_INDEX_NONE\fR. +.AP size_t numChars in The number of Unicode characters to copy from \fIunicode\fR when initializing, setting, or appending to a string value. -If negative, all characters up to the first null character are used. -.AP int index in +If \fBTCL_INDEX_NONE\fR, all characters up to the first null character are used. +.AP size_t index in The index of the Unicode character to return. -.AP int first in +.AP size_t first in The index of the first Unicode character in the Unicode range to be -returned as a new value. If negative, behave the same as if the +returned as a new value. If \fBTCL_INDEX_NONE\fR, behave the same as if the value was 0. -.AP int last in +.AP size_t last in The index of the last Unicode character in the Unicode range to be -returned as a new value. If negative, take all characters up to +returned as a new value. If \fBTCL_INDEX_NONE\fR, take all characters up to the last one available. .AP Tcl_Obj *objPtr in/out Points to a value to manipulate. .AP Tcl_Obj *appendObjPtr in The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. -.AP int *lengthPtr out +.AP "size_t \&| int" *lengthPtr out The location where \fBTcl_GetStringFromObj\fR will store the length of a value's string representation. May be (int *)NULL when not used. .AP "const char" *string in @@ -129,7 +126,7 @@ Null-terminated string value to append to \fIobjPtr\fR. .AP va_list argList in An argument list which must have been initialized using \fBva_start\fR, and cleared using \fBva_end\fR. -.AP int limit in +.AP size_t limit in Maximum number of bytes to be appended. .AP "const char" *ellipsis in Suffix to append when the limit leads to string truncation. @@ -138,11 +135,11 @@ If NULL is passed then the suffix is used. .AP "const char" *format in Format control string including % conversion specifiers. -.AP int objc in +.AP size_t objc in The number of elements to format or concatenate. .AP Tcl_Obj *objv[] in The array of values to format or concatenate. -.AP int newLength in +.AP size_t newLength in New length for the string value of \fIobjPtr\fR, not including the final null character. .BE @@ -191,7 +188,9 @@ Even in the limited situations where writing to this pointer is acceptable, one should take care to respect the copy-on-write semantics required by \fBTcl_Obj\fR's, with appropriate calls to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any -in-place modification of the string representation. +in-place modification of the string representation. If \fIlengthPtr\fR +points to an \fBint\fR variable, and the string has more than 2^31 bytes, +a panic will result. The procedure \fBTcl_GetString\fR is used in the common case where the caller does not need the length of the string representation. @@ -203,18 +202,19 @@ value as a Unicode string. This is given by the returned pointer and byte pointer is owned by the value manager and should not be modified by the caller. The procedure \fBTcl_GetUnicode\fR is used in the common case where the caller does not need the length of the unicode string -representation. +representation. If \fIlengthPtr\fR points to an \fBint\fR variable, +and the string has more than 2^31 unicode characters, a panic will result. .PP \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the value's Unicode representation. If the index is out of range or it references a low surrogate preceded by a high surrogate, it returns -1; .PP \fBTcl_GetRange\fR returns a newly created value comprised of the -characters between \fIfirst\fR and \fIlast\fR (inclusive) in the -value's Unicode representation. If the value's Unicode -representation is invalid, the Unicode representation is regenerated -from the value's string representation. If \fIfirst\fR < 0, then -the returned string starts at the beginning of the value. If \fIlast\fR < 0, +characters between \fIfirst\fR and \fIlast\fR (inclusive) in the value's +Unicode representation. If the value's Unicode representation +is invalid, the Unicode representation is regenerated from the value's +string representation. If \fIfirst\fR == TCL_INDEX_NONE, then the returned +string starts at the beginning of the value. If \fIlast\fR == TCL_INDEX_NONE, then the returned string ends at the end of the value. .PP \fBTcl_GetCharLength\fR returns the number of characters (as opposed @@ -251,12 +251,6 @@ 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 -\fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR -except that instead of taking a variable number of arguments it takes an -argument list. Interfaces using argument lists have been found to be -nonportable in practice. This function is deprecated and will be removed -in Tcl 9.0. -.PP \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR except that it imposes a limit on how many bytes are appended. This can be handy when the string to be appended might be @@ -269,7 +263,7 @@ all \fIlength\fR bytes that are available from being appended, then the appending is done so that the last bytes appended are from the string \fIellipsis\fR. This allows for an indication of the truncation to be left in the string. -When \fIlength\fR is \fB-1\fR, all bytes up to the first zero byte are appended, +When \fIlength\fR is \fBTCL_INDEX_NONE\fR, all bytes up to the first zero byte are appended, subject to the limit. When \fIellipsis\fR is NULL, the default string \fB...\fR is used. When \fIellipsis\fR is non-NULL, it must point to a zero-byte-terminated string in Tcl's internal UTF encoding. @@ -312,7 +306,7 @@ functionality is needed. .CS char buf[SOME_SUITABLE_LENGTH]; sprintf(buf, format, ...); -\fBTcl_NewStringObj\fR(buf, -1); +\fBTcl_NewStringObj\fR(buf, \fBTCL_INDEX_NONE\fR); .CE .PP but with greater convenience and no need to diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3 index 59af6ba..6bd03c9 100644 --- a/doc/TCL_MEM_DEBUG.3 +++ b/doc/TCL_MEM_DEBUG.3 @@ -34,7 +34,7 @@ and the Tcl \fBmemory\fR command can be used to validate and examine memory usage. .SH "GUARD ZONES" .PP -When memory debugging is enabled, whenever a call to \fBckalloc\fR is +When memory debugging is enabled, whenever a call to \fBTcl_Alloc\fR is made, slightly more memory than requested is allocated so the memory debugging code can keep track of the allocated memory, and eight-byte .QW "guard zones" @@ -44,7 +44,7 @@ C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR in the file \fIgeneric/tclCkalloc.c\fR \(em it can be extended if you suspect large overwrite problems, at some cost in performance.) A known pattern is written into the guard zones and, on -a call to \fBckfree\fR, the guard zones of the space being freed are +a call to \fBTcl_Free\fR, the guard zones of the space being freed are checked to see if either zone has been modified in any way. If one has been, the guard bytes and their new contents are identified, and a .QW "low guard failed" @@ -53,7 +53,7 @@ or message is issued. The .QW "guard failed" message includes the address of the memory packet and -the file name and line number of the code that called \fBckfree\fR. +the file name and line number of the code that called \fBTcl_Free\fR. This allows you to detect the common sorts of one-off problems, where not enough space was allocated to contain the data written, for example. @@ -66,15 +66,15 @@ suspect (or know) that corruption is occurring before the Tcl interpreter comes up far enough for you to issue commands, you can set \fBMEM_VALIDATE\fR define, recompile tclCkalloc.c and rebuild Tcl. This will enable memory validation from the first call to -\fBckalloc\fR, again, at a large performance impact. +\fBTcl_Alloc\fR, again, at a large performance impact. .PP If you are desperate and validating memory on every call to -\fBckalloc\fR and \fBckfree\fR is not enough, you can explicitly call +\fBTcl_Alloc\fR and \fBTcl_Free\fR is not enough, you can explicitly call \fBTcl_ValidateAllMemory\fR directly at any point. It takes a \fIchar *\fR and an \fIint\fR which are normally the filename and line number of the caller, but they can actually be anything you want. Remember to remove the calls after you find the problem. .SH "SEE ALSO" -ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory +Tcl_Alloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory .SH KEYWORDS memory, debug diff --git a/doc/TclZlib.3 b/doc/TclZlib.3 index 4d06923..bd37f9c 100644 --- a/doc/TclZlib.3 +++ b/doc/TclZlib.3 @@ -88,7 +88,7 @@ The initial value for the checksum algorithm. .AP "unsigned char" *bytes in An array of bytes to run the checksum algorithm over, or NULL to get the recommended initial value for the checksum algorithm. -.AP int length in +.AP size_t length in The number of bytes in the array. .AP int mode in What mode to operate the stream in. Should be either @@ -107,9 +107,9 @@ if the currently compressed data must be made available for access using into a state where the decompressor can recover from on corruption, or \fBTCL_ZLIB_FINALIZE\fR to ensure that the stream is finished and that any trailer demanded by the format is written. -.AP int count in -The maximum number of bytes to get from the stream, or -1 to get all remaining -bytes from the stream's buffers. +.AP size_t count in +The maximum number of bytes to get from the stream, or TCL_INDEX_NONE to get +all remaining bytes from the stream's buffers. .AP Tcl_Obj *compDict in A byte array value that is the compression dictionary to use with the stream. Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index 6a37cda..c208711 100644 --- a/doc/Tcl_Main.3 +++ b/doc/Tcl_Main.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. '\" -.TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures" +.TH Tcl_Main 3 9.0 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -29,7 +29,7 @@ Tcl_Obj * \fBTcl_SetMainLoop\fR(\fImainLoopProc\fR) .SH ARGUMENTS .AS Tcl_MainLoopProc *mainLoopProc -.AP int argc in +.AP size_t argc in Number of elements in \fIargv\fR. .AP char *argv[] in Array of strings containing command-line arguments. On Windows, when @@ -203,6 +203,11 @@ procedure (if any) returns, \fBTcl_Main\fR will also evaluate the \fBexit\fR command. .PP \fBTcl_Main\fR can not be used in stub-enabled extensions. +.PP +The difference between Tcl_MainEx and Tcl_MainExW is that the arguments +are passed as characters or wide characters. When used in stub-enabled +embedders, the stubs table must be first initialized using one of +\fBTcl_InitSubsystems\fR, \fBTcl_SetPanicProc\fR, \fBTcl_FindExecutable\fR or \fBTclZipfs_AppHook\fR. .SH "REFERENCE COUNT MANAGEMENT" .PP \fBTcl_SetStartupScript\fR takes a value (or NULL) for its \fIpath\fR diff --git a/doc/Thread.3 b/doc/Thread.3 index 2005c93..51df5bb 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -67,7 +67,7 @@ Id of the thread waited upon. .AP Tcl_ThreadCreateProc *proc in This procedure will act as the \fBmain()\fR of the newly created thread. The specified \fIclientData\fR will be its sole argument. -.AP ClientData clientData in +.AP void *clientData in Arbitrary information. Passed as sole argument to the \fIproc\fR. .AP int stackSize in The size of the stack given to the new thread. @@ -208,7 +208,7 @@ value and then finishes. .CS static \fBTcl_ThreadCreateType\fR MyThreadImplFunc( - ClientData clientData) + void *clientData) { int i, limit = (int) clientData; for (i=0 ; i<limit ; i++) { @@ -223,7 +223,7 @@ would do this: .PP .CS int limit = 1000000000; -ClientData limitData = (void*)((intptr_t) limit); +void *limitData = (void*)((intptr_t) limit); Tcl_ThreadId id; \fI/* holds identity of thread created */\fR int result; diff --git a/doc/ToUpper.3 b/doc/ToUpper.3 index 37ebd2b..86d2f98 100644 --- a/doc/ToUpper.3 +++ b/doc/ToUpper.3 @@ -22,13 +22,13 @@ int int \fBTcl_UniCharToTitle\fR(\fIch\fR) .sp -int +size_t \fBTcl_UtfToUpper\fR(\fIstr\fR) .sp -int +size_t \fBTcl_UtfToLower\fR(\fIstr\fR) .sp -int +size_t \fBTcl_UtfToTitle\fR(\fIstr\fR) .SH ARGUMENTS .AS char *str in/out diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index 99914a6..8ae946e 100644 --- a/doc/TraceCmd.3 +++ b/doc/TraceCmd.3 @@ -13,7 +13,7 @@ Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames an .nf \fB#include <tcl.h>\fR .sp -ClientData +void * \fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR .sp int @@ -32,9 +32,9 @@ OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and \fBTCL_TRACE_DELETE\fR. .AP Tcl_CommandTraceProc *proc in Procedure to call when specified operations occur to \fIcmdName\fR. -.AP ClientData clientData in +.AP void *clientData in Arbitrary argument to pass to \fIproc\fR. -.AP ClientData prevClientData in +.AP void *prevClientData in If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR, so this call will return information about next trace. If NULL, this call will return information about first trace. @@ -65,7 +65,7 @@ match the type \fBTcl_CommandTraceProc\fR: .PP .CS typedef void \fBTcl_CommandTraceProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, const char *\fIoldName\fR, const char *\fInewName\fR, @@ -74,7 +74,7 @@ typedef void \fBTcl_CommandTraceProc\fR( .PP The \fIclientData\fR and \fIinterp\fR parameters will have the same values as those passed to \fBTcl_TraceCommand\fR when the trace was -created. \fIClientData\fR typically points to an application-specific +created. \fIclientData\fR typically points to an application-specific data structure that describes what to do when \fIproc\fR is invoked. \fIOldName\fR gives the name of the command being renamed, and \fInewName\fR gives the name that the command is being renamed to (or diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index 5de6a44..90c90b9 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. '\" -.TH Tcl_TraceVar 3 8.7 Tcl "Tcl Library Procedures" +.TH Tcl_TraceVar 3 9.0 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -24,13 +24,13 @@ int .sp \fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR .sp -ClientData +void * \fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR .sp -ClientData +void * \fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR .SH ARGUMENTS -.AS Tcl_VarTraceProc prevClientData +.AS void *prevClientData .AP Tcl_Interp *interp in Interpreter containing variable. .AP "const char" *varName in @@ -46,7 +46,7 @@ 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 +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .AP "const char" *name1 in Name of scalar or array variable (without array index). @@ -54,7 +54,7 @@ Name of scalar or array variable (without array index). 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 +.AP void *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 @@ -107,7 +107,7 @@ before an array set, but that will trigger write traces. \fBTCL_TRACE_RESULT_DYNAMIC\fR 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_Free\fR. Must not be specified at the same time as \fBTCL_TRACE_RESULT_OBJECT\fR. .TP \fBTCL_TRACE_RESULT_OBJECT\fR @@ -124,7 +124,7 @@ It should have arguments and result that match the type .PP .CS typedef char *\fBTcl_VarTraceProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, const char *\fIname1\fR, const char *\fIname2\fR, @@ -134,12 +134,14 @@ typedef char *\fBTcl_VarTraceProc\fR( 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 +\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). +\fIName1\fR and \fIname2\fR give the name of the variable that +triggered the callback in the normal two-part form (see the description +of \fBTcl_TraceVar2\fR below for details). In case \fIname1\fR is an +alias to an array element (created through facilities such as \fBupvar\fR), +\fIname2\fR holds the index of the array element, rather than NULL. \fIFlags\fR is an OR-ed combination of bits providing several pieces of information. One of the bits \fBTCL_TRACE_READS\fR, \fBTCL_TRACE_WRITES\fR, @@ -308,7 +310,7 @@ The return value must be a pointer to a static character string containing an error message, unless (\fIexactly\fR one of) the \fBTCL_TRACE_RESULT_DYNAMIC\fR and \fBTCL_TRACE_RESULT_OBJECT\fR flags is set, which specify that the result is -either a dynamic string (to be released with \fBckfree\fR) or a +either a dynamic string (to be released with \fBTcl_Free\fR) or a Tcl_Obj* (cast to char* and to be released with \fBTcl_DecrRefCount\fR) containing the error message. If a trace procedure returns an error, no further traces are @@ -333,7 +335,8 @@ The routine \fBTcl_InterpDeleted\fR is an important tool for this. When \fBTcl_InterpDeleted\fR returns 1, \fIproc\fR will not be able to invoke any scripts in \fIinterp\fR. You may encounter old code using a deprecated flag value \fBTCL_INTERP_DESTROYED\fR to signal this -condition, but any supported code should be converted to stop using it. +condition, but Tcl 9 no longer supports this. Any supported code +must be converted to stop using it. .PP A trace procedure can be called at any time, even when there are partially formed results stored in the interpreter. If diff --git a/doc/Translate.3 b/doc/Translate.3 index 38831d3..256baec 100644 --- a/doc/Translate.3 +++ b/doc/Translate.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory +Tcl_TranslateFileName \- convert file name to native form .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -34,7 +34,7 @@ anything stored here. This utility procedure translates a file name to a platform-specific form which, after being converted to the appropriate encoding, is suitable for passing to the local operating system. In particular, it converts -network names into native form and does tilde substitution. +network names into native form. .PP However, with the advent of the newer \fBTcl_FSGetNormalizedPath\fR and \fBTcl_FSGetNativePath\fR, there is no longer any need to use this @@ -45,7 +45,7 @@ Finally \fBTcl_FSGetNativePath\fR does not require you to free anything afterwards. .PP If -\fBTcl_TranslateFileName\fR has to do tilde substitution or translate +\fBTcl_TranslateFileName\fR has to translate the name then it uses the dynamic string at \fI*bufferPtr\fR to hold the new string it generates. @@ -68,4 +68,4 @@ has its default empty value when \fBTcl_TranslateFileName\fR is invoked. .SH "SEE ALSO" filename(n) .SH KEYWORDS -file name, home directory, tilde, translate, user +file name, home directory, translate, user @@ -15,16 +15,16 @@ Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfToChar16, Tcl_UtfToWChar .sp typedef ... \fBTcl_UniChar\fR; .sp -int +size_t \fBTcl_UniCharToUtf\fR(\fIch, buf\fR) .sp -int +size_t \fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR) .sp -int +size_t \fBTcl_UtfToChar16\fR(\fIsrc, uPtr\fR) .sp -int +size_t \fBTcl_UtfToWChar\fR(\fIsrc, wPtr\fR) .sp char * @@ -55,19 +55,19 @@ int \fBTcl_UniCharLen\fR(\fIuniStr\fR) .sp int -\fBTcl_UniCharNcmp\fR(\fIucs, uct, numChars\fR) +\fBTcl_UniCharNcmp\fR(\fIucs, uct, uniLength\fR) .sp int -\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, numChars\fR) +\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, uniLength\fR) .sp int \fBTcl_UniCharCaseMatch\fR(\fIuniStr, uniPattern, nocase\fR) .sp int -\fBTcl_UtfNcmp\fR(\fIcs, ct, numChars\fR) +\fBTcl_UtfNcmp\fR(\fIcs, ct, length\fR) .sp int -\fBTcl_UtfNcasecmp\fR(\fIcs, ct, numChars\fR) +\fBTcl_UtfNcasecmp\fR(\fIcs, ct, length\fR) .sp int \fBTcl_UtfCharComplete\fR(\fIsrc, length\fR) @@ -93,7 +93,7 @@ int const char * \fBTcl_UtfAtIndex\fR(\fIsrc, index\fR) .sp -int +size_t \fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR) .SH ARGUMENTS .AS "const Tcl_UniChar" *uniPattern in/out @@ -132,18 +132,16 @@ A null-terminated utf-16 string. A null-terminated utf-16 string. .AP "const unsigned short" *utf16Pattern in A null-terminated utf-16 string. -.AP int length in +.AP size_t length in The length of the UTF-8 string in bytes (not UTF-8 characters). If -negative, all bytes up to the first null byte are used. -.AP int uniLength in +TCL_INDEX_NONE, all bytes up to the first null byte are used. +.AP size_t uniLength in The length of the Unicode string in characters. .AP "Tcl_DString" *dsPtr in/out A pointer to a previously initialized \fBTcl_DString\fR. -.AP "unsigned long" numChars in -The number of characters to compare. .AP "const char" *start in Pointer to the beginning of a UTF-8 string. -.AP int index in +.AP size_t index in The index of a character (not byte) in the UTF-8 string. .AP int *readPtr out If non-NULL, filled with the number of bytes in the backslash sequence, @@ -168,11 +166,12 @@ can consume in a single call. .PP \fBTcl_UniCharToUtf\fR stores the character \fIch\fR as a UTF-8 string in starting at \fIbuf\fR. The return value is the number of bytes stored -in \fIbuf\fR. If ch is a high surrogate (range U+D800 - U+DBFF), then -the return value will be 1 and a single byte in the range 0xF0 - 0xF4 -will be stored. If you still want to produce UTF-8 output for it (even -though knowing it's an illegal code-point on its own), just call -\fBTcl_UniCharToUtf\fR again specifying ch = -1. +in \fIbuf\fR. The character \fIch\fR can be or'ed with the value TCL_COMBINE +to enable special behavior, compatible with Tcl 8.x. Then, if ch is a high +surrogate (range U+D800 - U+DBFF), the return value will be 1 and a single +byte in the range 0xF0 - 0xF4 will be stored. If \fIch\fR is a low surrogate +(range U+DC00 - U+DFFF), an attempt is made to combine the result with +the earlier produced bytes, resulting in a 4-byte UTF-8 byte sequence. .PP \fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR and stores it as a Tcl_UniChar in \fI*chPtr\fR. The return value is the @@ -219,7 +218,7 @@ the number of Unicode characters (not bytes) in that string. \fBTcl_UniCharNcmp\fR and \fBTcl_UniCharNcasecmp\fR correspond to \fBstrncmp\fR and \fBstrncasecmp\fR, respectively, for Unicode characters. They accept two null-terminated Unicode strings and the number of characters -to compare. Both strings are assumed to be at least \fInumChars\fR characters +to compare. Both strings are assumed to be at least \fIuniLength\fR characters long. \fBTcl_UniCharNcmp\fR compares the two strings character-by-character according to the Unicode character ordering. It returns an integer greater than, equal to, or less than 0 if the first string is greater than, equal @@ -233,7 +232,7 @@ be case sensitive and returns whether the string matches the pattern. .PP \fBTcl_UtfNcmp\fR corresponds to \fBstrncmp\fR for UTF-8 strings. It accepts two null-terminated UTF-8 strings and the number of characters -to compare. (Both strings are assumed to be at least \fInumChars\fR +to compare. (Both strings are assumed to be at least \fIlength\fR characters long.) \fBTcl_UtfNcmp\fR compares the two strings character-by-character according to the Unicode character ordering. It returns an integer greater than, equal to, or less than 0 if the @@ -255,7 +254,7 @@ know if a full Unicode character has been seen. \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings. It returns the number of Tcl_UniChars that are represented by the UTF-8 string \fIsrc\fR. The length of the source string is \fIlength\fR bytes. If the -length is negative, all bytes up to the first null byte are used. +length is TCL_INDEX_NONE, all bytes up to the first null byte are used. .PP \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings. It returns a pointer to the first occurrence of the Unicode character \fIch\fR @@ -300,17 +299,14 @@ byte \fIsrc[0]\fR nor the byte \fIstart[-1]\fR nor the byte Pascal Ord() function. It returns the Unicode character represented at the specified character (not byte) \fIindex\fR in the UTF-8 string \fIsrc\fR. The source string must contain at least \fIindex\fR -characters. If a negative \fIindex\fR is given or \fIindex\fR points +characters. If \fIindex\fR is TCL_INDEX_NONE or \fIindex\fR points to the second half of a surrogate pair, it returns -1. .PP \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not byte) \fIindex\fR in the UTF-8 string \fIsrc\fR. The source string must contain at least \fIindex\fR characters. This is equivalent to calling -\fBTcl_UtfToUniChar\fR \fIindex\fR times, except if that would return -a pointer to the second byte of a valid 4-byte UTF-8 sequence, in which -case, \fBTcl_UtfToUniChar\fR will be called once more to find the end -of the sequence. If a negative \fIindex\fR is given, the returned pointer -points to the first character in the source string. +\fBTcl_UtfToUniChar\fR \fIindex\fR times. If \fIindex\fR is TCL_INDEX_NONE, +the return pointer points to the first character in the source string. .PP \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl commands. It parses a backslash sequence and stores the properly formed diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3 index 533cb4f..b501d36 100644 --- a/doc/WrongNumArgs.3 +++ b/doc/WrongNumArgs.3 @@ -19,7 +19,7 @@ Tcl_WrongNumArgs \- generate standard error message for wrong number of argument .AP Tcl_Interp interp in Interpreter in which error will be reported: error message gets stored in its result value. -.AP int objc in +.AP size_t objc in Number of leading arguments from \fIobjv\fR to include in error message. .AP "Tcl_Obj *const" objv[] in diff --git a/doc/binary.n b/doc/binary.n index 70f569b..c54bcc9 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -44,8 +44,9 @@ the range \eu0000\-\eu00FF. When encoding binary data as a readable string, the starting binary data is passed to the \fBbinary encode\fR command, together with the name of the encoding to use and any encoding-specific options desired. Data which has been -encoded can be converted back to binary form using \fBbinary decode\fR. The -following formats and options are supported. +encoded can be converted back to binary form using \fBbinary decode\fR. +The \fBbinary encode\fR command raises an error if the \fIdata\fR argument +is not binary data. The following formats and options are supported. .TP \fBbase64\fR . @@ -609,9 +610,9 @@ will return .PP The \fBbinary scan\fR command parses fields from a binary string, returning the number of conversions performed. \fIString\fR gives the -input bytes to be parsed (one byte per character, and characters not -representable as a byte have their high bits chopped) -and \fIformatString\fR indicates how to parse it. +input bytes to be parsed and \fIformatString\fR indicates how to parse it. +An error is raised if \fIstring\fR is anything other than a valid binary +data value. 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. diff --git a/doc/case.n b/doc/case.n deleted file mode 100644 index c48d634..0000000 --- a/doc/case.n +++ /dev/null @@ -1,60 +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. -'\" -.TH case n 7.0 Tcl "Tcl Built-In Commands" -.so man.macros -.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 "SEE ALSO" -switch(n) - -.SH KEYWORDS -case, match, regular expression @@ -143,18 +143,12 @@ interface with the operating system, .RE .TP \fB\-eofchar\fR \fIchar\fR -.TP -\fB\-eofchar\fR \fB{\fIchar outChar\fB}\fR . \fIchar\fR signals the end of the data when it is encountered in the input. -For output, \fIoutChar\fR is added when the channel is closed. If \fIchar\fR -is the empty string, there is no special character that marks the end of the -data. For read-write channels, one end-of-file character for input and another -for output may be given. When only one end-of-file character is given it is -applied to input only. +If \fIchar\fR is the empty string, there is no special character that marks +the end of the data. -The default value is the empty string, except that under Windows the default -value for reading is Control-z (\ex1A). The acceptable range is \ex01 - +The default value is the empty string. The acceptable range is \ex01 - \ex7f. A value outside this range results in an error. .TP \fB\-translation\fR \fItranslation\fR diff --git a/doc/define.n b/doc/define.n index 19969da..f1e799b 100644 --- a/doc/define.n +++ b/doc/define.n @@ -588,7 +588,7 @@ for reading from slots is via \fBinfo class\fR and \fBinfo object\fR). .SH EXAMPLES This example demonstrates how to use both forms of the \fBoo::define\fR and \fBoo::objdefine\fR commands (they work in the same way), as well as -illustrating four of the subcommands of them. +illustrating four of their subcommands. .PP .CS oo::class create c diff --git a/doc/encoding.n b/doc/encoding.n index 78580f2..6a273f4 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -38,22 +38,20 @@ system encoding is used. .VS "TCL8.7 TIP346, TIP607, TIP601" .PP .RS -The command does not fail on encoding errors. Instead, any not convertable bytes -(like incomplete UTF-8 sequences, see example below) are put as byte values into -the output stream. +If the option \fB-nocomplain\fR is given, the command does not fail on +encoding errors. Instead, any not convertable bytes (like incomplete UTF-8 + sequences, see example below) are put as byte values into the output stream. +If the option \fB-nocomplain\fR is not given, the command will fail with an +appropriate error message. .PP If the option \fB-failindex\fR with a variable name is given, the error reporting is changed in the following manner: in case of a conversion error, the position of the input byte causing the error is returned in the given variable. The return value of the command are the -converted characters until the first error position. +converted characters until the first error position. No error condition is raised. In case of no error, the value \fI-1\fR is written to the variable. This option may not be used together with \fB-nocomplain\fR. .PP -The option \fB-nocomplain\fR has no effect and is available for compatibility with -TCL 9. In TCL 9, the encoding command fails with an error on any encoding issue. -This switch restores the TCL8.7 behaviour. -.PP The \fB-strict\fR option follows more strict rules in conversion. For the \fButf-8\fR encoder, it disallows the the sequence \fB\\xC0\\x80\fR and noncharacters (which - otherwise - are just passed through). @@ -71,9 +69,12 @@ specified, the current system encoding is used. .VS "TCL8.7 TIP346, TIP607, TIP601" .PP .RS -The command does not fail on encoding errors. Instead, the replacement character -\fB?\fR is output for any not representable character (like the dot \fB\\U2022\fR +If the option \fB-nocomplain\fR is given, the command does not fail on +encoding errors. Instead, the replacement character \fB?\fR is output +for any not representable character (like the dot \fB\\U2022\fR in \fBiso-8859-1\fR encoding, see example below). +If the option \fB-nocomplain\fR is not given, the command will fail with an +appropriate error message. .PP If the option \fB-failindex\fR with a variable name is given, the error reporting is changed in the following manner: @@ -83,10 +84,6 @@ converted bytes until the first error position. No error condition is raised. In case of no error, the value \fI-1\fR is written to the variable. This option may not be used together with \fB-nocomplain\fR. .PP -The option \fB-nocomplain\fR has no effect and is available for compatibility with -TCL 9. In TCL 9, the encoding command fails with an error on any encoding issue. -This switch restores the TCL8.7 behaviour. -.PP The \fB-strict\fR option follows more strict rules in conversion. For the \fButf-8\fR encoder, it disallows the the sequence \fB\\xC0\\x80\fR and noncharacters (which - otherwise - are just passed through). @@ -147,8 +144,7 @@ Example 3: return the incomplete UTF-8 sequence by raw bytes: .CS % set s [\fBencoding convertfrom\fR -nocomplain utf-8 "A\exC3"] .CE -The result is "A" followed by the byte \exC3. The option \fB-nocomplain\fR -has no effect, but assures to get the same result with TCL9. +The result is "A" followed by the byte \exC3. .PP Example 4: detect the error location while transforming to ISO8859-1 (ISO-Latin 1): @@ -166,8 +162,6 @@ Example 5: replace a not representable character by the replacement character: % set s [\fBencoding convertto\fR -nocomplain utf-8 "A\eu0141"] A? .CE -The option \fB-nocomplain\fR has no effect, but assures to get the same result -with TCL9. .VE "TCL8.7 TIP346, TIP607, TIP601" .PP .SH "SEE ALSO" @@ -198,7 +198,7 @@ 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 +if the result contains no slashes then the directories in the PATH environment variable are searched for an executable by the given name. @@ -62,9 +62,7 @@ A \fBnumeric value\fR . Either integer or floating-point. The first two characters of an integer may also be \fB0d\fR for decimal, \fB0b\fR for binary, \fB0o\fR for octal or -\fB0x\fR for hexadicimal. For compatibility with older Tcl releases, an -operand that begins with \fB0\fR is interpreted as an octal integer even if the -second character is not \fBo\fR. +\fB0x\fR for hexadicimal. .PP A floating-point number may be take any of several common decimal formats, and may use the decimal point \fB.\fR, diff --git a/doc/fconfigure.n b/doc/fconfigure.n index 9061161..912702f 100644 --- a/doc/fconfigure.n +++ b/doc/fconfigure.n @@ -102,40 +102,32 @@ system, as returned by \fBencoding system\fR. .RE .TP \fB\-eofchar\fR \fIchar\fR -.TP -\fB\-eofchar\fR \fB{\fIchar 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. +character signals end-of-file when it is encountered during input. 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. +character marker. The default value for \fB\-eofchar\fR is the empty +string. The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7F; attempting to set \fB\-eofchar\fR to a value outside of this range will generate an error. -.VS "TCL8.7 TIP633" +.VS "TCL9.0 TIP633" .TP \fB\-nocomplainencoding\fR \fIbool\fR . Reporting mode of encoding errors. If set to a \fItrue\fR value, encoding errors are resolved by a replacement character (output) or verbatim bytes (input). No error is thrown. -This is the only available mode in Tcl 8.7. +If set to a \fIfalse\fR value, errors are thrown in case of encoding errors. .RS .PP -Starting from TCL 9.0, this value may be set to a \fIfalse\fR value to throw errors -in case of encoding errors. +The default value is \fIfalse\fR starting from TCL 9.0 and \fItrue\fR on TCL 8.7. +This option was introduced with TCL 8.7 and has the fix value \fItrue\fR. +.PP +See the \fI\-nocomplain\fR option of the \fBencoding\fR command for more information. .RE -.VE "TCL8.7 TIP633" +.VE "TCL9.0 TIP633" .VS "TCL8.7 TIP346" .TP \fB\-strictencoding\fR \fIbool\fR @@ -303,10 +295,10 @@ set data [read $f $numDataBytes] close $f .CE .SH "SEE ALSO" -close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n), +close(n), encoding(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n), Tcl_StandardChannels(3) .SH KEYWORDS -blocking, buffering, carriage return, end of line, flushing, linemode, +blocking, buffering, carriage return, end of line, encoding, flushing, linemode, newline, nonblocking, platform, translation, encoding, filter, byte array, binary '\" Local Variables: @@ -16,12 +16,10 @@ file \- Manipulate file names and attributes .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: +This command provides several operations on a file's name or attributes. The +\fIname\fR argument is the name of a file in most cases. The \fIoption\fR +argument 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 ?\fItime\fR? . @@ -145,21 +143,6 @@ returned. For example, .CE .PP returns \fBc:/\fR. -.PP -Note that tilde substitution will only be -performed if it is necessary to complete the command. For example, -.PP -.CS -\fBfile dirname\fR ~/src/foo.c -.CE -.PP -returns \fB~/src\fR, whereas -.PP -.CS -\fBfile dirname\fR ~ -.CE -.PP -returns \fB/home\fR (or something similar). .RE .TP \fBfile executable \fIname\fR @@ -397,19 +380,6 @@ 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 to ensure that an element is unambiguously relative. -For example, under Unix -.RS -.PP -.CS -\fBfile split\fR /foo/~bar/baz -.CE -.PP -returns -.QW \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 . @@ -507,11 +477,11 @@ native APIs and external programs that require a filename. Returns the result of performing tilde substitution on \fIname\fR. If the name begins with a tilde, then the file name will be interpreted as if the first element is replaced with the location of the home directory for the given user. -If the tilde is followed immediately by a path separator, the \fBHOME\fR +If the tilde is followed immediately by a path separator, the \fB$HOME\fR environment variable is substituted. Otherwise the characters between the tilde and the next separator are taken as a user name, which is used to retrieve the user's home directory for substitution. An error is raised if the -\fBHOME\fR environment variable or user does not exist. +\fB$HOME\fR environment variable or user does not exist. .RS .PP If the file name does not begin with a tilde, it is returned unmodified. diff --git a/doc/filename.n b/doc/filename.n index 335d8c7..628b2bb 100644 --- a/doc/filename.n +++ b/doc/filename.n @@ -119,26 +119,6 @@ Volume-relative path to a file \fBfoo\fR in the root directory of the current volume. This is not a valid UNC path, so the assumption is that the extra backslashes are superfluous. .RE -.SH "TILDE SUBSTITUTION" -.PP -In addition to the file name rules described above, Tcl also supports -\fIcsh\fR-style tilde substitution. If a file name starts with a tilde, -then the file name will be interpreted as if the first element is -replaced with the location of the home directory for the given user. If -the tilde is followed immediately by a separator, then the \fB$HOME\fR -environment variable is substituted. Otherwise the characters between -the tilde and the next separator are taken as a user name, which is used -to retrieve the user's home directory for substitution. This works on -Unix, MacOS X and Windows (except very old releases). -.PP -Old Windows platforms do not support tilde substitution when a user name -follows the tilde. On these platforms, attempts to use a tilde followed -by a user name will generate an error that the user does not exist when -Tcl attempts to interpret that part of the path or otherwise access the -file. The behaviour of these paths when not trying to interpret them is -the same as on Unix. File names that have a tilde without a user name -will be correctly substituted using the \fB$HOME\fR environment -variable, just like for Unix. .SH "PORTABILITY ISSUES" .PP Not all file systems are case sensitive, so scripts should avoid code diff --git a/doc/fpclassify.n b/doc/fpclassify.n index 22d365e..b6eb0e6 100644 --- a/doc/fpclassify.n +++ b/doc/fpclassify.n @@ -76,7 +76,7 @@ This command depends on the \fBfpclassify\fR() C macro conforming to (i.e., to ISO/IEC 9899:1999). .SH COPYRIGHT .nf -Copyright \(co 2018 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved +Copyright \(co 2018 Kevin B. Kenny <kennykb@acm.org>. All rights reserved .fi '\" Local Variables: '\" mode: nroff @@ -46,8 +46,8 @@ separators. .TP \fB\-nocomplain\fR . -Allows an empty list to be returned without error; without this -switch an error is returned if the result list would be empty. +Allows an empty list to be returned without error; This is the +default behavior in Tcl 9.0, so this switch has no effect any more. .TP \fB\-path\fR \fIpathPrefix\fR . @@ -185,16 +185,6 @@ command if you want the list sorted). Second, \fBglob\fR only returns the names of files that actually exist; in csh no check for existence is made unless a pattern contains a ?, *, or [] construct. -.LP -When the \fBglob\fR command returns relative paths whose filenames -start with a tilde -.QW ~ -(for example through \fBglob *\fR or \fBglob \-tails\fR, the returned -list will not quote the tilde with -.QW ./ . -This means care must be taken if those names are later to -be used with \fBfile join\fR, to avoid them being interpreted as -absolute paths pointing to a given user's home directory. .SH "WINDOWS PORTABILITY ISSUES" .PP For Windows UNC names, the servername and sharename components of the path diff --git a/doc/interp.n b/doc/interp.n index 08bed1c..7037c65 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -375,10 +375,6 @@ Returns a Tcl list of the names of all the child interpreters associated with the interpreter identified by \fIpath\fR. If \fIpath\fR is omitted, the invoking interpreter is used. .TP -\fBinterp\fR \fBslaves\fR ?\fIpath\fR? -. -Synonym for . \fBinterp\fR \fBchildren\fR ?\fIpath\fR? -.TP \fBinterp\fR \fBtarget\fR \fIpath alias\fR . Returns a Tcl list describing the target interpreter for an alias. The @@ -38,17 +38,14 @@ Tcl interpreter. The name of the initialization procedure is determined by \fIprefix\fR and whether or not the target interpreter is a safe one. For normal interpreters the name of the initialization -procedure will have the form \fIpfx\fB_Init\fR, where \fIpfx\fR -is the same as \fIprefix\fR except that the first letter is -converted to upper case and all other letters -are converted to lower case. For example, if \fIprefix\fR is -\fBfoo\fR or \fBFOo\fR, the initialization procedure's name will +procedure will have the form \fIprefix\fB_Init\fR. For example, if +\fIprefix\fR is \fBFoo\fR, the initialization procedure's name will be \fBFoo_Init\fR. .PP If the target interpreter is a safe interpreter, then the name -of the initialization procedure will be \fIpfx\fB_SafeInit\fR -instead of \fIpfx\fB_Init\fR. -The \fIpfx\fB_SafeInit\fR function should be written carefully, so that it +of the initialization procedure will be \fIprefix\fB_SafeInit\fR +instead of \fIprefix\fB_Init\fR. +The \fIprefix\fB_SafeInit\fR function should be written carefully, so that it initializes the safe interpreter only with partial functionality provided by the library that is safe for use by untrusted code. For more information on Safe\-Tcl, see the \fBsafe\fR manual entry. @@ -84,13 +81,11 @@ If \fIfileName\fR is an empty string, then \fIprefix\fR must be specified. .PP If \fIprefix\fR is omitted or specified as an empty string, -Tcl tries to guess the prefix. This may be done differently on -different platforms. The default guess, which is used on most -UNIX platforms, is to take the last element of +Tcl tries to guess the prefix by taking the last element of \fIfileName\fR, strip off the first three characters if they -are \fBlib\fR, then strip off the next three characters if they -are \fBtcl\fR, and use any following alphabetic and -underline characters, converted to titlecase as the prefix. +are \fBlib\fR, then strip off the next three characters if +they are \fBtcl9\fR, and use any following wordchars but not digits, +converted to titlecase as the prefix. For example, the command \fBload libxyz4.2.so\fR uses the prefix \fBXyz\fR and the command \fBload bin/last.so {}\fR uses the prefix \fBLast\fR. diff --git a/doc/lsearch.n b/doc/lsearch.n index dc6d1f7..c8d2ec9 100644 --- a/doc/lsearch.n +++ b/doc/lsearch.n @@ -65,8 +65,8 @@ These options may be given with all matching styles. . Changes the result to be the list of all matching indices (or all matching values if \fB\-inline\fR is specified as well.) If indices are returned, the -indices will be in numeric order. If values are returned, the order of the -values will be the order of those values within the input \fIlist\fR. +indices will be in ascending numeric order. If values are returned, the order +of the values will be the order of those values within the input \fIlist\fR. .TP \fB\-inline\fR . @@ -116,6 +116,8 @@ The indicated return value also becomes the new value of \fIx\fR \fBlset\fR x {2 1} j \fI\(-> {a b c} {d e f} {g j i}\fR \fBlset\fR x {2 3} j + \fI\(-> {a b c} {d e f} {g h i j}\fR +\fBlset\fR x {2 4} j \fI\(-> list index out of range\fR .CE .PP diff --git a/doc/mathfunc.n b/doc/mathfunc.n index 004b7e3..805cf82 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -124,10 +124,7 @@ of which work solely with floating-point numbers unless otherwise noted: In addition to these predefined functions, applications may define additional functions by using \fBproc\fR (or any other method, such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define -new commands in the \fBtcl::mathfunc\fR namespace. In addition, an -obsolete interface named \fBTcl_CreateMathFunc\fR() is available to -extensions that are written in C. The latter interface is not recommended -for new implementations. +new commands in the \fBtcl::mathfunc\fR namespace. .SS "DETAILED DEFINITIONS" .TP \fBabs \fIarg\fR diff --git a/doc/memory.n b/doc/memory.n index 4d6a7d1..dc58502 100644 --- a/doc/memory.n +++ b/doc/memory.n @@ -25,7 +25,7 @@ Write a list of all currently allocated memory to the specified \fIfile\fR. .TP \fBmemory break_on_malloc\fR \fIcount\fR . -After the \fIcount\fR allocations have been performed, \fBckalloc\fR +After the \fIcount\fR allocations have been performed, \fBTcl_Alloc\fR outputs a message to this effect and that it is now attempting to enter the C debugger. Tcl will then issue a \fISIGINT\fR signal against itself. If you are running Tcl under a C debugger, it should then enter the debugger @@ -35,8 +35,8 @@ command mode. . Returns a report containing the total allocations and frees since Tcl began, the current packets allocated (the current -number of calls to \fBckalloc\fR not met by a corresponding call -to \fBckfree\fR), the current bytes allocated, and the maximum number +number of calls to \fBTcl_Alloc\fR not met by a corresponding call +to \fBTcl_Free\fR), the current bytes allocated, and the maximum number of packets and bytes allocated. .TP \fBmemory init \fR[\fBon\fR|\fBoff\fR] @@ -59,34 +59,34 @@ that memory is properly cleaned up during process exit. .TP \fBmemory tag\fR \fIstring\fR . -Each packet of memory allocated by \fBckalloc\fR can have associated +Each packet of memory allocated by \fBTcl_Alloc\fR can have associated with it a string-valued tag. In the lists of allocated memory generated by \fBmemory active\fR and \fBmemory onexit\fR, the tag for each packet is printed along with other information about the packet. The \fBmemory tag\fR command sets the tag value for subsequent calls -to \fBckalloc\fR to be \fIstring\fR. +to \fBTcl_Alloc\fR to be \fIstring\fR. .TP \fBmemory trace \fR[\fBon\fR|\fBoff\fR] . Turns memory tracing on or off. When memory tracing is on, every call -to \fBckalloc\fR causes a line of trace information to be written to -\fIstderr\fR, consisting of the word \fIckalloc\fR, followed by the +to \fBTcl_Alloc\fR causes a line of trace information to be written to +\fIstderr\fR, consisting of the word \fITcl_Alloc\fR, followed by the address returned, the amount of memory allocated, and the C filename and line number of the code performing the allocation. For example: .RS .PP .CS -ckalloc 40e478 98 tclProc.c 1406 +Tcl_Alloc 40e478 98 tclProc.c 1406 .CE .PP -Calls to \fBckfree\fR are traced in the same manner. +Calls to \fBTcl_Free\fR are traced in the same manner. .RE .TP \fBmemory trace_on_at_malloc\fR \fIcount\fR . -Enable memory tracing after \fIcount\fR \fBckalloc\fRs have been performed. +Enable memory tracing after \fIcount\fR \fBTcl_Alloc\fRs have been performed. For example, if you enter \fBmemory trace_on_at_malloc 100\fR, -after the 100th call to \fBckalloc\fR, memory trace information will begin +after the 100th call to \fBTcl_Alloc\fR, memory trace information will begin being displayed for all allocations and frees. Since there can be a lot of memory activity before a problem occurs, judicious use of this option can reduce the slowdown caused by tracing (and the amount of trace information @@ -97,17 +97,17 @@ occurred since Tcl started is printed on a guard zone failure. \fBmemory validate \fR[\fBon\fR|\fBoff\fR] . Turns memory validation on or off. When memory validation is enabled, -on every call to \fBckalloc\fR or \fBckfree\fR, the guard zones are +on every call to \fBTcl_Alloc\fR or \fBTcl_Free\fR, the guard zones are checked for every piece of memory currently in existence that was -allocated by \fBckalloc\fR. This has a large performance impact and +allocated by \fBTcl_Alloc\fR. This has a large performance impact and should only be used when overwrite problems are strongly suspected. The advantage of enabling memory validation is that a guard zone -overwrite can be detected on the first call to \fBckalloc\fR or -\fBckfree\fR after the overwrite occurred, rather than when the +overwrite can be detected on the first call to \fBTcl_Alloc\fR or +\fBTcl_Free\fR after the overwrite occurred, rather than when the specific memory with the overwritten guard zone(s) is freed, which may occur long after the overwrite occurred. .SH "SEE ALSO" -ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG +Tcl_Alloc, Tcl_Free, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG .SH KEYWORDS memory, debug '\"Local Variables: diff --git a/doc/re_syntax.n b/doc/re_syntax.n index ef8c570..f68135e 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -390,7 +390,7 @@ value of \fBU+\fI10ffff\fR. .TP \fB\ev\fR . -vertical tab, as in C are all available. +vertical tab, as in C .TP \fB\ex\fIhh\fR . @@ -224,12 +224,10 @@ set string "#08D03F" \fBscan\fR $string "#%2x%2x%2x" r g b .CE .PP -Parse a \fIHH:MM\fR time string, noting that this avoids problems with -octal numbers by forcing interpretation as decimals (if we did not -care, we would use the \fB%i\fR conversion instead): +Parse a \fIHH:MM\fR time string: .PP .CS -set string "08:08" ;# *Not* octal! +set string "08:08" if {[\fBscan\fR $string "%d:%d" hours minutes] != 2} { error "not a valid time string" } diff --git a/doc/string.n b/doc/string.n index aefe485..5c493f5 100644 --- a/doc/string.n +++ b/doc/string.n @@ -383,42 +383,8 @@ for which \fBstring is space\fR returns 1, and "\e0"). These subcommands are currently supported, but are likely to go away in a future release as their functionality is either virtually never used or highly misleading. -.TP -\fBstring bytelength \fIstring\fR -. -Returns a decimal string giving the number of bytes used to represent -\fIstring\fR in memory when encoded as Tcl's internal modified UTF\-8; -Tcl may use other encodings for \fIstring\fR as well, and does not -guarantee to only use a single encoding for a particular \fIstring\fR. -Because UTF\-8 uses a variable number of bytes to represent Unicode -characters, the byte length will not be the same as the character -length in general. The cases where a script cares about the byte -length are rare. .RS .PP -In almost all cases, you should use the -\fBstring length\fR operation (including determining the length of a -Tcl byte array value). Refer to the \fBTcl_NumUtfChars\fR manual -entry for more details on the UTF\-8 representation. -.PP -Formally, the \fBstring bytelength\fR operation returns the content of -the \fIlength\fR field of the \fBTcl_Obj\fR structure, after calling -\fBTcl_GetString\fR to ensure that the \fIbytes\fR field is populated. -This is highly unlikely to be useful to Tcl scripts, as Tcl's internal -encoding is not strict UTF\-8, but rather a modified WTF\-8 with a -denormalized NUL (identical to that used in a number of places by -Java's serialization mechanism) to enable basic processing with -non-Unicode-aware C functions. As this representation should only -ever be used by Tcl's implementation, the number of bytes used to -store the representation is of very low value (except to C extension -code, which has direct access for the purpose of memory management, -etc.) -.PP -\fICompatibility note:\fR This subcommand is deprecated and will -be removed in Tcl 9.0. It is better to use the \fBencoding convertto\fR -command to convert a string to a known encoding (e.g. "utf-8" or "cesu-8") -and then apply \fBstring length\fR to that. -.PP .CS \fBstring length\fR [encoding convertto utf-8 $theString] .CE diff --git a/doc/tclvars.n b/doc/tclvars.n index 4d1413c..8214473 100644 --- a/doc/tclvars.n +++ b/doc/tclvars.n @@ -10,7 +10,7 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_precision, tcl_rcFileName, tcl_traceCompile, tcl_traceExec, tcl_wordchars, tcl_version \- Variables used by Tcl +argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_rcFileName, tcl_traceCompile, tcl_traceExec, tcl_wordchars, tcl_version \- Variables used by Tcl .BE .SH DESCRIPTION .PP @@ -354,70 +354,6 @@ This gives the size of the native-machine word in bytes (strictly, it is same as the result of evaluating \fIsizeof(long)\fR in C.) .RE .TP -\fBtcl_precision\fR -. -This variable controls the number of digits to generate -when converting floating-point values to strings. It defaults -to 0. \fIApplications should not change this value;\fR it is -provided for compatibility with legacy code. -.PP -.RS -The default value of 0 is special, meaning that Tcl should -convert numbers using as few digits as possible while still -distinguishing any floating point number from its nearest -neighbours. It differs from using an arbitrarily high value -for \fItcl_precision\fR in that an inexact number like \fI1.4\fR -will convert as \fI1.4\fR rather than \fI1.3999999999999999\fR -even though the latter is nearer to the exact value of the -binary number. -.RE -.PP -.RS -If \fBtcl_precision\fR is not zero, then when Tcl converts a floating -point number, it creates a decimal representation of at most -\fBtcl_precision\fR significant digits; the result may be shorter if -the shorter result represents the original number exactly. If no -result of at most \fBtcl_precision\fR digits is an exact representation -of the original number, the one that is closest to the original -number is chosen. -If the original number lies precisely between two equally accurate -decimal representations, then the one with an even value for the least -significant digit is chosen; for instance, if \fBtcl_precision\fR is 3, then -0.3125 will convert to 0.312, not 0.313, while 0.6875 will convert to -0.688, not 0.687. Any string of trailing zeroes that remains is trimmed. -.RE -.PP -.RS -a \fBtcl_precision\fR value of 17 digits is -.QW perfect -for IEEE floating-point in that it allows -double-precision values to be converted to strings and back to -binary with no loss of information. For this reason, you will often -see it as a value in legacy code that must run on Tcl versions before -8.5. It is no longer recommended; as noted above, a zero value is the -preferred method. -.RE -.PP -.RS -All interpreters in a thread share a single \fBtcl_precision\fR value: -changing it in one interpreter will affect all other interpreters as -well. Safe interpreters are not allowed to modify the -variable. -.RE -.PP -.RS -Valid values for \fBtcl_precision\fR range from 0 to 17. -.RE -.TP -\fBtcl_rcFileName\fR -. -This variable is used during initialization to indicate the name of a -user-specific startup file. If it is set by application-specific -initialization, then the Tcl startup code will check for the existence -of this file and \fBsource\fR it if it exists. For example, for \fBwish\fR -the variable is set to \fB~/.wishrc\fR for Unix and \fB~/wishrc.tcl\fR -for Windows. -.TP \fBtcl_traceCompile\fR . The value of this variable can be set to control diff --git a/doc/trace.n b/doc/trace.n index 570b263..959acc2 100644 --- a/doc/trace.n +++ b/doc/trace.n @@ -229,18 +229,18 @@ When the trace triggers, three arguments are appended to \fIcommandPrefix name1 name2 op\fR .CE .PP -\fIName1\fR and \fIname2\fR give the name(s) for the variable -being accessed: if the variable is a scalar then \fIname1\fR -gives the variable's name and \fIname2\fR is an empty string; -if the variable is an array element then \fIname1\fR gives the -name of the array and name2 gives the index into the array; -if an entire array is being deleted and the trace was registered +\fIName1\fR gives the name for the variable being accessed. +This is not necessarily the same as the name used in the +\fBtrace variable\fR command: the \fBupvar\fR command allows a +procedure to reference a variable under a different name. +If the trace was originally set on an array or array element, +\fIname2\fR provides which index into the array was affected. +This information is present even when \fIname1\fR refers to a +scalar, which may happen if the \fBupvar\fR command was used to +create a reference to a single array element. +If an entire array is being deleted and the trace was registered on the overall array, rather than a single element, then \fIname1\fR gives the array name and \fIname2\fR is an empty string. -\fIName1\fR and \fIname2\fR are not necessarily the same as the -name used in the \fBtrace variable\fR command: the \fBupvar\fR -command allows a procedure to reference a variable under a -different name. \fIOp\fR indicates what operation is being performed on the variable, and is one of \fBread\fR, \fBwrite\fR, or \fBunset\fR as defined above. diff --git a/doc/unload.n b/doc/unload.n index 00b709b..d5bbde8 100644 --- a/doc/unload.n +++ b/doc/unload.n @@ -123,8 +123,8 @@ different platforms. The default guess, which is used on most UNIX platforms, is to take the last element of \fIfileName\fR, strip off the first three characters if they are \fBlib\fR, then strip off the next three characters if they -are \fBtcl\fR, and use any following alphabetic and -underline characters, converted to titlecase as the prefix. +are \fBtcl9\fR, and use any following wordchars but not digits, +converted to titlecase as the prefix. For example, the command \fBunload libxyz4.2.so\fR uses the prefix \fBXyz\fR and the command \fBunload bin/last.so {}\fR uses the prefix \fBLast\fR. diff --git a/doc/upvar.n b/doc/upvar.n index 91defe6..b0324b2 100644 --- a/doc/upvar.n +++ b/doc/upvar.n @@ -98,11 +98,9 @@ trace variable originalVar w \fItraceproc\fR \fIsetByUpvar\fR originalVar 2 .CE .PP -If \fIotherVar\fR refers to an element of an array, then variable -traces set for the entire array will not be invoked when \fImyVar\fR -is accessed (but traces on the particular element will still be -invoked). In particular, if the array is \fBenv\fR, then changes -made to \fImyVar\fR will not be passed to subprocesses correctly. +If \fIotherVar\fR refers to an element of an array, then the element +name is passed as the second argument to the trace procedure. This +may be important information in case of traces set on an entire array. .SH EXAMPLE A \fBdecr\fR command that works like \fBincr\fR except it subtracts the value from the variable instead of adding it: diff --git a/doc/zipfs.3 b/doc/zipfs.3 index 3b13cd9..4d62ddf 100644 --- a/doc/zipfs.3 +++ b/doc/zipfs.3 @@ -87,8 +87,8 @@ it uses WCHAR instead of char. As a result, it requires your application to be compiled with the UNICODE preprocessor symbol defined (e.g., via the \fB-DUNICODE\fR compiler flag). .PP -The result of \fBTclZipfs_AppHook\fR is the full Tcl version (e.g., -\fB8.7.0+abcdef...abcdef.gcc-1002.utf16\fR). +The result of \fBTclZipfs_AppHook\fR is the full Tcl version with build +information (e.g., \fB9.0.0+abcdef...abcdef.gcc-1002\fR). The function \fImay\fR modify the variables pointed to by \fIargcPtr\fR and \fIargvPtr\fR to remove arguments; the current implementation does not do so, but callers \fIshould not\fR assume that this will be true in the future. |