diff options
Diffstat (limited to 'doc')
176 files changed, 1829 insertions, 2113 deletions
diff --git a/doc/Access.3 b/doc/Access.3 index 80b76a4..aaca223 100644 --- a/doc/Access.3 +++ b/doc/Access.3 @@ -18,6 +18,7 @@ int .sp int \fBTcl_Stat\fR(\fIpath\fR, \fIstatPtr\fR) +.fi .SH ARGUMENTS .AS "struct stat" *statPtr out .AP "const char" *path in diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index fd36aab..2ed5eee 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -9,11 +9,11 @@ .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 -.sp + Tcl_Obj * \fBTcl_GetReturnOptions\fR(\fIinterp, code\fR) .sp @@ -30,8 +30,7 @@ int .sp \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *)NULL\fR) .sp -\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR) -.sp +int \fBTcl_GetErrorLine\fR(\fIinterp\fR) .sp \fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR) @@ -39,8 +38,8 @@ int const char * \fBTcl_PosixError\fR(\fIinterp\fR) .sp -void \fBTcl_LogCommandInfo\fR(\fIinterp, script, command, commandLength\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp commandLength .AP Tcl_Interp *interp in @@ -60,7 +59,7 @@ unless \fIlength\fR is negative. .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 Tcl_Size 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. @@ -69,9 +68,6 @@ The \fB\-errorcode\fR return option will be set to this value. .AP "const char" *element in String to record as one element of the \fB\-errorcode\fR return option. Last \fIelement\fR argument must be (char *)NULL. -.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 lineNum The line number of a script where an error occurred. .AP "const char" *script in @@ -80,8 +76,9 @@ Pointer to first character in script containing command .AP "const char" *command in Pointer to first character in the command that generated the error; must point within the string given by \fIscript\fR. -.AP int commandLength in -Number of bytes in command; -1 means use all bytes up to first null byte +.AP Tcl_Size commandLength in +Number of bytes in command; a negative value means use all bytes up to the +first null byte. .BE .SH DESCRIPTION .PP @@ -247,12 +244,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 ddc1e46..999c1e8 100644 --- a/doc/Alloc.3 +++ b/doc/Alloc.3 @@ -4,52 +4,36 @@ '\" 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 .sp -char * +void * \fBTcl_Alloc\fR(\fIsize\fR) .sp -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) +.fi .SH ARGUMENTS .AS char *size -.AP "unsigned int" size in +.AP "size_t" size in Size in bytes of the memory block to allocate. -.AP char *ptr in +.AP void *ptr in Pointer to memory block to free or realloc. .AP Tcl_DString *dsPtr in Initialized DString pointer. @@ -84,18 +68,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. .PP \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..a5e9aa2 100644 --- a/doc/AllowExc.3 +++ b/doc/AllowExc.3 @@ -15,6 +15,7 @@ Tcl_AllowExceptions \- allow all exceptions in next script evaluation \fB#include <tcl.h>\fR .sp \fBTcl_AllowExceptions\fR(\fIinterp\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in @@ -30,8 +31,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/AppInit.3 b/doc/AppInit.3 index 44b2d6b..e61d188 100644 --- a/doc/AppInit.3 +++ b/doc/AppInit.3 @@ -16,6 +16,7 @@ Tcl_AppInit \- perform application-specific initialization .sp int \fBTcl_AppInit\fR(\fIinterp\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in diff --git a/doc/AssocData.3 b/doc/AssocData.3 index d4fa3d7..c1ca24c 100644 --- a/doc/AssocData.3 +++ b/doc/AssocData.3 @@ -13,12 +13,13 @@ 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) .sp \fBTcl_DeleteAssocData\fR(\fIinterp, key\fR) +.fi .SH ARGUMENTS .AS Tcl_InterpDeleteProc **delProcPtr .AP Tcl_Interp *interp in @@ -31,7 +32,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 +65,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..493c000 100644 --- a/doc/Async.3 +++ b/doc/Async.3 @@ -31,11 +31,12 @@ void .sp int \fBTcl_AsyncReady\fR() +.fi .SH ARGUMENTS .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 +96,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/BackgdErr.3 b/doc/BackgdErr.3 index adbe33c..4340e4d 100644 --- a/doc/BackgdErr.3 +++ b/doc/BackgdErr.3 @@ -17,6 +17,7 @@ Tcl_BackgroundException, Tcl_BackgroundError \- report Tcl exception that occurr \fBTcl_BackgroundException\fR(\fIinterp, code\fR) .sp \fBTcl_BackgroundError\fR(\fIinterp\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in 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/BoolObj.3 b/doc/BoolObj.3 index 71580af..de2a66b 100644 --- a/doc/BoolObj.3 +++ b/doc/BoolObj.3 @@ -24,6 +24,7 @@ int .sp int \fBTcl_GetBoolFromObj\fR(\fIinterp, objPtr, flags. charPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp intValue in/out .AP int intValue in diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3 index e21bc81..ae1a79c 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 @@ -16,7 +16,6 @@ Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetBytesFromObj, Tcl_GetByteArrayF Tcl_Obj * \fBTcl_NewByteArrayObj\fR(\fIbytes, numBytes\fR) .sp -void \fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, numBytes\fR) .sp .VS TIP568 @@ -29,13 +28,14 @@ unsigned char * .sp unsigned char * \fBTcl_SetByteArrayLength\fR(\fIobjPtr, numBytes\fR) +.fi .SH ARGUMENTS .AS "const unsigned char" *numBytesPtr in/out .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 Tcl_Size 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,11 +43,14 @@ 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 int *numBytesPtr out +.AP "Tcl_Size \&| 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. +May be (Tcl_Size *)NULL when not used. If it points to a variable which +type is not \fBTcl_Size\fR, a compiler warning will be generated. +If your extensions is compiled with -DTCL_8_API, this function will return +NULL for byte arrays larger than INT_MAX (which should +trigger proper error-handling), otherwise expect it to crash. .BE - .SH DESCRIPTION .PP These routines are used to create, modify, store, transfer, and retrieve @@ -92,11 +95,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,27 +119,12 @@ 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. -.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. +\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 On success, both \fBTcl_GetBytesFromObj\fR and \fBTcl_GetByteArrayFromObj\fR return a pointer into the internal representation of a \fBTcl_Obj\fR. @@ -153,7 +136,15 @@ and any string representation is invalidated. .PP 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. +to the space pointed to by \fInumBytesPtr\fR. This space may be of type +\fBTcl_Size\fR or of type \fBint\fR. It is recommended that callers provide +a \fBTcl_Size\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 @@ -166,8 +157,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 d8fab2a..418998e 100644 --- a/doc/CallDel.3 +++ b/doc/CallDel.3 @@ -17,13 +17,14 @@ Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interp \fBTcl_CallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR) .sp \fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR) +.fi .SH ARGUMENTS .AS Tcl_InterpDeleteProc clientData .AP Tcl_Interp *interp in Interpreter with which to associated callback. .AP Tcl_InterpDeleteProc *proc in Procedure to call when \fIinterp\fR is deleted. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -38,7 +39,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 027fb09..72dd939 100644 --- a/doc/Cancel.3 +++ b/doc/Cancel.3 @@ -17,6 +17,7 @@ int .sp int \fBTcl_Canceled\fR(\fIinterp, flags\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in @@ -30,7 +31,7 @@ OR'ed 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..ba7bc48 100644 --- a/doc/ChnlStack.3 +++ b/doc/ChnlStack.3 @@ -11,7 +11,6 @@ Tcl_StackChannel, Tcl_UnstackChannel, Tcl_GetStackedChannel, Tcl_GetTopChannel \- manipulate stacked I/O channels .SH SYNOPSIS .nf -.nf \fB#include <tcl.h>\fR .sp Tcl_Channel @@ -25,14 +24,14 @@ Tcl_Channel .sp Tcl_Channel \fBTcl_GetTopChannel\fR(\fIchannel\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_ChannelType clientData .AP Tcl_Interp *interp in 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 +48,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..ed549c0 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) @@ -63,8 +63,9 @@ Tcl_Class Tcl_Obj * \fBTcl_GetObjectClassName\fR(\fIinterp\fR, \fIobject\fR) .VE "TIP 605" +.fi .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 +82,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 Tcl_Size 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 Tcl_Size 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 +94,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 +201,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 +214,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/CmdCmplt.3 b/doc/CmdCmplt.3 index bb7532c..2c18efe 100644 --- a/doc/CmdCmplt.3 +++ b/doc/CmdCmplt.3 @@ -16,6 +16,7 @@ Tcl_CommandComplete \- Check for unmatched braces in a Tcl command .sp int \fBTcl_CommandComplete\fR(\fIcmd\fR) +.fi .SH ARGUMENTS .AS "const char" *cmd .AP "const char" *cmd in diff --git a/doc/Concat.3 b/doc/Concat.3 index e853fc3..5357dae 100644 --- a/doc/Concat.3 +++ b/doc/Concat.3 @@ -16,9 +16,10 @@ Tcl_Concat \- concatenate a collection of strings .sp const char * \fBTcl_Concat\fR(\fIargc, argv\fR) +.fi .SH ARGUMENTS .AS "const char *const" argv[] -.AP int argc in +.AP Tcl_Size 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 5f527ce..ba2e415 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_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 @@ -49,10 +37,6 @@ int objc, objv\fR) .sp int -\fBTcl_GetAlias\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr, - argcPtr, argvPtr\fR) -.sp -int \fBTcl_GetAliasObj\fR(\fIinterp, childCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr\fR) .sp @@ -61,6 +45,7 @@ int .sp int \fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR) +.fi .SH ARGUMENTS .AS "const char *const" **targetInterpPtr out .AP Tcl_Interp *interp in @@ -81,12 +66,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 Tcl_Size 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 Tcl_Size 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 @@ -98,16 +83,13 @@ command is defined for an alias. .AP "const char" **targetCmdPtr out Pointer to location to store the address of the name of the target command for an alias. -.AP int *argcPtr out -Pointer to location to store count of additional arguments to be passed to -the alias. The location is in storage owned by the caller. -.AP "const char" ***argvPtr out -Pointer to location to store a vector of strings, the additional arguments -to pass to an alias. The location is in storage owned by the caller, the -vector of strings is owned by the called function. -.AP int *objcPtr out +.AP "Tcl_Size \&| int" *objcPtr out Pointer to location to store count of additional value arguments to be passed to the alias. The location is in storage owned by the caller. +If it points to a variable which type is not \fBTcl_Size\fR, a compiler +warning will be generated. If your extensions is compiled with -DTCL_8_API, +this function will return TCL_ERROR for aliases with more than INT_MAX +value arguments, otherwise expect it to crash .AP Tcl_Obj ***objvPtr out Pointer to location to store a vector of Tcl_Obj structures, the additional arguments to pass to an alias command. The location is in storage @@ -142,38 +124,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 @@ -206,10 +169,6 @@ non\-\fBNULL\fR, the address indicated is set to the corresponding datum. For example, if \fItargetCmdPtr\fR is non\-\fBNULL\fR it is set to a pointer to the string containing the name of the target command. .PP -\fBTcl_GetAlias\fR is similar to \fBTcl_GetAliasObj\fR except that it -returns a pointer to a vector of string instead of a vector of -Tcl_Obj structures. \fBTcl_GetAlias\fR is deprecated. -.PP \fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from the set of hidden commands to the set of exposed commands, putting it under the name diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3 index 2a2169f..3c622f2 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 * @@ -59,13 +59,10 @@ int int \fBTcl_IsChannelExisting\fR(\fIchannelName\fR) .sp -void \fBTcl_CutChannel\fR(\fIchannel\fR) .sp -void \fBTcl_SpliceChannel\fR(\fIchannel\fR) .sp -void \fBTcl_ClearChannelHandlers\fR(\fIchannel\fR) .sp int @@ -80,9 +77,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 +86,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 @@ -121,7 +112,7 @@ Tcl_DriverFlushProc * .sp Tcl_DriverHandlerProc * \fBTcl_ChannelHandlerProc\fR(\fItypePtr\fR) -.sp +.fi .SH ARGUMENTS .AS "const Tcl_ChannelType" *channelName .AP "const Tcl_ChannelType" *typePtr in @@ -133,7 +124,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 +135,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 Tcl_Size 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 +293,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 +319,10 @@ The \fBTcl_ChannelType\fR structure contains the following fields: typedef struct { 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 +351,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, @@ -387,25 +374,9 @@ a pointer to the string. .SS VERSION .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 @@ -414,7 +385,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 @@ -441,22 +412,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 @@ -465,35 +437,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 @@ -502,7 +459,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); @@ -546,7 +503,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); @@ -576,17 +533,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 @@ -605,30 +562,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 @@ -637,7 +572,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); @@ -678,7 +613,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); @@ -716,7 +651,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 @@ -747,9 +682,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 @@ -776,7 +711,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 @@ -791,7 +726,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 @@ -820,7 +755,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 @@ -837,7 +772,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 @@ -885,58 +820,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..5b0e724 100644 --- a/doc/CrtChnlHdlr.3 +++ b/doc/CrtChnlHdlr.3 @@ -12,15 +12,12 @@ Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler \- call a procedure when a channel becomes readable or writable .SH SYNOPSIS .nf -.nf \fB#include <tcl.h>\fR .sp -void \fBTcl_CreateChannelHandler\fR(\fIchannel, mask, proc, clientData\fR) .sp -void \fBTcl_DeleteChannelHandler\fR(\fIchannel, proc, clientData\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_ChannelProc clientData .AP Tcl_Channel channel in @@ -29,10 +26,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 +45,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..cd59e8a 100644 --- a/doc/CrtCloseHdlr.3 +++ b/doc/CrtCloseHdlr.3 @@ -14,19 +14,17 @@ Tcl_CreateCloseHandler, Tcl_DeleteCloseHandler \- arrange for callbacks when cha .nf \fB#include <tcl.h>\fR .sp -void \fBTcl_CreateCloseHandler\fR(\fIchannel, proc, clientData\fR) .sp -void \fBTcl_DeleteCloseHandler\fR(\fIchannel, proc, clientData\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_CloseProc clientData .AP Tcl_Channel channel in The channel for which to create or delete a close callback. .AP Tcl_CloseProc *proc in The procedure to call as the callback. -.AP ClientData clientData in +.AP void *clientData in Arbitrary one-word value to pass to \fIproc\fR. .BE .SH DESCRIPTION @@ -38,7 +36,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 d15a920..5d25667 100644 --- a/doc/CrtCommand.3 +++ b/doc/CrtCommand.3 @@ -102,9 +102,12 @@ version 8.1 of Tcl. .PP \fIProc\fR must return an integer code that is expected to be one of \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or -\fBTCL_CONTINUE\fR. See the Tcl overview man page -for details on what these codes mean. Most normal commands will only -return \fBTCL_OK\fR or \fBTCL_ERROR\fR. In addition, \fIproc\fR must set +\fBTCL_CONTINUE\fR. See the \fBreturn\fR man page for details on +what these codes mean and the use of extended values for an extension's +private use. Most normal commands will only return \fBTCL_OK\fR +or \fBTCL_ERROR\fR. +.PP +In addition, \fIproc\fR must set the interpreter result; in the case of a \fBTCL_OK\fR return code this gives the result of the command, and in the case of \fBTCL_ERROR\fR it gives an error message. diff --git a/doc/CrtFileHdlr.3 b/doc/CrtFileHdlr.3 index f1b8df7..65a6794 100644 --- a/doc/CrtFileHdlr.3 +++ b/doc/CrtFileHdlr.3 @@ -17,6 +17,7 @@ Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks wi \fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR) .sp \fBTcl_DeleteFileHandler\fR(\fIfd\fR) +.fi .SH ARGUMENTS .AS Tcl_FileProc clientData .AP int fd in @@ -29,7 +30,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 +52,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/CrtInterp.3 b/doc/CrtInterp.3 index aacb868..159fb12 100644 --- a/doc/CrtInterp.3 +++ b/doc/CrtInterp.3 @@ -24,6 +24,7 @@ int .sp int \fBTcl_InterpActive\fR(\fIinterp\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in 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 bcb8c86..b28d901 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -40,12 +40,11 @@ int const char * \fBTcl_GetCommandName\fR(\fIinterp, token\fR) .sp -void \fBTcl_GetCommandFullName\fR(\fIinterp, token, objPtr\fR) .sp Tcl_Command \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_CmdDeleteProc *deleteProc in/out .AP Tcl_Interp *interp in @@ -58,7 +57,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 +100,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[]); @@ -133,9 +132,10 @@ that \fIobjv\fR[\fB2\fR] points at, but will not change where .PP \fIproc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. -See the Tcl overview man page -for details on what these codes mean. Most normal commands will only -return \fBTCL_OK\fR or \fBTCL_ERROR\fR. +See the \fBreturn\fR man page for details on what these codes mean and the +use of extended values for an extension's private use. Most normal commands +will only return \fBTCL_OK\fR or \fBTCL_ERROR\fR. +.PP In addition, if \fIproc\fR needs to return a non-empty result, it can call \fBTcl_SetObjResult\fR to set the interpreter's result. In the case of a \fBTCL_OK\fR return code this gives the result @@ -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, Tcl_Size \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. Note also that neither \fBTcl_SetCommandInfo\fR nor \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace. Use \fBTcl_Eval\fR to call the \fBrename\fR command to do that. diff --git a/doc/CrtTimerHdlr.3 b/doc/CrtTimerHdlr.3 index c229a23..eeeea77 100644 --- a/doc/CrtTimerHdlr.3 +++ b/doc/CrtTimerHdlr.3 @@ -18,13 +18,14 @@ Tcl_TimerToken \fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR) .sp \fBTcl_DeleteTimerHandler\fR(\fItoken\fR) +.fi .SH ARGUMENTS .AS Tcl_TimerToken milliseconds .AP int milliseconds in How many milliseconds to wait before invoking \fIproc\fR. .AP Tcl_TimerProc *proc in Procedure to invoke after \fImilliseconds\fR have elapsed. -.AP ClientData clientData in +.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 +52,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 519f348..8e4b92f 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -25,11 +25,12 @@ Tcl_Trace \fBTcl_CreateObjTrace2\fR(\fIinterp, level, flags, objProc2, clientData, deleteProc\fR) .sp \fBTcl_DeleteTrace\fR(\fIinterp, trace\fR) +.fi .SH ARGUMENTS .AS Tcl_CmdObjTraceDeleteProc *deleteProc .AP Tcl_Interp *interp in Interpreter containing command to be traced or untraced. -.AP int level in +.AP Tcl_Size 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 +98,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 33dd297..7265898 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, Tcl_DStringToObj \- 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, Tcl_DStringToObj \- manipulate dynamic strings .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -26,7 +26,7 @@ char * .sp \fBTcl_DStringEndSublist\fR(\fIdsPtr\fR) .sp -int +Tcl_Size \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) @@ -44,6 +42,7 @@ char * .sp Tcl_Obj * \fBTcl_DStringToObj\fR(\fIdsPtr\fR) +.fi .sp .SH ARGUMENTS .AS Tcl_DString newLength in/out @@ -53,10 +52,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 Tcl_Size length in +Number of bytes from \fIbytes\fR to add to dynamic string. If negative, add all characters up to null terminating character. -.AP int newLength in +.AP Tcl_Size newLength in New length for dynamic string, not including null terminating character. .AP Tcl_Interp *interp in/out @@ -132,10 +131,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. @@ -148,7 +143,8 @@ This saves the cost of allocating new memory and copying the string. an empty string. Since the dynamic string is reinitialized, there is no need to further call \fBTcl_DStringFree\fR on it and it can be reused without -calling \fBTcl_DStringInit\fR. +calling \fBTcl_DStringInit\fR. The caller must ensure that the dynamic +string stored in \fIdsPtr\fR is encoded in Tcl's internal UTF-8 format. .PP \fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR. It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and @@ -156,15 +152,15 @@ it clears \fIinterp\fR's result. If possible it does this by moving a pointer rather than by copying the string. .PP -\fBTcl_DStringToObj\fR returns a \fBTcl_Obj\fR containing the value of -the dynamic string given by \fIdsPtr\fR. It does this by moving -a pointer from \fIdsPtr\fR to a newly allocated \fBTcl_Obj\fR -and reinitializing to dynamic string to an empty string. -This saves the cost of allocating new memory and copying the string. -Since the dynamic string is reinitialized, there is no need to -further call \fBTcl_DStringFree\fR on it and it can be reused without -calling \fBTcl_DStringInit\fR. -The returned \fBTcl_Obj\fR has a reference count of 0. +\fBTcl_DStringToObj\fR returns a \fBTcl_Obj\fR containing the value of the +dynamic string given by \fIdsPtr\fR. It does this by moving a pointer from +\fIdsPtr\fR to a newly allocated \fBTcl_Obj\fR and reinitializing to dynamic +string to an empty string. This saves the cost of allocating new memory and +copying the string. Since the dynamic string is reinitialized, there is no need +to further call \fBTcl_DStringFree\fR on it and it can be reused without calling +\fBTcl_DStringInit\fR. The returned \fBTcl_Obj\fR has a reference count of 0. +The caller must ensure that the dynamic string stored in \fIdsPtr\fR is encoded +in Tcl's internal UTF-8 format. .SH KEYWORDS append, dynamic string, free, result diff --git a/doc/DetachPids.3 b/doc/DetachPids.3 index 26075c3..4d87529 100644 --- a/doc/DetachPids.3 +++ b/doc/DetachPids.3 @@ -20,9 +20,10 @@ Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in .sp Tcl_Pid \fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR) +.fi .SH ARGUMENTS .AS Tcl_Pid *statusPtr out -.AP int numPids in +.AP Tcl_Size 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..ec36d6a 100644 --- a/doc/DictObj.3 +++ b/doc/DictObj.3 @@ -33,10 +33,8 @@ int \fBTcl_DictObjFirst\fR(\fIinterp, dictPtr, searchPtr, keyPtrPtr, valuePtrPtr, donePtr\fR) .sp -void \fBTcl_DictObjNext\fR(\fIsearchPtr, keyPtrPtr, valuePtrPtr, donePtr\fR) .sp -void \fBTcl_DictObjDone\fR(\fIsearchPtr\fR) .sp int @@ -44,6 +42,7 @@ int .sp int \fBTcl_DictObjRemoveKeyList\fR(\fIinterp, dictPtr, keyc, keyv\fR) +.fi .SH ARGUMENTS .AS Tcl_DictSearch "**valuePtrPtr" in/out .AP Tcl_Interp *interp in @@ -70,9 +69,14 @@ 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 "Tcl_Size \&| int" *sizePtr out Points to a variable that will have the number of key/value pairs contained within the dictionary placed within it. +May be (Tcl_Size *)NULL when not used. If it points to a variable which +type is not \fBTcl_Size\fR, a compiler warning will be generated. +If your extensions is compiled with -DTCL_8_API, this function will return +NULL for dictionaries larger than INT_MAX (which should +trigger proper error-handling), otherwise expect it to crash. .AP Tcl_DictSearch *searchPtr in/out Pointer to record to use to keep track of progress in enumerating all key/value pairs in a dictionary. The contents of the record will be @@ -84,7 +88,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 Tcl_Size keyc in Indicates the number of keys that will be supplied in the \fIkeyv\fR array. .AP "Tcl_Obj *const" *keyv in @@ -138,7 +142,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/DoOneEvent.3 b/doc/DoOneEvent.3 index 17c76e6..b14f2e1 100644 --- a/doc/DoOneEvent.3 +++ b/doc/DoOneEvent.3 @@ -16,6 +16,7 @@ Tcl_DoOneEvent \- wait for events and invoke event handlers .sp int \fBTcl_DoOneEvent\fR(\fIflags\fR) +.fi .SH ARGUMENTS .AS int flags .AP int flags in diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3 index f7edcec..4696cc3 100644 --- a/doc/DoubleObj.3 +++ b/doc/DoubleObj.3 @@ -20,6 +20,7 @@ Tcl_Obj * .sp int \fBTcl_GetDoubleFromObj\fR(\fIinterp, objPtr, doublePtr\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp doubleValue in/out .AP double doubleValue in diff --git a/doc/DumpActiveMemory.3 b/doc/DumpActiveMemory.3 index 226209a..7c8dd7e 100644 --- a/doc/DumpActiveMemory.3 +++ b/doc/DumpActiveMemory.3 @@ -15,12 +15,10 @@ Tcl_DumpActiveMemory, Tcl_InitMemory, Tcl_ValidateAllMemory \- Validated memory int \fBTcl_DumpActiveMemory\fR(\fIfileName\fR) .sp -void \fBTcl_InitMemory\fR(\fIinterp\fR) .sp -void \fBTcl_ValidateAllMemory\fR(\fIfileName, line\fR) - +.fi .SH ARGUMENTS .AS Tcl_Interp *fileName .AP Tcl_Interp *interp in @@ -43,7 +41,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 +53,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 524d8b0..45398f3 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_ExternalToUtfDStringEx, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternalDStringEx, 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_ExternalToUtfDStringEx, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternalDStringEx, 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 @@ -16,7 +16,6 @@ Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDStr Tcl_Encoding \fBTcl_GetEncoding\fR(\fIinterp, name\fR) .sp -void \fBTcl_FreeEncoding\fR(\fIencoding\fR) .sp int @@ -42,16 +41,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 +Tcl_Size \fBTcl_GetEncodingNulLength\fR(\fIencoding\fR) .sp int @@ -60,7 +53,6 @@ int const char * \fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR) .sp -void \fBTcl_GetEncodingNames\fR(\fIinterp\fR) .sp Tcl_Encoding @@ -71,12 +63,7 @@ Tcl_Obj * .sp int \fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR) -.sp -const char * -\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR) -.sp -void -\fBTcl_SetDefaultEncodingDir\fR(\fIpath\fR) +.fi .SH ARGUMENTS .AS "const Tcl_EncodingType" *dstWrotePtr in/out .AP Tcl_Interp *interp in @@ -94,11 +81,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 Tcl_Size 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 @@ -117,9 +104,9 @@ byte is converted and then to reset to an initial state. The \fBTCL_PROFILE_*\fR bits defined in the \fBPROFILES\fR section below control the encoding profile to be used for dealing with invalid data or other errors in the encoding transform. -\fBTCL_ENCODING_STOPONERROR\fR is present for backward compatibility with -Tcl 8.6 and forces the encoding profile to \fBstrict\fR. - +The flag \fBTCL_ENCODING_STOPONERROR\fR has no effect, +it only has meaning in Tcl 8.x. +.PP Some flags bits may not be usable with some functions as noted in the function descriptions below. .AP Tcl_EncodingState *statePtr in/out @@ -147,7 +134,7 @@ buffer as a result of the conversion. May be NULL. .AP int *dstCharsPtr out Filled with the number of characters that correspond to the number of bytes stored in the output buffer. May be NULL. -.AP int *errorIdxPtr out +.AP Tcl_Size *errorIdxPtr out Filled with the index of the byte or character that caused the encoding transform to fail. May be NULL. .AP Tcl_DString *bufPtr out @@ -302,18 +289,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 @@ -343,7 +318,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 @@ -371,7 +346,7 @@ typedef struct { Tcl_EncodingConvertProc *\fIfromUtfProc\fR; Tcl_EncodingFreeProc *\fIfreeProc\fR; void *\fIclientData\fR; - int \fInullSize\fR; + Tcl_Size \fInullSize\fR; } \fBTcl_EncodingType\fR; .CE .PP @@ -458,15 +433,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 @@ -623,7 +589,7 @@ with at most one of \fBTCL_ENCODING_PROFILE_TCL8\fR, \fBTCL_ENCODING_PROFILE_STRICT\fR or \fBTCL_ENCODING_PROFILE_REPLACE\fR. These correspond to the \fBtcl8\fR, \fBstrict\fR and \fBreplace\fR profiles respectively. If none are specified, a version-dependent default profile is used. -For Tcl 8.7, the default profile is \fBtcl8\fR. +For Tcl 9.0, the default profile is \fBstrict\fR. .PP For details about profiles, see the \fBPROFILES\fR section in the documentation of the \fBencoding\fR command. diff --git a/doc/Ensemble.3 b/doc/Ensemble.3 index 96fff06..0c2ea9d 100644 --- a/doc/Ensemble.3 +++ b/doc/Ensemble.3 @@ -56,6 +56,7 @@ int .sp int \fBTcl_GetEnsembleNamespace\fR(\fIinterp, token, namespacePtrPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_Namespace **namespacePtrPtr in/out .AP Tcl_Interp *interp in/out diff --git a/doc/Environment.3 b/doc/Environment.3 index 7a5e396..da1d4f4 100644 --- a/doc/Environment.3 +++ b/doc/Environment.3 @@ -15,6 +15,7 @@ Tcl_PutEnv \- procedures to manipulate the environment .sp int \fBTcl_PutEnv\fR(\fIassignment\fR) +.fi .SH ARGUMENTS .AS "const char" *assignment .AP "const char" *assignment in @@ -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,7 @@ int .sp int \fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *)NULL\fR) -.sp -int -\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp **termPtr .AP Tcl_Interp *interp in @@ -53,7 +51,7 @@ OR'ed 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 Tcl_Size 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 +65,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 +121,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 +140,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 (char *)NULL to indicate the end of arguments. -.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 @@ -31,6 +31,7 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitTh .sp Tcl_ExitProc * \fBTcl_SetExitProc\fR(\fIproc\fR) +.fi .SH ARGUMENTS .AS Tcl_ExitProc clientData .AP int status in @@ -42,7 +43,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 +65,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 +94,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 +134,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/ExprLong.3 b/doc/ExprLong.3 index 0d369ce..8d5e06d 100644 --- a/doc/ExprLong.3 +++ b/doc/ExprLong.3 @@ -25,6 +25,7 @@ int .sp int \fBTcl_ExprString\fR(\fIinterp, expr\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *booleanPtr out .AP Tcl_Interp *interp in diff --git a/doc/ExprLongObj.3 b/doc/ExprLongObj.3 index 59413e1..09f83dd 100644 --- a/doc/ExprLongObj.3 +++ b/doc/ExprLongObj.3 @@ -24,6 +24,7 @@ int .sp int \fBTcl_ExprObj\fR(\fIinterp, objPtr, resultPtrPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp **resultPtrPtr out .AP Tcl_Interp *interp in diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index b015133..b6c6d1e 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -20,10 +20,9 @@ int int \fBTcl_FSUnregister\fR(\fIfsPtr\fR) .sp -ClientData +void * \fBTcl_FSData\fR(\fIfsPtr\fR) .sp -void \fBTcl_FSMountsChanged\fR(\fIfsPtr\fR) .sp const Tcl_Filesystem * @@ -123,7 +122,7 @@ Tcl_Obj * int \fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR) .sp -ClientData +void * \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR) .sp Tcl_Obj * @@ -182,6 +181,7 @@ unsigned long long .sp int \fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_GlobTypeData **srcPathPtr out .AP "const Tcl_Filesystem" *fsPtr in @@ -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,8 +220,8 @@ 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 +.AP Tcl_Size elements in +The number of elements in the \fIlistObj\fR which should be joined together. If negative, then all elements are joined. .AP Tcl_Obj **errorPtr out In the case of an error, filled with a value containing the name of @@ -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,16 @@ 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 -If non-NULL, filled with the number of elements in the split path. +.AP "Tcl_Size \&| int" *lenPtr out +Filled with the number of elements in the split path. +May be (Tcl_Size *)NULL when not used. If it points to a variable which +type is not \fBTcl_Size\fR, a compiler warning will be generated. +If your extensions is compiled with -DTCL_8_API, this function will return +NULL for paths having more than INT_MAX elements (which should +trigger proper error-handling), otherwise expect it to crash. .AP Tcl_Obj *basePtr in The base path on to which to join the given elements. May be NULL. -.AP int objc in +.AP Tcl_Size objc in The number of elements in \fIobjv\fR. .AP "Tcl_Obj *const" objv[] in The elements to join to the given base path. @@ -680,11 +685,6 @@ of zero, they will be freed when this function returns. \fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid Tcl path type, taking account of the fact that the cwd may have changed even if this value is already supposedly of the correct type. -The filename may begin with -.QW ~ -(to indicate current user's home directory) or -.QW ~<user> -(to indicate any user's home directory). .PP If the conversion succeeds (i.e.\ the value is a valid path in one of the current filesystems), then \fBTCL_OK\fR is returned. Otherwise @@ -706,14 +706,7 @@ from the given Tcl_Obj. .PP If the translation succeeds (i.e.\ the value is a valid path), then it is returned. Otherwise NULL will be returned, and an error message may be -left in the interpreter. A -.QW translated -path is one which contains no -.QW ~ -or -.QW ~user -sequences (these have been expanded to their current -representation in the filesystem). The value returned is owned by the +left in the interpreter. The value returned is owned by the caller, which must store it or call \fBTcl_DecrRefCount\fR to ensure memory is freed. This function is of little practical use, and \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually @@ -722,7 +715,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 @@ -789,7 +782,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 @@ -837,7 +830,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 @@ -852,7 +845,7 @@ The \fBTcl_Filesystem\fR structure contains the following fields: .CS typedef struct { const char *\fItypeName\fR; - int \fIstructureLength\fR; + Tcl_Size \fIstructureLength\fR; Tcl_FSVersion \fIversion\fR; Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR; Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR; @@ -1014,7 +1007,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 @@ -1024,8 +1017,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 @@ -1034,7 +1027,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 @@ -1045,7 +1038,7 @@ representation is the normalized path. .PP .CS typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR( - ClientData \fIclientData\fR); + void *\fIclientData\fR); .CE .SS CREATEINTERNALREPPROC .PP @@ -1056,7 +1049,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 @@ -1070,9 +1063,7 @@ must have a single unique string representation. Depending on the filesystem, there may be more than one unnormalized string representation which refers to that path (e.g.\ a relative path, a path with different -character case if the filesystem is case insensitive, a path contain a -reference to a home directory such as -.QW ~ , +character case if the filesystem is case insensitive, a path containing symbolic links, etc). If the very last component in the path is a symbolic link, it should not be converted into the value it points to (but diff --git a/doc/FindExec.3 b/doc/FindExec.3 index 6156382..756d8cb 100644 --- a/doc/FindExec.3 +++ b/doc/FindExec.3 @@ -18,6 +18,7 @@ const char * .sp const char * \fBTcl_GetNameOfExecutable\fR() +.fi .SH ARGUMENTS .AS char *argv0 .AP char *argv0 in @@ -35,8 +36,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 with build -information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\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 +63,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/GetCwd.3 b/doc/GetCwd.3 index 7a3b811..b901098 100644 --- a/doc/GetCwd.3 +++ b/doc/GetCwd.3 @@ -18,6 +18,7 @@ char * .sp int \fBTcl_Chdir\fR(\fIdirName\fR) +.fi .SH ARGUMENTS .AS Tcl_DString *bufferPtr in/out .AP Tcl_Interp *interp in diff --git a/doc/GetHostName.3 b/doc/GetHostName.3 index 8e43f8e..cdef270 100644 --- a/doc/GetHostName.3 +++ b/doc/GetHostName.3 @@ -13,6 +13,7 @@ Tcl_GetHostName \- get the name of the local host .sp const char * \fBTcl_GetHostName\fR() +.fi .BE .SH DESCRIPTION diff --git a/doc/GetIndex.3 b/doc/GetIndex.3 index ce01a5d..deb77fe 100644 --- a/doc/GetIndex.3 +++ b/doc/GetIndex.3 @@ -20,6 +20,7 @@ indexPtr\fR) int \fBTcl_GetIndexFromObjStruct\fR(\fIinterp, objPtr, structTablePtr, offset, msg, flags, indexPtr\fR) +.fi .SH ARGUMENTS .AS "const char" *structTablePtr in/out .AP Tcl_Interp *interp in diff --git a/doc/GetInt.3 b/doc/GetInt.3 index f15c12d..a0c1d1b 100644 --- a/doc/GetInt.3 +++ b/doc/GetInt.3 @@ -25,6 +25,7 @@ int .sp int \fBTcl_GetBool\fR(\fIinterp, src, flags, charPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *doublePtr out .AP Tcl_Interp *interp in @@ -71,12 +72,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..f3a3143 100644 --- a/doc/GetOpnFl.3 +++ b/doc/GetOpnFl.3 @@ -15,7 +15,7 @@ Tcl_GetOpenFile \- Return a FILE* for a channel registered in the given interpre .sp int \fBTcl_GetOpenFile\fR(\fIinterp, chanID, write, checkUsage, filePtr\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_Interp checkUsage out .AP Tcl_Interp *interp in @@ -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/GetStdChan.3 b/doc/GetStdChan.3 index 3472fee..91217e4 100644 --- a/doc/GetStdChan.3 +++ b/doc/GetStdChan.3 @@ -18,7 +18,7 @@ Tcl_Channel \fBTcl_GetStdChannel\fR(\fItype\fR) .sp \fBTcl_SetStdChannel\fR(\fIchannel, type\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_Channel channel .AP int type in diff --git a/doc/GetTime.3 b/doc/GetTime.3 index 0756d25..ff302e5 100644 --- a/doc/GetTime.3 +++ b/doc/GetTime.3 @@ -18,6 +18,7 @@ Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time \fBTcl_SetTimeProc\fR(\fIgetProc, scaleProc, clientData\fR) .sp \fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_GetTimeProc *getProc in .AP Tcl_Time *timePtr out @@ -27,13 +28,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 @@ -44,7 +45,7 @@ structure has the following definition: .PP .CS typedef struct { - long \fIsec\fR; + long long \fIsec\fR; long \fIusec\fR; } \fBTcl_Time\fR; .CE @@ -83,10 +84,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..5a85a2a 100644 --- a/doc/GetVersion.3 +++ b/doc/GetVersion.3 @@ -14,15 +14,15 @@ Tcl_GetVersion \- get the version of the library at runtime \fB#include <tcl.h>\fR .sp \fBTcl_GetVersion\fR(\fImajor, minor, patchLevel, type\fR) +.fi .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) @@ -46,6 +46,7 @@ Tcl_HashEntry * .sp char * \fBTcl_HashStats\fR(\fItablePtr\fR) +.fi .SH ARGUMENTS .AS "const Tcl_HashKeyType" *searchPtr out .AP Tcl_HashTable *tablePtr in @@ -66,9 +67,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 +186,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 +224,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 @@ -40,6 +40,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. .PP +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 .SH KEYWORDS diff --git a/doc/InitStubs.3 b/doc/InitStubs.3 index 4423666..80a21de 100644 --- a/doc/InitStubs.3 +++ b/doc/InitStubs.3 @@ -15,6 +15,7 @@ Tcl_InitStubs \- initialize the Tcl stubs mechanism .sp const char * \fBTcl_InitStubs\fR(\fIinterp, version, exact\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in @@ -63,9 +64,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 \fIlibtclstub.a\fR; on Windows platforms, the +library name is \fItclstub.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 0d09a41..4647567 100644 --- a/doc/InitSubSyst.3 +++ b/doc/InitSubSyst.3 @@ -14,21 +14,23 @@ Tcl_InitSubsystems \- initialize the Tcl library. \fB#include <tcl.h>\fR .sp const char * -\fBTcl_InitSubsystems\fR(\fIvoid\fR) +\fBTcl_InitSubsystems\fR() +.fi +.BE .SH DESCRIPTION .PP 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 with build -information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\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 3e61fce..7cc93c1 100644 --- a/doc/IntObj.3 +++ b/doc/IntObj.3 @@ -37,7 +37,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) @@ -48,6 +48,9 @@ int int \fBTcl_GetWideUIntFromObj\fR(\fIinterp, objPtr, uwidePtr\fR) .sp +int +\fBTcl_GetSizeIntFromObj\fR(\fIinterp, objPtr, sizePtr\fR) +.sp .sp \fB#include <tclTomMath.h>\fR .sp @@ -64,9 +67,10 @@ int .sp int \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR) +.fi .SH ARGUMENTS .AS Tcl_WideInt doubleValue in/out -.AP int endValue in +.AP Tcl_Size 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. @@ -91,10 +95,14 @@ 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 Tcl_Size *indexPtr out +Points to place to store the Tcl_Size 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 Points to place to store the unsigned wide integer value retrieved from \fIobjPtr\fR. +.AP Tcl_Size *sizePtr out +Points to place to store the \fBTcl_Size\fR integer value retrieved from \fIobjPtr\fR. .AP mp_int *bigValue in/out Points to a multi-precision integer structure declared by the LibTomMath library. @@ -144,7 +152,8 @@ of \fIobjPtr\fR may be changed to make subsequent calls to the same routine more efficient. .PP The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR, -\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and +\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetSizeIntFromObj\fR, +\fBTcl_GetBignumFromObj\fR, and \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral value of the appropriate type from the Tcl value \fIobjPtr\fR. If the attempt succeeds, then \fBTCL_OK\fR is returned, and the value is 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..5eb3ac8 100644 --- a/doc/Limit.3 +++ b/doc/Limit.3 @@ -28,35 +28,28 @@ int int \fBTcl_LimitTypeEnabled\fR(\fIinterp, type\fR) .sp -void \fBTcl_LimitTypeSet\fR(\fIinterp, type\fR) .sp -void \fBTcl_LimitTypeReset\fR(\fIinterp, type\fR) .sp int \fBTcl_LimitGetCommands\fR(\fIinterp\fR) .sp -void \fBTcl_LimitSetCommands\fR(\fIinterp, commandLimit\fR) .sp -void \fBTcl_LimitGetTime\fR(\fIinterp, timeLimitPtr\fR) .sp -void \fBTcl_LimitSetTime\fR(\fIinterp, timeLimitPtr\fR) .sp int \fBTcl_LimitGetGranularity\fR(\fIinterp, type\fR) .sp -void \fBTcl_LimitSetGranularity\fR(\fIinterp, type, granularity\fR) .sp -void \fBTcl_LimitAddHandler\fR(\fIinterp, type, handlerProc, clientData, deleteProc\fR) .sp -void \fBTcl_LimitRemoveHandler\fR(\fIinterp, type, handlerProc, clientData\fR) +.fi .SH ARGUMENTS .AS Tcl_LimitHandlerDeleteProc commandLimit in/out .AP Tcl_Interp *interp in @@ -65,7 +58,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 Tcl_Size 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 +76,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 +155,7 @@ following prototype: .PP .CS typedef void \fBTcl_LimitHandlerProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR); .CE .PP @@ -179,7 +172,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..ffedb9d 100644 --- a/doc/LinkVar.3 +++ b/doc/LinkVar.3 @@ -25,6 +25,7 @@ int \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR) .sp \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp varName in .AP Tcl_Interp *interp in @@ -59,7 +60,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 Tcl_Size size in .VS "TIP 312" The number of elements in the C array. Must be greater than zero. .VE "TIP 312" @@ -263,7 +264,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..deae5a5 100644 --- a/doc/ListObj.3 +++ b/doc/ListObj.3 @@ -35,6 +35,7 @@ int .sp int \fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR) +.fi .SH ARGUMENTS .AS "Tcl_Obj *const" *elemListPtr in/out .AP Tcl_Interp *interp in @@ -59,13 +60,18 @@ 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 "Tcl_Size \&| int" *objcPtr in Points to location where \fBTcl_ListObjGetElements\fR stores the number of element values in \fIlistPtr\fR. +May be (Tcl_Size *)NULL when not used. If it points to a variable which +type is not \fBTcl_Size\fR, a compiler warning will be generated. +If your extensions is compiled with -DTCL_8_API, this function will return +NULL for lists with more than INT_MAX elements (which should +trigger proper error-handling), otherwise expect it to crash. .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 Tcl_Size 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 +82,26 @@ 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 "Tcl_Size \&| int" *lengthPtr out Points to location where \fBTcl_ListObjLength\fR stores the length of the list. -.AP int index in +May be (Tcl_Size *)NULL when not used. If it points to a variable which +type is not \fBTcl_Size\fR, a compiler warning will be generated. +If your extensions is compiled with -DTCL_8_API, this function will return +TCL_ERROR for lists with more than INT_MAX elements (which should +trigger proper error-handling), otherwise expect it to crash. +.AP Tcl_Size 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 Tcl_Size 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 Tcl_Size count in The number of elements that \fBTcl_ListObjReplace\fR is to replace. .BE @@ -153,7 +164,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 +175,6 @@ 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. 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 @@ -19,6 +19,7 @@ int .sp void * \fBTcl_FindSymbol\fR(\fIinterp, loadHandle, symbol\fR) +.fi .SH ARGUMENTS .AS Tcl_LoadHandle loadHandle in .AP Tcl_Interp *interp in diff --git a/doc/Method.3 b/doc/Method.3 index 577cd54..ed2211b 100644 --- a/doc/Method.3 +++ b/doc/Method.3 @@ -58,10 +58,11 @@ Tcl_Method Tcl_Object \fBTcl_ObjectContextObject\fR(\fIcontext\fR) .sp -int +Tcl_Size \fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR) +.fi .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 +84,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 +96,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 Tcl_Size 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 Tcl_Size skip in The number of arguments passed to the method implementation that do not represent "real" arguments. .BE @@ -213,7 +214,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 +235,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 +249,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 @@ -40,7 +40,6 @@ int int \fBTcl_NRExprObj\fR(\fIinterp, objPtr, resultPtr\fR) .sp -void \fBTcl_NRAddCallback\fR(\fIinterp, postProcPtr, data0, data1, data2, data3\fR) .fi .SH ARGUMENTS @@ -63,13 +62,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 Tcl_Size objc in Number of items in \fIobjv\fR. .AP Tcl_Obj **objv in Words in the command. @@ -86,10 +85,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 +146,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 +162,7 @@ stack, to evaluate a script: .CS int \fITheCmdOldObjProc\fR( - ClientData clientData, + void *clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) @@ -194,7 +193,7 @@ call \fITheCmdNRObjProc\fR: .CS int \fITheCmdOldObjProc\fR( - ClientData clientData, + void *clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) @@ -207,7 +206,7 @@ int .CS int \fITheCmdNRObjProc\fR - ClientData clientData, + void *clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) @@ -228,7 +227,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 a7e8502..399bd7d 100644 --- a/doc/Namespace.3 +++ b/doc/Namespace.3 @@ -50,6 +50,7 @@ Tcl_Obj * .sp int \fBTcl_SetNamespaceUnknownHandler\fR(\fIinterp, nsPtr, handlerPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_NamespaceDeleteProc allowOverwrite in/out .AP Tcl_Interp *interp in/out @@ -57,7 +58,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 +118,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 6c379bc..6aab2e2 100644 --- a/doc/Notifier.3 +++ b/doc/Notifier.3 @@ -14,43 +14,33 @@ Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEven .nf \fB#include <tcl.h>\fR .sp -void \fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fR) .sp -void \fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fR) .sp -void \fBTcl_SetMaxBlockTime\fR(\fItimePtr\fR) .sp -void \fBTcl_QueueEvent\fR(\fIevPtr, position\fR) .sp -void \fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR) .sp -void \fBTcl_ThreadAlert\fR(\fIthreadId\fR) .sp Tcl_ThreadId \fBTcl_GetCurrentThread\fR() .sp -void \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR) .sp -ClientData +void * \fBTcl_InitNotifier\fR() .sp -void \fBTcl_FinalizeNotifier\fR(\fIclientData\fR) .sp int \fBTcl_WaitForEvent\fR(\fItimePtr\fR) .sp -void \fBTcl_AlertNotifier\fR(\fIclientData\fR) .sp -void \fBTcl_SetTimer\fR(\fItimePtr\fR) .sp int @@ -65,11 +55,10 @@ int int \fBTcl_SetServiceMode\fR(\fImode\fR) .sp -void \fBTcl_ServiceModeHook\fR(\fImode\fR) .sp -void \fBTcl_SetNotifier\fR(\fInotifierProcPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_EventDeleteProc *notifierProcPtr .AP Tcl_EventSetupProc *setupProc in @@ -78,7 +67,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 +78,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 +215,7 @@ the event source. .PP .CS typedef void \fBTcl_EventSetupProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, int \fIflags\fR); .CE .PP @@ -267,7 +256,7 @@ microseconds: .PP .CS typedef struct { - long \fIsec\fR; + long long \fIsec\fR; long \fIusec\fR; } \fBTcl_Time\fR; .CE @@ -304,7 +293,7 @@ following prototype: .PP .CS typedef void \fBTcl_EventCheckProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, int \fIflags\fR); .CE .PP @@ -399,7 +388,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 +413,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/Number.3 b/doc/Number.3 index 4642c10..99efab7 100644 --- a/doc/Number.3 +++ b/doc/Number.3 @@ -20,6 +20,7 @@ int .sp int \fBTcl_GetNumberFromObj\fR(\fIinterp, objPtr, clientDataPtr, typePtr\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp clientDataPtr out .AP Tcl_Interp *interp out @@ -27,9 +28,9 @@ When non-NULL, error information is recorded here when the value is not in any of the numeric formats recognized by Tcl. .AP "const char" *bytes in Points to first byte of the string value to be examined. -.AP int numBytes in +.AP Tcl_Size numBytes in The number of bytes, starting at \fIbytes\fR, that should be examined. -If the value \fBTCL_INDEX_NONE\fR is provided, then all bytes should +If \fBnumBytes\fR is negative, then all bytes should be examined until the first \fBNUL\fR byte terminates examination. .AP "void *" *clientDataPtr out Points to space where a pointer value may be written through which a numeric @@ -63,7 +64,7 @@ the same function. They differ only in how the arguments present the Tcl value to be examined. \fBTcl_GetNumber\fR accepts a counted string value in the arguments \fIbytes\fR and \fInumBytes\fR (or a \fBNUL\fR-terminated string value when \fInumBytes\fR is -\fBTCL_INDEX_NONE\fR). \fBTcl_GetNumberFromObj\fR accepts the Tcl value +negative). \fBTcl_GetNumberFromObj\fR accepts the Tcl value in \fIobjPtr\fR. .PP Both routines examine the Tcl value and determine whether Tcl recognizes diff --git a/doc/Object.3 b/doc/Object.3 index 818ba45..0f52a51 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl values +Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_BounceRefCount, Tcl_IsShared, Tcl_InvalidateStringRep \- manipulate Tcl values .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -23,10 +23,12 @@ Tcl_Obj * .sp \fBTcl_DecrRefCount\fR(\fIobjPtr\fR) .sp +\fBTcl_BounceRefCount\fR(\fIobjPtr\fR) +.sp int \fBTcl_IsShared\fR(\fIobjPtr\fR) .sp -\fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR) +\fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR)3 .fi .SH ARGUMENTS .AS Tcl_Obj *objPtr @@ -112,9 +114,9 @@ which is defined as follows. .PP .CS typedef struct { - int \fIrefCount\fR; + Tcl_Size \fIrefCount\fR; char *\fIbytes\fR; - int \fIlength\fR; + Tcl_Size \fIlength\fR; const Tcl_ObjType *\fItypePtr\fR; union { long \fIlongValue\fR; @@ -295,6 +297,8 @@ new reference to the value is created. The macro \fBTcl_DecrRefCount\fR decrements the count when a reference is no longer needed. If the value's reference count drops to zero, frees its storage. +The macro \fBTcl_BounceRefCount\fR will check if the value has no +references (i.e. in a "new" state) and free the value. A value shared by different code or data structures has \fIrefCount\fR greater than 1. Incrementing a value's reference count ensures that it will not be freed too early or have its value change @@ -312,12 +316,25 @@ the interpreter calls \fBTcl_DecrRefCount\fR to decrement each argument's reference count. When a value's reference count drops less than or equal to zero, \fBTcl_DecrRefCount\fR reclaims its storage. -Most command procedures do not have to be concerned about -reference counting since they use a value's value immediately -and do not retain a pointer to the value after they return. -However, if they do retain a pointer to a value in a data structure, -they must be careful to increment its reference count -since the retained pointer is a new reference. + +.PP +Most command procedures have not been concerned about reference +counting since they use a value immediately and do not retain +a pointer to the value after they return. However, there are some +procedures that may return a new value, with a refCount of 0. In this +situation, it is the caller's responsibility to free the value before +the procedure returns. One way to cover this is to always call +\fBTcl_IncrRefCount\fR before using the value, then call +\fBTcl_DecrRefCount\fR before returning. The other way is to use +\fBTcl_BounceRefCount\fR after the value is no longer needed or +referenced. This macro will free the value if there are no other +references to the value. When retaining a pointer to a value in a data +structure the procedure must be careful to increment its reference +count since the retained pointer is a new reference. Examples of +procedures that return new values are \fBTcl_NewIntObj\fR, and +commands like \fBlseq\fR, which creates an Abstract List, and an +lindex on this list may return a new Obj with a refCount of 0. + .PP Command procedures that directly modify values such as those for \fBlappend\fR and \fBlinsert\fR must be careful to @@ -351,6 +368,11 @@ must check whether the variable's value is shared before incrementing the integer in its internal representation. If it is shared, it needs to duplicate the value in order to avoid accidentally changing values in other data structures. +.PP +In cases where a value is obtained, used, and not retained, the value +can be freed using \fBTcl_BounceRefCount\fR. This +is functionally equivalent to calling \fBTcl_IncrRefCount\fR followed +\fBTcl_DecrRefCount\fR. .SH "SEE ALSO" Tcl_ConvertToType(3), Tcl_GetIntFromObj(3), Tcl_ListObjAppendElement(3), Tcl_ListObjIndex(3), Tcl_ListObjReplace(3), Tcl_RegisterObjType(3) .SH KEYWORDS diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index 1342d0d..ca9e0ce 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.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_ObjType 3 8.0 Tcl "Tcl Library Procedures" +.TH Tcl_ObjType 3 9.0 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -154,7 +154,7 @@ This definition permits us to pass internal representations and pointers to them as arguments and results in public routines. .SH "THE TCL_OBJTYPE STRUCTURE" .PP -Extension writers can define new value types by defining four +Extension writers can define new value types by defining four to twelve procedures and initializing a Tcl_ObjType structure to describe the type. Extension writers may also pass a pointer to their Tcl_ObjType structure to \fBTcl_RegisterObjType\fR if they wish to permit other @@ -169,6 +169,17 @@ typedef struct { Tcl_DupInternalRepProc *\fIdupIntRepProc\fR; Tcl_UpdateStringProc *\fIupdateStringProc\fR; Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR; + size_t \fIversion\fR; + /* List emulation functions - ObjType Version 1 & 2 */ + Tcl_ObjTypeLengthProc *lengthProc; + /* List emulation functions - ObjType Version 2 */ + Tcl_ObjTypeIndexProc *\fIindexProc\fR; + Tcl_ObjTypeSliceProc *\fIsliceProc\fR; + Tcl_ObjTypeReverseProc *\fIreverseProc\fR; + Tcl_ObjTypeGetElements *\fIgetElementsProc\fR; + Tcl_ObjTypeSetElement *\fIsetElementProc\fR; + Tcl_ObjTypeReplaceProc *\fIreplaceProc\fR; + Tcl_ObjTypeInOperatorProc *\fIinOperProc\fR; } \fBTcl_ObjType\fR; .CE .SS "THE NAME FIELD" @@ -244,8 +255,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, @@ -313,6 +324,135 @@ 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 \fBTCL_OBJTYPE_V0\fR for compatibility +of ObjType definitions prior to version 9.0. Specifics about versions +will be described further in the sections below. +.SH "ABSTRACT LIST TYPES" +.PP +Additional fields in the Tcl_ObjType descriptor allow for control over +how custom data values can be manipulated using Tcl's List commands +without converting the value to a List type. This requires the custom +type to provide functions that will perform the given operation on the +custom data representation. Not all functions are required. In the +absence of a particular function (set to NULL), the fallback is to +allow the internal List operation to perform the operation, most +likely causing the value type to be converted to a traditional list. +.SS "SCALAR VALUE TYPES" +.PP +For a custom value type that is scalar or atomic in nature, i.e., not +a divisible collection, version \fBTCL_OBJTYPE_V1\fR is +recommended. In this case, List commands will treat the scalar value +as if it where a list of length 1, and not convert the value to a List +type. +.SS "VERSION 2: ABSTRACT LISTS" +.PP +Version 2, \fBTCL_OBJTYPE_V2\fR, allows full List support when the +functions described below are provided. This allows for script level +use of the List commands without causing the type of the Tcl_Obj value +to be converted to a list. +.SS "THE LENGTHPROC FIELD" +.PP +The \fBLengthProc\fR function correlates with the \fBTcl_ListObjLength\fR +C API. The function returns the number of elements in the list. It +is used in every List operation and is required for all Abstract List +implementations. +.CS +typedef Tcl_Size +(Tcl_ObjTypeLengthProc) (Tcl_Obj *listPtr); +.CE +.PP +.SS "THE INDEXPROC FIELD" +.PP +The \fBIndexProc\fR function correlates with with the +\fBTcl_ListObjIndex\fR C API. The function returns a Tcl_Obj value for +the element at the specified index. +.CS +typedef int (\fBTcl_ObjTypeIndexProc\fR) ( + Tcl_Interp *interp, + Tcl_Obj *listPtr, + Tcl_Size index, + Tcl_Obj** elemObj); +.CE +.SS "THE SLICEPROC FIELD" +.PP +The \fBSliceProc\fR correlates with the \fBlrange\fR command, +returning a new List or Abstract List for the portion of the original +list specified. +.CS +typedef int (\fBTcl_ObjTypeSliceProc\fR) ( + Tcl_Interp *interp, + Tcl_Obj *listPtr, + Tcl_Size fromIdx, + Tcl_Size toIdx, + Tcl_Obj **newObjPtr); +.CE +.SS "THE REVERSEPROC FIELD" +.PP +The \fBReverseProc\fR correlates with the \fBlreverse\fR command, +returning a List or Abstract List that has the same elements as the +input Abstract List, with the elements in the reverse order. +.CS +typedef int (\fBTcl_ObjTypeReverseProc\fR) ( + Tcl_Interp *interp, + Tcl_Obj *listPtr, + Tcl_Obj **newObjPtr); +.CE +.SS "THE GETELEMENTS FIELD" +.PP +The \fBGetElements\fR function returns a count and a pointer to an +array of Tcl_Obj values for the entire Abstract List. This +correlates to the \fBTcl_ListObjGetElements\fR C API call. +.CS +typedef int (\fBTcl_ObjTypeGetElements\fR) ( + Tcl_Interp *interp, + Tcl_Obj *listPtr, + Tcl_Size *objcptr, + Tcl_Obj ***objvptr); +.CE +.SS "THE SETELEMENT FIELD" +.PP +The \fBSetElement\fR function replaces the element within the +specified list at the give index. This function correlates to the +\fBlset\fR command. +.CS +typedef Tcl_Obj *(\fBTcl_ObjTypeSetElement\fR) ( + Tcl_Interp *interp, + Tcl_Obj *listPtr, + Tcl_Size indexCount, + Tcl_Obj *const indexArray[], + Tcl_Obj *valueObj); +.CE +.SS "REPLACEPROC FIELD" +.PP +The \fBReplaceProc\fR returns a new list after modifying the list +replacing the elements to be deleted, and adding the elements to be +inserted. This function correlates to the \fBTcl_ListObjReplace\fR C API. +.CS +typedef int (\fBTcl_ObjTypeReplaceProc\fR) ( + Tcl_Interp *interp, + Tcl_Obj *listObj, + Tcl_Size first, + Tcl_Size numToDelete, + Tcl_Size numToInsert, + Tcl_Obj *const insertObjs[]); +.CE +.SS "THE INOPERPROC FIELD" +.PP +The \fBInOperProc\fR function determines whether the value is present in the +given list, according to equivalent string comparison of elements. The +\fBboolResult\fR is set to 1 (true) if the value is present, and 0 +(false) if it is not present. This function implements the "in" and +"ni" math operators for an abstract list. +.CS +typedef int (\fBTcl_ObjTypeInOperatorProc\fR) ( + Tcl_Interp *interp, + Tcl_Obj *valueObj, + Tcl_Obj *listObj, + int *boolResult); +.CE .SH "REFERENCE COUNT MANAGEMENT" .PP The \fIobjPtr\fR argument to \fBTcl_AppendAllObjTypes\fR should be an unshared @@ -331,7 +471,7 @@ modify the reference count of their arguments, but if the values contain subsidiary values (e.g., the elements of a list or the keys of a dictionary) then those subsidiary values may have their reference counts modified. .SH "SEE ALSO" -Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3) +Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_BounceRefCount(3) .SH KEYWORDS internal representation, value, value type, string representation, type conversion diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index 7c6df60..59364e0 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -32,7 +32,6 @@ int int \fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR) .sp -void \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR) .sp int @@ -47,34 +46,34 @@ int int \fBTcl_Close\fR(\fIinterp, channel\fR) .sp -int +Tcl_Size \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR) .sp -int +Tcl_Size \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR) .sp -int +Tcl_Size \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) .sp -int +Tcl_Size \fBTcl_Gets\fR(\fIchannel, lineRead\fR) .sp -int +Tcl_Size \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR) .sp -int +Tcl_Size \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR) .sp -int +Tcl_Size \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR) .sp -int +Tcl_Size \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR) .sp -int +Tcl_Size \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR) .sp -int +Tcl_Size \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR) .sp int @@ -106,7 +105,7 @@ int .sp int \fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_DString *channelName in/out .AP Tcl_Interp *interp in @@ -119,7 +118,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 Tcl_Size 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 +133,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 +153,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 Tcl_Size 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 +162,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 Tcl_Size 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 +175,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 Tcl_Size inputLen in Length of the input .AP int addAtEnd in Flag indicating whether the input should be added to the end or @@ -187,7 +186,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 Tcl_Size bytesToWrite in The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and output to the channel. .AP "long long" offset in @@ -406,12 +405,12 @@ to UTF-8 based on the channel's encoding and storing the produced data in \fIreadObjPtr\fR's string representation. The return value of \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR, that were stored in \fIreadObjPtr\fR. If an error occurs while reading, the -return value is TCL_INDEX_NONE and \fBTcl_ReadChars\fR records a POSIX error +return value is -1 and \fBTcl_ReadChars\fR records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. If an encoding error happens while the channel is in blocking mode with -profile strict, the characters retrieved until the encoding error happened will be stored in \fIreadObjPtr\fR. .PP -Setting \fIcharsToRead\fR to TCL_INDEX_NONE will cause the command to read +Setting \fIcharsToRead\fR to -1 will cause the command to read all characters currently available (non-blocking) or everything until eof (blocking mode). .PP @@ -473,14 +472,14 @@ character(s) are read and discarded. .PP If a line was successfully read, the return value is greater than or equal to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an -error occurs, \fBTcl_GetsObj\fR returns TCL_INDEX_NONE and records a POSIX error code +error occurs, \fBTcl_GetsObj\fR returns -1 and records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also -returns TCL_INDEX_NONE if the end of the file is reached; the \fBTcl_Eof\fR procedure +returns -1 if the end of the file is reached; the \fBTcl_Eof\fR procedure can be used to distinguish an error from an end-of-file condition. .PP -If the channel is in nonblocking mode, the return value can also be TCL_INDEX_NONE +If the channel is in nonblocking mode, the return value can also be -1 if no data was available or the data that was available did not contain an -end-of-line character. When TCL_INDEX_NONE is returned, the \fBTcl_InputBlocked\fR +end-of-line character. When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be invoked to determine if the channel is blocked because of input unavailability. .PP @@ -498,7 +497,7 @@ head of the queue. If \fIchannel\fR has a .QW sticky EOF set, no data will be added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or -TCL_INDEX_NONE if an error occurs. +-1 if an error occurs. .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE" .PP \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at @@ -515,7 +514,7 @@ to appear as soon as a complete line is accepted for output, set the \fB\-buffering\fR option on the channel to \fBline\fR mode. .PP The return value of \fBTcl_WriteChars\fR is a count of how many bytes were -accepted for output to the channel. This is either TCL_INDEX_NONE to +accepted for output to the channel. This is either -1 to indicate that an error occurred or another number greater than zero to indicate success. If an error occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be retrieved with \fBTcl_GetErrno\fR. diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3 index 63e6aab..709a8fc 100644 --- a/doc/OpenTcp.3 +++ b/doc/OpenTcp.3 @@ -25,7 +25,7 @@ Tcl_Channel .sp Tcl_Channel \fBTcl_OpenTcpServerEx\fR(\fIinterp, service, myaddr, flags, backlog, proc, clientData\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_TcpAcceptProc clientData .AP Tcl_Interp *interp in @@ -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 information 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 5abe1dd..25e38c2 100644 --- a/doc/Panic.3 +++ b/doc/Panic.3 @@ -7,33 +7,24 @@ .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 .sp -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 -void \fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_PanicProc *panicProc .AP "const char*" format in A printf-style format string. .AP "" arg in Arguments matching the format string. -.AP va_list argList in -An argument list of arguments matching the format string. -Must have been initialized using \fBva_start\fR, -and cleared using \fBva_end\fR. .AP Tcl_PanicProc *panicProc in Procedure to report fatal error message and abort. .BE @@ -83,14 +74,13 @@ 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 with build -information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\fR). +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 +88,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 72cd75c..594f4f1 100644 --- a/doc/ParseArgs.3 +++ b/doc/ParseArgs.3 @@ -15,23 +15,29 @@ Tcl_ParseArgsObjv \- parse arguments according to a tabular description .sp int \fBTcl_ParseArgsObjv\fR(\fIinterp, argTable, objcPtr, objv, remObjv\fR) +.fi .SH ARGUMENTS .AS "const Tcl_ArgvInfo" ***remObjv in/out .AP Tcl_Interp *interp out Where to store error messages. .AP "const Tcl_ArgvInfo" *argTable in Pointer to array of option descriptors. -.AP int *objcPtr in/out +.AP "Tcl_Size \&| 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. +May be (Tcl_Size *)NULL when not used. If it points to a variable which +type is not \fBTcl_Size\fR, a compiler warning will be generated. +If your extensions is compiled with -DTCL_8_API, this function will return +NULL for argument lists with more than INT_MAX elements (which should +trigger proper error-handling), otherwise expect it to crash. .AP "Tcl_Obj *const" *objv in The array of arguments to be parsed. .AP Tcl_Obj ***remObjv out 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 @@ -78,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 @@ -113,7 +119,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 @@ -132,10 +138,10 @@ function will have the following signature: .RS .PP .CS -typedef int (\fBTcl_ArgvGenFuncProc\fR)( - ClientData \fIclientData\fR, +typedef Tcl_Size (\fBTcl_ArgvGenFuncProc\fR)( + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, - int \fIobjc\fR, + Tcl_Size \fIobjc\fR, Tcl_Obj *const *\fIobjv\fR, void *\fIdstPtr\fR); .CE diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index e61cbf3..68b2b52 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,20 @@ 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) +.fi .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 Tcl_Size 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 +188,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 +197,20 @@ return parse information in two data structures, Tcl_Parse and Tcl_Token: .CS typedef struct { const char *\fIcommentStart\fR; - int \fIcommentSize\fR; + Tcl_Size \fIcommentSize\fR; const char *\fIcommandStart\fR; - int \fIcommandSize\fR; - int \fInumWords\fR; + Tcl_Size \fIcommandSize\fR; + Tcl_Size \fInumWords\fR; Tcl_Token *\fItokenPtr\fR; - int \fInumTokens\fR; + Tcl_Size \fInumTokens\fR; ... } \fBTcl_Parse\fR; typedef struct { int \fItype\fR; const char *\fIstart\fR; - int \fIsize\fR; - int \fInumComponents\fR; + Tcl_Size \fIsize\fR; + Tcl_Size \fInumComponents\fR; } \fBTcl_Token\fR; .CE .PP @@ -445,13 +431,6 @@ 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 bdf6103..c19065b 100644 --- a/doc/PkgRequire.3 +++ b/doc/PkgRequire.3 @@ -33,6 +33,7 @@ int .sp int \fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR) +.fi .SH ARGUMENTS .AS void *clientDataPtr out .AP Tcl_Interp *interp in @@ -54,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 Tcl_Size 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..d676b9a 100644 --- a/doc/Preserve.3 +++ b/doc/Preserve.3 @@ -19,9 +19,10 @@ Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it \fBTcl_Release\fR(\fIclientData\fR) .sp \fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR) +.fi .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 @@ -80,18 +81,15 @@ type \fBTcl_FreeProc\fR: .PP .CS typedef void \fBTcl_FreeProc\fR( - char *\fIblockPtr\fR); + void *\fIblockPtr\fR); .CE .PP The \fIblockPtr\fR argument to \fIfreeProc\fR will be the same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR. -The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the -\fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical -reasons, but the value is the same. .PP 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..79398ab 100644 --- a/doc/PrintDbl.3 +++ b/doc/PrintDbl.3 @@ -15,13 +15,11 @@ Tcl_PrintDouble \- Convert floating value to string \fB#include <tcl.h>\fR .sp \fBTcl_PrintDouble\fR(\fIinterp, value, dst\fR) +.fi .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 +39,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..7bfee95 100644 --- a/doc/RecEvalObj.3 +++ b/doc/RecEvalObj.3 @@ -15,6 +15,7 @@ Tcl_RecordAndEvalObj \- save command on history list before evaluating .sp int \fBTcl_RecordAndEvalObj\fR(\fIinterp, cmdPtr, flags\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in @@ -31,7 +32,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/RecordEval.3 b/doc/RecordEval.3 index 36ef6b9..a5887f0 100644 --- a/doc/RecordEval.3 +++ b/doc/RecordEval.3 @@ -16,6 +16,7 @@ Tcl_RecordAndEval \- save command on history list before evaluating .sp int \fBTcl_RecordAndEval\fR(\fIinterp, cmd, flags\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in diff --git a/doc/RegConfig.3 b/doc/RegConfig.3 index 46be360..f2bd2e3 100644 --- a/doc/RegConfig.3 +++ b/doc/RegConfig.3 @@ -14,9 +14,8 @@ Tcl_RegisterConfig \- procedures to register embedded configuration information .nf \fB#include <tcl.h>\fR .sp -void \fBTcl_RegisterConfig\fR(\fIinterp, pkgName, configuration, valEncoding\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_Interp *configuration .AP Tcl_Interp *interp in diff --git a/doc/RegExp.3 b/doc/RegExp.3 index 4010f13..114bbbb 100644 --- a/doc/RegExp.3 +++ b/doc/RegExp.3 @@ -27,7 +27,6 @@ Tcl_RegExp int \fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fItext\fR, \fIstart\fR) .sp -void \fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR) .sp Tcl_RegExp @@ -36,7 +35,6 @@ Tcl_RegExp int \fBTcl_RegExpExecObj\fR(\fIinterp\fR, \fIregexp\fR, \fItextObj\fR, \fIoffset\fR, \fInmatches\fR, \fIeflags\fR) .sp -void \fBTcl_RegExpGetInfo\fR(\fIregexp\fR, \fIinfoPtr\fR) .fi .SH ARGUMENTS @@ -64,7 +62,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 Tcl_Size 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 +78,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 Tcl_Size 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 Tcl_Size 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 negative, then all of the matching subexpressions will be remembered. Any other value will be taken as the maximum number of subexpressions to remember. @@ -350,9 +348,9 @@ defined as follows: .PP .CS typedef struct { - int \fInsubs\fR; + Tcl_Size \fInsubs\fR; Tcl_RegExpIndices *\fImatches\fR; - long \fIextendStart\fR; + Tcl_Size \fIextendStart\fR; } \fBTcl_RegExpInfo\fR; .CE .PP @@ -368,8 +366,8 @@ follows: .PP .CS typedef struct { - long \fIstart\fR; - long \fIend\fR; + Tcl_Size \fIstart\fR; + Tcl_Size \fIend\fR; } \fBTcl_RegExpIndices\fR; .CE .PP diff --git a/doc/SaveInterpState.3 b/doc/SaveInterpState.3 index 9f9a2de..619ff0b 100644 --- a/doc/SaveInterpState.3 +++ b/doc/SaveInterpState.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state +Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState \- save and restore an interpreter's state .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -21,12 +21,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) .fi .SH ARGUMENTS .AS Tcl_InterpState savedPtr @@ -36,40 +30,21 @@ Interpreter for which state should be saved. Return code value to save as part of interpreter state. .AP Tcl_InterpState state in Saved state token to be restored or discarded. -.AP Tcl_SavedResult *savedPtr in -Pointer to location where interpreter result should be saved or restored. .BE .SH DESCRIPTION .PP These routines allows a C procedure to take a snapshot of the current state of an interpreter so that it can be restored after a call to \fBTcl_Eval\fR or some other routine that modifies the interpreter -state. There are two triplets of routines meant to work together. +state. .PP -The first triplet stores the snapshot of interpreter state in +\fBTcl_SaveInterpState\fR stores a snapshot of the interpreter state in an opaque token returned by \fBTcl_SaveInterpState\fR. That token value may then be passed back to one of \fBTcl_RestoreInterpState\fR or \fBTcl_DiscardInterpState\fR, depending on whether the interp state is to be restored. So long as one of the latter two routines is called, Tcl will take care of memory management. .PP -The second triplet stores the snapshot of only the interpreter -result (not its complete state) in memory allocated by the caller. -These routines are passed a pointer to \fBTcl_SavedResult\fR -that is used to store enough information to restore the interpreter result. -\fBTcl_SavedResult\fR can be allocated on the stack of the calling -procedure. These routines do not save the state of any error -information in the interpreter (e.g. the \fB\-errorcode\fR or -\fB\-errorinfo\fR return options, when an error is in progress). -.PP -Because the routines \fBTcl_SaveInterpState\fR, -\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR perform -a superset of the functions provided by the other routines, -any new code should only make use of the more powerful routines. -The older, weaker routines \fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, -and \fBTcl_DiscardResult\fR continue to exist only for the sake -of existing programs that may already be using them. -.PP \fBTcl_SaveInterpState\fR takes a snapshot of those portions of interpreter state that make up the full result of script evaluation. This include the interpreter result, the return code (passed in @@ -77,8 +52,7 @@ as the \fIstatus\fR argument, and any return options, including \fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress. This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR. The call to \fBTcl_SaveInterpState\fR does not itself change the -state of the interpreter. Unlike \fBTcl_SaveResult\fR, it does -not reset the interpreter. +state of the interpreter. .PP \fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token previously returned by \fBTcl_SaveInterpState\fR and restores the @@ -96,26 +70,5 @@ must eventually be passed to either \fBTcl_RestoreInterpState\fR or \fBTcl_DiscardInterpState\fR to avoid a memory leak. Once the \fBTcl_InterpState\fR token is passed to one of them, the token is no longer valid and should not be used anymore. -.PP -\fBTcl_SaveResult\fR moves the string and value results -of \fIinterp\fR into the location specified by \fIstatePtr\fR. -\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and -leaves the result in its normal empty initialized state. -.PP -\fBTcl_RestoreResult\fR moves the string and value results from -\fIstatePtr\fR back into \fIinterp\fR. Any result or error that was -already in the interpreter will be cleared. The \fIstatePtr\fR is left -in an uninitialized state and cannot be used until another call to -\fBTcl_SaveResult\fR. -.PP -\fBTcl_DiscardResult\fR releases the saved interpreter state -stored at \fBstatePtr\fR. The state structure is left in an -uninitialized state and cannot be used until another call to -\fBTcl_SaveResult\fR. -.PP -Once \fBTcl_SaveResult\fR is called to save the interpreter -result, either \fBTcl_RestoreResult\fR or -\fBTcl_DiscardResult\fR must be called to properly clean up the -memory associated with the saved state. .SH KEYWORDS result, state, interp diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3 index 473b61c..e7593b7 100644 --- a/doc/SetChanErr.3 +++ b/doc/SetChanErr.3 @@ -14,18 +14,14 @@ Tcl_SetChannelError, Tcl_SetChannelErrorInterp, Tcl_GetChannelError, Tcl_GetChan .nf \fB#include <tcl.h>\fR .sp -void \fBTcl_SetChannelError\fR(\fIchan, msg\fR) .sp -void \fBTcl_SetChannelErrorInterp\fR(\fIinterp, msg\fR) .sp -void \fBTcl_GetChannelError\fR(\fIchan, msgPtr\fR) .sp -void \fBTcl_GetChannelErrorInterp\fR(\fIinterp, msgPtr\fR) -.sp +.fi .SH ARGUMENTS .AS Tcl_Channel chan .AP Tcl_Channel chan in @@ -87,14 +83,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..b2d1705 100644 --- a/doc/SetRecLmt.3 +++ b/doc/SetRecLmt.3 @@ -14,14 +14,15 @@ Tcl_SetRecursionLimit \- set maximum allowable nesting depth in interpreter .nf \fB#include <tcl.h>\fR .sp -int +Tcl_Size \fBTcl_SetRecursionLimit\fR(\fIinterp, depth\fR) +.fi .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 Tcl_Size depth in New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR. .BE @@ -29,7 +30,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 d08d06d..d3201aa 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) .fi .SH ARGUMENTS .AS Tcl_FreeProc sourceInterp out @@ -52,9 +48,6 @@ to the existing result of \fIinterp\fR. Address of procedure to call to release storage at \fIresult\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or \fBTCL_VOLATILE\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 Tcl_Interp *sourceInterp in Interpreter that the result and return options should be transferred from. .AP Tcl_Interp *targetInterp in @@ -144,11 +137,6 @@ extensions. Any number of \fIresult\fR arguments may be passed in a single call; the last argument in the list must be (char *)NULL. .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, @@ -185,22 +173,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 @@ -235,7 +207,7 @@ result that match the type \fBTcl_FreeProc\fR: .PP .CS typedef void \fBTcl_FreeProc\fR( - char *\fIblockPtr\fR); + void *\fIblockPtr\fR); .CE .PP When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to @@ -262,7 +234,7 @@ interpreter result value; it should be copied instead of being relied upon to persist after the next Tcl API call, as most Tcl operations can modify the interpreter result. .PP -\fBTcl_SetResult\fR, \fBTcl_AppendResult\fR, \fBTcl_AppendResultVA\fR, +\fBTcl_SetResult\fR, \fBTcl_AppendResult\fR, \fBTcl_AppendElement\fR, and \fBTcl_ResetResult\fR all modify the interpreter result. They may cause the old interpreter result to have its reference count decremented and a new interpreter result to be allocated. After they have been diff --git a/doc/SetVar.3 b/doc/SetVar.3 index 98b46d8..c34e55f 100644 --- a/doc/SetVar.3 +++ b/doc/SetVar.3 @@ -43,6 +43,7 @@ int .sp int \fBTcl_UnsetVar2\fR(\fIinterp, name1, name2, flags\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *newValuePtr .AP Tcl_Interp *interp in diff --git a/doc/Signal.3 b/doc/Signal.3 index 0a280f9..a0d7417 100644 --- a/doc/Signal.3 +++ b/doc/Signal.3 @@ -18,7 +18,7 @@ const char * .sp const char * \fBTcl_SignalMsg\fR(\fIsig\fR) -.sp +.fi .SH ARGUMENTS .AS int sig .AP int sig in diff --git a/doc/Sleep.3 b/doc/Sleep.3 index 656d72a..082adb2 100644 --- a/doc/Sleep.3 +++ b/doc/Sleep.3 @@ -15,6 +15,7 @@ Tcl_Sleep \- delay execution for a given number of milliseconds \fB#include <tcl.h>\fR .sp \fBTcl_Sleep\fR(\fIms\fR) +.fi .SH ARGUMENTS .AS int ms .AP int ms in diff --git a/doc/SourceRCFile.3 b/doc/SourceRCFile.3 index bf8c527..3175cd1 100644 --- a/doc/SourceRCFile.3 +++ b/doc/SourceRCFile.3 @@ -11,8 +11,8 @@ Tcl_SourceRCFile \- source the Tcl rc file .nf \fB#include <tcl.h>\fR .sp -void \fBTcl_SourceRCFile\fR(\fIinterp\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in diff --git a/doc/SplitList.3 b/doc/SplitList.3 index 863e322..d036ace 100644 --- a/doc/SplitList.3 +++ b/doc/SplitList.3 @@ -20,17 +20,18 @@ int char * \fBTcl_Merge\fR(\fIargc, argv\fR) .sp -int +Tcl_Size \fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR) .sp -int +Tcl_Size \fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR) .sp -int +Tcl_Size \fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR) .sp -int +Tcl_Size \fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR) +.fi .SH ARGUMENTS .AS "const char *const" ***argvPtr out .AP Tcl_Interp *interp out @@ -38,14 +39,19 @@ 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 "Tcl_Size \&| int" *argcPtr out Filled in with number of elements in \fIlist\fR. +May be (Tcl_Size *)NULL when not used. If it points to a variable which +type is not \fBTcl_Size\fR, a compiler warning will be generated. +If your extensions is compiled with -DTCL_8_API, this function will return +TCL_ERROR for lists with more than INT_MAX elements (which should +trigger proper error-handling), otherwise expect it to crash. .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 Tcl_Size 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 +61,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 Tcl_Size 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 +87,8 @@ For example, suppose that you have called \fBTcl_SplitList\fR with the following code: .PP .CS -int argc, code; +Tcl_Size argc; +int code; char *string; char **argv; \&... @@ -92,12 +99,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..452baff 100644 --- a/doc/SplitPath.3 +++ b/doc/SplitPath.3 @@ -20,19 +20,25 @@ char * .sp Tcl_PathType \fBTcl_GetPathType\fR(\fIpath\fR) +.fi .SH ARGUMENTS .AS "const char *const" ***argvPtr in/out .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 "Tcl_Size \&| int" *argcPtr out Filled in with number of path elements in \fIpath\fR. +May be (Tcl_Size *)NULL when not used. If it points to a variable which +type is not \fBTcl_Size\fR, a compiler warning will be generated. +If your extensions is compiled with -DTCL_8_API, argcPtr will be filled +with -1 for paths with more than INT_MAX elements (which should +trigger proper error-handling), otherwise expect it to crash. .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 Tcl_Size 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 +67,7 @@ For example, suppose that you have called \fBTcl_SplitPath\fR with the following code: .PP .CS -int argc; +Tcl_Size argc; char *path; char **argv; \&... @@ -72,7 +78,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..9cad43d 100644 --- a/doc/StaticLibrary.3 +++ b/doc/StaticLibrary.3 @@ -16,6 +16,7 @@ Tcl_StaticLibrary, Tcl_StaticPackage \- make a statically linked library availab \fBTcl_StaticLibrary\fR(\fIinterp, prefix, initProc, safeInitProc\fR) .sp \fBTcl_StaticPackage\fR(\fIinterp, prefix, initProc, safeInitProc\fR) +.fi .SH ARGUMENTS .AS Tcl_LibraryInitProc *safeInitProc .AP Tcl_Interp *interp in @@ -24,8 +25,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 +71,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/StrMatch.3 b/doc/StrMatch.3 index d664067..89b4ae0 100644 --- a/doc/StrMatch.3 +++ b/doc/StrMatch.3 @@ -19,6 +19,7 @@ int .sp int \fBTcl_StringCaseMatch\fR(\fIstr\fR, \fIpattern\fR, \fIflags\fR) +.fi .SH ARGUMENTS .AS "const char" *pattern .AP "const char" *str in diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 44b2500..4682cae 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 +Tcl_Size \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 * @@ -95,7 +92,7 @@ unless \fInumChars\fR is negative. (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 Tcl_Size 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. @@ -104,17 +101,17 @@ 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 +.AP Tcl_Size 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 +.AP Tcl_Size index in The index of the Unicode character to return. -.AP int first in +.AP Tcl_Size 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 value was 0. -.AP int last in +.AP Tcl_Size 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 the last one available. @@ -122,15 +119,17 @@ the last one available. A pointer to a value to read, or to an unshared value to modify. .AP Tcl_Obj *appendObjPtr in The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR. -.AP int *lengthPtr out +.AP "Tcl_Size \&| 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. +of a value's string representation. +May be (Tcl_Size *)NULL when not used. If it points to a variable which +type is not \fBTcl_Size\fR, a compiler warning will be generated. +If your extensions is compiled with -DTCL_8_API, this function will +panic for strings with more than INT_MAX bytes/characters, otherwise +expect it to crash. .AP "const char" *string in 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 Tcl_Size limit in Maximum number of bytes to be appended. .AP "const char" *ellipsis in Suffix to append when the limit leads to string truncation. @@ -139,11 +138,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 Tcl_Size 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 Tcl_Size newLength in New length for the string value of \fIobjPtr\fR, not including the final null character. .BE @@ -207,15 +206,15 @@ where the caller does not need the length of the unicode string representation. .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; +value's Unicode representation. If the index is out of range +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 is negative, then the returned +string starts at the beginning of the value. If \fIlast\fR negative, then the returned string ends at the end of the value. .PP \fBTcl_GetCharLength\fR returns the number of characters (as opposed @@ -254,12 +253,6 @@ values may contain internal null characters). Any number of \fIstring\fR arguments may be provided, but the last argument must be (char *)NULL 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 @@ -272,7 +265,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 negative, 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. diff --git a/doc/SubstObj.3 b/doc/SubstObj.3 index f10e01d..2867df8 100644 --- a/doc/SubstObj.3 +++ b/doc/SubstObj.3 @@ -15,6 +15,7 @@ Tcl_SubstObj \- perform substitutions on Tcl values .sp Tcl_Obj * \fBTcl_SubstObj\fR(\fIinterp, objPtr, flags\fR) +.fi .SH ARGUMENTS .AS Tcl_Interp **termPtr .AP Tcl_Interp *interp in 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 7a9628c..d14ba48 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 Tcl_Size 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 Tcl_Size 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 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..6410450 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 @@ -27,9 +27,10 @@ Tcl_Obj * \fBTcl_GetStartupScript\fR(\fIencodingPtr\fR) .sp \fBTcl_SetMainLoop\fR(\fImainLoopProc\fR) +.fi .SH ARGUMENTS .AS Tcl_MainLoopProc *mainLoopProc -.AP int argc in +.AP Tcl_Size argc in Number of elements in \fIargv\fR. .AP char *argv[] in Array of strings containing command-line arguments. On Windows, when @@ -203,6 +204,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 ac60230..2e5cd0a 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -14,25 +14,19 @@ Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData .nf \fB#include <tcl.h>\fR .sp -void \fBTcl_ConditionNotify\fR(\fIcondPtr\fR) .sp -void \fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR) .sp -void \fBTcl_ConditionFinalize\fR(\fIcondPtr\fR) .sp -Void * +void * \fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR) .sp -void \fBTcl_MutexLock\fR(\fImutexPtr\fR) .sp -void \fBTcl_MutexUnlock\fR(\fImutexPtr\fR) .sp -void \fBTcl_MutexFinalize\fR(\fImutexPtr\fR) .sp int @@ -40,6 +34,7 @@ int .sp int \fBTcl_JoinThread\fR(\fIid, result\fR) +.fi .SH ARGUMENTS .AS Tcl_CreateThreadProc proc out .AP Tcl_Condition *condPtr in @@ -67,9 +62,9 @@ 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 unsigned stackSize in +.AP size_t stackSize in The size of the stack given to the new thread. .AP int flags in Bitmask containing flags allowing the caller to modify behavior of @@ -81,10 +76,7 @@ waited upon into it. .SH INTRODUCTION Beginning with the 8.1 release, the Tcl core is thread safe, which allows you to incorporate Tcl into multithreaded applications without -customizing the Tcl core. Starting with the 8.6 release, Tcl -multithreading support is on by default. To disable Tcl multithreading -support, you must include the \fB\-\|\-disable-threads\fR option to -\fBconfigure\fR when you configure and compile your Tcl core. +customizing the Tcl core. .PP An important constraint of the Tcl threads implementation is that \fIonly the thread that created a Tcl interpreter can use that @@ -208,7 +200,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 +215,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..580a5b3 100644 --- a/doc/ToUpper.3 +++ b/doc/ToUpper.3 @@ -22,14 +22,15 @@ int int \fBTcl_UniCharToTitle\fR(\fIch\fR) .sp -int +Tcl_Size \fBTcl_UtfToUpper\fR(\fIstr\fR) .sp -int +Tcl_Size \fBTcl_UtfToLower\fR(\fIstr\fR) .sp -int +Tcl_Size \fBTcl_UtfToTitle\fR(\fIstr\fR) +.fi .SH ARGUMENTS .AS char *str in/out .AP int ch in diff --git a/doc/TraceCmd.3 b/doc/TraceCmd.3 index 94e8e64..c1f2cbb 100644 --- a/doc/TraceCmd.3 +++ b/doc/TraceCmd.3 @@ -13,14 +13,14 @@ Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames an .nf \fB#include <tcl.h>\fR .sp -ClientData -\fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR +void * +\fBTcl_CommandTraceInfo\fR(\fIinterp, cmdName, flags, proc, prevClientData\fR) .sp int -\fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR +\fBTcl_TraceCommand\fR(\fIinterp, cmdName, flags, proc, clientData\fR) .sp -void -\fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR +\fBTcl_UntraceCommand\fR(\fIinterp, cmdName, flags, proc, clientData\fR) +.fi .SH ARGUMENTS .AS Tcl_CommandTraceProc prevClientData .AP Tcl_Interp *interp in @@ -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. @@ -67,7 +67,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, @@ -76,7 +76,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 587ca70..3fb3ab6 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 @@ -15,22 +15,23 @@ Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, \fB#include <tcl.h>\fR .sp int -\fBTcl_TraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR +\fBTcl_TraceVar\fR(\fIinterp, varName, flags, proc, clientData\fR) .sp int -\fBTcl_TraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR +\fBTcl_TraceVar2\fR(\fIinterp, name1, name2, flags, proc, clientData\fR) .sp -\fBTcl_UntraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR +\fBTcl_UntraceVar\fR(\fIinterp, varName, flags, proc, clientData\fR) .sp -\fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR +\fBTcl_UntraceVar2\fR(\fIinterp, name1, name2, flags, proc, clientData\fR) .sp -ClientData -\fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR +void * +\fBTcl_VarTraceInfo\fR(\fIinterp, varName, flags, proc, prevClientData\fR) .sp -ClientData -\fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR +void * +\fBTcl_VarTraceInfo2\fR(\fIinterp, name1, name2, flags, proc, prevClientData\fR) +.fi .SH ARGUMENTS -.AS Tcl_VarTraceProc prevClientData +.AS void *prevClientData .AP Tcl_Interp *interp in Interpreter containing variable. .AP "const char" *varName in @@ -46,7 +47,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 +55,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 @@ -114,7 +115,7 @@ before an array set, but that will trigger write traces. . 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 @@ -132,7 +133,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, @@ -142,12 +143,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, @@ -316,7 +319,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 @@ -341,7 +344,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..0b6db29 100644 --- a/doc/Translate.3 +++ b/doc/Translate.3 @@ -9,20 +9,20 @@ .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 .sp char * \fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR) +.fi .SH ARGUMENTS .AS Tcl_DString *bufferPtr in/out .AP Tcl_Interp *interp in Interpreter in which to report an error, if any. .AP "const char" *name in -File name, which may start with a -.QW ~ . +File name .AP Tcl_DString *bufferPtr in/out If needed, this dynamic string is used to store the new file name. At the time of the call it should be uninitialized or free. The @@ -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 diff --git a/doc/UpVar.3 b/doc/UpVar.3 index 9e17ed5..d755b34 100644 --- a/doc/UpVar.3 +++ b/doc/UpVar.3 @@ -15,10 +15,11 @@ Tcl_UpVar, Tcl_UpVar2 \- link one variable to another \fB#include <tcl.h>\fR .sp int -\fBTcl_UpVar(\fIinterp, frameName, sourceName, destName, flags\fB)\fR +\fBTcl_UpVar\fR(\fIinterp, frameName, sourceName, destName, flags\fR) .sp int -\fBTcl_UpVar2(\fIinterp, frameName, name1, name2, destName, flags\fB)\fR +\fBTcl_UpVar2\fR(\fIinterp, frameName, name1, name2, destName, flags\fR) +.fi .SH ARGUMENTS .AS "const char" *sourceName .AP Tcl_Interp *interp in @@ -15,16 +15,16 @@ Tcl_UniChar, Tcl_UniCharToUtf, Tcl_UtfToUniChar, Tcl_UtfToChar16, Tcl_UtfToWChar .sp typedef ... \fBTcl_UniChar\fR; .sp -int +Tcl_Size \fBTcl_UniCharToUtf\fR(\fIch, buf\fR) .sp -int +Tcl_Size \fBTcl_UtfToUniChar\fR(\fIsrc, chPtr\fR) .sp -int +Tcl_Size \fBTcl_UtfToChar16\fR(\fIsrc, uPtr\fR) .sp -int +Tcl_Size \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, numBytes\fR) @@ -93,8 +93,9 @@ int const char * \fBTcl_UtfAtIndex\fR(\fIsrc, index\fR) .sp -int +Tcl_Size \fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR) +.fi .SH ARGUMENTS .AS "const Tcl_UniChar" *uniPattern in/out .AP char *buf out @@ -143,11 +144,9 @@ The length of the input in wchar_t units. If negative, the length includes all bytes until the first null. .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 Tcl_Size 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, @@ -172,11 +171,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 @@ -225,7 +225,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 @@ -239,7 +239,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 @@ -306,17 +306,13 @@ 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 -to the second half of a surrogate pair, it returns -1. +characters. If \fIindex\fR is negative 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 negative, +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 4f587aa..864d315 100644 --- a/doc/WrongNumArgs.3 +++ b/doc/WrongNumArgs.3 @@ -14,12 +14,13 @@ Tcl_WrongNumArgs \- generate standard error message for wrong number of argument \fB#include <tcl.h>\fR .sp \fBTcl_WrongNumArgs\fR(\fIinterp, objc, objv, message\fR) +.fi .SH ARGUMENTS .AS "Tcl_Obj *const" *message .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 Tcl_Size objc in Number of leading arguments from \fIobjv\fR to include in error message. .AP "Tcl_Obj *const" objv[] in diff --git a/doc/after.n b/doc/after.n index db3ffc4..a619935 100644 --- a/doc/after.n +++ b/doc/after.n @@ -12,23 +12,21 @@ .SH NAME after \- Execute a command after a time delay .SH SYNOPSIS +.nf \fBafter \fIms\fR -.sp \fBafter \fIms \fR?\fIscript script script ...\fR? -.sp \fBafter cancel \fIid\fR -.sp \fBafter cancel \fIscript script script ...\fR -.sp \fBafter idle \fR?\fIscript script script ...\fR? -.sp \fBafter info \fR?\fIid\fR? +.fi .BE .SH DESCRIPTION .PP This command is used to delay execution of the program or to execute a command in background sometime in the future. It has several forms, depending on the first argument to the command: +.\" METHOD: <none> .TP \fBafter \fIms\fR . @@ -37,6 +35,7 @@ A negative number is treated as 0. The command sleeps for \fIms\fR milliseconds and then returns. While the command is sleeping the application does not respond to events. +.\" METHOD: <timedelay> .TP \fBafter \fIms \fR?\fIscript script script ...\fR? . @@ -56,6 +55,7 @@ to cancel the delayed command using \fBafter cancel\fR. A \fIms\fR value of 0 (or negative) queues the event immediately with priority over other event types (if not installed with an event proc, which will wait for next round of events). +.\" METHOD: cancel .TP \fBafter cancel \fIid\fR . @@ -74,6 +74,7 @@ separators (just as in the \fBconcat\fR command). If there is a pending command that matches the string, it is canceled and will never be executed; if no such command is currently pending then the \fBafter cancel\fR command has no effect. +.\" METHOD: idle .TP \fBafter idle \fIscript \fR?\fIscript script ...\fR? . @@ -87,6 +88,7 @@ to cancel the delayed command using \fBafter cancel\fR. If an error occurs while executing the script then the background error will be reported by the command registered with \fBinterp bgerror\fR. +.\" METHOD: info .TP \fBafter info \fR?\fIid\fR? . diff --git a/doc/apply.n b/doc/apply.n index aeb2227..154ddff 100644 --- a/doc/apply.n +++ b/doc/apply.n @@ -44,18 +44,18 @@ interpreted relative to the global namespace even if its name does not start with .QW :: . .PP -The semantics of \fBapply\fR can also be described by: +The semantics of \fBapply\fR can also be described by approximately this: .PP .CS proc apply {fun args} { set len [llength $fun] if {($len < 2) || ($len > 3)} { - error "can't interpret \e"$fun\e" as anonymous function" + error "can't interpret \e"$fun\e" as anonymous function" } lassign $fun argList body ns set name ::$ns::[getGloballyUniqueName] set body0 { - rename [lindex [info level 0] 0] {} + rename [lindex [info level 0] 0] {} } proc $name $argList ${body0}$body set code [catch {uplevel 1 $name $args} res opt] diff --git a/doc/array.n b/doc/array.n index 268597d..6c63366 100644 --- a/doc/array.n +++ b/doc/array.n @@ -23,8 +23,10 @@ Unless otherwise specified for individual commands below, The \fIoption\fR argument determines what action is carried out by the command. The legal \fIoptions\fR (which may be abbreviated) are: +.\" METHOD: anymore .TP \fBarray anymore \fIarrayName searchId\fR +. Returns 1 if there are any more elements left to be processed in an array search, 0 if all elements have already been returned. @@ -35,6 +37,7 @@ This option is particularly useful if an array has an element with an empty name, since the return value from \fBarray nextelement\fR will not indicate whether the search has been completed. +.\" METHOD: default .TP \fBarray default \fIsubcommand arrayName args...\fR .VS TIP508 @@ -82,19 +85,25 @@ value. Raises an error if \fIarrayName\fR is an existing variable that is not an array. .VE TIP508 .RE +.\" METHOD: donesearch .TP \fBarray donesearch \fIarrayName searchId\fR +. This command terminates an array search and destroys all the state associated with that search. \fISearchId\fR indicates which search on \fIarrayName\fR to destroy, and must have been the return value from a previous invocation of \fBarray startsearch\fR. Returns an empty string. +.\" METHOD: exists .TP \fBarray exists \fIarrayName\fR +. Returns 1 if \fIarrayName\fR is an array variable, 0 if there is no variable by that name or if it is a scalar variable. +.\" METHOD: for .TP \fBarray for {\fIkeyVariable valueVariable\fB} \fIarrayName body\fP +. The first argument is a two element list of variable names for the key and value of each entry in the array. The second argument is the array name to iterate over. The third argument is the body to execute @@ -102,8 +111,10 @@ for each key and value returned. The ordering of the returned keys is undefined. If an array element is deleted or a new array element is inserted during the \fIarray for\fP process, the command will terminate with an error. +.\" METHOD: get .TP \fBarray get \fIarrayName\fR ?\fIpattern\fR? +. Returns a list containing pairs of elements. The first element in each pair is the name of an element in \fIarrayName\fR and the second element of each pair is the value of the @@ -118,8 +129,10 @@ the array contains no elements, then an empty list is returned. If traces on the array modify the list of elements, the elements returned are those that exist both before and after the call to \fBarray get\fR. +.\" METHOD: names .TP \fBarray names \fIarrayName\fR ?\fImode\fR? ?\fIpattern\fR? +. Returns a list containing the names of all of the elements in the array that match \fIpattern\fR. \fIMode\fR may be one of \fB\-exact\fR, \fB\-glob\fR, or \fB\-regexp\fR. If specified, \fImode\fR @@ -132,8 +145,10 @@ If \fIpattern\fR is omitted then the command returns all of the element names in the array. If there are no (matching) elements in the array, or if \fIarrayName\fR is not the name of an array variable, then an empty string is returned. +.\" METHOD: nextelement .TP \fBarray nextelement \fIarrayName searchId\fR +. Returns the name of the next element in \fIarrayName\fR, or an empty string if all elements of \fIarrayName\fR have already been returned in this search. The \fIsearchId\fR @@ -143,8 +158,10 @@ Warning: if elements are added to or deleted from the array, then all searches are automatically terminated just as if \fBarray donesearch\fR had been invoked; this will cause \fBarray nextelement\fR operations to fail for those searches. +.\" METHOD: set .TP \fBarray set \fIarrayName list\fR +. Sets the values of one or more elements in \fIarrayName\fR. \fIlist\fR must have a form like that returned by \fBarray get\fR, consisting of an even number of elements. @@ -154,13 +171,17 @@ is used as a new value for that array element. If the variable \fIarrayName\fR does not already exist and \fIlist\fR is empty, \fIarrayName\fR is created with an empty array value. +.\" METHOD: size .TP \fBarray size \fIarrayName\fR +. Returns a decimal string giving the number of elements in the array. If \fIarrayName\fR is not the name of an array then 0 is returned. +.\" METHOD: startsearch .TP \fBarray startsearch \fIarrayName\fR +. This command initializes an element-by-element search through the array given by \fIarrayName\fR, such that invocations of the \fBarray nextelement\fR command will return the names of the @@ -175,14 +196,18 @@ It is currently more efficient and easier to use either the \fBarray get\fR or \fBarray names\fR, together with \fBforeach\fR, to iterate over all but very large arrays. See the examples below for how to do this. +.\" METHOD: statistics .TP \fBarray statistics \fIarrayName\fR +. Returns statistics about the distribution of data within the hashtable that represents the array. This information includes the number of entries in the table, the number of buckets, and the utilization of the buckets. +.\" METHOD: unset .TP \fBarray unset \fIarrayName\fR ?\fIpattern\fR? +. Unsets all of the elements in the array that match \fIpattern\fR (using the matching rules of \fBstring match\fR). If \fIarrayName\fR is not the name of an array variable or there are no matching elements in the array, no diff --git a/doc/binary.n b/doc/binary.n index 6df3e5a..911e170 100644 --- a/doc/binary.n +++ b/doc/binary.n @@ -40,12 +40,15 @@ done by other Tcl commands (respectively \fBstring range\fR, binary string in Tcl is merely one where all the characters it contains are in the range \eu0000\-\eu00FF. .SH "BINARY ENCODE AND DECODE" +.\" METHOD: decode +.\" METHOD: encode .PP 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 . @@ -140,6 +143,7 @@ Note that neither the encoder nor the decoder handle the header and footer of the uuencode format. .RE .SH "BINARY FORMAT" +.\" METHOD: format .PP The \fBbinary format\fR command generates a binary string whose layout is specified by the \fIformatString\fR and whose contents come from @@ -613,12 +617,13 @@ will return .CE .RE .SH "BINARY SCAN" +.\" METHOD: scan .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/callback.n b/doc/callback.n index 3ab81ac..c96b23b 100644 --- a/doc/callback.n +++ b/doc/callback.n @@ -14,8 +14,8 @@ callback, mymethod \- generate callbacks to methods .nf package require tcl::oo -\fBcallback\fR \fImethodName\fR ?\fIarg ...\fR? -\fBmymethod\fR \fImethodName\fR ?\fIarg ...\fR? +\fBcallback\fI methodName\fR ?\fIarg ...\fR? +\fBmymethod\fI methodName\fR ?\fIarg ...\fR? .fi .BE .SH DESCRIPTION diff --git a/doc/catch.n b/doc/catch.n index 8d885d4..0a2c513 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -30,10 +30,12 @@ return codes: 1 (\fBTCL_ERROR\fR), 2 (\fBTCL_RETURN\fR), 3 (\fBTCL_BREAK\fR), and 4 (\fBTCL_CONTINUE\fR). Errors during evaluation of a script are indicated by a return code of \fBTCL_ERROR\fR. The other exceptional return codes are returned by the \fBreturn\fR, \fBbreak\fR, and \fBcontinue\fR commands -and in other special situations as documented. Tcl packages can define -new commands that return other integer values as return codes as well, -and scripts that make use of the \fBreturn \-code\fR command can also -have return codes other than the five defined by Tcl. +and in other special situations as documented. +New commands defined by Tcl packages as well as scripts that make +use of the \fBreturn \-code\fR command can return other integer +values as the return code. These must however lie outside the range +reserved for Tcl as documented for the \fBreturn\fR command. + .PP If the \fIresultVarName\fR argument is given, then the variable it names is set to the result of the script evaluation. When the return code from the @@ -29,7 +29,7 @@ and all threads. Change to the home directory of the user \fBfred\fR: .PP .CS -\fBcd\fR ~fred +\fBcd\fR [file home fred] .CE .PP Change to the directory \fBlib\fR that is a sibling directory of the @@ -192,24 +192,11 @@ operating system, as returned by \fBencoding system\fR. .\" OPTION: -eofchar .TP \fB\-eofchar\fI char\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. 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. +Otherwise (the default) there is no special end of file character marker. 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. @@ -1041,7 +1028,7 @@ full line. .CS % set f [open test_A_195_B.txt r] file384b6a8 -% chan configure $f -encoding utf-8 -profile strict +% chan configure $f -encoding utf-8 % catch {chan gets $f} e d 1 % set d @@ -1065,7 +1052,7 @@ position 1. The data at the error position is thus recovered by the next .CS % set f [open test_A_195_B.txt r] file35a65a0 -% chan configure $f -encoding utf-8 -profile strict -blocking 1 +% chan configure $f -encoding utf-8 -blocking 1 % catch {chan read $f} e d 1 % set d @@ -1086,7 +1073,7 @@ Finally the same example, but this time with a non-blocking channel. .CS % set f [open test_A_195_B.txt r] file35a65a0 -% chan configure $f -encoding utf-8 -profile strict -blocking 0 +% chan configure $f -encoding utf-8 -blocking 0 % chan read $f A % chan tell $f diff --git a/doc/class.n b/doc/class.n index c48f52d..1f4c774 100644 --- a/doc/class.n +++ b/doc/class.n @@ -48,6 +48,7 @@ The \fBoo::class\fR class does not define an explicit destructor. However, when a class is destroyed, all its subclasses and instances are also destroyed, along with all objects that it has been mixed into. .SS "EXPORTED METHODS" +.\" METHOD: create .TP \fIcls \fBcreate \fIname \fR?\fIarg ...\fR? . @@ -58,6 +59,7 @@ a successful result) returning the fully qualified name of the created object (the result of the constructor is ignored). If the constructor fails (i.e. returns a non-OK result) then the object is destroyed and the error message is the result of this method call. +.\" METHOD: new .TP \fIcls \fBnew \fR?\fIarg ...\fR? . @@ -75,6 +77,7 @@ classes should not be created using this method. .SS "NON-EXPORTED METHODS" .PP The \fBoo::class\fR class supports the following non-exported methods: +.\" METHOD: createWithNamespace .TP \fIcls \fBcreateWithNamespace\fI name nsName\fR ?\fIarg ...\fR? . diff --git a/doc/classvariable.n b/doc/classvariable.n index 2eef7e8..198f09e 100644 --- a/doc/classvariable.n +++ b/doc/classvariable.n @@ -15,7 +15,7 @@ classvariable \- create link from local variable to variable in class .nf package require tcl::oo -\fBclassvariable\fR \fIvariableName\fR ?\fI...\fR? +\fBclassvariable\fI variableName\fR ?\fI...\fR? .fi .BE .SH DESCRIPTION diff --git a/doc/clock.n b/doc/clock.n index f1fbf89..5a6e3e4 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -8,38 +8,38 @@ .SH NAME clock \- Obtain and manipulate dates and times .SH "SYNOPSIS" +.nf package require \fBTcl 8.5-\fR -.sp -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? -.sp + +\fBclock add\fI timeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? \fBclock clicks\fR ?\fI\-option\fR? -.sp -\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? -.sp +\fBclock format\fI timeVal\fR ?\fI\-option value\fR...? \fBclock microseconds\fR -.sp \fBclock milliseconds\fR -.sp -\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? -.sp +\fBclock scan\fI inputString\fR ?\fI\-option value\fR...? \fBclock seconds\fR -.sp +.fi .BE .SH "DESCRIPTION" .PP The \fBclock\fR command performs several operations that obtain and manipulate values that represent times. The command supports several subcommands that determine what action is carried out by the command. +.\" METHOD: add .TP -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? +\fBclock add\fI timeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? +. Adds a (possibly negative) offset to a time that is expressed as an integer number of seconds. See \fBCLOCK ARITHMETIC\fR for a full description. +.\" METHOD: clicks .TP \fBclock clicks\fR ?\fI\-option\fR? +. If no \fI\-option\fR argument is supplied, returns a high-resolution time value as a system-dependent integer value. The unit of the value is system-dependent but should be the highest resolution clock available -on the system such as a CPU cycle counter. See \fBHIGH RESOLUTION TIMERS\fR for a full description. +on the system such as a CPU cycle counter. +See \fBHIGH RESOLUTION TIMERS\fR for a full description. .RS .PP If the \fI\-option\fR argument is \fB\-milliseconds\fR, then the command @@ -52,32 +52,46 @@ is synonymous with \fBclock microseconds\fR (see below). This usage is obsolete, and \fBclock microseconds\fR is to be considered the preferred way of obtaining a count of microseconds. .RE +.\" METHOD: format .TP -\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...? +\fBclock format\fI timeVal\fR ?\fI\-option value\fR...? +. Formats a time that is expressed as an integer number of seconds into a format intended for consumption by users or external programs. See \fBFORMATTING TIMES\fR for a full description. +.\" METHOD: microseconds .TP \fBclock microseconds\fR -Returns the current time as an integer number of microseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. +. +Returns the current time as an integer number of microseconds. +See \fBHIGH RESOLUTION TIMERS\fR for a full description. +.\" METHOD: milliseconds .TP \fBclock milliseconds\fR -Returns the current time as an integer number of milliseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. +. +Returns the current time as an integer number of milliseconds. +See \fBHIGH RESOLUTION TIMERS\fR for a full description. +.\" METHOD: scan .TP -\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...? +\fBclock scan\fI inputString\fR ?\fI\-option value\fR...? +. Scans a time that is expressed as a character string and produces an integer number of seconds. See \fBSCANNING TIMES\fR for a full description. +.\" METHOD: seconds .TP \fBclock seconds\fR +. Returns the current time as an integer number of seconds. .SS "PARAMETERS" .TP \fIcount\fR +. An integer representing a count of some unit of time. See \fBCLOCK ARITHMETIC\fR for the details. .TP \fItimeVal\fR +. An integer value passed to the \fBclock\fR command that represents an absolute time as a number of seconds from the \fIepoch time\fR of 1 January 1970, 00:00 UTC. Note that the count of seconds does not @@ -97,18 +111,23 @@ of \fBclock seconds\fR. For example: \fBclock add -now 1 month; # next month\fR .TP \fIunit\fR +. One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR, \fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR. Used in conjunction with \fIcount\fR to identify an interval of time, for example, \fI3 seconds\fR or \fI1 year\fR. .SS "OPTIONS" +.\" OPTION: -base .TP \fB\-base\fR time +. Specifies that any relative times present in a \fBclock scan\fR command are to be given relative to \fItime\fR. \fItime\fR must be expressed as a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC. +.\" OPTION: -format .TP \fB\-format\fR format +. Specifies the desired output format for \fBclock format\fR or the expected input format for \fBclock scan\fR. The \fIformat\fR string consists of any number of characters other than the per-cent sign @@ -128,17 +147,21 @@ On \fBclock scan\fR, the lack of a \fB\-format\fR option indicates that a .QW "free format scan" is requested; see \fBFREE FORM SCAN\fR for a description of what happens. .RE +.\" OPTION: -gmt .TP \fB\-gmt\fR boolean +. If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR, \fBclock format\fR or \fBclock scan\fR should be processed in UTC. If \fIboolean\fR is false, the processing defaults to the local time zone. This usage is obsolete; the correct current usage is to specify the UTC time zone with -.QW "\fB\-timezone\fR \fI:UTC\fR" +.QW "\fB\-timezone\fI :UTC\fR" or any of the equivalent ways to specify it. +.\" OPTION: -locale .TP \fB\-locale\fR localeName +. Specifies that locale-dependent scanning and formatting (and date arithmetic for dates preceding the adoption of the Gregorian calendar) is to be done in the locale identified by \fIlocaleName\fR. The locale name may be any of @@ -152,8 +175,10 @@ descriptions of the individual format groups under \fBFORMAT GROUPS\fR. The effect of locale on clock arithmetic is discussed under \fBCLOCK ARITHMETIC\fR. .RE +.\" OPTION: -timezone .TP \fB\-timezone\fR zoneName +. Specifies that clock arithmetic, formatting, and scanning are to be done according to the rules for the time zone specified by \fIzoneName\fR. The permissible values, and their interpretation, are discussed under @@ -319,9 +344,9 @@ and their interpretation, are described under \fBFORMAT GROUPS\fR. If a \fB\-timezone\fR option is present, the following argument is a string that specifies the time zone in which the date and time are to be formatted. As an alternative to -.QW "\fB\-timezone\fR \fI:UTC\fR" , +.QW "\fB\-timezone\fI :UTC\fR" , the obsolete usage -.QW "\fB\-gmt\fR \fItrue\fR" +.QW "\fB\-gmt\fI true\fR" may be used. See \fBTIME ZONES\fR for the permissible variants for the time zone. .PP @@ -330,14 +355,14 @@ a string that specifies the locale in which the time is to be formatted, in the same format that is used for the \fBmsgcat\fR package. Note that the default, if \fB\-locale\fR is not specified, is the root locale \fB{}\fR rather than the current locale. The current locale may -be obtained by using \fB\-locale\fR \fBcurrent\fR. +be obtained by using \fB\-locale current\fR. In addition, some platforms support a \fBsystem\fR locale that reflects the user's current choices. For instance, on Windows, the format that the user has selected from dates and times in the Control Panel can be obtained by using the \fBsystem\fR locale. On platforms that do not define a user selection of date and time formats -separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is -synonymous with \fB\-locale\fR \fBcurrent\fR. +separate from \fBLC_TIME\fR, \fB\-locale system\fR is +synonymous with \fB\-locale current\fR. .SH "SCANNING TIMES" .PP The \fBclock scan\fR command accepts times that are formatted as @@ -355,8 +380,8 @@ and their interpretation, are described under \fBFORMAT GROUPS\fR. .PP If a \fB\-timezone\fR option is present, the following argument is a string that specifies the time zone in which the date and time -are to be interpreted. As an alternative to \fB\-timezone\fR \fI:UTC\fR, -the obsolete usage \fB\-gmt\fR \fItrue\fR may be used. See +are to be interpreted. As an alternative to \fB\-timezone\fI :UTC\fR, +the obsolete usage \fB\-gmt\fI true\fR may be used. See \fBTIME ZONES\fR for the permissible variants for the time zone. .PP If a \fB\-locale\fR option is present, the following argument is @@ -364,14 +389,14 @@ a string that specifies the locale in which the time is to be interpreted, in the same format that is used for the \fBmsgcat\fR package. Note that the default, if \fB\-locale\fR is not specified, is the root locale \fB{}\fR rather than the current locale. The current locale may -be obtained by using \fB\-locale\fR \fBcurrent\fR. +be obtained by using \fB\-locale current\fR. In addition, some platforms support a \fBsystem\fR locale that reflects the user's current choices. For instance, on Windows, the format that the user has selected from dates and times in the Control Panel can be obtained by using the \fBsystem\fR locale. On platforms that do not define a user selection of date and time formats -separate from \fBLC_TIME\fR, \fB\-locale\fR \fBsystem\fR is -synonymous with \fB\-locale\fR \fBcurrent\fR. +separate from \fBLC_TIME\fR, \fB\-locale system\fR is +synonymous with \fB\-locale current\fR. .PP If a \fB\-base\fR option is present, the following argument is a time (expressed in seconds from the epoch time) that is used as @@ -482,69 +507,57 @@ if the clock had not changed. .PP The following format groups are recognized by the \fBclock scan\fR and \fBclock format\fR commands. -.TP -\fB%a\fR -On output, produces an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day +.IP \fB%a\fR +On output, produces an abbreviation (\fIe.g., \fBMon\fR) for the day of the week in the given locale. On input, matches the name of the day of the week in the given locale (in either abbreviated or full form, or any unique prefix of either form). -.TP -\fB%A\fR -On output, produces the full name (\fIe.g.,\fR \fBMonday\fR) of the day +.IP \fB%A\fR +On output, produces the full name (\fIe.g., \fBMonday\fR) of the day of the week in the given locale. On input, matches the name of the day of the week in the given locale (in either abbreviated or full form, or any unique prefix of either form). -.TP -\fB%b\fR -On output, produces an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name +.IP \fB%b\fR +On output, produces an abbreviation (\fIe.g., \fBJan\fR) for the name of the month in the given locale. On input, matches the name of the month in the given locale (in either abbreviated or full form, or any unique prefix of either form). -.TP -\fB%B\fR -On output, produces the full name (\fIe.g.,\fR \fBJanuary\fR) +.IP \fB%B\fR +On output, produces the full name (\fIe.g., \fBJanuary\fR) of the month in the given locale. On input, matches the name of the month in the given locale (in either abbreviated or full form, or any unique prefix of either form). -.TP -\fB%c\fR +.IP \fB%c\fR On output, produces a localized representation of date and time of day; the localized representation is expected to use the Gregorian calendar. On input, matches whatever \fB%c\fR produces. -.TP -\fB%C\fR +.IP \fB%C\fR On output, produces the number of the century in Indo-Arabic numerals. On input, matches one or two digits, possibly with leading whitespace, that are expected to be the number of the century. -.TP -\fB%d\fR +.IP \fB%d\fR On output, produces the number of the day of the month, as two decimal digits. On input, matches one or two digits, possibly with leading whitespace, that are expected to be the number of the day of the month. -.TP -\fB%D\fR +.IP \fB%D\fR This format group is synonymous with \fB%m/%d/%Y\fR. It should be used only in exchanging data within the \fBen_US\fR locale, since other locales typically do not use this order for the fields of the date. -.TP -\fB%e\fR +.IP \fB%e\fR On output, produces the number of the day of the month, as one or two decimal digits (with a leading blank for one-digit dates). On input, matches one or two digits, possibly with leading whitespace, that are expected to be the number of the day of the month. -.TP -\fB%Ec\fR +.IP \fB%Ec\fR On output, produces a locale-dependent representation of the date and time of day in the locale's alternative calendar. On input, matches whatever \fB%Ec\fR produces. The locale's alternative calendar need not be the Gregorian calendar. -.TP -\fB%EC\fR +.IP \fB%EC\fR On output, produces a locale-dependent name of an era in the locale's alternative calendar. On input, matches the name of the era or any unique prefix. -.TP -\fB%EE\fR +.IP \fB%EE\fR On output, produces the string \fBB.C.E.\fR or \fBC.E.\fR, or a string of the same meaning in the locale, to indicate whether \fB%Y\fR refers to years before or after Year 1 of the Common Era. On input, accepts @@ -552,8 +565,7 @@ the string \fBB.C.E.\fR, \fBB.C.\fR, \fBC.E.\fR, \fBA.D.\fR, or the abbreviation appropriate to the current locale, and uses it to fix whether \fB%Y\fR refers to years before or after Year 1 of the Common Era. -.TP -\fB%Ej\fR +.IP \fB%Ej\fR On output, produces a string of digits giving the Astronomical Julian Date or Astronomical Julian Day Number (JDN/JD). In opposite to calendar julian day \fB%J\fR, it starts the day at noon. @@ -561,12 +573,11 @@ On input, accepts a string of digits (or floating point with the time fraction) and interprets it as an Astronomical Julian Day Number (JDN/JD). The Astronomical Julian Date is a count of the number of calendar days that have elapsed since 1 January, 4713 BCE of the proleptic -Julian calendar, which contains also the time fraction (after floating point). +Julian calendar, which contains also the time fraktion (after floating point). The epoch time of 1 January 1970 corresponds to Astronomical JDN 2440587.5. This value corresponds the julian day used in sqlite-database, and is the same as result of \fBselect julianday(:seconds, 'unixepoch')\fR. -.TP -\fB%EJ\fR +.IP \fB%EJ\fR On output, produces a string of digits giving the Calendar Julian Date. In opposite to julian day \fB%J\fR format group, it produces float number. In opposite to astronomical julian day \fB%Ej\fR group, it starts at midnight. @@ -574,213 +585,176 @@ On input, accepts a string of digits (or floating point with the time fraction) and interprets it as a Calendar Julian Day Number. The Calendar Julian Date is a count of the number of calendar days that have elapsed since 1 January, 4713 BCE of the proleptic -Julian calendar, which contains also the time fraction (after floating point). +Julian calendar, which contains also the time fraktion (after floating point). The epoch time of 1 January 1970 corresponds to Astronomical JDN 2440588. -.TP -\fB%Es\fR +.IP \fB%Es\fR This affects similar to \fB%s\fR, but in opposition to \fB%s\fR it parses or formats local seconds (not the posix seconds). Because \fB%s\fR has the same precedence as \fB%s\fR (uniquely determines a point in time), it overrides all other input formats. -.TP -\fB%Ex\fR +.IP \fB%Ex\fR On output, produces a locale-dependent representation of the date in the locale's alternative calendar. On input, matches whatever \fB%Ex\fR produces. The locale's alternative calendar need not be the Gregorian calendar. -.TP -\fB%EX\fR +.IP \fB%EX\fR On output, produces a locale-dependent representation of the time of day in the locale's alternative numerals. On input, matches whatever \fB%EX\fR produces. -.TP -\fB%Ey\fR +.IP \fB%Ey\fR On output, produces a locale-dependent number of the year of the era in the locale's alternative calendar and numerals. On input, matches such a number. -.TP -\fB%EY\fR +.IP \fB%EY\fR On output, produces a representation of the year in the locale's alternative calendar and numerals. On input, matches what \fB%EY\fR produces. Often synonymous with \fB%EC%Ey\fR. -.TP -\fB%g\fR +.IP \fB%g\fR On output, produces a two-digit year number suitable for use with the week-based ISO8601 calendar; that is, the year number corresponds to the week number produced by \fB%V\fR. On input, accepts such a two-digit year number, possibly with leading whitespace. -.TP -\fB%G\fR +.IP \fB%G\fR On output, produces a four-digit year number suitable for use with the week-based ISO8601 calendar; that is, the year number corresponds to the week number produced by \fB%V\fR. On input, accepts such a four-digit year number, possibly with leading whitespace. -.TP -\fB%h\fR +.IP \fB%h\fR This format group is synonymous with \fB%b\fR. -.TP -\fB%H\fR +.IP \fB%H\fR On output, produces a two-digit number giving the hour of the day (00-23) on a 24-hour clock. On input, accepts such a number. -.TP -\fB%I\fR +.IP \fB%I\fR On output, produces a two-digit number giving the hour of the day (12-11) on a 12-hour clock. On input, accepts such a number. -.TP -\fB%j\fR +.IP \fB%j\fR On output, produces a three-digit number giving the day of the year (001-366). On input, accepts such a number. -.TP -\fB%J\fR +.IP \fB%J\fR On output, produces a string of digits giving the calendar Julian Day Number. On input, accepts a string of digits and interprets it as a Julian Day Number. The Julian Day Number is a count of the number of calendar days that have elapsed since 1 January, 4713 BCE of the proleptic Julian calendar. The epoch time of 1 January 1970 corresponds to Julian Day Number 2440588. -.TP -\fB%k\fR +.IP \fB%k\fR On output, produces a one- or two-digit number giving the hour of the day (0-23) on a 24-hour clock. On input, accepts such a number. -.TP -\fB%l\fR +.IP \fB%l\fR On output, produces a one- or two-digit number giving the hour of the day (12-11) on a 12-hour clock. On input, accepts such a number. -.TP -\fB%m\fR +.IP \fB%m\fR On output, produces the number of the month (01-12) with exactly two digits. On input, accepts two digits and interprets them as the number of the month. -.TP -\fB%M\fR +.IP \fB%M\fR On output, produces the number of the minute of the hour (00-59) with exactly two digits. On input, accepts two digits and interprets them as the number of the minute of the hour. -.TP -\fB%N\fR +.IP \fB%N\fR On output, produces the number of the month (1-12) with one or two digits, and a leading blank for one-digit dates. On input, accepts one or two digits, possibly with leading whitespace, and interprets them as the number of the month. -.TP -\fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR +.IP "\fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR" All of these format groups are synonymous with their counterparts without the .QW \fBO\fR , except that the string is produced and parsed in the locale-dependent alternative numerals. -.TP -\fB%p\fR +.IP \fB%p\fR On output, produces an indicator for the part of the day, \fBAM\fR or \fBPM\fR, appropriate to the given locale. If the script of the given locale supports multiple letterforms, lowercase is preferred. On input, matches the representation \fBAM\fR or \fBPM\fR in the given locale, in either case. -.TP -\fB%P\fR +.IP \fB%P\fR On output, produces an indicator for the part of the day, \fBam\fR or \fBpm\fR, appropriate to the given locale. If the script of the given locale supports multiple letterforms, uppercase is preferred. On input, matches the representation \fBAM\fR or \fBPM\fR in the given locale, in either case. -.TP -\fB%Q\fR +.IP \fB%Q\fR This format group is reserved for internal use within the Tcl library. -.TP -\fB%r\fR +.\" It's the STARDATE! We're so Enterprise-ready... +.IP \fB%r\fR On output, produces a locale-dependent time of day representation on a 12-hour clock. On input, accepts whatever \fB%r\fR produces. -.TP -\fB%R\fR +.IP \fB%R\fR On output, the time in 24-hour notation (%H:%M). For a version including the seconds, see \fB%T\fR below. On input, accepts whatever \fB%R\fR produces. -.TP -\fB%s\fR +.IP \fB%s\fR On output, simply formats the \fItimeVal\fR argument as a decimal integer and inserts it into the output string. On input, accepts a decimal integer and uses is as the time value without any further processing. Since \fB%s\fR uniquely determines a point in time, it overrides all other input formats. -.TP -\fB%S\fR +.IP \fB%S\fR On output, produces a two-digit number of the second of the minute (00-59). On input, accepts two digits and uses them as the second of the minute. -.TP -\fB%t\fR +.IP \fB%t\fR On output, produces a TAB character. On input, matches a TAB character. -.TP -\fB%T\fR +.IP \fB%T\fR Synonymous with \fB%H:%M:%S\fR. -.TP -\fB%u\fR +.IP \fB%u\fR On output, produces the number of the day of the week (\fB1\fR\(->Monday, \fB7\fR\(->Sunday). On input, accepts a single digit and interprets it as the day of the week. Sunday may be either \fB0\fR or \fB7\fR. -.TP -\fB%U\fR +.IP \fB%U\fR On output, produces the ordinal number of the week of the year (00-53). The first Sunday of the year is the first day of week 01. On input accepts two digits which are otherwise ignored. This format group is never used in determining an input date. This interpretation of the week of the year was once common in US banking but is now largely obsolete. See \fB%V\fR for the ISO8601 week number. -.TP -\fB%V\fR +.IP \fB%V\fR On output, produces the number of the ISO8601 week as a two digit number (01-53). Week 01 is the week containing January 4; or the first week of the year containing at least 4 days; or the week containing the first Thursday of the year (the three statements are equivalent). Each week begins on a Monday. On input, accepts the ISO8601 week number. -.TP -\fB%w\fR +.IP \fB%w\fR On output, produces the ordinal number of the day of the week (Sunday==0; Saturday==6). On input, accepts a single digit and interprets it as the day of the week; Sunday may be represented as either 0 or 7. Note that \fB%w\fR is not the ISO8601 weekday number, which is produced and accepted by \fB%u\fR. -.TP -\fB%W\fR +.IP \fB%W\fR On output, produces a week number (00-53) within the year; week 01 begins on the first Monday of the year. On input, accepts two digits, which are otherwise ignored. This format group is never used in determining an input date. It is not the ISO8601 week number; that week is produced and accepted by \fB%V\fR. -.TP -\fB%x\fR +.IP \fB%x\fR On output, produces the date in a locale-dependent representation. On input, accepts whatever \fB%x\fR produces and is used to determine calendar date. -.TP -\fB%X\fR +.IP \fB%X\fR On output, produces the time of day in a locale-dependent representation. On input, accepts whatever \fB%X\fR produces and is used to determine time of day. -.TP -\fB%y\fR +.IP \fB%y\fR On output, produces the two-digit year of the century. On input, accepts two digits, and is used to determine calendar date. The date is presumed to lie between 1938 and 2037 inclusive. Note that \fB%y\fR does not yield a year appropriate for use with the ISO8601 week number \fB%V\fR; programs should use \fB%g\fR for that purpose. -.TP -\fB%Y\fR +.IP \fB%Y\fR On output, produces the four-digit calendar year. On input, accepts four digits and may be used to determine calendar date. Note that \fB%Y\fR does not yield a year appropriate for use with the ISO8601 week number \fB%V\fR; programs should use \fB%G\fR for that purpose. -.TP -\fB%z\fR +.IP \fB%z\fR On output, produces the current time zone, expressed in hours and minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a time zone specifier (see \fBTIME ZONES\fR below) that will be used to determine the time zone (this token is optionally applicable on input, so the value is not mandatory and can be missing in input). -.TP -\fB%Z\fR +.IP \fB%Z\fR On output, produces the current time zone's name, possibly translated to the given locale. On input, accepts a time zone specifier (see \fBTIME ZONES\fR below) that will be used to determine the @@ -790,15 +764,13 @@ parsing RFC822 dates. Other uses are fraught with ambiguity; for instance, the string \fBBST\fR may represent British Summer Time or Brazilian Standard Time. It is recommended that date/time strings for use by computers use numeric time zones instead. -.TP -\fB%%\fR +.IP \fB%%\fR On output, produces a literal .QW \fB%\fR character. On input, matches a literal .QW \fB%\fR character. -.TP -\fB%+\fR +.IP \fB%+\fR Synonymous with .QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" . .SH "TIME ZONES" @@ -811,7 +783,7 @@ A time zone specified inside a string being parsed and matched by a \fB%z\fR or \fB%Z\fR format group. .IP [2] A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR -command (or, equivalently, by \fB\-gmt\fR \fB1\fR). +command (or, equivalently, by \fB\-gmt 1\fR). .IP [3] A time zone specified in an environment variable \fBTCL_TZ\fR. .IP [4] @@ -897,8 +869,9 @@ specification. .SH "FREE FORM SCAN" .PP If the \fBclock scan\fR command is invoked without a \fB\-format\fR -option, then it requests a \fIfree-form scan.\fR \fI -This form of scan is deprecated.\fR The reason for the deprecation +option, then it requests a \fIfree-form scan\fR. +\fIThis form of scan is deprecated.\fR +The reason for the deprecation is that there are too many ambiguities. (Does the string .QW 2000 represent a year, a time of day, or a quantity?) No set of rules @@ -949,7 +922,7 @@ acceptable formats are .QW "\fIdd monthname yy\fR" , .QW "?\fICC\fR?\fIyymmdd\fR" , and -.QW "\fIdd\fB-\fImonthname\fB-\fR?\fICC\fR?\fIyy\fR" . +.QW "\fIdd\fB\-\fImonthname\fB\-\fR?\fICC\fR?\fIyy\fR" . The default year is the current year. If the year is less than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 as 1969-1999. Not all platforms can represent the years 38-70, so diff --git a/doc/concat.n b/doc/concat.n index d10f092..c83d2c4 100644 --- a/doc/concat.n +++ b/doc/concat.n @@ -28,7 +28,7 @@ Although \fBconcat\fR will concatenate lists, flattening them in the process (so giving the following interactive session): .PP .CS -\fI%\fR \fBconcat\fR a b {c d e} {f {g h}} +\fI% \fBconcat\fR a b {c d e} {f {g h}} \fIa b c d e f {g h}\fR .CE .PP @@ -36,7 +36,7 @@ it will also concatenate things that are not lists, as can be seen from this session: .PP .CS -\fI%\fR \fBconcat\fR " a b {c " d " e} f" +\fI% \fBconcat\fR " a b {c " d " e} f" \fIa b {c d e} f\fR .CE .PP @@ -44,14 +44,22 @@ Note also that the concatenation does not remove spaces from the middle of values, as can be seen here: .PP .CS -\fI%\fR \fBconcat\fR "a b c" { d e f } +\fI% \fBconcat\fR "a b c" { d e f } \fIa b c d e f\fR .CE .PP (i.e., there are three spaces between each of the \fBa\fR, the \fBb\fR and the \fBc\fR). +.PP +For \fItrue\fR list concatenation, the \fBlist\fR command should be used with +expansion of each input list: +.PP +.CS +\fI% \fRlist {*}"a b c" {*}{ d e f } +\fIa b c d e f\fR +.CE .SH "SEE ALSO" -append(n), eval(n), join(n) +append(n), eval(n), join(n), list(n) .SH KEYWORDS concatenate, join, list '\" Local Variables: diff --git a/doc/configurable.n b/doc/configurable.n index e00edb3..d2e6b18 100644 --- a/doc/configurable.n +++ b/doc/configurable.n @@ -25,8 +25,8 @@ package require TclOO \fB}\fR \fIobjectName \fBconfigure\fR -\fIobjectName \fBconfigure\fR \fI\-prop\fR -\fIobjectName \fBconfigure\fR \fI\-prop value\fR ?\fI\-prop value\fR... +\fIobjectName \fBconfigure\fI \-prop\fR +\fIobjectName \fBconfigure\fI \-prop value\fR ?\fI\-prop value\fR... .fi .SH "CLASS HIERARCHY" .nf @@ -54,6 +54,7 @@ definition command available in definition scripts for the class and instances \fBoo::objdefine\fR) and making a \fBconfigure\fR method available within the instances. .SS "CONFIGURE METHOD" +.\" METHOD: configure .PP The behavior of the \fBconfigure\fR method is modelled after the \fBfconfigure\fR/\fBchan configure\fR command. @@ -74,6 +75,7 @@ method fails, the preceding pairs (if any) will continue to have been applied, and the succeeding pairs (if any) will be not applied. On success, the result of the \fBconfigure\fR method in this mode operation will be an empty string. .SS "PROPERTY DEFINITIONS" +.\" COMMAND: property .PP When a class has been manufactured by the \fBoo::configurable\fR metaclass (or one of its subclasses), it gains an extra definition, \fBproperty\fR. The @@ -146,11 +148,13 @@ The configurable class system is comprised of several pieces. The definition namespaces during object creation that provide the other bits and pieces of machinery. The key pieces of the implementation are enumerated here so that they can be used by other code: +.\" COMMAND: configurable .TP \fBoo::configuresupport::configurable\fR . This is a class that provides the implementation of the \fBconfigure\fR method (described above in \fBCONFIGURE METHOD\fR). +.\" NAMESPACE: configurableclass .TP \fBoo::configuresupport::configurableclass\fR . @@ -159,6 +163,7 @@ This is a namespace that contains the definition dialect that provides the class constructors under normal circumstances), as described above in \fBPROPERTY DEFINITIONS\fR. It \fBnamespace export\fRs its \fBproperty\fR command so that it may be used easily in user definition dialects. +.\" NAMESPACE: configurableobject .TP \fBoo::configuresupport::configurableobject\fR . @@ -176,24 +181,28 @@ slots mean other than that they have unique names, no important order, can be inherited and discovered on classes and instances. .PP These slots, and their intended semantics, are: +.\" METHOD: readableproperties .TP \fBoo::configuresupport::readableproperties\fR . The set of properties of a class (not including those from its superclasses) that may be read from when configuring an instance of the class. This slot can also be read with the \fBinfo class properties\fR command. +.\" METHOD: writableproperties .TP \fBoo::configuresupport::writableproperties\fR . The set of properties of a class (not including those from its superclasses) that may be written to when configuring an instance of the class. This slot can also be read with the \fBinfo class properties\fR command. +.\" METHOD: objreadableproperties .TP \fBoo::configuresupport::objreadableproperties\fR . The set of properties of an object instance (not including those from its classes) that may be read from when configuring the object. This slot can also be read with the \fBinfo object properties\fR command. +.\" METHOD: objwritableproperties .TP \fBoo::configuresupport::objwritableproperties\fR . diff --git a/doc/const.n b/doc/const.n new file mode 100644 index 0000000..9bc77ba --- /dev/null +++ b/doc/const.n @@ -0,0 +1,85 @@ +'\" +'\" Copyright (c) 2023 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH const n 9.0 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +const \- create and initialize a constant +.SH SYNOPSIS +\fBconst \fIvarName value\fR +.BE +.SH DESCRIPTION +.PP +This command is normally used within a procedure body (or method body, +or lambda term) to create a constant within that procedure, or within a +\fBnamespace eval\fR body to create a constant within that namespace. +The constant is an unmodifiable variable, called \fIvarName\fR, that is +initialized with \fIvalue\fR. +The result of \fBconst\fR is always the empty string on success. +.PP +If a variable \fIvarName\fR does not exist, it is created with its value set +to \fIvalue\fR and marked as a constant; this means that no other command +(e.g., \fBset\fR, \fBappend\fR, \fBincr\fR, \fBunset\fR) +may modify or remove the variable; variables are checked for whether they +are constants before any traces are called. +If a variable \fIvarName\fR already exists, it is an error unless that +variable is marked as a constant (in which case \fBconst\fR is a no-op). +.PP +The \fIvarName\fR may not be a qualified name or reference an element of an +array by any means. If the variable exists and is an array, that is an error. +.PP +Constants are normally only removed by their containing procedure exiting or +their namespace being deleted. +.SH EXAMPLES +.PP +Create a constant in a procedure: +.PP +.CS +proc foo {a b} { + \fBconst\fR BAR 12345 + return [expr {$a + $b + $BAR}] +} +.CE +.PP +Create a constant in a namespace to factor out a regular expression: +.PP +.CS +namespace eval someNS { + \fBconst\fR FOO_MATCHER {(?i)}\emfoo\eM} + + proc findFoos str { + variable FOO_MATCHER + regexp -all $FOO_MATCHER $str + } + + proc findFooIndices str { + variable FOO_MATCHER + regexp -all -indices $FOO_MATCHER $str + } +} +.CE +.PP +Making a constant in a loop doesn't error: +.PP +.CS +proc foo {n} { + set result {} + for {set i 0} {$i < $n} {incr i} { + \fBconst\fR X 123 + lappend result [expr {$X + $i**2}] + } +} +.CE +.SH "SEE ALSO" +proc(n), namespace(n), set(n), unset(n) +.SH KEYWORDS +namespace, procedure, variable, constant +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/cookiejar.n b/doc/cookiejar.n index 1befca9..7d8e99e 100644 --- a/doc/cookiejar.n +++ b/doc/cookiejar.n @@ -15,13 +15,13 @@ cookiejar \- Implementation of the Tcl http package cookie jar protocol \fBpackage require\fR \fBcookiejar\fR ?\fB0.1\fR? \fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? -\fB::http::cookiejar create\fR \fIname\fR ?\fIfilename\fR? +\fB::http::cookiejar create\fI name\fR ?\fIfilename\fR? \fB::http::cookiejar new\fR ?\fIfilename\fR? \fIcookiejar\fR \fBdestroy\fR \fIcookiejar\fR \fBforceLoadDomainData\fR -\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR -\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR +\fIcookiejar\fR \fBgetCookies\fI protocol host path\fR +\fIcookiejar\fR \fBstoreCookie\fI options\fR \fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? .fi .SH DESCRIPTION @@ -33,6 +33,7 @@ create a cookie jar that manages a particular HTTP session. .PP The database management policy can be controlled at the package level by the \fBconfigure\fR method on the \fB::http::cookiejar\fR class object: +.\" METHOD: configure .TP \fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? . @@ -105,6 +106,7 @@ the database. .PP Cookie jar instances may be made with any of the standard TclOO instance creation methods (\fBcreate\fR or \fBnew\fR). +.\" METHOD: new .TP \fB::http::cookiejar new\fR ?\fIfilename\fR? . @@ -116,27 +118,31 @@ memory, which effectively forces all cookies within it to be session cookies. .SS "INSTANCE METHODS" .PP The following methods are supported on the instances: +.\" METHOD: destroy .TP -\fIcookiejar\fR \fBdestroy\fR +\fIcookiejar \fBdestroy\fR . This is the standard TclOO destruction method. It does \fInot\fR delete the SQLite database if it is written to disk. Callers are responsible for ensuring that the cookie jar is not in use by the http package at the time of destruction. +.\" METHOD: forceLoadDomainData .TP -\fIcookiejar\fR \fBforceLoadDomainData\fR +\fIcookiejar \fBforceLoadDomainData\fR . This method causes the cookie jar to immediately load (and cache) the domain list data. The domain list will be loaded from the \fB\-domainlist\fR configured a the package level if that is enabled, and otherwise will be obtained from the \fB\-domainfile\fR configured at the package level. +.\" METHOD: getCookies .TP -\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR +\fIcookiejar \fBgetCookies\fI protocol host path\fR . This method obtains the cookies for a particular HTTP request. \fIThis implements the http cookie jar protocol.\fR +.\" METHOD: policyAllow .TP -\fIcookiejar\fR \fBpolicyAllow\fR \fIoperation domain path\fR +\fIcookiejar \fBpolicyAllow\fI operation domain path\fR . This method is called by the \fBstoreCookie\fR method to get a decision on whether to allow \fIoperation\fR to be performed for the \fIdomain\fR and @@ -156,14 +162,16 @@ defined lifetime). The default implementation of this method just returns true, but subclasses of this class may impose their own rules. .RE +.\" METHOD: storeCookie .TP -\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR +\fIcookiejar \fBstoreCookie\fI options\fR . This method stores a single cookie from a particular HTTP response. Cookies that fail security checks are ignored. \fIThis implements the http cookie jar protocol.\fR +.\" METHOD: lookup .TP -\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? +\fIcookiejar \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? . This method looks a cookie by exact host (or domain) matching. If neither \fIhost\fR nor \fIkey\fR are supplied, the list of hosts for which a cookie is @@ -180,7 +188,7 @@ the start of the application. package require http \fBpackage require cookiejar\fR -set cookiedb ~/.tclcookies.db +set cookiedb [file join [file home] cookiejar] http::configure -cookiejar [\fBhttp::cookiejar new\fR $cookiedb] # No further explicit steps are required to use cookies @@ -203,7 +211,7 @@ oo::class create MyCookieJar { } } -set cookiedb ~/.tclcookies.db +set cookiedb [file join [file home] cookiejar] http::configure -cookiejar [MyCookieJar new $cookiedb] # No further explicit steps are required to use cookies diff --git a/doc/coroutine.n b/doc/coroutine.n index 8110628..cb4d3dd 100644 --- a/doc/coroutine.n +++ b/doc/coroutine.n @@ -13,10 +13,11 @@ coroutine, yield, yieldto, coroinject, coroprobe \- Create and produce values fr .SH SYNOPSIS .nf \fBcoroutine \fIname command\fR ?\fIarg...\fR? + \fByield\fR ?\fIvalue\fR? -\fByieldto\fR \fIcommand\fR ?\fIarg...\fR? +\fByieldto\fI command\fR ?\fIarg...\fR? \fIname\fR ?\fIvalue...\fR? -.sp + .VS "8.7, TIP383" \fBcoroinject \fIcoroName command\fR ?\fIarg...\fR? \fBcoroprobe \fIcoroName command\fR ?\fIarg...\fR? @@ -198,7 +199,7 @@ proc juggler {name target {value ""}} { while {$value ne ""} { puts "$name : $value" set value [string range $value 0 end-1] - lassign [\fByieldto\fR \fI$target\fR $value] value + lassign [\fByieldto\fI $target\fR $value] value } } \fBcoroutine\fR j1 juggler Larry [ @@ -12,22 +12,17 @@ .SH NAME dde \- Execute a Dynamic Data Exchange command .SH SYNOPSIS -.sp +.nf \fBpackage require dde 1.4\fR -.sp + \fBdde servername\fR ?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR? -.sp \fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR -.sp \fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR -.sp \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR -.sp \fBdde services \fIservice topic\fR -.sp \fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR? +.fi .BE - .SH DESCRIPTION .PP This command allows an application to send Dynamic Data Exchange (DDE) @@ -44,6 +39,7 @@ has the service name \fBExcel\fR. .PP The following commands are a subset of the full Dynamic Data Exchange set of commands. +.\" METHOD: servername .TP \fBdde servername \fR?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR? . @@ -68,6 +64,7 @@ safe interpreter then a \fB\-handler\fR procedure must be defined. The procedure is called with all the arguments provided by the remote call. .RE +.\" METHOD: execute .TP \fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR . @@ -80,11 +77,15 @@ script is run in the application. The \fB\-async\fR option requests asynchronous invocation. The command returns an error message if the script did not run, unless the \fB\-async\fR flag was used, in which case the command returns immediately with no error. +.RS +.PP Without the \fB\-binary\fR option all data will be sent in unicode. For dde clients which don't implement the CF_UNICODE clipboard format, this will automatically be translated to the system encoding. You can use the \fB\-binary\fR option in combination with the result of \fBencoding convertto\fR to send data in any other encoding. +.RE +.\" METHOD: poke .TP \fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR . @@ -95,11 +96,15 @@ specific but can be a command to the server or the name of a file to work on. The \fIitem\fR is also application specific and is often not used, but it must always be non-null. The \fIdata\fR field is given to the remote application. +.RS +.PP Without the \fB\-binary\fR option all data will be sent in unicode. For dde clients which don't implement the CF_UNICODE clipboard format, this will automatically be translated to the system encoding. You can use the \fB\-binary\fR option in combination with the result of \fBencoding convertto\fR to send data in any other encoding. +.RE +.\" METHOD: request .TP \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR . @@ -111,6 +116,7 @@ application-specific. The command returns the value of \fIitem\fR as defined in the application. Normally this is interpreted to be a string with terminating null. If \fB\-binary\fR is specified, the result is returned as a byte array. +.\" METHOD: services .TP \fBdde services \fIservice topic\fR . @@ -123,6 +129,7 @@ returned. If \fIservice\fR is non-empty and \fItopic\fR is, all topics for a given service are returned. If both are non-empty, if that service-topic pair currently exists, it is returned; otherwise, an empty string is returned. +.\" METHOD: eval .TP \fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR? . @@ -19,6 +19,7 @@ Performs one of several operations on dictionary values or variables containing dictionary values (see the \fBDICTIONARY VALUES\fR section below for a description), depending on \fIoption\fR. The legal \fIoption\fRs (which may be abbreviated) are: +.\" METHOD: append .TP \fBdict append \fIdictionaryVariable key \fR?\fIstring ...\fR? . @@ -32,12 +33,14 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the appending operation. .VE TIP508 +.\" METHOD: create .TP \fBdict create \fR?\fIkey value ...\fR? . Return a new dictionary that contains each of the key/value mappings listed as arguments (keys and values alternating, with each key being followed by its associated value.) +.\" METHOD: exists .TP \fBdict exists \fIdictionaryValue key \fR?\fIkey ...\fR? . @@ -45,6 +48,7 @@ This returns a boolean value indicating whether the given key (or path of keys through a set of nested dictionaries) exists in the given dictionary value. This returns a true value exactly when \fBdict get\fR on that path will succeed. +.\" METHOD: filter .TP \fBdict filter \fIdictionaryValue filterType arg \fR?\fIarg ...\fR? . @@ -54,6 +58,7 @@ type (which may be abbreviated.) Supported filter types are: .RS .TP \fBdict filter \fIdictionaryValue \fBkey\fR ?\fIglobPattern ...\fR? +. The key rule only matches those key/value pairs whose keys match any of the given patterns (in the style of \fBstring match\fR.) .TP @@ -72,9 +77,11 @@ result. The key/value pairs are tested in the order in which the keys were inserted into the dictionary. .TP \fBdict filter \fIdictionaryValue \fBvalue \fR?\fIglobPattern ...\fR? +. The value rule only matches those key/value pairs whose values match any of the given patterns (in the style of \fBstring match\fR.) .RE +.\" METHOD: for .TP \fBdict for {\fIkeyVariable valueVariable\fB} \fIdictionaryValue body\fR . @@ -90,6 +97,7 @@ terminate successfully immediately. If any evaluation of the body generates a \fBTCL_CONTINUE\fR result, this shall be treated exactly like a normal \fBTCL_OK\fR result. The order of iteration is the order in which the keys were inserted into the dictionary. +.\" METHOD: get .TP \fBdict get \fIdictionaryValue \fR?\fIkey ...\fR? . @@ -115,6 +123,8 @@ the value for that key. It is an error to attempt to retrieve a value for a key that is not present in the dictionary. .RE +.\" METHOD: getdef +.\" METHOD: getwithdefault .TP \fBdict getdef \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR .TP @@ -131,6 +141,7 @@ Note that there must always be at least one \fIkey\fR provided, and that \fBdict getdef\fR and \fBdict getwithdefault\fR are aliases for each other. .RE .VE "8.7, TIP342" +.\" METHOD: incr .TP \fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR? . @@ -146,6 +157,7 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the incrementing operation. .VE TIP508 +.\" METHOD: info .TP \fBdict info \fIdictionaryValue\fR . @@ -154,6 +166,7 @@ given dictionary though the format of this data is dependent on the implementation of the dictionary. For dictionaries that are implemented by hash tables, it is expected that this will return the string produced by \fBTcl_HashStats\fR, similar to \fBarray statistics\fR. +.\" METHOD: keys .TP \fBdict keys \fIdictionaryValue \fR?\fIglobPattern\fR? . @@ -161,6 +174,7 @@ Return a list of all keys in the given dictionary value. If a pattern is supplied, only those keys that match it (according to the rules of \fBstring match\fR) will be returned. The returned keys will be in the order that they were inserted into the dictionary. +.\" METHOD: lappend .TP \fBdict lappend \fIdictionaryVariable key \fR?\fIvalue ...\fR? . @@ -176,6 +190,7 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the list-appending operation. .VE TIP508 +.\" METHOD: map .TP \fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR . @@ -201,6 +216,7 @@ of iteration is the natural order of the dictionary (typically the order in which the keys were added to the dictionary; the order is the same as that used in \fBdict for\fR). .RE +.\" METHOD: merge .TP \fBdict merge \fR?\fIdictionaryValue ...\fR? . @@ -209,6 +225,7 @@ Return a dictionary that contains the contents of each of the contain a mapping for the same key, the resulting dictionary maps that key to the value according to the last dictionary on the command line containing a mapping for that key. +.\" METHOD: remove .TP \fBdict remove \fIdictionaryValue \fR?\fIkey ...\fR? . @@ -217,6 +234,7 @@ first argument except without mappings for each of the keys listed. It is legal for there to be no keys to remove, and it also legal for any of the keys to be removed to not be present in the input dictionary in the first place. +.\" METHOD: replace .TP \fBdict replace \fIdictionaryValue \fR?\fIkey value ...\fR? . @@ -225,6 +243,7 @@ first argument except with some values different or some extra key/value pairs added. It is legal for this command to be called with no key/value pairs, but illegal for this command to be called with a key but no value. +.\" METHOD: set .TP \fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR . @@ -238,10 +257,12 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the value insert/update operation. .VE TIP508 +.\" METHOD: size .TP \fBdict size \fIdictionaryValue\fR . Return the number of key/value mappings in the given dictionary value. +.\" METHOD: unset .TP \fBdict unset \fIdictionaryVariable key \fR?\fIkey ...\fR? . @@ -258,6 +279,7 @@ If \fIdictionaryVariable\fR indicates an element that does not exist of an array that has a default value set, the default value and will be used as the value of the dictionary prior to the value remove operation. .VE TIP508 +.\" METHOD: update .TP \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR . @@ -290,6 +312,7 @@ Note that the mapping of values to variables does not use traces; changes to the \fIdictionaryVariable\fR's contents only happen when \fIbody\fR terminates. .RE +.\" METHOD: values .TP \fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR? . @@ -298,6 +321,7 @@ pattern is supplied, only those values that match it (according to the rules of \fBstring match\fR) will be returned. The returned values will be in the order of that the keys associated with those values were inserted into the dictionary. +.\" METHOD: with .TP \fBdict with \fIdictionaryVariable \fR?\fIkey ...\fR? \fIbody\fR . diff --git a/doc/encoding.n b/doc/encoding.n index 4377471..c28406f 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -128,10 +128,17 @@ Continue further processing of the source data using a fallback strategy such as replacing or discarding the offending bytes in a profile-defined manner. .VE "TCL8.7 TIP656" .PP -The following profiles are currently implemented with \fBtcl8\fR being +The following profiles are currently implemented with \fBstrict\fR being the default if the \fB-profile\fR is not specified. .VS "TCL8.7 TIP656" .TP +\fBstrict\fR +. +The \fBstrict\fR profile always stops processing when an conversion error is +encountered. The error is signalled via an exception or the \fB-failindex\fR +option mechanism. The \fBstrict\fR profile implements a Unicode standard +conformant behavior. +.TP \fBtcl8\fR . The \fBtcl8\fR profile always follows the first strategy above and corresponds @@ -151,13 +158,6 @@ When converting from Tcl strings to an external encoding format using target encoding are replaced by an encoding-dependent character, usually the question mark \fB?\fR. .TP -\fBstrict\fR -. -The \fBstrict\fR profile always stops processing when an conversion error is -encountered. The error is signalled via an exception or the \fB-failindex\fR -option mechanism. The \fBstrict\fR profile implements a Unicode standard -conformant behavior. -.TP \fBreplace\fR . Like the \fBtcl8\fR profile, the \fBreplace\fR profile always continues diff --git a/doc/error.n b/doc/error.n index c05f8b9..9ff4298 100644 --- a/doc/error.n +++ b/doc/error.n @@ -14,7 +14,6 @@ error \- Generate an error .SH SYNOPSIS \fBerror \fImessage\fR ?\fIinfo\fR? ?\fIcode\fR? .BE - .SH DESCRIPTION .PP Returns a \fBTCL_ERROR\fR code, which causes command interpretation to be @@ -55,7 +55,7 @@ described below then it is used by \fBexec\fR to control the flow of input and output among the subprocess(es). Such arguments will not be passed to the subprocess(es). In forms such as -.QW "\fB<\fR \fIfileName\fR" , +.QW "\fB<\fI fileName\fR" , \fIfileName\fR may either be in a separate argument from .QW \fB<\fR or in the same argument with no intervening space (i.e. @@ -201,7 +201,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. @@ -482,7 +482,7 @@ encrypted so that only the current user can access it requires use of the \fICIPHER\fR command, like this: .PP .CS -set secureDir "~/Desktop/Secure Directory" +set secureDir [file join [file home] Desktop/SecureDirectory] file mkdir $secureDir \fBexec\fR CIPHER /e /s:[file nativename $secureDir] .CE @@ -14,7 +14,6 @@ exit \- End the application .SH SYNOPSIS \fBexit \fR?\fIreturnCode\fR? .BE - .SH DESCRIPTION .PP Terminate the process, returning \fIreturnCode\fR to the @@ -60,9 +60,7 @@ A \fBnumeric value\fR .RS 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 hexadecimal. .PP A floating-point number may be take any of several common decimal formats, and may use the decimal point \fB.\fR, @@ -12,16 +12,15 @@ .SH NAME file \- Manipulate file names and attributes .SH SYNOPSIS -\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR? +\fBfile \fIoption name\fR ?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP -This command provides several operations on a file's name or attributes. -\fIName\fR is the name of a file; if it starts with a tilde, then tilde -substitution is done before executing the command (see the manual entry for -\fBfilename\fR for details). \fIOption\fR indicates what to do with the -file name. Any unique abbreviation for \fIoption\fR is acceptable. The -valid options are: +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: +.\" METHOD: atime .TP \fBfile atime \fIname\fR ?\fItime\fR? . @@ -33,6 +32,7 @@ does not exist or its access time cannot be queried or set then an error is generated. On Windows, FAT file systems do not support access time. On \fBzipfs\fR file systems, access time is mapped to the modification time. +.\" METHOD: attributes .TP \fBfile attributes \fIname\fR .TP @@ -125,6 +125,7 @@ The uncompressed size of the file. This is \fB0\fR for directories. Other attributes may be present in the returned list. These should be ignored. .RE +.\" METHOD: channels .TP \fBfile channels\fR ?\fIpattern\fR? . @@ -132,8 +133,9 @@ If \fIpattern\fR is not specified, returns a list of names of all registered open channels in this interpreter. If \fIpattern\fR is specified, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. +.\" METHOD: copy .TP -\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR +\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource target\fR .TP \fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR . @@ -154,6 +156,7 @@ or overwrite a file with a directory will all result in errors even if specified, halting at the first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument following the \fB\-\|\-\fR will be treated as a \fIsource\fR even if it starts with a \fB\-\fR. +.\" METHOD: delete .TP \fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? ?\fIpathname\fR ... ? . @@ -173,8 +176,10 @@ the first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument following the \fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with a \fB\-\fR. +.\" METHOD: dirname .TP \fBfile dirname \fIname\fR +. Returns a name comprised of all of the path components in \fIname\fR excluding the last element. If \fIname\fR is a relative file name and only contains one path element, then returns @@ -188,22 +193,8 @@ 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 +.\" METHOD: executable .TP \fBfile executable \fIname\fR . @@ -211,17 +202,20 @@ Returns \fB1\fR if file \fIname\fR is executable by the current user, \fB0\fR otherwise. On Windows, which does not have an executable attribute, the command treats all directories and any files with extensions \fBexe\fR, \fBcom\fR, \fBcmd\fR or \fBbat\fR as executable. +.\" METHOD: exists .TP \fBfile exists \fIname\fR . Returns \fB1\fR if file \fIname\fR exists and the current user has search privileges for the directories leading to it, \fB0\fR otherwise. +.\" METHOD: extension .TP \fBfile extension \fIname\fR . Returns all of the characters in \fIname\fR after and including the last dot in the last element of \fIname\fR. If there is no dot in the last element of \fIname\fR then returns the empty string. +.\" METHOD: home .TP \fBfile home ?\fIusername\fR? .VS "8.7, TIP 602" @@ -240,14 +234,17 @@ raised if the \fIusername\fR does not correspond to a user account on the system. .RE .VE "8.7, TIP 602" +.\" METHOD: isdirectory .TP \fBfile isdirectory \fIname\fR . Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise. +.\" METHOD: isfile .TP \fBfile isfile \fIname\fR . Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise. +.\" METHOD: join .TP \fBfile join \fIname\fR ?\fIname ...\fR? . @@ -268,6 +265,7 @@ Note that any of the names can contain separators, and that the result is always canonical for the current platform: \fB/\fR for Unix and Windows. .RE +.\" METHOD: link .TP \fBfile link\fR ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR? . @@ -302,17 +300,15 @@ must be relative to the actual \fIlinkName\fR's location (not to the cwd), but on all other platforms where relative links are not supported, target paths will always be converted to absolute, normalized form before the link is created (and therefore relative paths are interpreted -as relative to the cwd). Furthermore, -.QW ~user -paths are always expanded -to absolute form. When creating links on filesystems that either do not +as relative to the cwd). When creating links on filesystems that either do not support any links, or do not support the specific type requested, an error message will be returned. Most Unix platforms support both symbolic and hard links (the latter for files only). Windows supports symbolic directory links and hard file links on NTFS drives. .RE +.\" METHOD: lstat .TP -\fBfile lstat \fIname ?varName?\fR +\fBfile lstat \fIname\fR ?\fIvarName\fR? . Same as \fBstat\fR option (see below) except uses the \fIlstat\fR kernel call instead of \fIstat\fR. This means that if \fIname\fR @@ -320,6 +316,7 @@ refers to a symbolic link the information returned is for the link rather than the file it refers to. On systems that do not support symbolic links this option behaves exactly the same as the \fBstat\fR option. +.\" METHOD: mkdir .TP \fBfile mkdir\fR ?\fIdir\fR ...? . @@ -329,6 +326,7 @@ well as \fIdir\fR itself. If an existing directory is specified, then no action is taken and no error is returned. Trying to overwrite an existing file with a directory will result in an error. Arguments are processed in the order specified, halting at the first error, if any. +.\" METHOD: mtime .TP \fBfile mtime \fIname\fR ?\fItime\fR? . @@ -339,12 +337,14 @@ standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file does not exist or its modified time cannot be queried or set then an error is generated. On \fBzipfs\fR file systems, modification time cannot be explicitly set. +.\" METHOD: nativename .TP \fBfile nativename \fIname\fR . Returns the platform-specific name of the file. This is useful if the filename is needed to pass to a platform-specific call, such as to a subprocess via \fBexec\fR under Windows (see \fBEXAMPLES\fR below). +.\" METHOD: normalize .TP \fBfile normalize \fIname\fR . @@ -366,11 +366,13 @@ last link in the path is necessary, because Tcl or the user may wish to operate on the actual symbolic link itself (for example \fBfile delete\fR, \fBfile rename\fR, \fBfile copy\fR are defined to operate on symbolic links, not on the things that they point to). +.\" METHOD: owned .TP \fBfile owned \fIname\fR . Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR otherwise. +.\" METHOD: pathtype .TP \fBfile pathtype \fIname\fR . @@ -381,11 +383,13 @@ working directory, then the path type will be \fBrelative\fR. If \fIname\fR refers to a file relative to the current working directory on a specified volume, or to a specific file on the current working volume, then the path type is \fBvolumerelative\fR. +.\" METHOD: readable .TP \fBfile readable \fIname\fR . Returns \fB1\fR if file \fIname\fR is readable by the current user, \fB0\fR otherwise. +.\" METHOD: readlink .TP \fBfile readlink \fIname\fR . @@ -393,8 +397,9 @@ Returns the value of the symbolic link given by \fIname\fR (i.e. the name of the file it points to). If \fIname\fR is not a symbolic link or its value cannot be read, then an error is returned. On systems that do not support symbolic links this option is undefined. +.\" METHOD: rename .TP -\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR +\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource target\fR .TP \fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR . @@ -412,6 +417,7 @@ result in errors. Arguments are processed in the order specified, halting at the first error, if any. A \fB\-\|\-\fR marks the end of switches; the argument following the \fB\-\|\-\fR will be treated as a \fIsource\fR even if it starts with a \fB\-\fR. +.\" METHOD: rootname .TP \fBfile rootname \fIname\fR . @@ -420,6 +426,7 @@ last .QW . character in the last component of name. If the last component of \fIname\fR does not contain a dot, then returns \fIname\fR. +.\" METHOD: separator .TP \fBfile separator\fR ?\fIname\fR? . @@ -428,12 +435,14 @@ path segments for native files on this platform. If a path is given, the filesystem responsible for that path is asked to return its separator character. If no file system accepts \fIname\fR, an error is generated. +.\" METHOD: size .TP \fBfile size \fIname\fR . Returns a decimal string giving the size of file \fIname\fR in bytes. If the file does not exist or its size cannot be queried then an error is generated. +.\" METHOD: split .TP \fBfile split \fIname\fR . @@ -441,21 +450,9 @@ 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 +.\" METHOD: stat .TP -\fBfile stat \fIname ?varName?\fR +\fBfile stat \fIname\fR ?\fIvarName\fR? . Invokes the \fBstat\fR kernel call on \fIname\fR, and returns a dictionary with the information returned from the kernel call. If @@ -469,6 +466,7 @@ field from the \fBstat\fR return structure; see the manual entry for \fBstat\fR for details on the meanings of the values. The \fBtype\fR element gives the type of the file in the same form returned by the command \fBfile type\fR. +.\" METHOD: system .TP \fBfile system \fIname\fR . @@ -490,6 +488,7 @@ to represent a file on a remote ftp site mounted as a virtual filesystem through an extension called .QW vfs . If the file does not belong to any filesystem, an error is generated. +.\" METHOD: tail .TP \fBfile tail \fIname\fR . @@ -498,6 +497,7 @@ Returns all of the characters in the last filesystem component of If \fIname\fR contains no separators then returns \fIname\fR. So, \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all return \fBb\fR. +.\" METHOD: tempdir .TP \fBfile tempdir\fR ?\fItemplate\fR? .VS "8.7, TIP 431" @@ -528,6 +528,7 @@ between platforms: .CE .RE .VE "8.7, TIP 431" +.\" METHOD: tempfile .TP \fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR? .\" TIP #210 @@ -545,28 +546,31 @@ Note that temporary files are \fIonly\fR ever created on the native filesystem. As such, they can be relied upon to be used with operating-system native APIs and external programs that require a filename. .RE +.\" METHOD: tildeexpand .TP \fBfile tildeexpand \fIname\fR .VS "8.7, TIP 602" 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. .RE .VE "8.7, TIP 602" +.\" METHOD: type .TP \fBfile type \fIname\fR . Returns a string giving the type of file \fIname\fR, which will be one of \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR, \fBfifo\fR, \fBlink\fR, or \fBsocket\fR. +.\" METHOD: volumes .TP \fBfile volumes\fR . @@ -580,6 +584,7 @@ On Windows, it will return a list of the available local drives .QW "a:/ c:/" ). If any virtual filesystem has mounted additional volumes, they will be in the returned list. +.\" METHOD: writable .TP \fBfile writable \fIname\fR . @@ -645,7 +650,7 @@ interface) but the name passed to the operating system must be in native format: .PP .CS -exec {*}[auto_execok start] {} [\fBfile nativename\fR ~/example.txt] +exec {*}[auto_execok start] {} [\fBfile nativename\fR C:/Users/fred/example.txt] .CE .SH "SEE ALSO" filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n), diff --git a/doc/filename.n b/doc/filename.n index 0520677..373a8ee 100644 --- a/doc/filename.n +++ b/doc/filename.n @@ -142,24 +142,20 @@ Zipfs paths are case-sensitive on all platforms. .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). +Unlike earlier versions of Tcl, Tcl 9 does not do implicit tilde substitution +on file paths with the exception noted below. The commands \fBfile home\fR and +\fBfile tildeexpand\fR may be used to explicitly accomplish the same. .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. +The exception to the above is initialization of the \fBauto_path\fR variable +and the Tcl module search paths as documented in the manpages for +\fBtclvars\fR and \fBtm\fR. When any path in an environment variable used to +initialize these starts with a tilde, it 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, 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 +POSIX, MacOS X and Windows platforms. .SH "PORTABILITY ISSUES" .PP Not all file systems are case sensitive, so scripts should avoid code @@ -14,7 +14,6 @@ for \- 'For' loop .SH SYNOPSIS \fBfor \fIstart test next body\fR .BE - .SH DESCRIPTION .PP \fBFor\fR is a looping command, similar in structure to the C diff --git a/doc/foreach.n b/doc/foreach.n index 43f961a..1f9f88e 100644 --- a/doc/foreach.n +++ b/doc/foreach.n @@ -16,7 +16,6 @@ foreach \- Iterate over all elements in one or more lists .br \fBforeach \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR .BE - .SH DESCRIPTION .PP The \fBforeach\fR command implements a loop where the loop @@ -96,10 +95,8 @@ set x {} # The value of x is "a d e b f g c {} {}" # There are 3 iterations of the loop. .CE - .SH "SEE ALSO" for(n), while(n), break(n), continue(n) - .SH KEYWORDS foreach, iteration, list, loop '\" Local Variables: diff --git a/doc/format.n b/doc/format.n index f762f7a..b1e204a 100644 --- a/doc/format.n +++ b/doc/format.n @@ -126,23 +126,22 @@ then the next argument to the \fBformat\fR command determines the precision; it must be a numeric string. .SS "OPTIONAL SIZE MODIFIER" .PP -The fifth part of a conversion specifier is a size modifier, which must -be \fBh\fR, \fBl\fR, \fBq\fR, \fBj\fR, \fBz\fR, \fBt\fR, -\fBll\fR, or \fBL\fR. If it is \fBll\fR it specifies that an integer -value is taken without truncation for conversion to a formatted -substring. If it is \fBh\fR it specifies that an integer value is -truncated to a 16-bit range before converting. This option is rarely -useful. If it is \fBl\fR (or \fBj\fR or \fBq\fR) it specifies that the -integer value is truncated to the same range as that produced by the -\fBwide()\fR function of the \fBexpr\fR command (at least a 64-bit range). +The fifth part of a conversion specifier is a size modifier, +which must be \fBll\fR, \fBh\fR, \fBl\fR, \fBz\fR, \fBt\fR, or \fBL\fR. +If it is \fBll\fR it specifies that an integer value is taken +without truncation for conversion to a formatted substring. +If it is \fBh\fR it specifies that an integer value is +truncated to a 16-bit range before converting. This option is rarely useful. +If it is \fBl\fR (or \fBj\fR or \fBq\fR) it specifies that the integer value +is truncated to the same range as that produced by the \fBwide()\fR +function of the \fBexpr\fR command (at least a 64-bit range). If it is \fBz\fR or \fBt\fR it specifies that the integer value is truncated to the range determined by the value of the \fBpointerSize\fR element of the \fBtcl_platform\fR array. If it is \fBL\fR it specifies that an integer or double value is taken without truncation for conversion to a formatted substring. If neither of those are present, the integer value is -truncated to the range determined by the value of the -\fBwordSize\fR element of the \fBtcl_platform\fR array). +truncated to a 32-bit range. .SS "MANDATORY CONVERSION TYPE" .PP The last thing in a conversion specifier is an alphabetic character diff --git a/doc/fpclassify.n b/doc/fpclassify.n index c1db73b..18722dc 100644 --- a/doc/fpclassify.n +++ b/doc/fpclassify.n @@ -66,7 +66,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 @@ -30,7 +30,7 @@ they are treated as switches. The following switches are currently supported: .\" OPTION: -directory .TP -\fB\-directory\fR \fIdirectory\fR +\fB\-directory\fI directory\fR . Search for files which match the given patterns starting in the given \fIdirectory\fR. This allows searching of directories whose name @@ -49,11 +49,11 @@ 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. .\" OPTION: -path .TP -\fB\-path\fR \fIpathPrefix\fR +\fB\-path\fI pathPrefix\fR . Search for files with the given \fIpathPrefix\fR where the rest of the name matches the given patterns. This allows searching for files with names @@ -77,11 +77,11 @@ is equivalent to .QW "\fBset pwd [pwd]; cd $dir; glob *; cd $pwd\fR" . For \fB\-path\fR specifications, the returned names will include the last path segment, so -.QW "\fBglob \-tails \-path [file rootname ~/foo.tex] .*\fR" +.QW "\fBglob \-tails \-path [file rootname /home/fred/foo.tex] .*\fR" will return paths like \fBfoo.aux foo.bib foo.tex\fR etc. .\" OPTION: -types .TP -\fB\-types\fR \fItypeList\fR +\fB\-types\fI typeList\fR . Only list files or directories which match \fItypeList\fR, where the items in the list have two forms. The first form is like the \-type option of @@ -165,16 +165,6 @@ which must be matched explicitly (this is to avoid a recursive pattern like from recursing up the directory hierarchy as well as down). In addition, all .QW / characters must be matched explicitly. -.LP -If the first character in a \fIpattern\fR is -.QW ~ -then it refers to the home directory for the user whose name follows the -.QW ~ . -If the -.QW ~ -is followed immediately by -.QW / -then the value of the HOME environment variable is used. .PP The \fBglob\fR command differs from csh globbing in two ways. First, it does not sort its result list (use the \fBlsort\fR @@ -182,26 +172,10 @@ 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 -may not contain ?, *, or [] constructs. On Windows NT, if \fIpattern\fR is -of the form -.QW \fB~\fIusername\fB@\fIdomain\fR , -it refers to the home -directory of the user whose account information resides on the specified NT -domain server. Otherwise, user account information is obtained from -the local computer. +may not contain ?, *, or [] constructs. .PP Since the backslash character has a special meaning to the glob command, glob patterns containing Windows style path separators need @@ -236,7 +210,7 @@ Find all the Tcl files in the user's home directory, irrespective of what the current directory is: .PP .CS -\fBglob\fR \-directory ~ *.tcl +\fBglob\fR \-directory [file home] *.tcl .CE .PP Find all subdirectories of the current directory: diff --git a/doc/history.n b/doc/history.n index 5bdd7c2..1c2b581 100644 --- a/doc/history.n +++ b/doc/history.n @@ -39,14 +39,18 @@ The \fBhistory\fR command can take any of the following forms: \fBhistory\fR . Same as \fBhistory info\fR, described below. +.\" METHOD: add .TP \fBhistory add\fI command \fR?\fBexec\fR? +. Adds the \fIcommand\fR argument to the history list as a new event. If \fBexec\fR is specified (or abbreviated) then the command is also executed and its result is returned. If \fBexec\fR is not specified then an empty string is returned as result. +.\" METHOD: change .TP \fBhistory change\fI newValue\fR ?\fIevent\fR? +. Replaces the value recorded for an event with \fInewValue\fR. \fIEvent\fR specifies the event to replace, and defaults to the \fIcurrent\fR event (not event \fB\-1\fR). This command @@ -54,32 +58,44 @@ is intended for use in commands that implement new forms of history substitution and wish to replace the current event (which invokes the substitution) with the command created through substitution. The return value is an empty string. +.\" METHOD: clear .TP \fBhistory clear\fR +. Erase the history list. The current keep limit is retained. The history event numbers are reset. +.\" METHOD: event .TP \fBhistory event\fR ?\fIevent\fR? +. Returns the value of the event given by \fIevent\fR. \fIEvent\fR defaults to \fB\-1\fR. +.\" METHOD: info .TP \fBhistory info \fR?\fIcount\fR? +. Returns a formatted string (intended for humans to read) giving the event number and contents for each of the events in the history list except the current event. If \fIcount\fR is specified then only the most recent \fIcount\fR events are returned. +.\" METHOD: keep .TP \fBhistory keep \fR?\fIcount\fR? +. This command may be used to change the size of the history list to \fIcount\fR events. Initially, 20 events are retained in the history list. If \fIcount\fR is not specified, the current keep limit is returned. +.\" METHOD: nextid .TP \fBhistory nextid\fR +. Returns the number of the next event to be recorded in the history list. It is useful for things like printing the event number in command-line prompts. +.\" METHOD: redo .TP \fBhistory redo \fR?\fIevent\fR? +. Re-executes the command indicated by \fIevent\fR and returns its result. \fIEvent\fR defaults to \fB\-1\fR. This command results in history revision: see below for details. @@ -93,8 +109,8 @@ history operations \fBsubstitute\fR and \fBwords\fR have been removed. The history option \fBredo\fR results in much simpler .QW "history revision" . When this option is invoked then the most recent event -is modified to eliminate the history command and replace it with -the result of the history command. +is modified to eliminate the \fBhistory\fR command and replace it with +the result of the \fBhistory\fR command. If you want to redo an event without modifying history, then use the \fBevent\fR operation to retrieve some event, and the \fBadd\fR operation to add it to history and execute it. @@ -16,63 +16,35 @@ http \- Client-side implementation of the HTTP/1.1 protocol .nf \fBpackage require http\fR ?\fB2.10\fR? .\" See Also -useragent option documentation in body! -.sp + \fB::http::config\fR ?\fI\-option value\fR ...? -.sp \fB::http::geturl \fIurl\fR ?\fI\-option value\fR ...? -.sp \fB::http::formatQuery\fI key value\fR ?\fIkey value\fR ...? -.sp \fB::http::quoteString\fI value\fR -.sp \fB::http::reset\fI token\fR ?\fIwhy\fR? -.sp \fB::http::wait \fItoken\fR -.sp \fB::http::status \fItoken\fR -.sp \fB::http::size \fItoken\fR -.sp \fB::http::error \fItoken\fR -.sp \fB::http::postError \fItoken\fR -.sp \fB::http::cleanup \fItoken\fR -.sp \fB::http::requestLine\fI token\fR -.sp \fB::http::requestHeaders\fI token\fR ?\fIheaderName\fR? -.sp \fB::http::requestHeaderValue\fI token headerName\fR -.sp \fB::http::responseLine\fI token\fR -.sp \fB::http::responseCode\fI token\fR -.sp \fB::http::reasonPhrase\fI code\fR -.sp \fB::http::responseHeaders\fI token\fR ?\fIheaderName\fR? -.sp \fB::http::responseHeaderValue\fI token headerName\fR -.sp \fB::http::responseInfo\fI token\fR -.sp \fB::http::responseBody\fI token\fR -.sp \fB::http::register \fIproto port command\fR ?\fIsocketCmdVarName\fR? ?\fIuseSockThread\fR? ?\fIendToEndProxy\fR? -.sp \fB::http::registerError \fIsock\fR ?\fImessage\fR? -.sp \fB::http::unregister \fIproto\fR -.sp \fB::http::code \fItoken\fR -.sp \fB::http::data \fItoken\fR -.sp \fB::http::meta \fItoken\fR ?\fIheaderName\fR? -.sp \fB::http::metaValue\fI token headerName\fR -.sp \fB::http::ncode \fItoken\fR .fi .SH "EXPORTED COMMANDS" @@ -287,7 +259,7 @@ The default is \fButf-8\fR, as specified by RFC 2718. The value of the User-Agent header in the HTTP request. In an unsafe interpreter, the default value depends upon the operating system, and the version numbers of \fBhttp\fR and \fBTcl\fR, and is (for example) -.QW "\fBMozilla/5.0 (Windows; U; Windows NT 10.0) http/2.9.0 Tcl/8.6.9\fR" . +.QW "\fBMozilla/5.0 (Windows; U; Windows NT 10.0) http/2.10.0 Tcl/9.0.0\fR" . A safe interpreter cannot determine its operating system, and so the default in a safe interpreter is to use a Windows 10 value with the current version numbers of \fBhttp\fR and \fBTcl\fR. @@ -14,38 +14,42 @@ tcl::idna \- Support for normalization of Internationalized Domain Names .nf package require tcl::idna 1.0 -\fBtcl::idna decode\fR \fIhostname\fR -\fBtcl::idna encode\fR \fIhostname\fR -\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR? -\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR? +\fBtcl::idna decode\fI hostname\fR +\fBtcl::idna encode\fI hostname\fR +\fBtcl::idna puny decode\fI string\fR ?\fIcase\fR? +\fBtcl::idna puny encode\fI string\fR ?\fIcase\fR? \fBtcl::idna version\fR .fi +.BE .SH DESCRIPTION This package provides an implementation of the punycode scheme used in Internationalised Domain Names, and some access commands. (See RFC 3492 for a description of punycode.) +.\" METHOD: decode .TP -\fBtcl::idna decode\fR \fIhostname\fR +\fBtcl::idna decode\fI hostname\fR . This command takes the name of a host that potentially contains punycode-encoded character sequences, \fIhostname\fR, and returns the hostname as might be displayed to the user. Note that there are often UNICODE characters that have extremely similar glyphs, so care should be taken with displaying hostnames to users. +.\" METHOD: encode .TP -\fBtcl::idna encode\fR \fIhostname\fR +\fBtcl::idna encode\fI hostname\fR . This command takes the name of a host as might be displayed to the user, \fIhostname\fR, and returns the version of the hostname with characters not permitted in basic hostnames encoded with punycode. +.\" METHOD: puny .TP -\fBtcl::idna puny\fR \fIsubcommand ...\fR +\fBtcl::idna puny\fI subcommand ...\fR . This command provides direct access to the basic punycode encoder and decoder. It supports two \fIsubcommand\fRs: .RS .TP -\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR? +\fBtcl::idna puny decode\fI string\fR ?\fIcase\fR? . This command decodes the punycode-encoded string, \fIstring\fR, and returns the result. If \fIcase\fR is provided, it is a boolean to make the case be @@ -53,7 +57,7 @@ folded to upper case (if \fIcase\fR is true) or lower case (if \fIcase\fR is false) during the decoding process; if omitted, no case transformation is applied. .TP -\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR? +\fBtcl::idna puny encode\fI string\fR ?\fIcase\fR? . This command encodes the string, \fIstring\fR, and returns the punycode-encoded version of the string. If \fIcase\fR is provided, it is a @@ -61,6 +65,7 @@ boolean to make the case be folded to upper case (if \fIcase\fR is true) or lower case (if \fIcase\fR is false) during the encoding process; if omitted, no case transformation is applied. .RE +.\" METHOD: version .TP \fBtcl::idna version\fR . @@ -14,7 +14,6 @@ if \- Execute scripts conditionally .SH SYNOPSIS \fBif \fIexpr1 \fR?\fBthen\fR? \fIbody1 \fBelseif \fIexpr2 \fR?\fBthen\fR? \fIbody2\fR \fBelseif\fR ... ?\fBelse\fR? ?\fIbodyN\fR? .BE - .SH DESCRIPTION .PP The \fIif\fR command evaluates \fIexpr1\fR as an expression (in the @@ -20,23 +20,28 @@ info \- Information about the state of the Tcl interpreter .SH DESCRIPTION .PP Available commands: +.\" METHOD: args .TP \fBinfo args \fIprocname\fR . Returns the names of the parameters to the procedure named \fIprocname\fR. +.\" METHOD: body .TP \fBinfo body \fIprocname\fR . Returns the body of the procedure named \fIprocname\fR. +.\" METHOD: class .TP \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR . Returns information about the class named \fIclass\fR. See \fBCLASS INTROSPECTION\fR below. +.\" METHOD: cmdcount .TP \fBinfo cmdcount\fR . Returns the total number of commands evaluated in this interpreter. +.\" METHOD: cmdtype .TP \fBinfo cmdtype \fIcommandName\fR .VS TIP426 @@ -70,6 +75,7 @@ that represents an instance of \fBoo::object\fR or one of its subclasses. \fIcommandName\fR was created by \fBzlib stream\fR. .RE .VE TIP426 +.\" METHOD: commands .TP \fBinfo commands \fR?\fIpattern\fR? . @@ -78,24 +84,43 @@ Returns the names of all commands visible in the current namespace. If \fBstring match\fR. Only the last component of \fIpattern\fR is a pattern. Other components identify a namespace. See \fBNAMESPACE RESOLUTION\fR in the \fBnamespace\fR(n) documentation. +.\" METHOD: complete .TP \fBinfo complete \fIcommand\fR . Returns 1 if \fIcommand\fR is a complete command, and \fB0\fR otherwise. Typically used in line-oriented input environments to allow users to type in commands that span multiple lines. +.\" METHOD: constant +.TP +\fBinfo constant \fIvarName\fR +.VS "TIP 677" +Returns 1 if \fIvarName\fR is a constant variable (see \fBconst\fR) and 0 +otherwise. +.VE "TIP 677" +.\" METHOD: consts +.TP +\fBinfo consts\fR ?\fIpattern\fR? +.VS "TIP 677" +Returns the list of constant variables (see \fBconst\fR) in the current scope, +or the list of constant variables matching \fIpattern\fR (if that is provided) +in a manner similar to \fBinfo vars\fR. +.VE "TIP 677" +.\" METHOD: coroutine .TP \fBinfo coroutine\fR . Returns the name of the current \fBcoroutine\fR, or the empty string if there is no current coroutine or the current coroutine has been deleted. +.\" METHOD: default .TP \fBinfo default \fIprocname parameter varname\fR . If the parameter \fIparameter\fR for the procedure named \fIprocname\fR has a default value, stores that value in \fIvarname\fR and returns \fB1\fR. Otherwise, returns \fB0\fR. +.\" METHOD: errorstack .TP \fBinfo errorstack \fR?\fIinterp\fR? . @@ -123,11 +148,13 @@ options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR is a convenient way of retrieving it for uncaught errors at top-level in an interactive \fBinterpreter\fR. .RE +.\" METHOD: exists .TP \fBinfo exists \fIvarName\fR . Returns \fB1\fR if a variable named \fIvarName\fR is visible and has been defined, and \fB0\fR otherwise. +.\" METHOD: frame .TP \fBinfo frame\fR ?\fIdepth\fR? . @@ -206,6 +233,7 @@ is given a literal list argument the system tracks the line number within the list words as well, and otherwise all line numbers are counted relative to the start of each word (smallest scope) .RE +.\" METHOD: functions .TP \fBinfo functions \fR?\fIpattern\fR? . @@ -213,6 +241,7 @@ If \fIpattern\fR is not given, returns a list of all the math functions currently defined. If \fIpattern\fR is given, returns only those names that match \fIpattern\fR according to \fBstring match\fR. +.\" METHOD: globals .TP \fBinfo globals \fR?\fIpattern\fR? . @@ -222,16 +251,20 @@ Global variables are variables in the global namespace. If \fIpattern\fR is given, only those names matching \fIpattern\fR are returned. Matching is determined using the same rules as for \fBstring match\fR. +.\" METHOD: hostname .TP \fBinfo hostname\fR . Returns the name of the current host. - +.RS +.PP This name is not guaranteed to be the fully-qualified domain name of the host. Where machines have several different names, as is common on systems with both TCP/IP (DNS) and NetBIOS-based networking installed, it is the name that is suitable for TCP/IP networking that is returned. +.RE +.\" METHOD: level .TP \fBinfo level\fR ?\fIlevel\fR? . @@ -241,11 +274,13 @@ Otherwise returns the complete command active at the given level. If is \fInumber\fR levels up from the current level. A complete command is the words in the command, with all substitutions performed, meaning that it is a list. See \fBuplevel\fR for more information on levels. +.\" METHOD: library .TP \fBinfo library\fR . Returns the value of \fBtcl_library\fR, which is the name of the library directory in which the scripts distributed with Tcl scripts are stored. +.\" METHOD: loaded .TP \fBinfo loaded \fR?\fIinterp\fR? ?\fIpackage\fR? . @@ -254,6 +289,7 @@ Returns the name of each file loaded in \fIinterp\fR va \fBload\fR as part of is the name of the loaded file and the name of the package for which the file was loaded. For a statically-loaded package the name of the file is the empty string. For \fIinterp\fR, the empty string is the current interpreter. +.\" METHOD: locals .TP \fBinfo locals \fR?\fIpattern\fR? . @@ -261,22 +297,25 @@ If \fIpattern\fR is given, returns the name of each local variable matching \fIpattern\fR according to \fBstring match\fR. Otherwise, returns the name of each local variable. A variables defined with the \fBglobal\fR, \fBupvar\fR or \fBvariable\fR is not local. - +.\" METHOD: nameofexecutable .TP \fBinfo nameofexecutable\fR . Returns the absolute pathname of the program for the current interpreter. If such a file can not be identified an empty string is returned. +.\" METHOD: object .TP \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR . Returns information about the object named \fIobject\fR. \fIsubcommand\fR is described \fBOBJECT INTROSPECTION\fR below. +.\" METHOD: patchlevel .TP \fBinfo patchlevel\fR . Returns the value of the global variable \fBtcl_patchLevel\fR, in which the exact version of the Tcl library initially stored. +.\" METHOD: procs .TP \fBinfo procs \fR?\fIpattern\fR? . @@ -285,6 +324,7 @@ only those names that match according to \fBstring match\fR. Only the final component in \fIpattern\fR is actually considered a pattern. Any qualifying components simply select a namespace. See \fBNAMESPACE RESOLUTION\fR in the \fBnamespace\fR(n) documentation. +.\" METHOD: script .TP \fBinfo script\fR ?\fIfilename\fR? . @@ -293,17 +333,20 @@ empty string if no pathname can be determined. If \fIfilename\fR is given, sets the return value of any future calls to \fBinfo script\fR for the duration of the innermost active script. This is useful in virtual file system applications. +.\" METHOD: sharedlibextension .TP \fBinfo sharedlibextension\fR . Returns the extension used on this platform for names of shared libraries, e.g. \fB.so\fR under Solaris. Returns the empty string if shared libraries are not supported on this platform. +.\" METHOD: tclversion .TP \fBinfo tclversion\fR . Returns the value of the global variable \fBtcl_version\fR, in which the major and minor version of the Tcl library are stored. +.\" METHOD: vars .TP \fBinfo vars\fR ?\fIpattern\fR? . @@ -313,11 +356,15 @@ If \fIpattern\fR is not given, returns the names of all visible variables. If Other components identify a namespace. See \fBNAMESPACE RESOLUTION\fR in the \fBnamespace\fR(n) documentation. When \fIpattern\fR is a qualified name, results are fully qualified. - -A variable that has declared but not yet defined is included in the results. +.RS +.PP +A variable that has been declared but not yet given a value will be included in +the results. +.RE .SS "CLASS INTROSPECTION" .PP The following \fIsubcommand\fR values are supported by \fBinfo class\fR: +.\" METHOD: call .TP \fBinfo class call\fI class method\fR . @@ -348,6 +395,7 @@ and the call chains that this command files do not actually contain private methods. .VE TIP500 .RE +.\" METHOD: constructor .TP \fBinfo class constructor\fI class\fR . @@ -357,6 +405,7 @@ element is the list of arguments to the constructor in a form suitable for passing to another call to \fBproc\fR or a method definition, and the second element is the body of the constructor. If no constructor is present, this returns the empty list. +.\" METHOD: definition .TP \fBinfo class definition\fI class method\fR . @@ -365,6 +414,7 @@ This subcommand returns a description of the definition of the method named list; the first element is the list of arguments to the method in a form suitable for passing to another call to \fBproc\fR or a method definition, and the second element is the body of the method. +.\" METHOD: definitionnamespace .TP \fBinfo class definitionnamespace\fI class\fR ?\fIkind\fR? .VS TIP524 @@ -383,26 +433,31 @@ this command returns the empty string. In those circumstances, the namespace to use using the class inheritance hierarchy. .RE .VE TIP524 +.\" METHOD: destructor .TP \fBinfo class destructor\fI class\fR . This subcommand returns the body of the destructor of class \fIclass\fR. If no destructor is present, this returns the empty string. +.\" METHOD: filters .TP \fBinfo class filters\fI class\fR . This subcommand returns the list of filter methods set on the class. +.\" METHOD: forward .TP \fBinfo class forward\fI class method\fR . This subcommand returns the argument list for the method forwarding called \fImethod\fR that is set on the class called \fIclass\fR. +.\" METHOD: instances .TP \fBinfo class instances\fI class\fR ?\fIpattern\fR? . This subcommand returns a list of instances of class \fIclass\fR. If the optional \fIpattern\fR argument is present, it constrains the list of returned instances to those that match it according to the rules of \fBstring match\fR. +.\" METHOD: methods .TP \fBinfo class methods\fI class\fR ?\fIoptions...\fR? . @@ -456,6 +511,7 @@ class's methods) are to be returned. .RE .VE TIP500 .RE +.\" METHOD: methodtype .TP \fBinfo class methodtype\fI class method\fR . @@ -464,11 +520,13 @@ the method named \fImethod\fR of class \fIclass\fR. When the result is \fBmethod\fR, further information can be discovered with \fBinfo class definition\fR, and when the result is \fBforward\fR, further information can be discovered with \fBinfo class forward\fR. +.\" METHOD: mixins .TP \fBinfo class mixins\fI class\fR . This subcommand returns a list of all classes that have been mixed into the class named \fIclass\fR. +.\" METHOD: properties .TP \fBinfo class properties\fI class\fR ?\fIoptions...\fR .VS "TIP 558" @@ -495,6 +553,7 @@ This option asks for the writable properties to be returned. Only readable or writable properties are returned, not both. .RE .VE "TIP 558" +.\" METHOD: subclasses .TP \fBinfo class subclasses\fI class\fR ?\fIpattern\fR? . @@ -502,11 +561,13 @@ This subcommand returns a list of direct subclasses of class \fIclass\fR. If the optional \fIpattern\fR argument is present, it constrains the list of returned classes to those that match it according to the rules of \fBstring match\fR. +.\" METHOD: superclasses .TP \fBinfo class superclasses\fI class\fR . This subcommand returns a list of direct superclasses of class \fIclass\fR in inheritance precedence order. +.\" METHOD: variables .TP \fBinfo class variables\fI class\fR ?\fB\-private\fR? . @@ -520,6 +581,7 @@ declared instead. .SS "OBJECT INTROSPECTION" .PP The following \fIsubcommand\fR values are supported by \fBinfo object\fR: +.\" METHOD: call .TP \fBinfo object call\fI object method\fR . @@ -549,12 +611,14 @@ and the call chains that this command files do not actually contain private methods. .VE TIP500 .RE +.\" METHOD: class .TP \fBinfo object class\fI object\fR ?\fIclassName\fR? . If \fIclassName\fR is not given, this subcommand returns class of the \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a boolean value indicating whether the \fIobject\fR is of that class. +.\" METHOD: creationid .TP \fBinfo object creationid\fI object\fR .VS TIP500 @@ -567,6 +631,7 @@ cannot be controlled at object creation time or altered afterwards. identifiers associated with the object, especially for private variables. .RE .VE TIP500 +.\" METHOD: definition .TP \fBinfo object definition\fI object method\fR . @@ -575,15 +640,18 @@ This subcommand returns a description of the definition of the method named element list; the first element is the list of arguments to the method in a form suitable for passing to another call to \fBproc\fR or a method definition, and the second element is the body of the method. +.\" METHOD: filters .TP \fBinfo object filters\fI object\fR . This subcommand returns the list of filter methods set on the object. +.\" METHOD: forward .TP \fBinfo object forward\fI object method\fR . This subcommand returns the argument list for the method forwarding called \fImethod\fR that is set on the object called \fIobject\fR. +.\" METHOD: isa .TP \fBinfo object isa\fI category object\fR ?\fIarg\fR? . @@ -616,6 +684,7 @@ This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether direct or indirect). .RE +.\" METHOD: methods .TP \fBinfo object methods\fI object\fR ?\fIoption...\fR? . @@ -669,6 +738,7 @@ object's instance methods) are to be returned. .RE .VE TIP500 .RE +.\" METHOD: methodtype .TP \fBinfo object methodtype\fI object method\fR . @@ -677,16 +747,19 @@ the method named \fImethod\fR of object \fIobject\fR. When the result is \fBmethod\fR, further information can be discovered with \fBinfo object definition\fR, and when the result is \fBforward\fR, further information can be discovered with \fBinfo object forward\fR. +.\" METHOD: mixins .TP \fBinfo object mixins\fI object\fR . This subcommand returns a list of all classes that have been mixed into the object named \fIobject\fR. +.\" METHOD: namespace .TP \fBinfo object namespace\fI object\fR . This subcommand returns the name of the internal namespace of the object named \fIobject\fR. +.\" METHOD: properties .TP \fBinfo object properties\fI object\fR ?\fIoptions...\fR .VS "TIP 558" @@ -714,6 +787,7 @@ This option asks for the writable properties to be returned. Only readable or writable properties are returned, not both. .RE .VE "TIP 558" +.\" METHOD: variables .TP \fBinfo object variables\fI object\fR ?\fB\-private\fR? . @@ -724,6 +798,7 @@ object's methods). If the \fB\-private\fR option is given, this lists the private variables declared instead. .VE TIP500 +.\" METHOD: vars .TP \fBinfo object vars\fI object\fR ?\fIpattern\fR? . diff --git a/doc/interp.n b/doc/interp.n index c3225fd..74745be 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -401,11 +401,6 @@ on the IO channel. Both interpreters must close it to close the underlying IO channel; IO channels accessible in an interpreter are automatically closed when an interpreter is destroyed. -.\" METHOD: slaves -.TP -\fBinterp slaves\fR ?\fIpath\fR? -. -Synonym for . \fBinterp\fR \fBchildren\fR ?\fIpath\fR? .\" METHOD: target .TP \fBinterp target\fI path alias\fR diff --git a/doc/ledit.n b/doc/ledit.n index 48bc608..b956cc1 100644 --- a/doc/ledit.n +++ b/doc/ledit.n @@ -26,6 +26,8 @@ the same as index values for the command \fBstring index\fR, supporting simple index arithmetic and indices relative to the end of the list. The index \fB0\fR refers to the first element of the list, and \fBend\fR refers to the last element of the list. +(Unlike with \fBlpop\fR, \fBlset\fR, and \fBlindex\fR, indices into sublists +are not supported.) .PP If either \fIfirst\fR or \fIlast\fR is less than zero, it is considered to refer to the position before the first element of the list. This allows @@ -42,7 +44,7 @@ with no elements being deleted. The \fIvalue\fR arguments specify zero or more new elements to be added to the list in place of those that were deleted. Each \fIvalue\fR argument will become a separate element of -the list. If no \fIvalue\fR arguments are specified, then the elements +the list. If no \fIvalue\fR arguments are specified, the elements between \fIfirst\fR and \fIlast\fR are simply deleted. .SH EXAMPLES .PP diff --git a/doc/library.n b/doc/library.n index 0342cbe..bb3db05 100644 --- a/doc/library.n +++ b/doc/library.n @@ -30,6 +30,7 @@ auto_execok, auto_import, auto_load, auto_mkindex, auto_qualify, auto_reset, tcl \fBreadFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? \fBwriteFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? \fIcontents\fR .VE "Tcl 8.7, TIP 670" +.fi .BE .SH INTRODUCTION .PP @@ -61,6 +62,7 @@ the auto-load mechanism defined below. .SH "COMMAND PROCEDURES" .PP The following procedures are provided in the Tcl library: +.\" COMMAND: auto_execok .TP \fBauto_execok \fIcmd\fR . @@ -97,6 +99,7 @@ you would do: set mayFrob [expr {[llength [\fBauto_execok\fR frobnicate]] > 0}] .CE .RE +.\" COMMAND: auto_import .TP \fBauto_import \fIpattern\fR . @@ -111,6 +114,7 @@ matching rules of \fBnamespace import\fR. .PP It is not normally necessary to call this command directly. .RE +.\" COMMAND: auto_load .TP \fBauto_load \fIcmd\fR . @@ -142,6 +146,7 @@ reload the index database from disk. It is not normally necessary to call this command directly; the default \fBunknown\fR handler will do so. .RE +.\" COMMAND: auto_mkindex .TP \fBauto_mkindex \fIdir pattern pattern ...\fR . @@ -184,6 +189,7 @@ code, such as global initialization code or procedure names with special characters like \fB$\fR, \fB*\fR, \fB[\fR or \fB]\fR, you are safer using \fBauto_mkindex_old\fR. .RE +.\" COMMAND: auto_reset .TP \fBauto_reset\fR . @@ -192,6 +198,7 @@ Destroys all the information cached by \fBauto_execok\fR and time it is needed. \fBAuto_reset\fR also deletes any procedures listed in the auto-load index, so that fresh copies of them will be loaded the next time that they are used. +.\" COMMAND: auto_qualify .TP \fBauto_qualify \fIcommand namespace\fR . @@ -212,6 +219,7 @@ if it were a command in the global namespace. for producing auto-loading indexes such as \fIpkgIndex.tcl\fR, and for performing the actual auto-loading of functions at runtime. .RE +.\" COMMAND: auto_findLibrary .TP \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR . @@ -235,6 +243,7 @@ relative to the executable file in the standard installation bin or bin/\fIarch\fR directory; relative to the executable file in the current build tree; relative to the executable file in a parallel build tree. +.\" COMMAND: parray .TP \fBparray \fIarrayName\fR ?\fIpattern\fR? . @@ -256,6 +265,7 @@ For example, to print the contents of the \fBtcl_platform\fR array, do: .SS "WORD BOUNDARY HELPERS" .PP These procedures are mainly used internally by Tk. +.\" COMMAND: tcl_endOfWord .TP \fBtcl_endOfWord \fIstr start\fR . @@ -267,6 +277,7 @@ are no more end-of-word locations after the starting point. See the description of \fBtcl_wordchars\fR and \fBtcl_nonwordchars\fR below for more details on how Tcl determines which characters are word characters. +.\" COMMAND: tcl_startOfNextWord .TP \fBtcl_startOfNextWord \fIstr start\fR . @@ -288,6 +299,7 @@ for {set idx 0} {$idx >= 0} { } .CE .RE +.\" COMMAND: tcl_startOfPreviousWord .TP \fBtcl_startOfPreviousWord \fIstr start\fR . @@ -295,6 +307,7 @@ Returns the index of the first start-of-word location that occurs before a starting index \fIstart\fR in the string \fIstr\fR. Returns \-1 if there are no more start-of-word locations before the starting point. +.\" COMMAND: tcl_wordBreakAfter .TP \fBtcl_wordBreakAfter \fIstr start\fR . @@ -303,6 +316,7 @@ Returns the index of the first word boundary after the starting index boundaries after the starting point in the given string. The index returned refers to the second character of the pair that comprises a boundary. +.\" COMMAND: tcl_wordBreakBefore .TP \fBtcl_wordBreakBefore \fIstr start\fR . @@ -311,6 +325,8 @@ Returns the index of the first word boundary before the starting index boundaries before the starting point in the given string. The index returned refers to the second character of the pair that comprises a boundary. +.SS "FILE ACCESS HELPERS" +.\" COMMAND: foreachLine .TP \fBforeachLine \fIvarName filename body\fR .VS "Tcl 8.7, TIP 670" @@ -325,6 +341,7 @@ The overall result of \fBforeachLine\fR is the empty string (assuming no errors from I/O or from evaluating the body of the loop); the file will be closed prior to the procedure returning. .VE "Tcl 8.7, TIP 670" +.\" COMMAND: readFile .TP \fBreadFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? .VS "Tcl 8.7, TIP 670" @@ -335,6 +352,7 @@ The second argument says how to read in the file, either as \fBtext\fR will include any trailing newline. The file will be closed prior to the procedure returning. .VE "Tcl 8.7, TIP 670" +.\" COMMAND: writeFile .TP \fBwriteFile \fIfilename\fR ?\fBtext\fR|\fBbinary\fR? \fIcontents\fR .VS "Tcl 8.7, TIP 670" @@ -352,6 +370,7 @@ The following global variables are defined or used by the procedures in the Tcl library. They fall into two broad classes, handling unknown commands and packages, and determining what are words. .SS "AUTOLOADING AND PACKAGE MANAGEMENT VARIABLES" +.\" VARIABLE: auto_execs .TP \fBauto_execs\fR . @@ -361,6 +380,7 @@ particular commands exist as executable files. .PP Not normally usefully accessed directly by user code. .RE +.\" VARIABLE: auto_index .TP \fBauto_index\fR . @@ -370,16 +390,19 @@ disk. .PP Not normally usefully accessed directly by user code. .RE +.\" VARIABLE: auto_noexec .TP \fBauto_noexec\fR . If set to any value, then \fBunknown\fR will not attempt to auto-exec any commands. +.\" VARIABLE: auto_noload .TP \fBauto_noload\fR . If set to any value, then \fBunknown\fR will not attempt to auto-load any commands. +.\" VARIABLE: auto_path .TP \fBauto_path\fR . @@ -405,6 +428,7 @@ lappend \fBauto_path\fR [file dirname [info script]]/lib Note that if the script uses \fBcd\fR, it is advisable to ensure that entries on the \fBauto_path\fR are \fBfile normalize\fRd. .RE +.\" VARIABLE: env(TCL_LIBRARY) .TP \fBenv(TCL_LIBRARY)\fR . @@ -419,6 +443,7 @@ Use of this environment variable is not recommended outside of testing. Tcl installations should already know where to find their own script files, as the value is baked in during the build or installation. .RE +.\" VARIABLE: env(TCLLIBPATH) .TP \fBenv(TCLLIBPATH)\fR . @@ -441,6 +466,7 @@ as their own threads or subprocesses). These variables are only used in the \fBtcl_endOfWord\fR, \fBtcl_startOfNextWord\fR, \fBtcl_startOfPreviousWord\fR, \fBtcl_wordBreakAfter\fR, and \fBtcl_wordBreakBefore\fR commands. +.\" VARIABLE: tcl_nonwordchars .TP \fBtcl_nonwordchars\fR . @@ -449,6 +475,7 @@ like \fBtcl_endOfWord\fR to identify whether a character is part of a word or not. If the pattern matches a character, the character is considered to be a non-word character. The default value is .QW "\\W" . +.\" VARIABLE: tcl_wordchars .TP \fBtcl_wordchars\fR . @@ -15,7 +15,7 @@ link \- create link from command to method of object .nf package require tcl::oo -\fBlink\fR \fImethodName\fR ?\fI...\fR? +\fBlink\fI methodName\fR ?\fI...\fR? \fBlink\fR \fB{\fIcommandName methodName\fB}\fR ?\fI...\fR? .fi .BE @@ -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. @@ -18,14 +18,15 @@ lpop \- Get and remove an element in a list The \fBlpop\fR command accepts a parameter, \fIvarName\fR, which it interprets as the name of a variable containing a Tcl list. It also accepts one or more \fIindices\fR into -the list. If no indices are presented, it defaults to "end". +the list. If no indices are presented, it defaults to "\fBend\fR". .PP When presented with a single index, the \fBlpop\fR command addresses the \fIindex\fR'th element in it, removes if from the list and returns the element. .PP If \fIindex\fR is negative or greater or equal than the number -of elements in \fI$varName\fR, then an error occurs. +of elements in the list in the variable called \fIvarName\fR, an +error occurs. .PP The interpretation of each simple \fIindex\fR value is the same as for the command \fBstring index\fR, supporting simple index @@ -34,7 +35,8 @@ arithmetic and indices relative to the end of the list. If additional \fIindex\fR arguments are supplied, then each argument is used in turn to address an element within a sublist designated by the previous indexing operation, -allowing the script to remove elements in sublists. +allowing the script to remove elements in sublists, similar to +\fBlindex\fR and \fBlset\fR. The command, .PP .CS diff --git a/doc/lsearch.n b/doc/lsearch.n index 20d497f..cc5d795 100644 --- a/doc/lsearch.n +++ b/doc/lsearch.n @@ -70,8 +70,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. .\" OPTION: -inline .TP \fB\-inline\fR @@ -11,85 +11,115 @@ .SH NAME lseq \- Build a numeric sequence returned as a list .SH SYNOPSIS +.nf \fBlseq \fIstart \fR?(\fB..\fR|\fBto\fR)? \fIend\fR ??\fBby\fR? \fIstep\fR? - -\fBlseq \fIstart \fBcount\fR \fIcount\fR ??\fBby\fR? \fIstep\fR? - +\fBlseq \fIstart \fBcount\fI count\fR ??\fBby\fR? \fIstep\fR? \fBlseq \fIcount\fR ?\fBby \fIstep\fR? +.fi .BE .SH DESCRIPTION .PP The \fBlseq\fR command creates a sequence of numeric values using the given -parameters \fIstart\fR, \fIend\fR, and \fIstep\fR. -The \fIoperation\fR argument -.QW \fB..\fR -or -.QW \fBto\fR -defines an inclusive range; if it is omitted, the range is exclusive. -The \fBcount\fR option is used to define a count of the number of elements in -the list. -The \fIstep\fR (which may be preceded by \fBby\fR) is 1 if not provided. -The short form with a -single \fIcount\fR value will create a range from 0 to \fIcount\fR-1 (i.e., -\fIcount\fR values). +parameters \fIstart\fR, \fIend\fR, and \fIstep\fR. The \fIoperation\fR +argument "\fB..\fR" or "\fBto\fR" defines the range. The "\fBcount\fR" option +is used to define a count of the number of elements in the list. A short form +use of the command, with a single count value, will create a range from 0 to +\fIcount\fR-1. +.PP +The \fBlseq\fR command can produce both increasing and decreasing +sequences. When both \fIstart\fR and \fIend\fR are provided without a +\fIstep\fR value, then if \fIstart\fR <= \fIend\fR, the sequence will be +increasing and if \fIstart\fR > \fIend\fR it will be decreasing. If a +\fIstep\fR vale is included, it's sign should agree with the direction of the +sequence (descending \(-> negative and ascending \(-> positive), otherwise an +empty list is returned. For example: +.RS +.PP +.CS \" +% \fBlseq\fR 1 to 5 ;# increasing +\fI\(-> 1 2 3 4 5 + +% \fBlseq\fR 5 to 1 ;# decreasing +\fI\(-> 5 4 3 2 1 + +% \fBlseq\fR 6 to 1 by 2 ;# decreasing, step wrong sign, empty list + +% \fBlseq\fR 1 to 5 by 0 ;# all step sizes of 0 produce an empty list +.\" +.CE +.RE +.PP +The numeric arguments, \fIstart\fR, \fIend\fR, \fIstep\fR, and \fIcount\fR, +may also be a valid expression. The expression will be evaluated and the +numeric result will be used. An expression that does not evaluate to a number +will produce an invalid argument error. +.PP +\fIStart\fR defines the initial value and \fIend\fR defines the limit, not +necessarily the last value. \fBlseq\fR produces a list with \fIcount\fR +elements, and if \fIcount\fR is not supplied, it is computed as: +.RS +.PP +.CS +\fIcount\fR = int( (\fIend\fR - \fIstart\fR + \fIstep\fR) / \fIstep\fR ) +.CE +.RE .PP The numeric arguments, \fIstart\fR, \fIend\fR, \fIstep\fR, and \fIcount\fR, can also be a valid expression. the \fBlseq\fR command will evaluate the expression (as if with \fBexpr\fR) and use the numeric result, or return an error as with any invalid argument value; a non-numeric expression result will result in an error. - .SH EXAMPLES .CS .\" \fBlseq\fR 3 - \fI\(-> 0 1 2\fR +\fI\(-> 0 1 2\fR \fBlseq\fR 3 0 - \fI\(-> 3 2 1 0\fR +\fI\(-> 3 2 1 0\fR \fBlseq\fR 10 .. 1 by -2 - \fI\(-> 10 8 6 4 2\fR +\fI\(-> 10 8 6 4 2\fR set l [\fBlseq\fR 0 -5] - \fI\(-> 0 -1 -2 -3 -4 -5\fR +\fI\(-> 0 -1 -2 -3 -4 -5\fR foreach i [\fBlseq\fR [llength $l]] { puts l($i)=[lindex $l $i] } - \fI\(-> l(0)=0\fR - \fI\(-> l(1)=-1\fR - \fI\(-> l(2)=-2\fR - \fI\(-> l(3)=-3\fR - \fI\(-> l(4)=-4\fR - \fI\(-> l(5)=-5\fR +\fI\(-> l(0)=0\fR +\fI\(-> l(1)=-1\fR +\fI\(-> l(2)=-2\fR +\fI\(-> l(3)=-3\fR +\fI\(-> l(4)=-4\fR +\fI\(-> l(5)=-5\fR foreach i [\fBlseq\fR {[llength $l]-1} 0] { puts l($i)=[lindex $l $i] } - \fI\(-> l(5)=-5\fR - \fI\(-> l(4)=-4\fR - \fI\(-> l(3)=-3\fR - \fI\(-> l(2)=-2\fR - \fI\(-> l(1)=-1\fR - \fI\(-> l(0)=0\fR +\fI\(-> l(5)=-5\fR +\fI\(-> l(4)=-4\fR +\fI\(-> l(3)=-3\fR +\fI\(-> l(2)=-2\fR +\fI\(-> l(1)=-1\fR +\fI\(-> l(0)=0\fR set i 17 \fI\(-> 17\fR -if {$i in [\fBlseq\fR 0 50]} { # equivalent to: (0 <= $i && $i < 50) +if {$i in [\fBlseq\fR 0 50]} { # equivalent to: (0 <= $i && $i <= 50) puts "Ok" } else { puts "outside :(" } - \fI\(-> Ok\fR +\fI\(-> Ok\fR set sqrs [lmap i [\fBlseq\fR 1 10] { expr {$i*$i} }] - \fI\(-> 1 4 9 16 25 36 49 64 81 100\fR +\fI\(-> 1 4 9 16 25 36 49 64 81 100\fR .\" .CE .SH "SEE ALSO" -foreach(n), list(n), lappend(n), lassign(n), ledit(n), lindex(n), linsert(n), -llength(n), lmap(n), lpop(n), lrange(n), lremove(n), lreplace(n), +foreach(n), list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n), +lmap(n), lpop(n), lrange(n), lremove(n), lreplace(n), lreverse(n), lsearch(n), lset(n), lsort(n) .SH KEYWORDS element, index, list @@ -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..c84dbf7 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -13,86 +13,51 @@ .SH NAME mathfunc \- Mathematical functions for Tcl expressions .SH SYNOPSIS +.nf package require \fBTcl 8.5-\fR -.sp -\fB::tcl::mathfunc::abs\fR \fIarg\fR -.br -\fB::tcl::mathfunc::acos\fR \fIarg\fR -.br -\fB::tcl::mathfunc::asin\fR \fIarg\fR -.br -\fB::tcl::mathfunc::atan\fR \fIarg\fR -.br -\fB::tcl::mathfunc::atan2\fR \fIy\fR \fIx\fR -.br -\fB::tcl::mathfunc::bool\fR \fIarg\fR -.br -\fB::tcl::mathfunc::ceil\fR \fIarg\fR -.br -\fB::tcl::mathfunc::cos\fR \fIarg\fR -.br -\fB::tcl::mathfunc::cosh\fR \fIarg\fR -.br -\fB::tcl::mathfunc::double\fR \fIarg\fR -.br -\fB::tcl::mathfunc::entier\fR \fIarg\fR -.br -\fB::tcl::mathfunc::exp\fR \fIarg\fR -.br -\fB::tcl::mathfunc::floor\fR \fIarg\fR -.br -\fB::tcl::mathfunc::fmod\fR \fIx\fR \fIy\fR -.br -\fB::tcl::mathfunc::hypot\fR \fIx\fR \fIy\fR -.br -\fB::tcl::mathfunc::int\fR \fIarg\fR -.br + +\fB::tcl::mathfunc::abs\fI arg\fR +\fB::tcl::mathfunc::acos\fI arg\fR +\fB::tcl::mathfunc::asin\fI arg\fR +\fB::tcl::mathfunc::atan\fI arg\fR +\fB::tcl::mathfunc::atan2\fI y x\fR +\fB::tcl::mathfunc::bool\fI arg\fR +\fB::tcl::mathfunc::ceil\fI arg\fR +\fB::tcl::mathfunc::cos\fI arg\fR +\fB::tcl::mathfunc::cosh\fI arg\fR +\fB::tcl::mathfunc::double\fI arg\fR +\fB::tcl::mathfunc::entier\fI arg\fR +\fB::tcl::mathfunc::exp\fI arg\fR +\fB::tcl::mathfunc::floor\fI arg\fR +\fB::tcl::mathfunc::fmod\fI x y\fR +\fB::tcl::mathfunc::hypot\fI x y\fR +\fB::tcl::mathfunc::int\fI arg\fR .VS "8.7, TIP 521" -\fB::tcl::mathfunc::isfinite\fR \fIarg\fR -.br -\fB::tcl::mathfunc::isinf\fR \fIarg\fR -.br -\fB::tcl::mathfunc::isnan\fR \fIarg\fR -.br -\fB::tcl::mathfunc::isnormal\fR \fIarg\fR +\fB::tcl::mathfunc::isfinite\fI arg\fR +\fB::tcl::mathfunc::isinf\fI arg\fR +\fB::tcl::mathfunc::isnan\fI arg\fR +\fB::tcl::mathfunc::isnormal\fI arg\fR .VE "8.7, TIP 521" -.br -\fB::tcl::mathfunc::isqrt\fR \fIarg\fR -.br +\fB::tcl::mathfunc::isqrt\fI arg\fR .VS "8.7, TIP 521" -\fB::tcl::mathfunc::issubnormal\fR \fIarg\fR -.br -\fB::tcl::mathfunc::isunordered\fR \fIx y\fR +\fB::tcl::mathfunc::issubnormal\fI arg\fR +\fB::tcl::mathfunc::isunordered\fI x y\fR .VE "8.7, TIP 521" -.br -\fB::tcl::mathfunc::log\fR \fIarg\fR -.br -\fB::tcl::mathfunc::log10\fR \fIarg\fR -.br -\fB::tcl::mathfunc::max\fR \fIarg\fR ?\fIarg\fR ...? -.br -\fB::tcl::mathfunc::min\fR \fIarg\fR ?\fIarg\fR ...? -.br -\fB::tcl::mathfunc::pow\fR \fIx\fR \fIy\fR -.br +\fB::tcl::mathfunc::log\fI arg\fR +\fB::tcl::mathfunc::log10\fI arg\fR +\fB::tcl::mathfunc::max\fI arg\fR ?\fIarg\fR ...? +\fB::tcl::mathfunc::min\fI arg\fR ?\fIarg\fR ...? +\fB::tcl::mathfunc::pow\fI x y\fR \fB::tcl::mathfunc::rand\fR -.br -\fB::tcl::mathfunc::round\fR \fIarg\fR -.br -\fB::tcl::mathfunc::sin\fR \fIarg\fR -.br -\fB::tcl::mathfunc::sinh\fR \fIarg\fR -.br -\fB::tcl::mathfunc::sqrt\fR \fIarg\fR -.br -\fB::tcl::mathfunc::srand\fR \fIarg\fR -.br -\fB::tcl::mathfunc::tan\fR \fIarg\fR -.br -\fB::tcl::mathfunc::tanh\fR \fIarg\fR -.br -\fB::tcl::mathfunc::wide\fR \fIarg\fR -.sp +\fB::tcl::mathfunc::round\fI arg\fR +\fB::tcl::mathfunc::sin\fI arg\fR +\fB::tcl::mathfunc::sinh\fI arg\fR +\fB::tcl::mathfunc::sqrt\fI arg\fR +\fB::tcl::mathfunc::srand\fI arg\fR +\fB::tcl::mathfunc::tan\fI arg\fR +\fB::tcl::mathfunc::tanh\fI arg\fR +\fB::tcl::mathfunc::wide\fI arg\fR +.fi .BE .SH "DESCRIPTION" .PP @@ -124,31 +89,33 @@ 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" +.\" COMMAND: abs .TP \fBabs \fIarg\fR . Returns the absolute value of \fIarg\fR. \fIArg\fR may be either integer or floating-point, and the result is returned in the same form. +.\" COMMAND: acos .TP \fBacos \fIarg\fR . Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR] radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. +.\" COMMAND: asin .TP \fBasin \fIarg\fR . Returns the arc sine of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. +.\" COMMAND: atan .TP \fBatan \fIarg\fR . Returns the arc tangent of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] radians. +.\" COMMAND: atan2 .TP \fBatan2 \fIy x\fR . @@ -156,6 +123,7 @@ Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI\-pi\fR,\fIpi\fR] radians. \fIx\fR and \fIy\fR cannot both be 0. If \fIx\fR is greater than \fI0\fR, this is equivalent to .QW "\fBatan \fR[\fBexpr\fR {\fIy\fB/\fIx\fR}]" . +.\" COMMAND: bool .TP \fBbool \fIarg\fR . @@ -164,21 +132,25 @@ Accepts any numeric value, or any string acceptable to boolean value \fB0\fR or \fB1\fR. Non-zero numbers are true. Other numbers are false. Non-numeric strings produce boolean value in agreement with \fBstring is true\fR and \fBstring is false\fR. +.\" COMMAND: ceil .TP \fBceil \fIarg\fR . Returns the smallest integral floating-point value (i.e. with a zero fractional part) not less than \fIarg\fR. The argument may be any numeric value. +.\" COMMAND: cos .TP \fBcos \fIarg\fR . Returns the cosine of \fIarg\fR, measured in radians. +.\" COMMAND: cosh .TP \fBcosh \fIarg\fR . Returns the hyperbolic cosine of \fIarg\fR. If the result would cause an overflow, an error is returned. +.\" COMMAND: double .TP \fBdouble \fIarg\fR . @@ -187,6 +159,7 @@ If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts \fIarg\fR to floating-point and returns the converted value. May return \fBInf\fR or \fB\-Inf\fR when the argument is a numeric value that exceeds the floating-point range. +.\" COMMAND: entier .TP \fBentier \fIarg\fR . @@ -194,22 +167,26 @@ The argument may be any numeric value. The integer part of \fIarg\fR is determined and returned. The integer range returned by this function is unlimited, unlike \fBint\fR and \fBwide\fR which truncate their range to fit in particular storage widths. +.\" COMMAND: exp .TP \fBexp \fIarg\fR . Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR. If the result would cause an overflow, an error is returned. +.\" COMMAND: floor .TP \fBfloor \fIarg\fR . Returns the largest integral floating-point value (i.e. with a zero fractional part) not greater than \fIarg\fR. The argument may be any numeric value. +.\" COMMAND: fmod .TP \fBfmod \fIx y\fR . Returns the floating-point remainder of the division of \fIx\fR by \fIy\fR. If \fIy\fR is 0, an error is returned. +.\" COMMAND: hypot .TP \fBhypot \fIx y\fR . @@ -218,6 +195,7 @@ approximately .QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]" except for being more numerically stable when the two arguments have substantially different magnitudes. +.\" COMMAND: int .TP \fBint \fIarg\fR . @@ -226,6 +204,7 @@ is determined, and then the low order bits of that integer value up to the machine word size are returned as an integer value. For reference, the number of bytes in the machine word are stored in the \fBwordSize\fR element of the \fBtcl_platform\fR array. +.\" COMMAND: isfinite .TP \fBisfinite \fIarg\fR .VS "8.7, TIP 521" @@ -233,6 +212,7 @@ Returns 1 if the floating-point number \fIarg\fR is finite. That is, if it is zero, subnormal, or normal. Returns 0 if the number is infinite or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isinf .TP \fBisinf \fIarg\fR .VS "8.7, TIP 521" @@ -240,6 +220,7 @@ Returns 1 if the floating-point number \fIarg\fR is infinite. Returns 0 if the number is finite or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isnan .TP \fBisnan \fIarg\fR .VS "8.7, TIP 521" @@ -247,6 +228,7 @@ Returns 1 if the floating-point number \fIarg\fR is Not-a-Number. Returns 0 if the number is finite or infinite. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isnormal .TP \fBisnormal \fIarg\fR .VS "8.7, TIP 521" @@ -254,6 +236,7 @@ Returns 1 if the floating-point number \fIarg\fR is normal. Returns 0 if the number is zero, subnormal, infinite or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isqrt .TP \fBisqrt \fIarg\fR . @@ -261,6 +244,7 @@ Computes the integer part of the square root of \fIarg\fR. \fIArg\fR must be a positive value, either an integer or a floating point number. Unlike \fBsqrt\fR, which is limited to the precision of a floating point number, \fIisqrt\fR will return a result of arbitrary precision. +.\" COMMAND: issubnormal .TP \fBissubnormal \fIarg\fR .VS "8.7, TIP 521" @@ -269,6 +253,7 @@ result of gradual underflow. Returns 0 if the number is zero, normal, infinite or NaN. Throws an error if \fIarg\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: isunordered .TP \fBisunordered \fIx y\fR .VS "8.7, TIP 521" @@ -278,31 +263,37 @@ are both chosen from among the set of zero, subnormal, normal and infinite values. Throws an error if either \fIx\fR or \fIy\fR cannot be promoted to a floating-point value. .VE "8.7, TIP 521" +.\" COMMAND: log .TP \fBlog \fIarg\fR . Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a positive value. +.\" COMMAND: log10 .TP \fBlog10 \fIarg\fR . Returns the base 10 logarithm of \fIarg\fR. \fIArg\fR must be a positive value. +.\" COMMAND: max .TP \fBmax \fIarg\fB \fI...\fR . Accepts one or more numeric arguments. Returns the one argument with the greatest value. +.\" COMMAND: min .TP \fBmin \fIarg\fB \fI...\fR . Accepts one or more numeric arguments. Returns the one argument with the least value. +.\" COMMAND: pow .TP \fBpow \fIx y\fR . Computes the value of \fIx\fR raised to the power \fIy\fR. If \fIx\fR is negative, \fIy\fR must be an integer value. +.\" COMMAND: rand .TP \fBrand\fR . @@ -313,20 +304,24 @@ determines all future results from subsequent calls to \fBrand\fR, so \fBrand\fR should not be used to generate a sequence of secrets, such as one-time passwords. The seed of the generator is initialized from the internal clock of the machine or may be set with the \fBsrand\fR function. +.\" COMMAND: round .TP \fBround \fIarg\fR . If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts \fIarg\fR to integer by rounding and returns the converted value. +.\" COMMAND: sin .TP \fBsin \fIarg\fR . Returns the sine of \fIarg\fR, measured in radians. +.\" COMMAND: sinh .TP \fBsinh \fIarg\fR . Returns the hyperbolic sine of \fIarg\fR. If the result would cause an overflow, an error is returned. +.\" COMMAND: sqrt .TP \fBsqrt \fIarg\fR . @@ -334,20 +329,24 @@ The argument may be any non-negative numeric value. Returns a floating-point value that is the square root of \fIarg\fR. May return \fBInf\fR when the argument is a numeric value that exceeds the square of the maximum value of the floating-point range. +.\" COMMAND: srand .TP \fBsrand \fIarg\fR . The \fIarg\fR, which must be an integer, is used to reset the seed for the random number generator of \fBrand\fR. Returns the first random number (see \fBrand\fR) from that seed. Each interpreter has its own seed. +.\" COMMAND: tan .TP \fBtan \fIarg\fR . Returns the tangent of \fIarg\fR, measured in radians. +.\" COMMAND: tanh .TP \fBtanh \fIarg\fR . Returns the hyperbolic tangent of \fIarg\fR. +.\" COMMAND: wide .TP \fBwide \fIarg\fR . diff --git a/doc/mathop.n b/doc/mathop.n index 3a13456..95a5d0e 100644 --- a/doc/mathop.n +++ b/doc/mathop.n @@ -11,64 +11,39 @@ .SH NAME mathop \- Mathematical operators as Tcl commands .SH SYNOPSIS +.nf package require \fBTcl 8.5-\fR -.sp -\fB::tcl::mathop::!\fR \fInumber\fR -.br -\fB::tcl::mathop::~\fR \fInumber\fR -.br + +\fB::tcl::mathop::!\fI number\fR +\fB::tcl::mathop::~\fI number\fR \fB::tcl::mathop::+\fR ?\fInumber\fR ...? -.br -\fB::tcl::mathop::\-\fR \fInumber\fR ?\fInumber\fR ...? -.br +\fB::tcl::mathop::\-\fI number\fR ?\fInumber\fR ...? \fB::tcl::mathop::*\fR ?\fInumber\fR ...? -.br -\fB::tcl::mathop::/\fR \fInumber\fR ?\fInumber\fR ...? -.br -\fB::tcl::mathop::%\fR \fInumber number\fR -.br +\fB::tcl::mathop::/\fI number\fR ?\fInumber\fR ...? +\fB::tcl::mathop::%\fI number number\fR \fB::tcl::mathop::**\fR ?\fInumber\fR ...? -.br \fB::tcl::mathop::&\fR ?\fInumber\fR ...? -.br \fB::tcl::mathop::|\fR ?\fInumber\fR ...? -.br \fB::tcl::mathop::^\fR ?\fInumber\fR ...? -.br -\fB::tcl::mathop::<<\fR \fInumber number\fR -.br -\fB::tcl::mathop::>>\fR \fInumber number\fR -.br +\fB::tcl::mathop::<<\fI number number\fR +\fB::tcl::mathop::>>\fI number number\fR \fB::tcl::mathop::==\fR ?\fIarg\fR ...? -.br -\fB::tcl::mathop::!=\fR \fIarg arg\fR -.br +\fB::tcl::mathop::!=\fI arg arg\fR \fB::tcl::mathop::<\fR ?\fIarg\fR ...? -.br \fB::tcl::mathop::<=\fR ?\fIarg\fR ...? -.br \fB::tcl::mathop::>=\fR ?\fIarg\fR ...? -.br \fB::tcl::mathop::>\fR ?\fIarg\fR ...? -.br \fB::tcl::mathop::eq\fR ?\fIarg\fR ...? -.br -\fB::tcl::mathop::ne\fR \fIarg arg\fR -.br +\fB::tcl::mathop::ne\fI arg arg\fR .VS "8.7, TIP461" \fB::tcl::mathop::lt\fR ?\fIarg\fR ...? -.br \fB::tcl::mathop::le\fR ?\fIarg\fR ...? -.br \fB::tcl::mathop::gt\fR ?\fIarg\fR ...? -.br \fB::tcl::mathop::ge\fR ?\fIarg\fR ...? .VE "8.7, TIP461" -.br -\fB::tcl::mathop::in\fR \fIarg list\fR -.br -\fB::tcl::mathop::ni\fR \fIarg list\fR -.sp +\fB::tcl::mathop::in\fI arg list\fR +\fB::tcl::mathop::ni\fI arg list\fR +.fi .BE .SH DESCRIPTION .PP @@ -92,34 +67,39 @@ The following operator commands are supported: .SS "MATHEMATICAL OPERATORS" .PP The behaviors of the mathematical operator commands are as follows: +.\" COMMAND: ! .TP -\fB!\fR \fIboolean\fR +\fB!\fI boolean\fR . Returns the boolean negation of \fIboolean\fR, where \fIboolean\fR may be any numeric value or any other form of boolean value (i.e. it returns truth if the argument is falsity or zero, and falsity if the argument is truth or non-zero). +.\" COMMAND: + .TP \fB+\fR ?\fInumber\fR ...? . Returns the sum of arbitrarily many arguments. Each \fInumber\fR argument may be any numeric value. If no arguments are given, the result will be zero (the summation identity). +.\" COMMAND: - .TP -\fB\-\fR \fInumber\fR ?\fInumber\fR ...? +\fB\-\fI number\fR ?\fInumber\fR ...? . If only a single \fInumber\fR argument is given, returns the negation of that numeric value. Otherwise returns the number that results when all subsequent numeric values are subtracted from the first one. All \fInumber\fR arguments must be numeric values. At least one argument must be given. +.\" COMMAND: * .TP \fB*\fR ?\fInumber\fR ...? . Returns the product of arbitrarily many arguments. Each \fInumber\fR may be any numeric value. If no arguments are given, the result will be one (the multiplicative identity). +.\" COMMAND: / .TP -\fB/\fR \fInumber\fR ?\fInumber\fR ...? +\fB/\fI number\fR ?\fInumber\fR ...? . If only a single \fInumber\fR argument is given, returns the reciprocal of that numeric value (i.e. the value obtained by dividing 1.0 by that value). @@ -134,8 +114,9 @@ results will be as if the functions \fIfloor\fR and \fIint\fR are applied to them, in that order). If all values in the operation are integers, the result will be an integer. .RE +.\" COMMAND: % .TP -\fB%\fR \fInumber number\fR +\fB%\fI number number\fR . Returns the integral modulus (i.e., remainder) of the first argument with respect to the second. @@ -152,6 +133,7 @@ clarity): \fB==\fR [\fB*\fR [\fB/\fI x y\fR] \fIy\fR] [\fB\-\fI x\fR [\fB%\fI x y\fR]] .CE .RE +.\" COMMAND: ** .TP \fB**\fR ?\fInumber\fR ...? . @@ -171,6 +153,7 @@ arguments are integral values. .PP The behaviors of the comparison operator commands (most of which operate preferentially on numeric arguments) are as follows: +.\" COMMAND: == .TP \fB==\fR ?\fIarg\fR ...? . @@ -178,23 +161,27 @@ Returns whether each argument is equal to the arguments on each side of it in the sense of the \fBexpr\fR == operator (\fIi.e.\fR, numeric comparison if possible, exact string comparison otherwise). If fewer than two arguments are given, this operation always returns a true value. +.\" COMMAND: eq .TP \fBeq\fR ?\fIarg\fR ...? . Returns whether each argument is equal to the arguments on each side of it using exact string comparison. If fewer than two arguments are given, this operation always returns a true value. +.\" COMMAND: != .TP -\fB!=\fR \fIarg arg\fR +\fB!=\fI arg arg\fR . Returns whether the two arguments are not equal to each other, in the sense of the \fBexpr\fR != operator (\fIi.e.\fR, numeric comparison if possible, exact string comparison otherwise). +.\" COMMAND: ne .TP -\fBne\fR \fIarg arg\fR +\fBne\fI arg arg\fR . Returns whether the two arguments are not equal to each other using exact string comparison. +.\" COMMAND: < .TP \fB<\fR ?\fIarg\fR ...? . @@ -205,6 +192,7 @@ otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the \fBlt\fR operator or the \fBstring compare\fR command should be used instead. +.\" COMMAND: <= .TP \fB<=\fR ?\fIarg\fR ...? . @@ -215,6 +203,7 @@ otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the \fBle\fR operator or the \fBstring compare\fR command should be used instead. +.\" COMMAND: > .TP \fB>\fR ?\fIarg\fR ...? . @@ -225,6 +214,7 @@ otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the \fBgt\fR operator or the \fBstring compare\fR command should be used instead. +.\" COMMAND: >= .TP \fB>=\fR ?\fIarg\fR ...? . @@ -235,6 +225,7 @@ otherwise performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. When the arguments are numeric but should be compared as strings, the \fBge\fR operator or the \fBstring compare\fR command should be used instead. +.\" COMMAND: lt .TP \fBlt\fR ?\fIarg\fR ...? .VS "8.7, TIP461" @@ -243,6 +234,7 @@ after the first having to be strictly more than the one preceding it. Comparisons are performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. .VE "8.7, TIP461" +.\" COMMAND: le .TP \fBle\fR ?\fIarg\fR ...? .VS "8.7, TIP461" @@ -251,6 +243,7 @@ after the first having to be equal to or strictly more than the one preceding it Comparisons are performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. .VE "8.7, TIP461" +.\" COMMAND: gt .TP \fBgt\fR ?\fIarg\fR ...? .VS "8.7, TIP461" @@ -259,6 +252,7 @@ after the first having to be strictly less than the one preceding it. Comparisons are performed using UNICODE string comparison. If fewer than two arguments are present, this operation always returns a true value. .VE "8.7, TIP461" +.\" COMMAND: ge .TP \fBge\fR ?\fIarg\fR ...? .VS "8.7, TIP461" @@ -271,38 +265,44 @@ arguments are present, this operation always returns a true value. .PP The behaviors of the bit-wise operator commands (all of which only operate on integral arguments) are as follows: +.\" COMMAND: ~ .TP -\fB~\fR \fInumber\fR +\fB~\fI number\fR . Returns the bit-wise negation of \fInumber\fR. \fINumber\fR may be an integer of any size. Note that the result of this operation will always have the opposite sign to the input \fInumber\fR. +.\" COMMAND: & .TP \fB&\fR ?\fInumber\fR ...? . Returns the bit-wise AND of each of the arbitrarily many arguments. Each \fInumber\fR must have an integral value. If no arguments are given, the result will be minus one. +.\" COMMAND: | .TP \fB|\fR ?\fInumber\fR ...? . Returns the bit-wise OR of each of the arbitrarily many arguments. Each \fInumber\fR must have an integral value. If no arguments are given, the result will be zero. +.\" COMMAND: ^ .TP \fB^\fR ?\fInumber\fR ...? . Returns the bit-wise XOR of each of the arbitrarily many arguments. Each \fInumber\fR must have an integral value. If no arguments are given, the result will be zero. +.\" COMMAND: << .TP -\fB<<\fR \fInumber number\fR +\fB<<\fI number number\fR . Returns the result of bit-wise shifting the first argument left by the number of bits specified in the second argument. Each \fInumber\fR must have an integral value. +.\" COMMAND: >> .TP -\fB>>\fR \fInumber number\fR +\fB>>\fI number number\fR . Returns the result of bit-wise shifting the first argument right by the number of bits specified in the second argument. Each \fInumber\fR @@ -310,13 +310,15 @@ must have an integral value. .SS "LIST OPERATORS" .PP The behaviors of the list-oriented operator commands are as follows: +.\" COMMAND: in .TP -\fBin\fR \fIarg list\fR +\fBin\fI arg list\fR . Returns whether the value \fIarg\fR is present in the list \fIlist\fR (according to exact string comparison of elements). +.\" COMMAND: ni .TP -\fBni\fR \fIarg list\fR +\fBni\fI arg list\fR . Returns whether the value \fIarg\fR is not present in the list \fIlist\fR (according to exact string comparison of elements). diff --git a/doc/memory.n b/doc/memory.n index fc3ff99..8fe6a9b 100644 --- a/doc/memory.n +++ b/doc/memory.n @@ -18,96 +18,106 @@ debugging capabilities. The memory command has several suboptions, which are described below. It is only available when Tcl has been compiled with memory debugging enabled (when \fBTCL_MEM_DEBUG\fR is defined at compile time), and after \fBTcl_InitMemory\fR has been called. +.\" METHOD: active .TP -\fBmemory active\fR \fIfile\fR +\fBmemory active\fI file\fR . Write a list of all currently allocated memory to the specified \fIfile\fR. +.\" METHOD: break_on_malloc .TP -\fBmemory break_on_malloc\fR \fIcount\fR +\fBmemory break_on_malloc\fI count\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 command mode. +.\" METHOD: info .TP \fBmemory info\fR . 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. +.\" METHOD: init .TP \fBmemory init \fR[\fBon\fR|\fBoff\fR] . Turn on or off the preinitialization of all allocated memory with bogus bytes. Useful for detecting the use of uninitialized values. +.\" METHOD: objs .TP \fBmemory objs \fIfile\fR . Causes a list of all allocated Tcl_Obj values to be written to the specified \fIfile\fR immediately, together with where they were allocated. Useful for checking for leaks of values. +.\" METHOD: onexit .TP -\fBmemory onexit\fR \fIfile\fR +\fBmemory onexit\fI file\fR . Causes a list of all allocated memory to be written to the specified \fIfile\fR during the finalization of Tcl's memory subsystem. Useful for checking that memory is properly cleaned up during process exit. +.\" METHOD: tag .TP -\fBmemory tag\fR \fIstring\fR +\fBmemory tag\fI string\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. +.\" METHOD: trace .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 +.\" METHOD: trace_on_at_malloc .TP -\fBmemory trace_on_at_malloc\fR \fIcount\fR +\fBmemory trace_on_at_malloc\fI count\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 produced), if you can identify a number of allocations that occur before the problem sets in. The current number of memory allocations that have occurred since Tcl started is printed on a guard zone failure. +.\" METHOD: validate .TP \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/msgcat.n b/doc/msgcat.n index 9d82688..21b6aa1 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -13,51 +13,34 @@ msgcat \- Tcl message catalog .SH SYNOPSIS .nf \fBpackage require tcl 8.7\fR -.sp \fBpackage require msgcat 1.7\fR -.sp + \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR? -.sp \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR? -.sp .VS "TIP 412" \fB::msgcat::mcexists\fR ?\fB\-exactnamespace\fR? ?\fB\-exactlocale\fR? \fIsrc-string\fR .VE "TIP 412" -.sp .VS "TIP 490" \fB::msgcat::mcpackagenamespaceget\fR .VE "TIP 490" -.sp \fB::msgcat::mclocale \fR?\fInewLocale\fR? -.sp .VS "TIP 499" \fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ... .VE "TIP 499" -.sp .VS "TIP 412" \fB::msgcat::mcloadedlocales subcommand\fR ?\fIlocale\fR? .VE "TIP 412" -.sp \fB::msgcat::mcload \fIdirname\fR -.sp \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR? -.sp \fB::msgcat::mcmset \fIlocale src-trans-list\fR -.sp \fB::msgcat::mcflset \fIsrc-string \fR?\fItranslate-string\fR? -.sp \fB::msgcat::mcflmset \fIsrc-trans-list\fR -.sp \fB::msgcat::mcunknown \fIlocale src-string\fR ?\fIarg arg ...\fR? -.sp .VS "TIP 412" \fB::msgcat::mcpackagelocale subcommand\fR ?\fIlocale\fR? -.sp \fB::msgcat::mcpackageconfig subcommand\fI option\fR ?\fIvalue\fR? -.sp \fB::msgcat::mcforgetpackage\fR .VE "TIP 412" -.sp .VS "TIP 499" \fB::msgcat::mcutil subcommand\fR ?\fIlocale\fR? .VS "TIP 499" @@ -115,7 +98,7 @@ use the result. If an application is written for a single language in this fashion, then it is easy to add support for additional languages later simply by defining new message catalog entries. .RE -.\" COMMAND: mcn +.\" COMMAND: mcc .TP \fB::msgcat::mcn \fInamespace src-string\fR ?\fIarg arg ...\fR? .VS "TIP 490" diff --git a/doc/namespace.n b/doc/namespace.n index 5b09890..c19791c 100644 --- a/doc/namespace.n +++ b/doc/namespace.n @@ -24,6 +24,7 @@ See the section \fBWHAT IS A NAMESPACE?\fR below for a brief overview of namespaces. The legal values of \fIsubcommand\fR are listed below. Note that you can abbreviate the \fIsubcommand\fRs. +.\" METHOD: children .TP \fBnamespace children \fR?\fInamespace\fR? ?\fIpattern\fR? . @@ -40,6 +41,7 @@ a pattern that starts with double colon (\fB::\fR) is used directly, otherwise the namespace \fInamespace\fR (or the fully-qualified name of the current namespace) is prepended onto the pattern. +.\" METHOD: code .TP \fBnamespace code \fIscript\fR . @@ -68,6 +70,7 @@ A scoped command captures a command together with its namespace context in a way that allows it to be executed properly later. See the section \fBSCOPED SCRIPTS\fR for some examples of how this is used to create callback scripts. +.\" METHOD: current .TP \fBnamespace current\fR . @@ -77,6 +80,7 @@ The actual name of the global namespace is (i.e., an empty string), but this command returns \fB::\fR for the global namespace as a convenience to programmers. +.\" METHOD: delete .TP \fBnamespace delete \fR?\fInamespace namespace ...\fR? . @@ -89,14 +93,16 @@ however, the namespace is marked to prevent other code from looking it up by name. If a namespace does not exist, this command returns an error. If no namespace names are given, this command does nothing. +.\" METHOD: ensemble .TP -\fBnamespace ensemble\fR \fIsubcommand\fR ?\fIarg ...\fR? +\fBnamespace ensemble \fIsubcommand\fR ?\fIarg ...\fR? . Creates and manipulates a command that is formed out of an ensemble of subcommands. See the section \fBENSEMBLES\fR below for further details. +.\" METHOD: eval .TP -\fBnamespace eval\fR \fInamespace arg\fR ?\fIarg ...\fR? +\fBnamespace eval \fInamespace arg\fR ?\fIarg ...\fR? . Activates a namespace called \fInamespace\fR and evaluates some code in that context. @@ -111,11 +117,13 @@ If \fInamespace\fR has leading namespace qualifiers and any leading namespaces do not exist, they are automatically created. .RE +.\" METHOD: exists .TP -\fBnamespace exists\fR \fInamespace\fR +\fBnamespace exists \fInamespace\fR . Returns \fB1\fR if \fInamespace\fR is a valid namespace in the current context, returns \fB0\fR otherwise. +.\" METHOD: export .TP \fBnamespace export \fR?\fB\-clear\fR? ?\fIpattern pattern ...\fR? . @@ -137,6 +145,7 @@ the namespace's export pattern list is reset to empty before any \fIpattern\fR arguments are appended. If no \fIpattern\fRs are given and the \fB\-clear\fR flag is not given, this command returns the namespace's current export list. +.\" METHOD: forget .TP \fBnamespace forget \fR?\fIpattern pattern ...\fR? . @@ -162,8 +171,9 @@ It then checks whether any of those commands were previously imported by the current namespace. If so, this command deletes the corresponding imported commands. In effect, this undoes the action of a \fBnamespace import\fR command. +.\" METHOD: import .TP -\fBnamespace import \fR?\fB\-force\fR? ?\fIpattern\fR \fIpattern ...\fR? +\fBnamespace import \fR?\fB\-force\fR? ?\fIpattern pattern ...\fR? . Imports commands into a namespace, or queries the set of imported commands in a namespace. When no arguments are present, @@ -205,8 +215,9 @@ at the time when the \fBnamespace import\fR command is executed. If another command is defined and exported in this namespace later on, it will not be imported. .RE +.\" METHOD: inscope .TP -\fBnamespace inscope\fR \fInamespace\fR \fIscript\fR ?\fIarg ...\fR? +\fBnamespace inscope \fInamespace script\fR ?\fIarg ...\fR? . Executes a script in the context of the specified \fInamespace\fR. This command is not expected to be used directly by programmers; @@ -232,6 +243,7 @@ is equivalent to thus additional arguments will not undergo a second round of substitution, as is the case with \fBnamespace eval\fR. .RE +.\" METHOD: origin .TP \fBnamespace origin \fIcommand\fR . @@ -247,6 +259,7 @@ this command returns the fully-qualified name of the original command in the first namespace, \fIa\fR. If \fIcommand\fR does not refer to an imported command, the command's own fully-qualified name is returned. +.\" METHOD: parent .TP \fBnamespace parent\fR ?\fInamespace\fR? . @@ -254,6 +267,7 @@ Returns the fully-qualified name of the parent namespace for namespace \fInamespace\fR. If \fInamespace\fR is not specified, the fully-qualified name of the current namespace's parent is returned. +.\" METHOD: path .TP \fBnamespace path\fR ?\fInamespaceList\fR? . @@ -263,8 +277,9 @@ current namespace's command resolution path is set to those namespaces and returns the empty list. The default command resolution path is always empty. See the section \fBNAME RESOLUTION\fR below for an explanation of the rules regarding name resolution. +.\" METHOD: qualifiers .TP -\fBnamespace qualifiers\fR \fIstring\fR +\fBnamespace qualifiers\fI string\fR . Returns any leading namespace qualifiers for \fIstring\fR. Qualifiers are namespace names separated by double colons (\fB::\fR). @@ -274,8 +289,9 @@ and for \fB::\fR it returns an empty string. This command is the complement of the \fBnamespace tail\fR command. It does not check whether the namespace names are, in fact, the names of currently defined namespaces. +.\" METHOD: tail .TP -\fBnamespace tail\fR \fIstring\fR +\fBnamespace tail\fI string\fR . Returns the simple name at the end of a qualified string. Qualifiers are namespace names separated by double colons (\fB::\fR). @@ -285,8 +301,9 @@ and for \fB::\fR it returns an empty string. This command is the complement of the \fBnamespace qualifiers\fR command. It does not check whether the namespace names are, in fact, the names of currently defined namespaces. +.\" METHOD: upvar .TP -\fBnamespace upvar\fR \fInamespace\fR ?\fIotherVar myVar \fR...? +\fBnamespace upvar\fI namespace\fR ?\fIotherVar myVar \fR...? . This command arranges for zero or more local variables in the current procedure to refer to variables in \fInamespace\fR. The namespace name is @@ -296,6 +313,7 @@ The command \fBupvar 0 ${ns}::a b\fR, with the sole exception of the resolution rules used for qualified namespace or variable names. \fBnamespace upvar\fR returns an empty string. +.\" METHOD: unknown .TP \fBnamespace unknown\fR ?\fIscript\fR? . @@ -309,6 +327,7 @@ the handler is invoked, the full invocation line will be appended to the script and the result evaluated in the context of the namespace. The default handler for all namespaces is \fB::unknown\fR. If no argument is given, it returns the handler for the current namespace. +.\" METHOD: which .TP \fBnamespace which\fR ?\fB\-command\fR? ?\fB\-variable\fR? \fIname\fR . @@ -476,8 +495,10 @@ However, if the name does not start with a \fB::\fR (i.e., is \fIrelative\fR), Tcl follows basic rules for looking it up: .IP \(bu -\fBVariable names\fR are always resolved by looking first in the current -namespace, and then in the global namespace. +\fBVariable names\fR are always resolved starting in the current +namespace. In the absence of special resolvers, foo::bar::baz refers to +a variable named "baz" in a namespace named "bar" that is a child of a +namespace named "foo" that is a child of the current namespace of the interpreter. .IP \(bu \fBCommand names\fR are always resolved by looking in the current namespace first. If not found there, they are searched for in every namespace on the @@ -497,10 +518,9 @@ set traceLevel 0 } .CE .PP -Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR -and then in the global namespace. +Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR. It looks up the command \fBprintTrace\fR in the same way. -If a variable or command name is not found in either context, +If a variable or command name is not found, the name is undefined. To make this point absolutely clear, consider the following example: .PP @@ -515,11 +535,9 @@ set traceLevel 0 } .CE .PP -Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR. -Since it is not found there, Tcl then looks for it -in the global namespace. -The variable \fBFoo::traceLevel\fR is completely ignored -during the name resolution process. +Here Tcl looks for \fBtraceLevel\fR in the namespace \fBFoo::Debug\fR. +The variables \fBFoo::traceLevel\fR and \fBFoo::Debug::traceLevel\fR +are completely ignored during the name resolution process. .PP You can use the \fBnamespace which\fR command to clear up any question about name resolution. @@ -529,19 +547,19 @@ For example, the command: \fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR -variable traceLevel} .CE .PP -returns \fB::traceLevel\fR. -On the other hand, the command, +returns the empty string. +The command, .PP .CS \fBnamespace eval\fR Foo {\fBnamespace which\fR -variable traceLevel} .CE .PP -returns \fB::Foo::traceLevel\fR. +returns the empty string as well. .PP As mentioned above, -namespace names are looked up differently -than the names of variables and commands. -Namespace names are always resolved in the current namespace. +namespace names and variables are looked up differently +than the names of commands. +Namespace names and variables are always resolved in the current namespace. This means, for example, that a \fBnamespace eval\fR command that creates a new namespace always creates a child of the current namespace @@ -729,6 +747,7 @@ namespace is deleted. The link between an ensemble command and its namespace is maintained however the ensemble is renamed. .PP Three subcommands of the \fBnamespace ensemble\fR command are defined: +.\" METHOD: create .TP \fBnamespace ensemble create\fR ?\fIoption value ...\fR? . @@ -740,6 +759,7 @@ command. If not overridden with the \fB\-command\fR option, this command creates an ensemble with exactly the same name as the linked namespace. See the section \fBENSEMBLE OPTIONS\fR below for a full list of options supported and their effects. +.\" METHOD: configure .TP \fBnamespace ensemble configure \fIcommand\fR ?\fIoption\fR? ?\fIvalue ...\fR? . @@ -747,8 +767,9 @@ Retrieves the value of an option associated with the ensemble command named \fIcommand\fR, or updates some options associated with that ensemble command. See the section \fBENSEMBLE OPTIONS\fR below for a full list of options supported and their effects. +.\" METHOD: exists .TP -\fBnamespace ensemble exists\fR \fIcommand\fR +\fBnamespace ensemble exists\fI command\fR . Returns a boolean value that describes whether the command \fIcommand\fR exists and is an ensemble command. This command only diff --git a/doc/object.n b/doc/object.n index 98679d1..2bed231 100644 --- a/doc/object.n +++ b/doc/object.n @@ -48,6 +48,7 @@ The \fBoo::object\fR class does not define an explicit constructor. The \fBoo::object\fR class does not define an explicit destructor. .SS "EXPORTED METHODS" The \fBoo::object\fR class supports the following exported methods: +.\" METHOD: destroy .TP \fIobj \fBdestroy\fR . @@ -58,12 +59,14 @@ always the empty string. .SS "NON-EXPORTED METHODS" .PP The \fBoo::object\fR class supports the following non-exported methods: +.\" METHOD: eval .TP \fIobj \fBeval\fR ?\fIarg ...\fR? . This method concatenates the arguments, \fIarg\fR, as if with \fBconcat\fR, and then evaluates the resulting script in the namespace that is uniquely associated with \fIobj\fR, returning the result of the evaluation. +.\" METHOD: unknown .TP \fIobj \fBunknown ?\fImethodName\fR? ?\fIarg ...\fR? . @@ -78,6 +81,7 @@ The default implementation (i.e., the one defined by the \fBoo::object\fR class) generates a suitable error, detailing what methods the object supports given whether the object was invoked by its public name or through the \fBmy\fR command. +.\" METHOD: variable .TP \fIobj \fBvariable \fR?\fIvarName ...\fR? . @@ -86,11 +90,13 @@ the object \fIobj\fR's unique namespace into the caller's context. Thus, if it is invoked from inside a procedure then the namespace variable in the object is linked to the local variable in the procedure. Each \fIvarName\fR argument must not have any namespace separators in it. The result is the empty string. +.\" METHOD: varname .TP \fIobj \fBvarname \fIvarName\fR . This method returns the globally qualified name of the variable \fIvarName\fR in the unique namespace for the object \fIobj\fR. +.\" METHOD: <cloned> .TP \fIobj \fB<cloned> \fIsourceObjectName\fR .VS @@ -12,12 +12,11 @@ .SH NAME open \- Open a file-based or command pipeline channel .SH SYNOPSIS -.sp +.nf \fBopen \fIfileName\fR -.br \fBopen \fIfileName access\fR -.br \fBopen \fIfileName access permissions\fR +.fi .BE .SH DESCRIPTION .PP @@ -162,7 +161,7 @@ and set additional configuration options specific to serial ports (where supported): .\" OPTION: -mode .TP -\fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR +\fB\-mode\fI baud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR . This option is a set of 4 comma-separated values: the baud rate, parity, number of data bits, and number of stop bits for this serial port. The @@ -180,7 +179,7 @@ data bits and should be an integer from 5 to 8, while \fIstop\fR is the number of stop bits and should be the integer 1 or 2. .\" OPTION: -handshake .TP -\fB\-handshake\fR \fItype\fR +\fB\-handshake\fI type\fR . (Windows and Unix). This option is used to setup automatic handshake control. Note that not all handshake types maybe supported by your operating @@ -206,7 +205,7 @@ It returns a list of two integers representing the current number of bytes in the input and output queue respectively. .\" OPTION: -timeout .TP -\fB\-timeout\fR \fImsec\fR +\fB\-timeout\fI msec\fR . (Windows and Unix). This option is used to set the timeout for blocking read operations. It specifies the maximum interval between the @@ -217,7 +216,7 @@ nonblocking reads. This option cannot be queried. .\" OPTION: -ttycontrol .TP -\fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR +\fB\-ttycontrol\fI {signal boolean signal boolean ...}\fR . (Windows and Unix). This option is used to setup the handshake output lines (see below) permanently or to send a BREAK over the serial line. @@ -241,7 +240,7 @@ e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR. The \fIsignal\fR names are returned upper case. .\" OPTION: -xchar .TP -\fB\-xchar\fR \fI{xonChar xoffChar}\fR +\fB\-xchar\fI {xonChar xoffChar}\fR . (Windows and Unix). This option is used to query or change the software handshake characters. Normally the operating system default should be @@ -249,7 +248,7 @@ DC1 (0x11) and DC3 (0x13) representing the ASCII standard XON and XOFF characters. .\" OPTION: -closemode .TP -\fB\-closemode\fR \fIcloseMode\fR +\fB\-closemode\fI closeMode\fR .VS "8.7, TIP 160" (Windows and Unix). This option is used to query or change the close mode of the serial channel, which defines how pending output in operating system @@ -270,7 +269,7 @@ been consumed. This may slow down \fBclose\fR noticeably. .VE "8.7, TIP 160" .\" OPTION: -inputmode .TP -\fB\-inputmode\fR \fIinputMode\fR +\fB\-inputmode\fI inputMode\fR .VS "8.7, TIP 160" (Unix only; Windows has the equivalent option on console channels). This option is used to query or change the input mode of the serial channel under @@ -307,7 +306,7 @@ width and height of the terminal. .VE "8.7, TIP 160" .\" OPTION: -pollinterval .TP -\fB\-pollinterval\fR \fImsec\fR +\fB\-pollinterval\fI msec\fR . (Windows only). This option is used to set the maximum time between polling for fileevents. @@ -317,9 +316,9 @@ you want to poll the serial port more or less often than 10 msec (the default). .\" OPTION: -sysbuffer .TP -\fB\-sysbuffer\fR \fIinSize\fR +\fB\-sysbuffer\fI inSize\fR .TP -\fB\-sysbuffer\fR \fI{inSize outSize}\fR +\fB\-sysbuffer\fI {inSize outSize}\fR . (Windows only). This option is used to change the size of Windows system buffers for a serial channel. Especially at higher communication @@ -468,7 +467,7 @@ On Windows only, console channels (usually \fBstdin\fR or \fBstdout\fR) support the following options: .\" OPTION: -inputmode .TP -\fB\-inputmode\fR \fIinputMode\fR +\fB\-inputmode\fI inputMode\fR . This option is used to query or change the input mode of the console channel, which controls how interactive input from users is handled. The following diff --git a/doc/package.n b/doc/package.n index bb53390..d27a44a 100644 --- a/doc/package.n +++ b/doc/package.n @@ -12,7 +12,7 @@ package \- Facilities for package loading and version control .SH SYNOPSIS .nf -\fBpackage files\fR \fIpackage\fR +\fBpackage files\fI package\fR \fBpackage forget\fR ?\fIpackage package ...\fR? \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR? \fBpackage names\fR @@ -43,19 +43,22 @@ primarily by system scripts that maintain the package database. .PP The behavior of the \fBpackage\fR command is determined by its first argument. The following forms are permitted: +.\" METHOD: files .TP -\fBpackage files\fR \fIpackage\fR +\fBpackage files \fIpackage\fR . Lists all files forming part of \fIpackage\fR. Auto-loaded files are not included in this list, only files which were directly sourced during package initialization. The list order corresponds with the order in which the files were sourced. +.\" METHOD: forget .TP \fBpackage forget\fR ?\fIpackage package ...\fR? . Removes all information about each specified package from this interpreter, including information provided by both \fBpackage ifneeded\fR and \fBpackage provide\fR. +.\" METHOD: ifneeded .TP \fBpackage ifneeded \fIpackage version\fR ?\fIscript\fR? . @@ -78,6 +81,7 @@ If the \fIscript\fR argument is omitted, the current script for version \fIversion\fR of package \fIpackage\fR is returned, or an empty string if no \fBpackage ifneeded\fR command has been invoked for this \fIpackage\fR and \fIversion\fR. +.\" METHOD: names .TP \fBpackage names\fR . @@ -86,11 +90,13 @@ interpreter for which a version has been provided (via \fBpackage provide\fR) or for which a \fBpackage ifneeded\fR script is available. The order of elements in the list is arbitrary. +.\" METHOD: present .TP \fBpackage present\fR ?\fB\-exact\fR? \fIpackage\fR ?\fIrequirement...\fR? . This command is equivalent to \fBpackage require\fR except that it does not try and load the package if it is not already loaded. +.\" METHOD: provide .TP \fBpackage provide \fIpackage \fR?\fIversion\fR? . @@ -104,6 +110,7 @@ If the \fIversion\fR argument is omitted, then the command returns the version number that is currently provided, or an empty string if no \fBpackage provide\fR command has been invoked for \fIpackage\fR in this interpreter. +.\" METHOD: require .TP \fBpackage require \fR\fIpackage \fR?\fIrequirement...\fR? . @@ -156,6 +163,7 @@ package, then the command returns an error. This form of the command is used when only the given \fIversion\fR of \fIpackage\fR is acceptable to the caller. This command is equivalent to \fBpackage require \fIpackage version\fR-\fIversion\fR. +.\" METHOD: unknown .TP \fBpackage unknown \fR?\fIcommand\fR? . @@ -178,18 +186,21 @@ argument, then the current \fBpackage unknown\fR script is returned, or an empty string if there is none. If \fIcommand\fR is specified as an empty string, then the current \fBpackage unknown\fR script is removed, if there is one. +.\" METHOD: vcompare .TP \fBpackage vcompare \fIversion1 version2\fR . Compares the two version numbers given by \fIversion1\fR and \fIversion2\fR. Returns -1 if \fIversion1\fR is an earlier version than \fIversion2\fR, 0 if they are equal, and 1 if \fIversion1\fR is later than \fIversion2\fR. +.\" METHOD: versions .TP \fBpackage versions \fIpackage\fR . Returns a list of all the version numbers of \fIpackage\fR for which information has been provided by \fBpackage ifneeded\fR commands. +.\" METHOD: vsatisfies .TP \fBpackage vsatisfies \fIversion requirement...\fR . @@ -250,8 +261,10 @@ requirement if, and only if it is greater than or equal to the .QW a0 . There is no constraint to a maximum. .RE +.\" METHOD: prefer .TP \fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR? +. With no arguments, the commands returns either .QW latest or diff --git a/doc/packagens.n b/doc/packagens.n index 6d7f624..42a0686 100644 --- a/doc/packagens.n +++ b/doc/packagens.n @@ -11,14 +11,12 @@ pkg::create \- Construct an appropriate 'package ifneeded' command for a given p .SH SYNOPSIS \fB::pkg::create\fR \fB\-name \fIpackageName \fB\-version \fIpackageVersion\fR ?\fB\-load \fIfilespec\fR? ... ?\fB\-source \fIfilespec\fR? ... .BE - .SH DESCRIPTION .PP \fB::pkg::create\fR is a utility procedure that is part of the standard Tcl library. It is used to create an appropriate \fBpackage ifneeded\fR command for a given package specification. It can be used to construct a \fBpkgIndex.tcl\fR file for use with the \fBpackage\fR mechanism. - .SH OPTIONS The parameters supported are: .\" OPTION: -name @@ -14,7 +14,6 @@ pid \- Retrieve process identifiers .SH SYNOPSIS \fBpid \fR?\fIfileId\fR? .BE - .SH DESCRIPTION .PP If the \fIfileId\fR argument is given then it should normally @@ -40,7 +39,6 @@ puts [string repeat - 70] puts [read $pipeline] close $pipeline .CE - .SH "SEE ALSO" exec(n), open(n) .SH KEYWORDS diff --git a/doc/platform.n b/doc/platform.n index 78dfc79..3ff0568 100644 --- a/doc/platform.n +++ b/doc/platform.n @@ -13,7 +13,7 @@ platform \- System identification support code and utilities .SH SYNOPSIS .nf \fBpackage require platform\fR ?\fB1.0.10\fR? -.sp + \fBplatform::generic\fR \fBplatform::identify\fR \fBplatform::patterns \fIidentifier\fR diff --git a/doc/platform_shell.n b/doc/platform_shell.n index 8844ad6..22c2ca4 100644 --- a/doc/platform_shell.n +++ b/doc/platform_shell.n @@ -13,7 +13,7 @@ platform::shell \- System identification support code and utilities .SH SYNOPSIS .nf \fBpackage require platform::shell\fR ?\fB1.1.4\fR? -.sp + \fBplatform::shell::generic \fIshell\fR \fBplatform::shell::identify \fIshell\fR \fBplatform::shell::platform \fIshell\fR diff --git a/doc/prefix.n b/doc/prefix.n index 309bfef..a2180e5 100644 --- a/doc/prefix.n +++ b/doc/prefix.n @@ -12,8 +12,8 @@ tcl::prefix \- facilities for prefix matching .SH SYNOPSIS .nf -\fB::tcl::prefix all\fR \fItable string\fR -\fB::tcl::prefix longest\fR \fItable string\fR +\fB::tcl::prefix all\fI table string\fR +\fB::tcl::prefix longest\fI table string\fR \fB::tcl::prefix match\fR ?\fIoption ...\fR? \fItable string\fR .fi .BE @@ -21,16 +21,19 @@ tcl::prefix \- facilities for prefix matching .PP This document describes commands looking up a prefix in a list of strings. The following commands are supported: +.\" METHOD: all .TP -\fB::tcl::prefix all\fR \fItable string\fR +\fB::tcl::prefix all\fI table string\fR . Returns a list of all elements in \fItable\fR that begin with the prefix \fIstring\fR. +.\" METHOD: longest .TP -\fB::tcl::prefix longest\fR \fItable string\fR +\fB::tcl::prefix longest\fI table string\fR . Returns the longest common prefix of all elements in \fItable\fR that begin with the prefix \fIstring\fR. +.\" METHOD: match .TP \fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable string\fR . diff --git a/doc/process.n b/doc/process.n index b006134..78c05ad 100644 --- a/doc/process.n +++ b/doc/process.n @@ -18,6 +18,7 @@ tcl::process \- Subprocess management This command provides a way to manage subprocesses created by the \fBopen\fR and \fBexec\fR commands, as identified by the process identifiers (PIDs) of those subprocesses. The legal \fIoptions\fR (which may be abbreviated) are: +.\" METHOD: autopurge .TP \fB::tcl::process autopurge\fR ?\fIflag\fR? . @@ -28,12 +29,14 @@ status as a boolean value. When autopurge is active, executed or a pipe channel created by \fBopen\fR is closed. When autopurge is inactive, \fB::tcl::process\fR purge must be called explicitly. By default autopurge is active. +.\" METHOD: list .TP \fB::tcl::process list\fR . Returns the list of subprocess PIDs. This includes all currently executing subprocesses and all terminated subprocesses that have not yet had their corresponding process table entries purged. +.\" METHOD: purge .TP \fB::tcl::process purge\fR ?\fIpids\fR? . @@ -41,6 +44,7 @@ Cleans up all data associated with terminated subprocesses. If \fIpids\fR is specified as a list of PIDs then the command only cleanup data for the matching subprocesses if they exist, and raises an error otherwise. If a process listed is still active, this command does nothing to that process. +.\" METHOD: status .TP \fB::tcl::process status\fR ?\fIswitches\fR? ?\fIpids\fR? . diff --git a/doc/return.n b/doc/return.n index 9bf1ae2..d285e87 100644 --- a/doc/return.n +++ b/doc/return.n @@ -78,7 +78,10 @@ were the command \fBcontinue\fR. \fIvalue\fR . \fIValue\fR must be an integer; it will be returned as the -return code for the current procedure. +return code for the current procedure. Applications +and packages should use values in the range 5 to 1073741823 (0x3fffffff) +for their own purposes. Values outside this range are reserved +for use by Tcl. .LP When a procedure wants to signal that it has received invalid arguments from its caller, it may use \fBreturn -code error\fR @@ -511,32 +511,32 @@ own value is also specified: .PP .CS safe::interpCreate foo -accessPath { - /usr/local/TclHome/lib/tcl8.7 - /usr/local/TclHome/lib/tcl8.7/http1.0 - /usr/local/TclHome/lib/tcl8.7/opt0.4 - /usr/local/TclHome/lib/tcl8.7/msgs - /usr/local/TclHome/lib/tcl8.7/encoding + /usr/local/TclHome/lib/tcl9.0 + /usr/local/TclHome/lib/tcl9.0/http1.0 + /usr/local/TclHome/lib/tcl9.0/opt0.4 + /usr/local/TclHome/lib/tcl9.0/msgs + /usr/local/TclHome/lib/tcl9.0/encoding /usr/local/TclHome/lib } # The child's ::auto_path must be given a suitable value: safe::interpConfigure foo -autoPath { - /usr/local/TclHome/lib/tcl8.7 + /usr/local/TclHome/lib/tcl9.0 /usr/local/TclHome/lib } # The two commands can be combined: safe::interpCreate foo -accessPath { - /usr/local/TclHome/lib/tcl8.7 - /usr/local/TclHome/lib/tcl8.7/http1.0 - /usr/local/TclHome/lib/tcl8.7/opt0.4 - /usr/local/TclHome/lib/tcl8.7/msgs - /usr/local/TclHome/lib/tcl8.7/encoding + /usr/local/TclHome/lib/tcl9.0 + /usr/local/TclHome/lib/tcl9.0/http1.0 + /usr/local/TclHome/lib/tcl9.0/opt0.4 + /usr/local/TclHome/lib/tcl9.0/msgs + /usr/local/TclHome/lib/tcl9.0/encoding /usr/local/TclHome/lib } -autoPath { - /usr/local/TclHome/lib/tcl8.7 + /usr/local/TclHome/lib/tcl9.0 /usr/local/TclHome/lib } .CE @@ -74,19 +74,17 @@ one of Tcl's integer values. The size modifier field dictates the integer range acceptable to be stored in a variable, or, for the inline case, in a position in the result list. The syntactically valid values for the size modifier are \fBh\fR, -\fBl\fR, \fBq\fR, \fBj\fR, \fBz\fR, \fBt\fR, \fBll\fR, and \fBL\fR. +\fBl\fR, \fBz\fR, \fBt\fR, \fBq\fR, \fBj\fR, \fBll\fR, and \fBL\fR. The \fBh\fR size modifier value is equivalent to the absence of a size modifier in the the conversion specifier. Either one indicates the -integer range to be stored is limited to the range determined by the -value of the \fBwordSize\fR element of the \fBtcl_platform\fR array). -The \fBL\fR, \fBq\fR or \fBj\fR size modifiers are equivalent to the -\fBl\fR size modifier. Either of them indicates the integer range to -be stored is limited to the same range produced by the \fBwide()\fR -function of the \fBexpr\fR command. The \fBll\fR size modifier -indicates that the integer range to be stored is unlimited. -The \fBz\fR and \fBt\fR modifiers indicate the integer range to be -the same as for either \fBh\fR or \fBl\fR, depending on the -value of the \fBpointerSize\fR element of the \fBtcl_platform\fR array. +integer range to be stored is limited to the 32-bit range. The \fBL\fR +size modifier is equivalent to the \fBll\fR size modifier. Either one +indicates the integer range to be stored is unlimited. The \fBl\fR (or +\fBq\fR or \fBj\fR) size modifier indicates that the integer range to be +stored is limited to the same range produced by the \fBwide()\fR function +of the \fBexpr\fR command. The \fBz\fR and \fBt\fR modifiers indicate the +integer range to be the same as for either \fBh\fR or \fBl\fR, depending +on the value of the \fBpointerSize\fR element of the \fBtcl_platform\fR array. .SS "MANDATORY CONVERSION CHARACTER" .PP The following conversion characters are supported: @@ -204,12 +202,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" } @@ -253,8 +249,6 @@ An interactive session demonstrating the truncation of integer values determined by size modifiers: .PP .CS -\fI%\fR set tcl_platform(wordSize) -4 \fI%\fR scan 20000000000000000000 %d 2147483647 \fI%\fR scan 20000000000000000000 %ld diff --git a/doc/socket.n b/doc/socket.n index 06d3b5b..623fac6 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -261,8 +261,6 @@ close $sockChan puts "The time on $server is $line1" puts "That is [lindex $line2 0]s since the server started" .CE -.SH "HISTORY" -Support for IPv6 was added in Tcl 8.6. .SH "SEE ALSO" chan(n), flush(n), open(n), read(n) .SH KEYWORDS diff --git a/doc/source.n b/doc/source.n index a26507d..d4d8332 100644 --- a/doc/source.n +++ b/doc/source.n @@ -15,7 +15,7 @@ source \- Evaluate a file or resource as a Tcl script .SH SYNOPSIS \fBsource \fIfileName\fR .sp -\fBsource\fR \fB\-encoding \fIencoding fileName\fR +\fBsource\fR \fB\-encoding \fIencodingName fileName\fR .BE .SH DESCRIPTION .PP diff --git a/doc/string.n b/doc/string.n index 27d0d08..480f3ce 100644 --- a/doc/string.n +++ b/doc/string.n @@ -402,47 +402,6 @@ 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. -.\" METHOD: bytelength -.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 -.RE .\" METHOD: wordend .TP \fBstring wordend \fIstring charIndex\fR diff --git a/doc/tclvars.n b/doc/tclvars.n index 6d091c6..04cbc6c 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 @@ -31,6 +31,10 @@ the parent directory of \fBtcl_library\fR, the directories listed in the \fBtcl_pkgPath\fR variable. Additional locations to look for files and package indices should normally be added to this variable using \fBlappend\fR. +Initialization of auto_path from the TCLLIBPATH environment +variable undergoes tilde substitution (see \fBfilename\fR) on each +path. Any tilde substitution that fails because the user is unknown +will be omitted from auto_path. .RS .PP Additional variables relating to package management exist. More @@ -75,11 +79,11 @@ The following elements of \fBenv\fR are special to Tcl: \fBenv(HOME)\fR . This environment variable, if set, gives the location of the directory -considered to be the current user's home directory, and to which a -call of \fBcd\fR without arguments or with just -.QW ~ -as an argument will change into. Most platforms set this correctly by -default; it does not normally need to be set by user code. +considered to be the current user's home directory. The value of this variable +is returned by the \fBfile home\fR command. Most platforms set this correctly by +default; it does not normally need to be set by user code. On Windows, if not +already set, it is set to the value of the \fBUSERPROFILE\fR environment +variable. .TP \fBenv(TCL_LIBRARY)\fR . @@ -338,71 +342,6 @@ and the value from the GetUserName() system call on Windows. 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 -.\" VARIABLE: tcl_rcFileName -.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. .\" VARIABLE: tcl_traceCompile .TP \fBtcl_traceCompile\fR diff --git a/doc/timerate.n b/doc/timerate.n index a334d81..0207fd8 100644 --- a/doc/timerate.n +++ b/doc/timerate.n @@ -13,9 +13,7 @@ timerate \- Calibrated performance measurements of script execution time .SH SYNOPSIS .nf \fBtimerate \fIscript\fR ?\fItime\fR? ?\fImax-count\fR? -.sp \fBtimerate \fR?\fB\-direct\fR? ?\fB\-overhead\fI estimate\fR? \fIscript\fR ?\fItime\fR? ?\fImax-count\fR? -.sp \fBtimerate \fR?\fB\-calibrate\fR? ?\fB\-direct\fR? \fIscript\fR ?\fItime\fR? ?\fImax-count\fR? .fi .BE @@ -300,6 +300,10 @@ environment variables: \fB$::env(TCL8.1_TM_PATH)\fR \fB$::env(TCL8_1_TM_PATH)\fR \fB$::env(TCL8.0_TM_PATH)\fR \fB$::env(TCL8_0_TM_PATH)\fR .CE +.PP +Paths initialized from the environment variables undergo tilde +substitution (see \fBfilename\fR). Any path whose tilde substitution +fails because the user is unknown will be omitted from search paths. .SH "SEE ALSO" package(n), Tcl Improvement Proposal #189 .QW "\fITcl Modules\fR" diff --git a/doc/trace.n b/doc/trace.n index 3435585..6eba974 100644 --- a/doc/trace.n +++ b/doc/trace.n @@ -238,18 +238,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 add 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 add 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. @@ -375,26 +375,6 @@ associated with the trace. If \fIname\fR does not exist or does not have any traces set, then the result of the command will be an empty string. .RE -.PP -For backwards compatibility, three other subcommands are available: -.RS -.TP -\fBtrace variable \fIname ops command\fR -This is equivalent to \fBtrace add variable \fIname ops command\fR. -.TP -\fBtrace vdelete \fIname ops command\fR -This is equivalent to \fBtrace remove variable \fIname ops command\fR -.TP -\fBtrace vinfo \fIname\fR -This is equivalent to \fBtrace info variable \fIname\fR -.RE -.PP -These subcommands are deprecated and will likely be removed in a -future version of Tcl. They use an older syntax in which \fBarray\fR, -\fBread\fR, \fBwrite\fR, \fBunset\fR are replaced by \fBa\fR, \fBr\fR, -\fBw\fR and \fBu\fR respectively, and the \fIops\fR argument is not a -list, but simply a string concatenation of the operations, such as -\fBrwua\fR. .SH EXAMPLES .PP Print a message whenever either of the global variables \fBfoo\fR and diff --git a/doc/unload.n b/doc/unload.n index dfa823b..fdc3555 100644 --- a/doc/unload.n +++ b/doc/unload.n @@ -126,8 +126,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 79f7605..6543be8 100644 --- a/doc/upvar.n +++ b/doc/upvar.n @@ -97,11 +97,9 @@ trace add variable originalVar write \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 31af7d7..c15ba02 100644 --- a/doc/zipfs.3 +++ b/doc/zipfs.3 @@ -86,7 +86,7 @@ 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 with build -information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\fR). +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. |