diff options
Diffstat (limited to 'doc')
69 files changed, 1067 insertions, 228 deletions
diff --git a/doc/Access.3 b/doc/Access.3 index 699d7ed..5a29ec2 100644 --- a/doc/Access.3 +++ b/doc/Access.3 @@ -20,7 +20,7 @@ int \fBTcl_Stat\fR(\fIpath\fR, \fIstatPtr\fR) .SH ARGUMENTS .AS "struct stat" *statPtr out -.AP char *path in +.AP "const char" *path in Native name of the file to check the attributes of. .AP int mode in Mask consisting of one or more of \fBR_OK\fR, \fBW_OK\fR, \fBX_OK\fR and diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 5b0fe5a..53f134a 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -49,7 +49,7 @@ Interpreter in which to record information. The code returned from script evaluation. .AP Tcl_Obj *options A dictionary of return options. -.AP char *message in +.AP "const char" *message in For \fBTcl_AddErrorInfo\fR, this is a conventional C string to append to the \fB\-errorinfo\fR return option. For \fBTcl_AddObjErrorInfo\fR, @@ -66,7 +66,7 @@ appending to the \fB\-errorinfo\fR return option. If negative, all bytes up to the first null byte are used. .AP Tcl_Obj *errorObjPtr in The \fB\-errorcode\fR return option will be set to this value. -.AP char *element in +.AP "const char" *element in String to record as one element of the \fB\-errorcode\fR return option. Last \fIelement\fR argument must be NULL. .AP va_list argList in @@ -308,6 +308,22 @@ The global variables \fBerrorInfo\fR and \fBerrorCode\fR are not modified by \fBTcl_ResetResult\fR so they continue to hold a record of information about the most recent error seen in an interpreter. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The result of \fBTcl_GetReturnOptions\fR will have at least one +reference to it from the Tcl interpreter. If not using it immediately, +you should use \fBTcl_IncrRefCount\fR to add your own reference. +.PP +The \fIoptions\fR argument to \fBTcl_SetReturnOptions\fR will have a +reference added by the Tcl interpreter; it may safely be called with a +zero-reference value. +.PP +\fBTcl_AppendObjToErrorInfo\fR only reads its \fIobjPtr\fR argument; +it does not modify its reference count at all. +.PP +The \fIerrorObjPtr\fR argument to \fBTcl_SetObjErrorCode\fR will have a +reference added by the Tcl interpreter; it may safely be called with a +zero-reference value. .SH "SEE ALSO" Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_Interp(3), Tcl_ResetResult(3), Tcl_SetErrno(3), errorCode(n), errorInfo(n) diff --git a/doc/Alloc.3 b/doc/Alloc.3 index 8f25c52..70b0f7d 100644 --- a/doc/Alloc.3 +++ b/doc/Alloc.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory +Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetMemoryInfo, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -28,6 +28,9 @@ char * char * \fBTcl_AttemptRealloc\fR(\fIptr, size\fR) .sp +void +\fBTcl_GetMemoryInfo\fR(\fIdsPtr\fR) +.sp char * \fBckalloc\fR(\fIsize\fR) .sp @@ -48,6 +51,8 @@ char * Size in bytes of the memory block to allocate. .AP char *ptr in Pointer to memory block to free or realloc. +.AP Tcl_DString *dsPtr in +Initialized DString pointer. .BE .SH DESCRIPTION @@ -88,5 +93,9 @@ 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. +\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. + .SH KEYWORDS alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG diff --git a/doc/Async.3 b/doc/Async.3 index 347ba3d..e6ec5f8 100644 --- a/doc/Async.3 +++ b/doc/Async.3 @@ -9,7 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events +Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncMarkFromSignal, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -17,11 +17,16 @@ Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady Tcl_AsyncHandler \fBTcl_AsyncCreate\fR(\fIproc, clientData\fR) .sp +void \fBTcl_AsyncMark\fR(\fIasync\fR) .sp int +\fBTcl_AsyncMarkFromSignal\fR(\fIasync\fR, \fIsigNumber\fR) +.sp +int \fBTcl_AsyncInvoke\fR(\fIinterp, code\fR) .sp +void \fBTcl_AsyncDelete\fR(\fIasync\fR) .sp int @@ -34,6 +39,8 @@ Procedure to invoke to handle an asynchronous event. One-word value to pass to \fIproc\fR. .AP Tcl_AsyncHandler async in Token for asynchronous event handler. +.AP int sigNumber in +POSIX signal number, when used in a signal context. .AP Tcl_Interp *interp in Tcl interpreter in which command was being evaluated when handler was invoked, or NULL if handler was invoked when there was no interpreter @@ -60,10 +67,11 @@ to a clean state, such as after the current Tcl command completes. .PP \fBTcl_AsyncCreate\fR, \fBTcl_AsyncDelete\fR, and \fBTcl_AsyncReady\fR are thread sensitive. They access and/or set a thread-specific data -structure in the event of a core built with \fI\-\-enable\-threads\fR. The token -created by \fBTcl_AsyncCreate\fR contains the needed thread information it -was called from so that calling \fBTcl_AsyncMark\fR(\fItoken\fR) will only yield -the origin thread into the asynchronous handler. +structure in the event of a core built with \fI\-\-enable\-threads\fR. +The token created by \fBTcl_AsyncCreate\fR contains the needed thread +information it was called from so that calling \fBTcl_AsyncMarkFromSignal\fR +or \fBTcl_AsyncMark\fR with this token will only yield the origin +thread into the asynchronous handler. .PP \fBTcl_AsyncCreate\fR creates an asynchronous handler and returns a token for it. @@ -72,13 +80,16 @@ any occurrences of the asynchronous event that it is intended to handle (it is not safe to create a handler at the time of an event). When an asynchronous event occurs the code that detects the event -(such as a signal handler) should call \fBTcl_AsyncMark\fR with the -token for the handler. -\fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it -will not invoke the handler immediately. -Tcl will call the \fIproc\fR associated with the handler later, when -the world is in a safe state, and \fIproc\fR can then carry out -the actions associated with the asynchronous event. +(such as a POSIX signal handler) should call \fBTcl_AsyncMarkFromSignal\fR +with the token for the handler and the POSIX signal number. The +return value of this function is true, when the handler will be +marked, false otherwise. +For non-signal contexts, \fBTcl_AsyncMark\fR serves the same purpose. +\fBTcl_AsyncMarkFromSignal\fR and \fBTcl_AsyncMark\fR will mark +the handler as ready to execute, but will not invoke the handler +immediately. Tcl will call the \fIproc\fR associated with the +handler later, when the world is in a safe state, and \fIproc\fR +can then carry out the actions associated with the asynchronous event. \fIProc\fR should have arguments and result that match the type \fBTcl_AsyncProc\fR: .PP diff --git a/doc/Backslash.3 b/doc/Backslash.3 index 0805f8e..1a807f6 100644 --- a/doc/Backslash.3 +++ b/doc/Backslash.3 @@ -18,7 +18,7 @@ char \fBTcl_Backslash\fR(\fIsrc, countPtr\fR) .SH ARGUMENTS .AS char *countPtr out -.AP char *src in +.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 diff --git a/doc/BoolObj.3 b/doc/BoolObj.3 index 7268e1f..9bbdc7e 100644 --- a/doc/BoolObj.3 +++ b/doc/BoolObj.3 @@ -88,6 +88,18 @@ will lead to a \fBTCL_OK\fR return (and the boolean value 1), while the same value passed to \fBTcl_GetBoolean\fR will lead to a \fBTCL_ERROR\fR return. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewBooleanObj\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_SetBooleanObj\fR does not modify the reference count of its +\fIobjPtr\fR argument, but does require that the object be unshared. +.PP +\fBTcl_GetBooleanFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. Note however that this function +may set the interpreter result; if that is the only place that +is holding a reference to the object, it will be deleted. .SH "SEE ALSO" Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3 index 09400c8..2a7d7a3 100644 --- a/doc/ByteArrObj.3 +++ b/doc/ByteArrObj.3 @@ -85,6 +85,18 @@ newly allocated bytes at the end of the array have arbitrary values. If the length of array is reduced to the new length. The return value is a pointer to the value's new array of bytes. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_SetByteArrayObj\fR and \fBTcl_SetByteArrayLength\fR do not modify the +reference count of their \fIobjPtr\fR arguments, but do require that the +object be unshared. +.PP +\fBTcl_GetByteArrayFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. + .SH "SEE ALSO" Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount diff --git a/doc/Cancel.3 b/doc/Cancel.3 index 847707e..73edaf6 100644 --- a/doc/Cancel.3 +++ b/doc/Cancel.3 @@ -67,6 +67,14 @@ other procedures. If an error is returned and this bit is set in result, where it can be retrieved with \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR. If this flag bit is not set then no error message is left and the interpreter's result will not be modified. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_CancelEval\fR always decrements the reference count of its +\fIresultObjPtr\fR argument (if that is non-NULL). It is expected to +be usually called with an object with zero reference count. If the +object is shared with some other location (including the Tcl +evaluation stack) it should have its reference count incremented +before calling this function. .SH "SEE ALSO" interp(n), Tcl_Eval(3), TIP 285 diff --git a/doc/Class.3 b/doc/Class.3 index 57203d5..5f8e061 100644 --- a/doc/Class.3 +++ b/doc/Class.3 @@ -241,6 +241,29 @@ NULL if the whole chain is to be processed (the argument itself is never NULL); this variable may be updated by the callback. The \fImethodNameObj\fR parameter gives an unshared object containing the name of the method being invoked, as provided by the user; this object may be updated by the callback. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjPtr\fR argument to \fBTcl_GetObjectFromObj\fR will not have its +reference count manipulated, but this function may modify the interpreter +result (to report any error) so interpreter results should not be fed into +this without an additional reference being used. +.PP +The result of \fBTcl_GetObjectName\fR is a value that is owned by the object +that is regenerated when this function is first called after the object is +renamed. If the value is to be retained at all, the caller should increment +the reference count. +.PP +The first \fIobjc\fR values in the \fIobjv\fR argument to +\fBTcl_NewObjectInstance\fR are the arguments to pass to the constructor. They +must have a reference count of at least 1, and may have their reference counts +changed during the running of the constructor. Constructors may modify the +interpreter result, which consequently means that interpreter results should +not be used as arguments without an additional reference being taken. +.PP +The \fImethodNameObj\fR argument to a Tcl_ObjectMapMethodNameProc +implementation will be a value with a reference count of at least 1 where at +least one reference is not held by the interpreter result. It is expected that +method name mappers will only read their \fImethodNameObj\fR arguments. .SH "SEE ALSO" Method(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n) .SH KEYWORDS diff --git a/doc/CrtAlias.3 b/doc/CrtAlias.3 index 92f9b0c..2623dcd 100644 --- a/doc/CrtAlias.3 +++ b/doc/CrtAlias.3 @@ -243,8 +243,16 @@ any script evaluation mechanism will fail. .PP For a description of the Tcl interface to multiple interpreters, see \fIinterp(n)\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_CreateAliasObj\fR increments the reference counts of the values +in its \fIobjv\fR argument. (That reference lasts the same length of +time as the owning alias.) +.PP +\fBTcl_GetAliasObj\fR returns (via its \fIobjvPtr\fR argument) a +pointer to values that it holds a reference to. .SH "SEE ALSO" -interp +interp(n) .SH KEYWORDS alias, command, exposed commands, hidden commands, interpreter, invoke, diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3 index acceb5b..bb96fc9 100644 --- a/doc/CrtMathFnc.3 +++ b/doc/CrtMathFnc.3 @@ -156,6 +156,10 @@ pointed to by \fIargTypesPointer\fR. \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 diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index 2cd9222..f15e277 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -54,7 +54,7 @@ const char * .AS Tcl_CmdDeleteProc *deleteProc in/out .AP Tcl_Interp *interp in Interpreter in which to create a new command or that contains a command. -.AP char *cmdName in +.AP "const char" *cmdName in Name of command. .AP Tcl_ObjCmdProc *proc in Implementation of the new command: \fIproc\fR will be called whenever @@ -323,6 +323,21 @@ instead. The result from \fBTcl_GetCommandTypeName\fR will be exactly that string which was registered, and not a copy; use of a compile-time constant string is \fIstrongly recommended\fR. .VE "info cmdtype feature" +.SH "REFERENCE COUNT MANAGEMENT" +.PP +When the \fIproc\fR passed to \fBTcl_CreateObjCommand\fR is called, +the values in its \fIobjv\fR argument will have a reference count of +at least 1, with that guaranteed reference being from the Tcl +evaluation stack. You should not call \fBTcl_DecrRefCount\fR on any of +those values unless you call \fBTcl_IncrRefCount\fR on them first. +Also, when the \fIproc\fR is called, the interpreter result is +guaranteed to be an empty string value with a reference count of 1. +.PP +\fBTcl_GetCommandFullName\fR does not modify the reference count of its +\fIobjPtr\fR argument, but does require that the object be unshared. +.PP +\fBTcl_GetCommandFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3) .SH KEYWORDS diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3 index b1e6483..bf8587d 100644 --- a/doc/CrtTrace.3 +++ b/doc/CrtTrace.3 @@ -187,5 +187,14 @@ There is no way to be notified when the trace created by \fBTcl_CreateTrace\fR is deleted. There is no way for the \fIproc\fR associated with a call to \fBTcl_CreateTrace\fR to abort execution of \fIcommand\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +When the \fIproc\fR passed to \fBTcl_CreateObjTrace\fR is called, +the values in its \fIobjv\fR argument will have a reference count of +at least 1, with that guaranteed reference being from the Tcl +evaluation stack. You should not call \fBTcl_DecrRefCount\fR on any of +those values unless you call \fBTcl_IncrRefCount\fR on them first. +.SH "SEE ALSO" +trace(n) .SH KEYWORDS command, create, delete, interpreter, trace diff --git a/doc/DictObj.3 b/doc/DictObj.3 index 2c111c4..0b4c1ca 100644 --- a/doc/DictObj.3 +++ b/doc/DictObj.3 @@ -190,6 +190,73 @@ path as this is easy to construct from repeated use of dictionaries are created for non-terminal keys where they do not already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal keys must exist and have dictionaries as their values. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewDictObj\fR always returns a zero-reference object, much like +\fBTcl_NewObj\fR. +.PP +\fBTcl_DictObjPut\fR does not modify the reference count of its \fIdictPtr\fR +argument, but does require that the object be unshared. If +\fBTcl_DictObjPut\fR returns \fBTCL_ERROR\fR it does not manipulate any +reference counts; but if it returns \fBTCL_OK\fR then it definitely increments +the reference count of \fIvaluePtr\fR and may increment the reference count of +\fIkeyPtr\fR; the latter case happens exactly when the key did not previously +exist in the dictionary. Note however that this function may set the +interpreter result; if that is the only place that is holding a reference to +an object, it will be deleted. +.PP +\fBTcl_DictObjGet\fR only reads from its \fIdictPtr\fR and \fIkeyPtr\fR +arguments, and does not manipulate their reference counts at all. If the +\fIvaluePtrPtr\fR argument is not set to NULL (and the function doesn't return +\fBTCL_ERROR\fR), it will be set to a value with a reference count of at least +1, with a reference owned by the dictionary. Note however that this function +may set the interpreter result; if that is the only place that is holding a +reference to an object, it will be deleted. +.PP +\fBTcl_DictObjRemove\fR does not modify the reference count of its +\fIdictPtr\fR argument, but does require that the object be unshared. It does +not manipulate the reference count of its \fIkeyPtr\fR argument at all. Note +however that this function may set the interpreter result; if that is the only +place that is holding a reference to an object, it will be deleted. +.PP +\fBTcl_DictObjSize\fR does not modify the reference count of its \fIdictPtr\fR +argument; it only reads. Note however that this function may set the +interpreter result; if that is the only place that is holding a reference to +the dictionary object, it will be deleted. +.PP +\fBTcl_DictObjFirst\fR does not modify the reference count of its +\fIdictPtr\fR argument; it only reads. The variables given by the +\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated +to contain references to the relevant values in the dictionary; their +reference counts will be at least 1 (due to the dictionary holding a reference +to them). It may also manipulate internal references; these are not exposed to +user code, but require a matching \fBTcl_DictObjDone\fR call. Note however +that this function may set the interpreter result; if that is the only place +that is holding a reference to the dictionary object, it will be deleted. +.PP +Similarly for \fBTcl_DictObjNext\fR; the variables given by the +\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated +to contain references to the relevant values in the dictionary; their +reference counts will be at least 1 (due to the dictionary holding a reference +to them). +.PP +\fBTcl_DictObjDone\fR does not manipulate (user-visible) reference counts. +.PP +\fBTcl_DictObjPutKeyList\fR is similar to \fBTcl_DictObjPut\fR; it does not +modify the reference count of its \fIdictPtr\fR argument, but does require +that the object be unshared. It may increment the reference count of any value +passed in the \fIkeyv\fR argument, and will increment the reference count of +the \fIvaluePtr\fR argument on success. It is recommended that values passed +via \fIkeyv\fR and \fIvaluePtr\fR do not have zero reference counts. Note +however that this function may set the interpreter result; if that is the only +place that is holding a reference to an object, it will be deleted. +.PP +\fBTcl_DictObjRemoveKeyList\fR is similar to \fBTcl_DictObjRemove\fR; it does +not modify the reference count of its \fIdictPtr\fR argument, but does require +that the object be unshared, and does not modify the reference counts of any +of the values passed in the \fIkeyv\fR argument. Note however that this +function may set the interpreter result; if that is the only place that is +holding a reference to an object, it will be deleted. .SH EXAMPLE Using the dictionary iteration interface to search determine if there is a key that maps to itself: diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3 index 85e4de5..c70f5d1 100644 --- a/doc/DoubleObj.3 +++ b/doc/DoubleObj.3 @@ -58,6 +58,18 @@ and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR. The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent calls to \fBTcl_GetDoubleFromObj\fR more efficient. '\" TODO: add discussion of treatment of NaN value +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewDoubleObj\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_SetDoubleObj\fR does not modify the reference count of its +\fIobjPtr\fR argument, but does require that the object be unshared. +.PP +\fBTcl_GetDoubleFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. Note however that this function +may set the interpreter result; if that is the only place that +is holding a reference to the object, it will be deleted. .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult .SH KEYWORDS diff --git a/doc/Encoding.3 b/doc/Encoding.3 index 2d2461e..c68070c 100644 --- a/doc/Encoding.3 +++ b/doc/Encoding.3 @@ -556,5 +556,16 @@ been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR from the \fBencoding\fR subdirectory of each directory that Tcl searches for its script library. If the encoding file exists, but is malformed, an error message will be left in \fIinterp\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_GetEncodingFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. Note however that this function may set +the interpreter result; if that is the only place that is holding a reference +to the object, it will be deleted. +.PP +\fBTcl_GetEncodingSearchPath\fR returns an object with a reference count of at +least 1. +.SH "SEE ALSO" +encoding(n) .SH KEYWORDS utf, encoding, convert diff --git a/doc/Ensemble.3 b/doc/Ensemble.3 index febc48f..b768fd6 100644 --- a/doc/Ensemble.3 +++ b/doc/Ensemble.3 @@ -209,6 +209,27 @@ namespace whose list of exported commands is used if both the mapping dictionary and the subcommand list properties are NULL. May be read using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code (\fBTCL_OK\fR, or \fBTCL_ERROR\fR if the token does not refer to an ensemble). +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_FindEnsemble\fR does not modify the reference count of its +\fIcmdNameObj\fR argument; it only reads. Note however that this function may +set the interpreter result; if that is the only place that is holding a +reference to the object, it will be deleted. +.PP +The ensemble property getters (\fBTcl_GetEnsembleMappingDict\fR, +\fBTcl_GetEnsembleParameterList\fR, \fBTcl_GetEnsembleSubcommandList\fR, and +\fBTcl_GetEnsembleUnknownHandler\fR) do not manipulate the reference count of +the values they provide out; if those are non-NULL, they will have a reference +count of at least 1. Note that these functions may set the interpreter +result. +.PP +The ensemble property setters (\fBTcl_SetEnsembleMappingDict\fR, +\fBTcl_SetEnsembleParameterList\fR, \fBTcl_SetEnsembleSubcommandList\fR, and +\fBTcl_SetEnsembleUnknownHandler\fR) will increment the reference count of the +new value of the property they are given if they succeed (and decrement the +reference count of the old value of the property, if relevant). If the +property setters return \fBTCL_ERROR\fR, the reference count of the Tcl_Obj +argument is left unchanged. .SH "SEE ALSO" namespace(n), Tcl_DeleteCommandFromToken(3) .SH KEYWORDS @@ -65,7 +65,7 @@ null terminating character. If \-1, then all characters up to the first null byte are used. .AP "const char" *script in Points to first byte of script to execute (null-terminated and UTF-8). -.AP char *part in +.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 @@ -207,6 +207,20 @@ the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was invoked in an inappropriate place. This means that top-level applications should never see a return code from \fBTcl_EvalObjEx\fR other than \fBTCL_OK\fR or \fBTCL_ERROR\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_EvalObjEx\fR and \fBTcl_GlobalEvalObj\fR both increment and +decrement the reference count of their \fIobjPtr\fR argument; you must +not pass them any value with a reference count of zero. They also +manipulate the interpreter result; you must not count on the +interpreter result to hold the reference count of any value over +these calls. +.PP +\fBTcl_EvalObjv\fR may increment and decrement the reference count of +any value passed via its \fIobjv\fR argument; you must not pass any +value with a reference count of zero. This function also manipulates +the interpreter result; you must not count on the interpreter result +to hold the reference count of any value over this call. .SH KEYWORDS execute, file, global, result, script, value diff --git a/doc/ExprLongObj.3 b/doc/ExprLongObj.3 index 837e0a8..59413e1 100644 --- a/doc/ExprLongObj.3 +++ b/doc/ExprLongObj.3 @@ -98,6 +98,15 @@ containing the expression's value at \fI*resultPtrPtr\fR. In this case, the caller is responsible for calling \fBTcl_DecrRefCount\fR to decrement the value's reference count when it is finished with the value. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR, +\fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprObj\fR all increment and +decrement the reference count of their \fIobjPtr\fR arguments; you +must not pass them any value with a reference count of zero. They also +manipulate the interpreter result; you must not count on the +interpreter result to hold the reference count of any value over these +calls. .SH "SEE ALSO" Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index 4583b22..4951ec5 100644 --- a/doc/FileSystem.3 +++ b/doc/FileSystem.3 @@ -45,7 +45,7 @@ int \fBTcl_FSDeleteFile\fR(\fIpathPtr\fR) .sp int -\fBTcl_FSRemoveDirectory\fR(\fIpathPtr, int recursive, errorPtr\fR) +\fBTcl_FSRemoveDirectory\fR(\fIpathPtr, recursive, errorPtr\fR) .sp int \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR) @@ -79,10 +79,10 @@ int \fBTcl_FSUtime\fR(\fIpathPtr, tval\fR) .sp int -\fBTcl_FSFileAttrsGet\fR(\fIinterp, int index, pathPtr, objPtrRef\fR) +\fBTcl_FSFileAttrsGet\fR(\fIinterp, index, pathPtr, objPtrRef\fR) .sp int -\fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR) +\fBTcl_FSFileAttrsSet\fR(\fIinterp, index, pathPtr, objPtr\fR) .sp const char *const * \fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR) @@ -197,6 +197,8 @@ rename operation. .AP Tcl_Obj *destPathPtr in As for \fIpathPtr\fR, but used for the destination filename for a copy or rename operation. +.AP int recursive in +Whether to remove subdirectories and their contents as well. .AP "const char" *encodingName in The encoding of the data stored in the file identified by \fIpathPtr\fR and to be evaluated. @@ -224,6 +226,10 @@ 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 the file which caused an error in the various copy/rename operations. +.AP int index in +The index of the attribute in question. +.AP Tcl_Obj *objPtr in +The value to set in the operation. .AP Tcl_Obj **objPtrRef out Filled with a value containing the result of the operation. .AP Tcl_Obj *resultPtr out @@ -241,9 +247,9 @@ The structure that contains the result of a stat or lstat operation. Name of a procedure to look up in the file's symbol table .AP "const char" *sym2 in Name of a procedure to look up in the file's symbol table -.AP Tcl_PackageInitProc **proc1Ptr out +.AP Tcl_LibraryInitProc **proc1Ptr out Filled with the init function for this code. -.AP Tcl_PackageInitProc **proc2Ptr out +.AP Tcl_LibraryInitProc **proc2Ptr out Filled with the safe-init function for this code. .AP ClientData *clientDataPtr out Filled with the clientData value to pass to this code's unload @@ -1628,6 +1634,158 @@ typedef int \fBTcl_FSChdirProc\fR( The \fBTcl_FSChdirProc\fR changes the applications current working directory to the value specified in \fIpathPtr\fR. The function returns -1 on error or 0 on success. +.SH "REFERENCE COUNT MANAGEMENT" +.SS "PUBLIC API CALLS" +.PP +For all of these functions, \fIpathPtr\fR (including the \fIsrcPathPtr\fR and +\fIdestPathPtr\fR arguments to \fBTcl_FSCopyFile\fR, +\fBTcl_FSCopyDirectory\fR, and \fBTcl_FSRenameFile\fR, the \fIfirstPtr\fR and +\fIsecondPtr\fR arguments to \fBTcl_FSEqualPaths\fR, and the \fIlinkNamePtr\fR +and \fItoPtr\fR arguments to \fBTcl_FSLink\fR) must not be a zero reference +count value; references may be retained in internal caches even for +theoretically read-only operations. These functions may also manipulate the +interpreter result (if they take and are given a non-NULL \fIinterp\fR +argument); you must not count on the interpreter result to hold the reference +count of any argument value over these calls and should manage your own +references there. However, references held by the arguments to a Tcl command +\fIare\fR suitable for reference count management purposes for the duration of +the implementation of that command. +.PP +The \fIerrorPtr\fR argument to \fBTcl_FSCopyDirectory\fR and +\fBTcl_FSRemoveDirectory\fR is, when an object is set into it at all, set to +an object with a non-zero reference count that should be passed to +\fBTcl_DecrRefCount\fR when no longer needed. +.PP +\fBTcl_FSListVolumes\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_FSLink\fR always returns a non-zero-reference object when it is +asked to read; you must call \fBTcl_DecrRefCount\fR on the object +once you no longer need it. +.PP +\fBTcl_FSGetCwd\fR always returns a non-zero-reference object; you +must call \fBTcl_DecrRefCount\fR on the object once you no longer need +it. +.PP +\fBTcl_FSPathSeparator\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_FSJoinPath\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. Its \fIlistObj\fR argument can have any reference +count; it is only read by this function. +.PP +\fBTcl_FSSplitPath\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_FSGetNormalizedPath\fR returns an object with a non-zero +reference count where Tcl is the owner. You should increment its +reference count if you want to retain it, but do not need to if you +are just using the value immediately. +.PP +\fBTcl_FSJoinToPath\fR always returns a zero-reference object, much like +\fBTcl_NewObj\fR. Its \fIbasePtr\fR argument follows the rules above for +\fIpathPtr\fR, as do the values in the \fIobjv\fR argument. +.PP +\fBTcl_FSGetTranslatedPath\fR returns a non-zero-reference object (or +NULL in the error case); you must call \fBTcl_DecrRefCount\fR on the +object once you no longer need it. +.PP +\fBTcl_FSNewNativePath\fR always returns a zero-reference object (or +NULL), much like \fBTcl_NewObj\fR. +.PP +\fBTcl_FSFileSystemInfo\fR always returns a zero-reference object (or +NULL), much like \fBTcl_NewObj\fR. +.PP +The \fIobjPtr\fR and \fIobjPtrRef\fR arguments to \fBTcl_FSFileAttrsGet\fR, +\fBTcl_FSFileAttrsSet\fR and \fBTcl_FSFileAttrStrings\fR are conventional Tcl +values; the \fIobjPtr\fR argument will be read but not retained, and the +\fIobjPtrRef\fR argument will have (on success) a zero-reference value written +into it (as with \fBTcl_NewObj\fR). \fBTcl_FSFileAttrsGet\fR and +\fBTcl_FSFileAttrsSet\fR may also manipulate the interpreter result. +.PP +The \fIresultPtr\fR argument to \fBTcl_FSMatchInDirectory\fR will not have its +reference count manipulated, but it should have a reference count of no more +than 1, and should not be the current interpreter result (as the function may +overwrite that on error). +.SS "VIRTUAL FILESYSTEM INTERFACE" +.PP +For all virtual filesystem implementation functions, any \fIpathPtr\fR +arguments should not have their reference counts manipulated. If they take an +\fIinterp\fR argument, they may set an error message in that, but must not +manipulate the \fIpathPtr\fR afterwards. Aside from that: +.TP +\fIinternalToNormalizedProc\fR +. +This should return a zero-reference count value, as if allocated with +\fBTcl_NewObj\fR. +.TP +\fInormalizePathProc\fR +. +Unlike with other API implementation functions, the \fIpathPtr\fR argument +here is guaranteed to be an unshared object that should be updated. Its +reference count should not be modified. +.TP +\fIfilesystemPathTypeProc\fR +. +The return value (if non-NULL) either has a reference count of zero or needs +to be maintained (on a per-thread basis) by the filesystem. Tcl will increment +the reference count of the value if it wishes to retain it. +.TP +\fIfilesystemSeparatorProc\fR +. +The return value should be a value with reference count of zero. +.TP +\fImatchInDirectoryProc\fR +. +The \fIresultPtr\fR argument should be assumed to hold a list that can be +appended to (i.e., that has a reference count no greater than 1). No reference +to it should be retained. +.TP +\fIlinkProc\fR +. +If \fItoPtr\fR is NULL, this should return a value with reference count 1 that +has just been allocated and passed to \fBTcl_IncrRefCount\fR. If \fItoPtr\fR +is not NULL, it should be returned on success. +.TP +\fIlistVolumesProc\fR +. +The result value should be a list (if non-NULL); it will have its reference +count decremented once (with \fBTcl_DecrRefCount\fR) by Tcl once done. +.TP +\fIfileAttrStringsProc\fR +. +If the result is NULL, the \fIobjPtrRef\fR should have a list value written to +it; that list will have its reference count both incremented (with +\fBTcl_IncrRefCount\fR) and decremented (with \fBTcl_DecrRefCount\fR). +.TP +\fIfileAttrsGetProc\fR +. +The \fIobjPtrRef\fR argument should have (on non-error return) a zero +reference count value written to it (allocated as if with \fBTcl_NewObj\fR). +.TP +\fIfileAttrsSetProc\fR +. +The \fIobjPtr\fR argument should either just be read or its reference count +incremented to retain it. +.TP +\fIremoveDirectoryProc\fR +. +If an error is being reported, the problem filename reported via +\fIerrorPtr\fR should be newly allocated (as if with \fBTcl_NewObj\fR) and +have a reference count of 1 (i.e., have been passed to +\fBTcl_IncrRefCount\fR). +.TP +\fIcopyDirectoryProc\fR +. +If an error is being reported, the problem filename reported via +\fIerrorPtr\fR should be newly allocated (as if with \fBTcl_NewObj\fR) and +have a reference count of 1 (i.e., have been passed to +\fBTcl_IncrRefCount\fR). +.TP +\fIgetCwdProc\fR +. +The result will be passed to \fBTcl_DecrRefCount\fR by the implementation of +\fBTcl_FSGetCwd\fR after it has been normalized. .SH "SEE ALSO" cd(n), file(n), filename(n), load(n), open(n), pwd(n), source(n), unload(n) .SH KEYWORDS diff --git a/doc/GetCwd.3 b/doc/GetCwd.3 index f4f37a1..b19f587 100644 --- a/doc/GetCwd.3 +++ b/doc/GetCwd.3 @@ -17,7 +17,7 @@ char * \fBTcl_GetCwd\fR(\fIinterp\fR, \fIbufferPtr\fR) .sp int -\fBTcl_Chdir\fR(\fIpath\fR) +\fBTcl_Chdir\fR(\fIdirName\fR) .SH ARGUMENTS .AS Tcl_DString *bufferPtr in/out .AP Tcl_Interp *interp in @@ -27,7 +27,7 @@ This dynamic string is used to store the current working directory. At the time of the call it should be uninitialized or free. The caller must eventually call \fBTcl_DStringFree\fR to free up anything stored here. -.AP char *path in +.AP "const char" *dirName in File path in UTF\-8 format. .BE @@ -45,7 +45,7 @@ must call \fBTcl_DStringFree()\fR when the result is no longer needed. The format of the path is UTF\-8. .PP \fBTcl_Chdir\fR changes the applications current working directory to -the value specified in \fIpath\fR. The format of the passed in string +the value specified in \fIdirName\fR. The format of the passed in string must be UTF\-8. The function returns -1 on error or 0 on success. .SH KEYWORDS diff --git a/doc/GetIndex.3 b/doc/GetIndex.3 index 8591c56..a788848 100644 --- a/doc/GetIndex.3 +++ b/doc/GetIndex.3 @@ -105,6 +105,12 @@ array of characters at \fItablePtr\fR+\fIoffset\fR bytes, etc.) This is particularly useful when processing things like \fBTk_ConfigurationSpec\fR, whose string keys are in the same place in each of several array elements. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_GetIndexFromObj\fR and \fBTcl_GetIndexFromObjStruct\fR do not modify +the reference count of their \fIobjPtr\fR arguments; they only read. Note +however that these functions may set the interpreter result; if that is the +only place that is holding a reference to the object, it will be deleted. .SH "SEE ALSO" prefix(n), Tcl_WrongNumArgs(3) .SH KEYWORDS @@ -330,5 +330,19 @@ typedef void \fBTcl_FreeHashEntryProc\fR( If this is NULL then \fBTcl_Free\fR is used to free the space for the entry. Tcl_Obj* keys use this function to decrement the reference count on the value. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +When a hash table is created with \fBTcl_InitCustomHashTable\fR, the +\fBTcl_CreateHashEntry\fR function will increment the reference count of its +\fIkey\fR argument when it creates a key (but not if there is an existing +matching key). The reference count of the key will be decremented when the +corresponding hash entry is deleted, whether with \fBTcl_DeleteHashEntry\fR or +with \fBTcl_DeleteHashTable\fR. The \fBTcl_GetHashKey\fR function will return +the key without further modifying its reference count. +.PP +Custom hash tables that use a Tcl_Obj* as key will generally need to do +something similar in their \fIallocEntryProc\fR. +.SH "SEE ALSO" +Dict(3) .SH KEYWORDS hash table, key, lookup, search, value @@ -2,7 +2,7 @@ '\" Copyright (c) 1998-2000 Scriptics Corporation. '\" All rights reserved. '\" -.TH Tcl_Init 3 8.0 Tcl "Tcl Library Procedures" +.TH Tcl_Init 3 8.7 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -13,10 +13,15 @@ Tcl_Init \- find and source initialization script .sp int \fBTcl_Init\fR(\fIinterp\fR) +.sp +const char * +\fBTcl_SetPreInitScript\fR(\fIscriptPtr\fR) .SH ARGUMENTS .AS Tcl_Interp *interp .AP Tcl_Interp *interp in Interpreter to initialize. +.AP "const char" *scriptPtr in +Address of the initialization script. .BE .SH DESCRIPTION @@ -26,6 +31,13 @@ Interpreter to initialize. path. .PP \fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures. +.PP +\fBTcl_SetPreInitScript\fR registers the pre-initialization script and +returns the former (now replaced) script pointer. +A value of \fINULL\fR may be passed to not register any script. +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. .SH "SEE ALSO" Tcl_AppInit, Tcl_Main diff --git a/doc/IntObj.3 b/doc/IntObj.3 index 36bfa7d..d640dbb 100644 --- a/doc/IntObj.3 +++ b/doc/IntObj.3 @@ -160,6 +160,27 @@ If anything later in the caller requires The \fBTcl_InitBignumFromDouble\fR routine is a utility procedure that extracts the integer part of \fIdoubleValue\fR and stores that integer value in the \fBmp_int\fR value \fIbigValue\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR, and +\fBTcl_NewBignumObj\fR always return a zero-reference object, much like +\fBTcl_NewObj\fR. +.PP +\fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR, and +\fBTcl_SetBignumObj\fR do not modify the reference count of their \fIobjPtr\fR +arguments, but do require that the object be unshared. +.PP +\fBTcl_GetIntFromObj\fR, \fBTcl_GetIntForIndex\fR, \fBTcl_GetLongFromObj\fR, +\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and +\fBTcl_TakeBignumFromObj\fR do not modify the reference count of their +\fIobjPtr\fR arguments; they only read. Note however that this function may +set the interpreter result; if that is the only place that is holding a +reference to the object, it will be deleted. Also note that if +\fBTcl_TakeBignumFromObj\fR is given an unshared value, the value of that +object may be modified; it is intended to be used when the value is +.QW consumed +by the operation at this point. + .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult .SH KEYWORDS diff --git a/doc/ListObj.3 b/doc/ListObj.3 index ab836d8..67721c9 100644 --- a/doc/ListObj.3 +++ b/doc/ListObj.3 @@ -246,6 +246,31 @@ with a NULL \fIobjvPtr\fR: result = \fBTcl_ListObjReplace\fR(interp, listPtr, first, count, 0, NULL); .CE +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewListObj\fR always returns a zero-reference object, much like +\fBTcl_NewObj\fR. If a non-NULL \fIobjv\fR argument is given, the reference +counts of the first \fIobjc\fR values in that array are incremented. +.PP +\fBTcl_SetListObj\fR does not modify the reference count of its \fIobjPtr\fR +argument, but does require that the object be unshared. The reference counts +of the first \fIobjc\fR values in the \fIobjv\fR array are incremented. +.PP +\fBTcl_ListObjGetElements\fR, \fBTcl_ListObjIndex\fR, and +\fBTcl_ListObjLength\fR do not modify the reference count of their +\fIlistPtr\fR arguments; they only read. Note however that these three +functions may set the interpreter result; if that is the only place that is +holding a reference to the object, it will be deleted. +.PP +\fBTcl_ListObjAppendList\fR, \fBTcl_ListObjAppendElement\fR, and +\fBTcl_ListObjReplace\fR require an unshared \fIlistPtr\fR argument. +\fBTcl_ListObjAppendList\fR only reads its \fIelemListPtr\fR argument. +\fBTcl_ListObjAppendElement\fR increments the reference count of its +\fIobjPtr\fR on success. \fBTcl_ListObjReplace\fR increments the reference +count of the first \fIobjc\fR values in the \fIobjv\fR array on success. Note +however that all these three functions may set the interpreter result on +failure; if that is the only place that is holding a reference to the object, +it will be deleted. .SH "SEE ALSO" Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjResult(3) .SH KEYWORDS @@ -60,6 +60,10 @@ be unloaded with \fBTcl_FSUnloadFile\fR. the symbol cannot be found, it returns NULL and sets an error message in the given \fIinterp\fR (if that is non-NULL). Note that it is unsafe to use this operation on a handle that has been passed to \fBTcl_FSUnloadFile\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The reference count of the \fIpathPtr\fR argument to \fBTcl_LoadFile\fR may be +incremented. As such, it should not be given a zero reference count value. .SH "SEE ALSO" Tcl_FSLoadFile(3), Tcl_FSUnloadFile(3), load(n), unload(n) .SH KEYWORDS diff --git a/doc/Method.3 b/doc/Method.3 index 9e636a1..577cd54 100644 --- a/doc/Method.3 +++ b/doc/Method.3 @@ -258,8 +258,32 @@ also return TCL_ERROR; it should return TCL_OK otherwise. The \fIoldClientData\fR field to a Tcl_CloneProc gives the value from the method being copied from, and the \fInewClientDataPtr\fR field will point to a variable in which to write the value for the method being copied to. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fInameObj\fR argument to \fBTcl_NewMethod\fR and +\fBTcl_NewInstanceMethod\fR (when non-NULL) will have its reference count +incremented if there is no existing method with that name in that +class/object. +.PP +The result of \fBTcl_MethodName\fR is a value with a reference count of at +least one. It should not be modified without first duplicating it (with +\fBTcl_DuplicateObj\fR). +.PP +The values in the first \fIobjc\fR values of the \fIobjv\fR argument to +\fBTcl_ObjectContextInvokeNext\fR are assumed to have a reference count of at +least 1; the containing array is assumed to endure until the next method +implementation (see \fBnext\fR) returns. Be aware that methods may +\fByield\fR; if any post-call actions are desired (e.g., decrementing the +reference count of values passed in here), they must be scheduled with +\fBTcl_NRAddCallback\fR. +.PP +The \fIcallProc\fR of the \fBTcl_MethodType\fR structure takes values of at +least reference count 1 in its \fIobjv\fR argument. It may add its own +references, but must not decrement the reference count below that level; the +caller of the method will decrement the reference count once the method +returns properly (and the reference will be held if the method \fByield\fRs). .SH "SEE ALSO" -Class(3), oo::class(n), oo::define(n), oo::object(n) +Class(3), NRE(3), oo::class(n), oo::define(n), oo::object(n) .SH KEYWORDS constructor, method, object @@ -40,7 +40,7 @@ void .AS Tcl_CmdDeleteProc *interp in .AP Tcl_Interp *interp in The relevant Interpreter. -.AP char *cmdName in +.AP "const char" *cmdName in Name of the command to create. .AP Tcl_ObjCmdProc *proc in Called in order to evaluate a command. Is often just a small wrapper that uses @@ -227,6 +227,25 @@ int Any function comprising a routine can push other functions, making it possible implement looping and sequencing constructs using the function stack. .PP +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The first \fIobjc\fR values in the \fIobjv\fR array passed to the functions +\fBTcl_NRCallObjProc\fR, \fBTcl_NREvalObjv\fR, and \fBTcl_NRCmdSwap\fR should +have a reference count of at least 1; they may have additional references +taken during the execution. +.PP +The \fIobjPtr\fR argument to \fBTcl_NREvalObj\fR and \fBTcl_NRExprObj\fR +should have a reference count of at least 1, and may have additional +references taken to it during execution. +.PP +The \fIresultObj\fR argument to \fBTcl_NRExprObj\fR should be an unshared +object. +.PP +Use \fBTcl_NRAddCallback\fR to schedule any required final decrementing of the +reference counts of arguments to any of the other functions on this page, as +with any other post-processing step in the non-recursive execution engine. +.PP +The .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3) .SH KEYWORDS diff --git a/doc/Namespace.3 b/doc/Namespace.3 index a037442..49b772c 100644 --- a/doc/Namespace.3 +++ b/doc/Namespace.3 @@ -46,10 +46,10 @@ Tcl_Command \fBTcl_FindCommand\fR(\fIinterp, name, contextNsPtr, flags\fR) .sp Tcl_Obj * -\fBTcl_GetNamespaceUnknownHandler(\fIinterp, nsPtr\fR) +\fBTcl_GetNamespaceUnknownHandler\fR(\fIinterp, nsPtr\fR) .sp int -\fBTcl_SetNamespaceUnknownHandler(\fIinterp, nsPtr, handlerPtr\fR) +\fBTcl_SetNamespaceUnknownHandler\fR(\fIinterp, nsPtr, handlerPtr\fR) .SH ARGUMENTS .AS Tcl_NamespaceDeleteProc allowOverwrite in/out .AP Tcl_Interp *interp in/out @@ -159,6 +159,18 @@ for the namespace, or NULL if none is set. \fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to its default. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjPtr\fR argument to \fBTcl_AppendExportList\fR should be an +unshared object, as it will be modified by this function. The +reference count of \fIobjPtr\fR will not be altered. +.PP +\fBTcl_GetNamespaceUnknownHandler\fR returns a possibly shared value. +Its reference count should be incremented if the value is to be +retained. +.PP +The \fIhandlerPtr\fR argument to \fBTcl_SetNamespaceUnknownHandler\fR +will have its reference count incremented if it is a non-empty list. .SH "SEE ALSO" Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3) .SH KEYWORDS diff --git a/doc/Object.3 b/doc/Object.3 index eadd041..2099552 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -283,7 +283,12 @@ to reduce storage requirements. Reference counting is used to determine when a value is no longer needed and can safely be freed. A value just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR -has \fIrefCount\fR 0. +has \fIrefCount\fR 0, meaning that the object can often be given to a function +like \fBTcl_SetObjResult\fR, \fBTcl_ListObjAppendElement\fR, or +\fBTcl_DictObjPut\fR (as a value) without explicit reference management, all +of which are common use cases. (The latter two require that the the target +list or dictionary be well-formed, but that is often easy to arrange when the +value is being initially constructed.) The macro \fBTcl_IncrRefCount\fR increments the reference count when a new reference to the value is created. The macro \fBTcl_DecrRefCount\fR decrements the count diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index 67f5174..7e3cc12 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.3 @@ -248,6 +248,28 @@ The \fIfreeIntRepProc\fR implementation must not access the uses of that field during value deletion. The defined tasks for the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR member. +.PP +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. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjPtr\fR argument to \fBTcl_AppendAllObjTypes\fR should be an unshared +value; this function will not modify the reference count of that value, but +will modify its contents. If \fIobjPtr\fR is not (interpretable as) a list, +this function will set the interpreter result and produce an error; using an +unshared empty value is strongly recommended. +.PP +The \fIobjPtr\fR argument to \fBTcl_ConvertToType\fR can have any non-zero +reference count; this function will not modify the reference count, but may +write to the interpreter result on error so values that originate from there +should have an additional reference made before calling this. +.PP +None of the callback functions in the \fBTcl_ObjType\fR structure should +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) .SH KEYWORDS diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 index c1d1922..4e42b93 100644 --- a/doc/OpenFileChnl.3 +++ b/doc/OpenFileChnl.3 @@ -641,6 +641,24 @@ the channel was created with \fBTcl_OpenFileChannel\fR, \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other channel types may return a different type of handle on Windows platforms. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIreadObjPtr\fR argument to \fBTcl_ReadChars\fR must be an unshared +value; it will be modified by this function. Using the interpreter result for +this purpose is \fIstrongly\fR not recommended; the preferred pattern is to +use a new value from \fBTcl_NewObj\fR to receive the data and only to pass it +to \fBTcl_SetObjResult\fR if this function succeeds. +.PP +The \fIlineObjPtr\fR argument to \fBTcl_GetsObj\fR must be an unshared value; +it will be modified by this function. Using the interpreter result for this +purpose is \fIstrongly\fR not recommended; the preferred pattern is to use a +new value from \fBTcl_NewObj\fR to receive the data and only to pass it to +\fBTcl_SetObjResult\fR if this function succeeds. +.PP +The \fIwriteObjPtr\fR argument to \fBTcl_WriteObj\fR should be a value with +any reference count. This function will not modify the reference count. Using +the interpreter result without adding an additional reference to it is not +recommended. .SH "SEE ALSO" DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3) .SH KEYWORDS diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3 index def55de..f29f161 100644 --- a/doc/ParseArgs.3 +++ b/doc/ParseArgs.3 @@ -189,6 +189,12 @@ will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked to the lifetime of the string representation of the argument value that it came from, and so should be copied if it needs to be retained. The \fIsrcPtr\fR and \fIclientData\fR fields are ignored. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The values in the \fIobjv\fR argument to \fBTcl_ParseArgsObjv\fR will not have +their reference counts modified by this function. The interpreter result may +be modified on error; the values passed should not be the interpreter result +with no further reference added. .SH "SEE ALSO" Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3) .SH KEYWORDS diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3 index 40a0818..03b97f7 100644 --- a/doc/ParseCmd.3 +++ b/doc/ParseCmd.3 @@ -191,6 +191,7 @@ 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. @@ -463,5 +464,12 @@ 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 71f3acf..77e73f1 100644 --- a/doc/PkgRequire.3 +++ b/doc/PkgRequire.3 @@ -91,7 +91,11 @@ functions. \fBTcl_PkgRequireProc\fR is the form of \fBpackage require\fR handling multiple requirements. The other forms are present for backward compatibility and translate their invocations to this form. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The requirements values given (in the \fIobjv\fR argument) to +\fBTcl_PkgRequireProc\fR must have non-zero reference counts. .SH KEYWORDS package, present, provide, require, version .SH "SEE ALSO" -package(n), Tcl_StaticPackage(3) +package(n), Tcl_StaticLibrary(3) diff --git a/doc/RecEvalObj.3 b/doc/RecEvalObj.3 index f9550a2..e68f4b5 100644 --- a/doc/RecEvalObj.3 +++ b/doc/RecEvalObj.3 @@ -44,6 +44,12 @@ allow the user to re-issue recently invoked commands. If the \fIflags\fR argument contains the \fBTCL_NO_EVAL\fR bit then the command is recorded without being evaluated. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The reference count of the \fIcmdPtr\fR argument to \fBTcl_RecordAndEvalObj\fR +must be at least 1. This function will modify the interpreter result; do not +use an existing result as \fIcmdPtr\fR directly without incrementing its +reference count. .SH "SEE ALSO" Tcl_EvalObjEx, Tcl_GetObjResult diff --git a/doc/RegConfig.3 b/doc/RegConfig.3 index d73e3d7..ef46ba5 100644 --- a/doc/RegConfig.3 +++ b/doc/RegConfig.3 @@ -28,7 +28,7 @@ configuration as ASCII string. This means that this information is in UTF-8 too. Must not be NULL. .AP "const Tcl_Config" *configuration in Refers to an array of Tcl_Config entries containing the information -embedded in the binary library. Must not be NULL. The end of the array +embedded in the library. Must not be NULL. The end of the array is signaled by either a key identical to NULL, or a key referring to the empty string. .AP "const char" *valEncoding in @@ -40,10 +40,10 @@ too. Must not be NULL. .PP The function described here has its base in TIP 59 and provides extensions with support for the embedding of configuration -information into their binary library and the generation of a +information into their library and the generation of a Tcl-level interface for querying this information. .PP -To embed configuration information into their binary library an +To embed configuration information into their library an extension has to define a non-volatile array of Tcl_Config entries in one if its source files and then call \fBTcl_RegisterConfig\fR to register that information. @@ -108,4 +108,4 @@ typedef struct Tcl_Config { .\" No cross references yet. .\" .SH "SEE ALSO" .SH KEYWORDS -embedding, configuration, binary library +embedding, configuration, library diff --git a/doc/RegExp.3 b/doc/RegExp.3 index aa757bc..40429c9 100644 --- a/doc/RegExp.3 +++ b/doc/RegExp.3 @@ -51,14 +51,14 @@ can be efficiently searched. .AP Tcl_Obj *patObj in/out Refers to the value from which to get a regular expression. The compiled regular expression is cached in the value. -.AP char *text in +.AP "const char" *text in Text to search for a match with a regular expression. .AP "const char" *pattern in String in the form of a regular expression pattern. .AP Tcl_RegExp regexp in Compiled regular expression. Must have been returned previously by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR. -.AP char *start in +.AP "const char" *start in If \fItext\fR is just a portion of some other string, this argument identifies the beginning of the larger string. If it is not the same as \fItext\fR, then no @@ -377,6 +377,22 @@ If no match was found, then it indicates the earliest point at which a match might occur if additional text is appended to the string. If it is no match is possible even with further text, this field will be set to \-1. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fItextObj\fR and \fIpatObj\fR arguments to \fBTcl_RegExpMatchObj\fR must +have reference counts of at least 1. Note however that this function may set +the interpreter result; neither argument should be the direct interpreter +result without an additional reference being taken. +.PP +The \fIpatObj\fR argument to \fBTcl_GetRegExpFromObj\fR must have a reference +count of at least 1. Note however that this function may set the interpreter +result; the argument should not be the direct interpreter result without an +additional reference being taken. +.PP +The \fItextObj\fR argument to \fBTcl_RegExpExecObj\fR must have a reference +count of at least 1. Note however that this function may set the interpreter +result; the argument should not be the direct interpreter result without an +additional reference being taken. .SH "SEE ALSO" re_syntax(n) .SH KEYWORDS diff --git a/doc/SetChanErr.3 b/doc/SetChanErr.3 index 5bb86be..473b61c 100644 --- a/doc/SetChanErr.3 +++ b/doc/SetChanErr.3 @@ -35,20 +35,20 @@ Refers to the Tcl interpreter whose bypass area is accessed. .AP Tcl_Obj* msg in Error message put into a bypass area. A list of return options and values, followed by a string message. Both message and the option/value information -are optional. +are optional. This \fImust\fR be a well-formed list. .AP Tcl_Obj** msgPtr out Reference to a place where the message stored in the accessed bypass area can be stored in. .BE .SH DESCRIPTION .PP -The current definition of a Tcl channel driver does not permit the direct +The standard definition of a Tcl channel driver does not permit the direct return of arbitrary error messages, except for the setting and retrieval of channel options. All other functions are restricted to POSIX error codes. .PP The functions described here overcome this limitation. Channel drivers are allowed to use \fBTcl_SetChannelError\fR and \fBTcl_SetChannelErrorInterp\fR -to place arbitrary error messages in \fBbypass areas\fR defined for channels +to place arbitrary error messages in \fIbypass areas\fR defined for channels and interpreters. And the generic I/O layer uses \fBTcl_GetChannelError\fR and \fBTcl_GetChannelErrorInterp\fR to look for messages in the bypass areas and arrange for their return as errors. The POSIX error codes set by a driver are @@ -134,6 +134,15 @@ leave all their error information in the interpreter result. .ta 1.9i 4i \fBTcl_Close\fR \fBTcl_UnstackChannel\fR \fBTcl_UnregisterChannel\fR .DE +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fImsg\fR argument to \fBTcl_SetChannelError\fR and +\fBTcl_SetChannelErrorInterp\fR, if not NULL, may have any reference count; +these functions will copy. +.PP +\fBTcl_GetChannelError\fR and \fBTcl_GetChannelErrorInterp\fR write a value +reference into their \fImsgPtr\fR, but do not manipulate its reference count. +The reference count will be at least 1 (unless the reference is NULL). .SH "SEE ALSO" Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3) .SH KEYWORDS diff --git a/doc/SetResult.3 b/doc/SetResult.3 index 1622290..04a4b7f 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -239,6 +239,33 @@ typedef void \fBTcl_FreeProc\fR( .PP When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to the value of \fIresult\fR passed to \fBTcl_SetResult\fR. + +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The interpreter result is one of the main places that owns references to +values, along with the bytecode execution stack, argument lists, variables, +and the list and dictionary collection values. +.PP +\fBTcl_SetObjResult\fR takes a value with an arbitrary reference count +\fI(specifically including zero)\fR and guarantees to increment the reference +count. If code wishes to continue using the value after setting it as the +result, it should add its own reference to it with \fBTcl_IncrRefCount\fR. +.PP +\fBTcl_GetObjResult\fR returns the current interpreter result value. This will +have a reference count of at least 1. If the caller wishes to keep the +interpreter result value, it should increment its reference count. +.PP +\fBTcl_GetStringResult\fR does not manipulate reference counts, but the string +it returns is owned by (and has a lifetime controlled by) the current +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_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 +called, the reference count of the interpreter result is guaranteed to be 1. .SH "SEE ALSO" Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp, Tcl_GetReturnOptions diff --git a/doc/SetVar.3 b/doc/SetVar.3 index 4aa671a..eb8333b 100644 --- a/doc/SetVar.3 +++ b/doc/SetVar.3 @@ -242,6 +242,27 @@ but the array remains. If an array name is specified without an index, then the entire array is removed. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The result of \fBTcl_SetVar2Ex\fR, \fBTcl_ObjSetVar2\fR, \fBTcl_GetVar2Ex\fR, +and \fBTcl_ObjGetVar2\fR is (if non-NULL) a value with a reference of at least +1, where that reference is held by the variable that the function has just +operated upon. +.PP +The \fInewValuePtr\fR argument to \fBTcl_SetVar2Ex\fR and \fBTcl_ObjSetVar2\fR +may be an arbitrary reference count value; its reference count will be +incremented on success. However, it is recommended to not use a zero reference +count value, as that makes correct handling of the error case tricky. +.PP +The \fIpart1\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR can +have any reference count; these functions never modify it. It is recommended +to not use a zero reference count for this argument. +.PP +The \fIpart2\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR, if +non-NULL, should not have a zero reference count as these functions may +retain a reference to it (particularly when it is used to create an array +element that did not previously exist). + .SH "SEE ALSO" Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar diff --git a/doc/SplitList.3 b/doc/SplitList.3 index d19ca14..863e322 100644 --- a/doc/SplitList.3 +++ b/doc/SplitList.3 @@ -36,7 +36,7 @@ int .AP Tcl_Interp *interp out Interpreter to use for error reporting. If NULL, then no error message is left. -.AP char *list in +.AP "const char" *list in Pointer to a string with proper list structure. .AP int *argcPtr out Filled in with number of elements in \fIlist\fR. diff --git a/doc/StaticLibrary.3 b/doc/StaticLibrary.3 new file mode 100644 index 0000000..9a77ab7 --- /dev/null +++ b/doc/StaticLibrary.3 @@ -0,0 +1,78 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tcl_StaticLibrary 3 7.5 Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +Tcl_StaticLibrary, Tcl_StaticPackage \- make a statically linked library available via the 'load' command +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +\fBTcl_StaticLibrary\fR(\fIinterp, prefix, initProc, safeInitProc\fR) +.sp +\fBTcl_StaticPackage\fR(\fIinterp, prefix, initProc, safeInitProc\fR) +.SH ARGUMENTS +.AS Tcl_LibraryInitProc *safeInitProc +.AP Tcl_Interp *interp in +If not NULL, points to an interpreter into which the library has +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). +.AP Tcl_LibraryInitProc *initProc in +Procedure to invoke to incorporate this library into a trusted +interpreter. +.AP Tcl_LibraryInitProc *safeInitProc in +Procedure to call to incorporate this library into a safe interpreter +(one that will execute untrusted scripts). NULL means the library +cannot be used in safe interpreters. +.BE +.SH DESCRIPTION +.PP +This procedure may be invoked to announce that a library has been +linked statically with a Tcl application and, optionally, that it +has already been incorporated into an interpreter. +Once \fBTcl_StaticLibrary\fR has been invoked for a library, it +may be incorporated into interpreters using the \fBload\fR command. +\fBTcl_StaticLibrary\fR is normally invoked only by the \fBTcl_AppInit\fR +procedure for the application, not by libraries for themselves +(\fBTcl_StaticLibrary\fR should only be invoked for statically +linked libraries, and code in the library itself should not need +to know whether the library is dynamically loaded or statically linked). +.PP +When the \fBload\fR command is used later to incorporate the library into +an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will +be invoked, depending on whether the target interpreter is safe +or not. +\fIinitProc\fR and \fIsafeInitProc\fR must both match the +following prototype: +.PP +.CS +typedef int \fBTcl_LibraryInitProc\fR( + Tcl_Interp *\fIinterp\fR); +.CE +.PP +The \fIinterp\fR argument identifies the interpreter in which the library +is to be incorporated. The initialization procedure must return \fBTCL_OK\fR or +\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in +the event of an error it should set the interpreter's result to point to an +error message. The result or error from the initialization procedure will +be returned as the result of the \fBload\fR command that caused the +initialization procedure to be invoked. +.PP +\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. +.SH KEYWORDS +initialization procedure, package, static linking +.SH "SEE ALSO" +load(n), package(n), Tcl_PkgRequire(3) diff --git a/doc/StaticPkg.3 b/doc/StaticPkg.3 deleted file mode 100644 index b22edcc..0000000 --- a/doc/StaticPkg.3 +++ /dev/null @@ -1,73 +0,0 @@ -'\" -'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures" -.so man.macros -.BS -.SH NAME -Tcl_StaticPackage \- make a statically linked package available via the 'load' command -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_StaticPackage\fR(\fIinterp, pkgName, initProc, safeInitProc\fR) -.SH ARGUMENTS -.AS Tcl_PackageInitProc *safeInitProc -.AP Tcl_Interp *interp in -If not NULL, points to an interpreter into which the package has -already been loaded (i.e., the caller has already invoked the -appropriate initialization procedure). NULL means the package -has not yet been incorporated into any interpreter. -.AP "const char" *pkgName in -Name of the package; should be properly capitalized (first letter -upper-case, all others lower-case). -.AP Tcl_PackageInitProc *initProc in -Procedure to invoke to incorporate this package into a trusted -interpreter. -.AP Tcl_PackageInitProc *safeInitProc in -Procedure to call to incorporate this package into a safe interpreter -(one that will execute untrusted scripts). NULL means the package -cannot be used in safe interpreters. -.BE -.SH DESCRIPTION -.PP -This procedure may be invoked to announce that a package has been -linked statically with a Tcl application and, optionally, that it -has already been loaded into an interpreter. -Once \fBTcl_StaticPackage\fR has been invoked for a package, it -may be loaded into interpreters using the \fBload\fR command. -\fBTcl_StaticPackage\fR is normally invoked only by the \fBTcl_AppInit\fR -procedure for the application, not by packages for themselves -(\fBTcl_StaticPackage\fR should only be invoked for statically -loaded packages, and code in the package itself should not need -to know whether the package is dynamically or statically loaded). -.PP -When the \fBload\fR command is used later to load the package into -an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will -be invoked, depending on whether the target interpreter is safe -or not. -\fIinitProc\fR and \fIsafeInitProc\fR must both match the -following prototype: -.PP -.CS -typedef int \fBTcl_PackageInitProc\fR( - Tcl_Interp *\fIinterp\fR); -.CE -.PP -The \fIinterp\fR argument identifies the interpreter in which the package -is to be loaded. The initialization procedure must return \fBTCL_OK\fR or -\fBTCL_ERROR\fR to indicate whether or not it completed successfully; in -the event of an error it should set the interpreter's result to point to an -error message. The result or error from the initialization procedure will -be returned as the result of the \fBload\fR command that caused the -initialization procedure to be invoked. -.PP -\fBTcl_StaticPackage\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. -.SH KEYWORDS -initialization procedure, package, static linking -.SH "SEE ALSO" -load(n), package(n), Tcl_PkgRequire(3) diff --git a/doc/StringObj.3 b/doc/StringObj.3 index c55f57d..772073e 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -383,6 +383,33 @@ white space, then that value is ignored entirely. This white-space removal was added to make the output of the \fBconcat\fR command cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a newly-created value whose ref count is zero. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewStringObj\fR, \fBTcl_NewUnicodeObj\fR, \fBTcl_Format\fR, +\fBTcl_ObjPrintf\fR, and \fBTcl_ConcatObj\fR always return a zero-reference +object, much like \fBTcl_NewObj\fR. +.PP +\fBTcl_GetStringFromObj\fR, \fBTcl_GetString\fR, \fBTcl_GetUnicodeFromObj\fR, +\fBTcl_GetUnicode\fR, \fBTcl_GetUniChar\fR, \fBTcl_GetCharLength\fR, and +\fBTcl_GetRange\fR all only work with an existing value; they do not +manipulate its reference count in any way. +.PP +\fBTcl_SetStringObj\fR, \fBTcl_SetUnicodeObj\fR, \fBTcl_AppendToObj\fR, +\fBTcl_AppendUnicodeToObj\fR, \fBTcl_AppendObjToObj\fR, +\fBTcl_AppendStringsToObj\fR, \fBTcl_AppendStringsToObjVA\fR, +\fBTcl_AppendLimitedToObj\fR, \fBTcl_AppendFormatToObj\fR, +\fBTcl_AppendPrintfToObj\fR, \fBTcl_SetObjLength\fR, and +\fBTcl_AttemptSetObjLength\fR and require their \fIobjPtr\fR to be an unshared +value (i.e, a reference count no more than 1) as they will modify it. +.PP +Additional arguments to the above functions (the \fIappendObjPtr\fR argument +to \fBTcl_AppendObjToObj\fR, values in the \fIobjv\fR argument to +\fBTcl_Format\fR, \fBTcl_AppendFormatToObj\fR, and \fBTcl_ConcatObj\fR) can +have any reference count, but reference counts of zero are not recommended. +.PP +\fBTcl_Format\fR and \fBTcl_AppendFormatToObj\fR may modify the interpreter +result, which involves changing the reference count of a value. + .SH "SEE ALSO" Tcl_NewObj(3), Tcl_IncrRefCount(3), Tcl_DecrRefCount(3), format(n), sprintf(3) .SH KEYWORDS diff --git a/doc/SubstObj.3 b/doc/SubstObj.3 index a2b6214..fa30fb1 100644 --- a/doc/SubstObj.3 +++ b/doc/SubstObj.3 @@ -62,6 +62,13 @@ result of the whole substitution on \fIobjPtr\fR will be truncated at the point immediately before the start of the command substitution, and no characters will be added to the result or substitutions performed after that point. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjPtr\fR argument to \fBTcl_SubstObj\fR must not have a reference +count of zero. This function modifies the interpreter result, both on success +and on failure; the result of this function on success is exactly the current +interpreter result. Successful results should have their reference count +incremented if they are to be retained. .SH "SEE ALSO" subst(n) .SH KEYWORDS diff --git a/doc/TclZlib.3 b/doc/TclZlib.3 index 4a5df89..4d06923 100644 --- a/doc/TclZlib.3 +++ b/doc/TclZlib.3 @@ -262,6 +262,31 @@ file named by the \fBfilename\fR field was modified. Suitable for use with . The type of the uncompressed data (either \fBbinary\fR or \fBtext\fR) if known. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR take a value with arbitrary +reference count for their \fIdataObj\fR and \fIdictObj\fR arguments (the +latter often being NULL instead), and set the interpreter result with their +output value (or an error). The existing interpreter result should not be +passed as any argument value unless an additional reference is held. +.PP +\fBTcl_ZlibStreamInit\fR takes a value with arbitrary reference count for its +\fIdictObj\fR argument; it only reads from it. The existing interpreter result +should not be passed unless an additional reference is held. +.PP +\fBTcl_ZlibStreamGetCommandName\fR returns a zero reference count value, much +like \fBTcl_NewObj\fR. +.PP +The \fIdataObj\fR argument to \fBTcl_ZlibStreamPut\fR is a value with +arbitrary reference count; it is only ever read from. +.PP +The \fIdataObj\fR argument to \fBTcl_ZlibStreamGet\fR is an unshared value +(see \fBTcl_IsShared\fR) that will be updated by the function. +.PP +The \fIcompDict\fR argument to \fBTcl_ZlibStreamSetCompressionDictionary\fR, +if non-NULL, may be duplicated or may have its reference count incremented. +Using a zero reference count value is not recommended. + .SH "PORTABILITY NOTES" These functions will fail gracefully if Tcl is not linked with the zlib library. diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3 index 62ceeab..904ecbe 100644 --- a/doc/Tcl_Main.3 +++ b/doc/Tcl_Main.3 @@ -10,13 +10,17 @@ .so man.macros .BS .SH NAME -Tcl_Main, Tcl_SetStartupScript, Tcl_GetStartupScript, Tcl_SetMainLoop \- main program, startup script, and event loop definition for Tcl-based applications +Tcl_Main, Tcl_MainEx, Tcl_MainExW, Tcl_SetStartupScript, Tcl_GetStartupScript, Tcl_SetMainLoop \- main program, startup script, and event loop definition for Tcl-based applications .SH SYNOPSIS .nf \fB#include <tcl.h>\fR .sp \fBTcl_Main\fR(\fIargc, argv, appInitProc\fR) .sp +\fBTcl_MainEx\fR(\fIargc, charargv, appInitProc, interp\fR) +.sp +\fBTcl_MainExW\fR(\fIargc, wideargv, appInitProc, interp\fR) +.sp \fBTcl_SetStartupScript\fR(\fIpath, encoding\fR) .sp Tcl_Obj * @@ -30,6 +34,10 @@ Number of elements in \fIargv\fR. .AP char *argv[] in Array of strings containing command-line arguments. On Windows, when using -DUNICODE, the parameter type changes to wchar_t *. +.AP char *charargv[] in +As argv, but does not change type to wchar_t. +.AP char *wideargv[] in +As argv, but type is always wchar_t. .AP Tcl_AppInitProc *appInitProc in Address of an application-specific initialization procedure. The value for this argument is usually \fBTcl_AppInit\fR. @@ -42,6 +50,8 @@ If non-NULL, location to write a copy of the (const char *) pointing to the encoding name. .AP Tcl_MainLoopProc *mainLoopProc in Address of an application-specific event loop procedure. +.AP Tcl_Interp *interp in +Already created Tcl Interpreter. .BE .SH DESCRIPTION .PP @@ -191,6 +201,15 @@ 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. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_SetStartupScript\fR takes a value (or NULL) for its \fIpath\fR +argument, and will increment the reference count of it. +.PP +\fBTcl_GetStartupScript\fR returns a value with reference count at least 1, or +NULL. It's \fIencodingPtr\fR is also used (if non-NULL) to return a value with +a reference count at least 1, or NULL. In both cases, the owner of the values +is the current thread. .SH "SEE ALSO" tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3), exit(n), encoding(n) diff --git a/doc/TraceVar.3 b/doc/TraceVar.3 index 82aa7b8..7751cf7 100644 --- a/doc/TraceVar.3 +++ b/doc/TraceVar.3 @@ -359,6 +359,14 @@ Traces on a variable are always removed whenever the variable is deleted; the only time \fBTCL_TRACE_DESTROYED\fR is not set is for a whole-array trace invoked when only a single element of an array is unset. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +When a \fIproc\fR callback is invoked, and that callback was installed with +the \fBTCL_TRACE_RESULT_OBJECT\fR flag, the result of the callback is a +Tcl_Obj reference when there is an error. The result will have its reference +count decremented once when no longer needed, or may have additional +references made to it (e.g., by setting it as the interpreter result with +\fBTcl_SetObjResult\fR). .SH BUGS .PP Array traces are not yet integrated with the Tcl \fBinfo exists\fR command, diff --git a/doc/UniCharIsAlpha.3 b/doc/UniCharIsAlpha.3 index 61490ed..a07af9a 100644 --- a/doc/UniCharIsAlpha.3 +++ b/doc/UniCharIsAlpha.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tcl_UniCharIsAlnum, Tcl_UniCharIsAlpha, Tcl_UniCharIsControl, Tcl_UniCharIsDigit, Tcl_UniCharIsGraph, Tcl_UniCharIsLower, Tcl_UniCharIsPrint, Tcl_UniCharIsPunct, Tcl_UniCharIsSpace, Tcl_UniCharIsUpper, Tcl_UniCharIsWordChar \- routines for classification of Tcl_UniChar characters +Tcl_UniCharIsAlnum, Tcl_UniCharIsAlpha, Tcl_UniCharIsControl, Tcl_UniCharIsDigit, Tcl_UniCharIsGraph, Tcl_UniCharIsLower, Tcl_UniCharIsPrint, Tcl_UniCharIsPunct, Tcl_UniCharIsSpace, Tcl_UniCharIsUpper, Tcl_UniCharIsUnicode, Tcl_UniCharIsWordChar \- routines for classification of Tcl_UniChar characters .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -44,6 +44,9 @@ int \fBTcl_UniCharIsUpper\fR(\fIch\fR) .sp int +\fBTcl_UniCharIsUnicode\fR(\fIch\fR) +.sp +int \fBTcl_UniCharIsWordChar\fR(\fIch\fR) .SH ARGUMENTS .AS int ch @@ -81,6 +84,9 @@ with the various routines. .PP \fBTcl_UniCharIsUpper\fR tests if the character is an uppercase Unicode character. .PP +\fBTcl_UniCharIsUnicode\fR tests if the character is a Unicode character, not being +a surrogate or noncharacter. +.PP \fBTcl_UniCharIsWordChar\fR tests if the character is alphanumeric or a connector punctuation mark. @@ -233,10 +233,10 @@ characters. .PP \fBTcl_UtfCharComplete\fR returns 1 if the source UTF-8 string \fIsrc\fR of \fIlength\fR bytes is long enough to be decoded by -\fBTcl_UtfToUniChar\fR, or 0 otherwise. This function does not guarantee -that the UTF-8 string is properly formed. This routine is used by -procedures that are operating on a byte at a time and need to know if a -full Unicode character has been seen. +\fBTcl_UtfToUniChar\fR/\fBTcl_UtfNext\fR, or 0 otherwise. This function +does not guarantee that the UTF-8 string is properly formed. This routine +is used by procedures that are operating on a byte at a time and need to +know if a full Unicode character has been seen. .PP \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings. It returns the number of Tcl_UniChars that are represented by the UTF-8 string @@ -257,7 +257,8 @@ Given \fIsrc\fR, a pointer to some location in a UTF-8 string, \fBTcl_UtfNext\fR returns a pointer to the next UTF-8 character in the string. The caller must not ask for the next character after the last character in the string if the string is not terminated by a null -character. +character. \fBTcl_UtfCharComplete\fR can be used in that case to +make sure enough bytes are available before calling \fBTcl_UtfNext\fR. .PP \fBTcl_UtfPrev\fR is used to step backward through but not beyond the UTF-8 string that begins at \fIstart\fR. If the UTF-8 string is made @@ -274,12 +275,12 @@ always a pointer to a location in the string. It always returns a pointer to a byte that begins a character when scanning for characters beginning from \fIstart\fR. When \fIsrc\fR is greater than \fIstart\fR, it always returns a pointer less than \fIsrc\fR and greater than or -equal to (\fIsrc\fR - \fBTCL_UTF_MAX\fR). The character that begins +equal to (\fIsrc\fR - 4). The character that begins at the returned pointer is the first one that either includes the byte \fIsrc[-1]\fR, or might include it if the right trail bytes are present at \fIsrc\fR and greater. \fBTcl_UtfPrev\fR never reads the byte \fIsrc[0]\fR nor the byte \fIstart[-1]\fR nor the byte -\fIsrc[-\fBTCL_UTF_MAX\fI-1]\fR. +\fIsrc[-5]\fR. .PP \fBTcl_UniCharAtIndex\fR corresponds to a C string array dereference or the Pascal Ord() function. It returns the Unicode character represented at the diff --git a/doc/WrongNumArgs.3 b/doc/WrongNumArgs.3 index 93e2ebb..533cb4f 100644 --- a/doc/WrongNumArgs.3 +++ b/doc/WrongNumArgs.3 @@ -73,6 +73,12 @@ is now an \fIindexObject\fR because it was passed to .CS wrong # args: should be "foo barfly fileName count" .CE +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The \fIobjv\fR argument to \fBTcl_WrongNumArgs\fR should be the exact +arguments passed to the command or method implementation function that is +calling \fBTcl_WrongNumArgs\fR. As such, all values referenced in it should +have reference counts greater than zero; this is usually a non-issue. .SH "SEE ALSO" Tcl_GetIndexFromObj(3) .SH KEYWORDS diff --git a/doc/clock.n b/doc/clock.n index e2f4402..2264938 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -868,7 +868,7 @@ the minus sign one west of Greenwich. A time zone string conforming to the Posix specification of the \fBTZ\fR environment variable will be recognized. The specification may be found at -\fIhttp://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR. +\fIhttps://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR. .PP If the Posix time zone string contains a DST (Daylight Savings Time) part, but doesn't contain a rule stating when DST starts or ends, @@ -892,7 +892,7 @@ to use it as a location name, as above. .SH "LOCALIZATION" .PP Developers wishing to localize the date and time formatting and parsing -are referred to \fIhttp://tip.tcl.tk/173\fR for a +are referred to \fIhttps://tip.tcl-lang.org/173\fR for a specification. .SH "FREE FORM SCAN" .PP diff --git a/doc/cookiejar.n b/doc/cookiejar.n index 0d8b81a..7d2f46b 100644 --- a/doc/cookiejar.n +++ b/doc/cookiejar.n @@ -182,7 +182,7 @@ set cookiedb ~/.tclcookies.db http::configure -cookiejar [\fBhttp::cookiejar new\fR $cookiedb] # No further explicit steps are required to use cookies -set tok [http::geturl http://core.tcl.tk/] +set tok [http::geturl http://core.tcl-lang.org/] .CE .PP To only allow a particular domain to use cookies, perhaps because you only @@ -205,7 +205,7 @@ set cookiedb ~/.tclcookies.db http::configure -cookiejar [MyCookieJar new $cookiedb] # No further explicit steps are required to use cookies -set tok [http::geturl http://core.tcl.tk/] +set tok [http::geturl http://core.tcl-lang.org/] .CE .SH "SEE ALSO" http(n), oo::class(n), sqlite3(n) @@ -172,7 +172,7 @@ particularly important website: .PP .CS package require dde -\fBdde execute\fR -async iexplore WWW_OpenURL http://www.tcl.tk/ +\fBdde execute\fR -async iexplore WWW_OpenURL http://www.tcl-lang.org/ .CE .SH "SEE ALSO" tk(n), winfo(n), send(n) diff --git a/doc/encoding.n b/doc/encoding.n index 5aac181..e78a8e7 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -81,29 +81,13 @@ omitted then the command returns the current system encoding. The system encoding is used whenever Tcl passes strings to system calls. .SH EXAMPLE .PP -It is common practice to write script files using a text editor that -produces output in the euc-jp encoding, which represents the ASCII -characters as singe bytes and Japanese characters as two bytes. This -makes it easy to embed literal strings that correspond to non-ASCII -characters by simply typing the strings in place in the script. -However, because the \fBsource\fR command always reads files using the -current system encoding, Tcl will only source such files correctly -when the encoding used to write the file is the same. This tends not -to be true in an internationalized setting. For example, if such a -file was sourced in North America (where the ISO8859\-1 is normally -used), each byte in the file would be treated as a separate character -that maps to the 00 page in Unicode. The resulting Tcl strings will -not contain the expected Japanese characters. Instead, they will -contain a sequence of Latin-1 characters that correspond to the bytes -of the original string. The \fBencoding\fR command can be used to -convert this string to the expected Japanese Unicode characters. For -example, +The following example converts a byte sequence in Japanese euc-jp encoding to a TCL string: .PP .CS set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"] .CE .PP -would return the Unicode string +The result is the unicode codepoint: .QW "\eu306F" , which is the Hiragana letter HA. .SH "SEE ALSO" @@ -22,6 +22,10 @@ of one or more subprocesses to execute. The arguments take the form of a standard shell pipeline where each \fIarg\fR becomes one word of a command, and each distinct command becomes a subprocess. +The result of the command is the standard output of the final subprocess in +the pipeline, interpreted using the system \fBencoding\fR; to use any other +encoding (especially including binary data), the pipeline must be +\fBopen\fRed, configured and read explicitly. .PP If the initial arguments to \fBexec\fR start with \fB\-\fR then they are treated as command-line switches and are not part @@ -411,7 +415,9 @@ With the file \fIcmp.bat\fR looking something like: .CS @gcc %* .CE +.PP or like another variant using single parameters: +.PP .CS @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9 .CE @@ -6,14 +6,14 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH "http" n 2.9 http "Tcl Bundled Packages" +.TH "http" n 2.10 http "Tcl Bundled Packages" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME http \- Client-side implementation of the HTTP/1.1 protocol .SH SYNOPSIS -\fBpackage require http\fI ?\fB2.9\fR? +\fBpackage require http\fI ?\fB2.10\fR? .\" See Also -useragent option documentation in body! .sp \fB::http::config\fR ?\fI\-option value\fR ...? @@ -13,22 +13,21 @@ load \- Load machine code and initialize new commands .SH SYNOPSIS \fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName\fR .br -\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName\fR +\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName prefix\fR .br -\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName packageName interp\fR +\fBload\fR ?\fB\-global\fR? ?\fB\-lazy\fR? ?\fB\-\-\fR? \fIfileName prefix interp\fR .BE .SH DESCRIPTION .PP This command loads binary code from a file into the application's address space and calls an initialization procedure -in the package to incorporate it into an interpreter. \fIfileName\fR +in the library to incorporate it into an interpreter. \fIfileName\fR is the name of the file containing the code; its exact form varies from system to system but on most systems it is a shared library, such as a \fB.so\fR file under Solaris or a DLL under Windows. -\fIpackageName\fR is the name of the package, and is used to -compute the name of an initialization procedure. +\fIprefix\fR is used to compute the name of an initialization procedure. \fIinterp\fR is the path name of the interpreter into which to load -the package (see the \fBinterp\fR manual entry for details); +the library (see the \fBinterp\fR manual entry for details); if \fIinterp\fR is omitted, it defaults to the interpreter in which the \fBload\fR command was invoked. .PP @@ -37,32 +36,32 @@ one of two initialization procedures will be invoked in the new code. Typically the initialization procedure will add new commands to a Tcl interpreter. The name of the initialization procedure is determined by -\fIpackageName\fR and whether or not the target interpreter +\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 \fIpkg\fB_Init\fR, where \fIpkg\fR -is the same as \fIpackageName\fR except that the first letter is +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 \fIpackageName\fR is +are converted to lower case. For example, if \fIprefix\fR is \fBfoo\fR or \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 \fIpkg\fB_SafeInit\fR -instead of \fIpkg\fB_Init\fR. -The \fIpkg\fB_SafeInit\fR function should be written carefully, so that it +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 initializes the safe interpreter only with partial functionality provided -by the package that is safe for use by untrusted code. For more information +by the library that is safe for use by untrusted code. For more information on Safe\-Tcl, see the \fBsafe\fR manual entry. .PP The initialization procedure must match the following prototype: .PP .CS -typedef int \fBTcl_PackageInitProc\fR( +typedef int \fBTcl_LibraryInitProc\fR( Tcl_Interp *\fIinterp\fR); .CE .PP The \fIinterp\fR argument identifies the interpreter in which the -package is to be loaded. The initialization procedure must return +library is to be loaded. The initialization procedure must return \fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed successfully; in the event of an error it should set the interpreter's result to point to an error message. The result of the \fBload\fR command @@ -74,37 +73,37 @@ interpreters, then the first \fBload\fR will load the code and call the initialization procedure; subsequent \fBload\fRs will call the initialization procedure without loading the code again. For Tcl versions lower than 8.5, it is not possible to unload or reload a -package. From version 8.5 however, the \fBunload\fR command allows the unloading +library. From version 8.5 however, the \fBunload\fR command allows the unloading of libraries loaded with \fBload\fR, for libraries that are aware of the Tcl's unloading mechanism. .PP -The \fBload\fR command also supports packages that are statically -linked with the application, if those packages have been registered -by calling the \fBTcl_StaticPackage\fR procedure. -If \fIfileName\fR is an empty string, then \fIpackageName\fR must +The \fBload\fR command also supports libraries that are statically +linked with the application, if those libraries have been registered +by calling the \fBTcl_StaticLibrary\fR procedure. +If \fIfileName\fR is an empty string, then \fIprefix\fR must be specified. .PP -If \fIpackageName\fR is omitted or specified as an empty string, -Tcl tries to guess the name of the package. -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 \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 as the module name. -For example, the command \fBload libtclxyz4.2.so\fR uses the module -name \fBxyz\fR and the command \fBload bin/last.so {}\fR uses the -module name \fBlast\fR. -.PP -If \fIfileName\fR is an empty string, then \fIpackageName\fR must +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 +\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. +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. +.PP +If \fIfileName\fR is an empty string, then \fIprefix\fR must be specified. -The \fBload\fR command first searches for a statically loaded package -(one that has been registered by calling the \fBTcl_StaticPackage\fR +The \fBload\fR command first searches for a statically loaded library +(one that has been registered by calling the \fBTcl_StaticLibrary\fR procedure) by that name; if one is found, it is used. Otherwise, the \fBload\fR command searches for a dynamically loaded -package by that name, and uses it if it is found. If several +library by that name, and uses it if it is found. If several different files have been \fBload\fRed with different versions of -the package, Tcl picks the file that was loaded first. +the library, Tcl picks the file that was loaded first. .PP If \fB\-global\fR is specified preceding the filename, all symbols found in the shared library are exported for global use by other @@ -112,7 +111,7 @@ libraries. The option \fB\-lazy\fR delays the actual loading of symbols until their first actual use. The options may be abbreviated. The option \fB\-\-\fR indicates the end of the options, and should be used if you wish to use a filename which starts with \fB\-\fR -and you provide a packageName to the \fBload\fR command. +and you provide a prefix to the \fBload\fR command. .PP On platforms which do not support the \fB\-global\fR or \fB\-lazy\fR options, the options still exist but have no effect. Note that use @@ -155,7 +154,7 @@ The following is a minimal extension: .CS #include <tcl.h> #include <stdio.h> -static int fooCmd(ClientData clientData, +static int fooCmd(void *clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) { printf("called with %d arguments\en", objc); return TCL_OK; @@ -189,7 +188,7 @@ switch $tcl_platform(platform) { foo .CE .SH "SEE ALSO" -info sharedlibextension, package(n), Tcl_StaticPackage(3), safe(n) +info sharedlibextension, package(n), Tcl_StaticLibrary(3), safe(n) .SH KEYWORDS binary code, dynamic library, load, safe interpreter, shared library '\"Local Variables: diff --git a/doc/msgcat.n b/doc/msgcat.n index 74a7020..1384fa8 100644 --- a/doc/msgcat.n +++ b/doc/msgcat.n @@ -219,7 +219,7 @@ As an example, the user may prefer French or English text. This may be configure .PP .VS "TIP 499" .TP -\fB::msgcat:mcloadedlocales subcommand\fR ?\fIlocale\fR? +\fB::msgcat::mcloadedlocales subcommand\fR ?\fIlocale\fR? . This group of commands manage the list of loaded locales for packages not setting a package locale. .PP @@ -72,7 +72,7 @@ indicate that the opened channel should be configured as if with the reading or writing of binary data. .PP In the second form, \fIaccess\fR consists of a list of any of the -following flags, all of which have the standard POSIX meanings. +following flags, most of which have the standard POSIX meanings. One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR. .TP 15 \fBRDONLY\fR @@ -453,6 +453,12 @@ application are competing for the console at the same time. If the command pipeline is started from a script, so that Tcl is not accessing the console, or if the command pipeline does not use standard input or output, but is redirected from or to a file, then the above problems do not occur. +.PP +Files opened in the +.QW \fBa\fR +mode or with the \fBAPPEND\fR flag set are implemented by seeking immediately +before each write, which is not an atomic operation and does not carry the +guarantee of strict appending that is present on POSIX platforms. .RE .TP \fBUnix\fR\0\0\0\0\0\0\0 @@ -527,6 +533,19 @@ Note that the equivalent options exist on Unix, but are on the serial channel type. .VE "8.7, TIP 160" .SH "EXAMPLES" +Open a file for writing, forcing it to be created and raising an error if it +already exists. +.PP +.CS +set myNewFile [\fBopen\fR filename.txt {WRONLY CREAT EXCL}] +.CE +.PP +Open a file for writing as a log file. +.PP +.CS +set myLogFile [\fBopen\fR filename.log "a"] +fconfigure $myLogFile -buffering line +.CE .PP Open a command pipeline and catch any errors: .PP @@ -538,6 +557,18 @@ if {[catch {close $fl} err]} { } .CE .PP +Open a command pipeline and read binary data from it. Note the unusual form +with +.QW |[list +that handles non-trivial edge cases with arguments that potentially have +spaces in. +.PP +.CS +set fl [\fBopen\fR |[list create_image_data $input] "rb"] +set binData [read $fl] +close $fl +.CE +.PP .VS "8.7, TIP 160" Read a password securely from the user (assuming that the script is being run interactively): diff --git a/doc/packagens.n b/doc/packagens.n index 65535ef..d55151f 100644 --- a/doc/packagens.n +++ b/doc/packagens.n @@ -29,7 +29,7 @@ This parameter specifies the name of the package. It is required. This parameter specifies the version of the package. It is required. .TP \fB\-load \fIfilespec\fR -This parameter specifies a binary library that must be loaded with the +This parameter specifies a library that must be loaded with the \fBload\fR command. \fIfilespec\fR is a list with two elements. The first element is the name of the file to load. The second, optional element is a list of commands supplied by loading that file. If the diff --git a/doc/re_syntax.n b/doc/re_syntax.n index 9a9e2b0..ef8c570 100644 --- a/doc/re_syntax.n +++ b/doc/re_syntax.n @@ -446,7 +446,7 @@ commonly-used character classes: .TP \fB\ew\fR . -\fB[[:alnum:]_]\fR (note underscore) +\fB[[:alnum:]_\eu203F\eu2040\eu2054\euFE33\euFE34\euFE4D\euFE4E\euFE4F\euFF3F]\fR (including punctuation connector characters) .TP \fB\eD\fR . @@ -458,7 +458,7 @@ commonly-used character classes: .TP \fB\eW\fR . -\fB[^[:alnum:]_]\fR (note underscore) +\fB[^[:alnum:]_\eu203F\eu2040\eu2054\euFE33\euFE34\euFE4D\euFE4E\euFE4F\euFF3F]\fR (including punctuation connector characters) .RE .PP Within bracket expressions, diff --git a/doc/refchan.n b/doc/refchan.n index 8737556..c17117d 100644 --- a/doc/refchan.n +++ b/doc/refchan.n @@ -322,6 +322,19 @@ invocation (usually \fBfconfigure\fR or \fBchan configure\fR) will appear to have thrown this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, etc.) is treated as and converted to an error. .RE +.TP +\fIcmdPrefix \fBtruncate\fR \fIchannelId length\fR +. +This \fIoptional\fR subcommand handles changing the length of the +underlying data stream for the channel \fIchannelId\fR. Its length +gets set to \fIlength\fR. +.RS +.PP +If the subcommand throws an error the command which caused its +invocation (usually \fBchan truncate\fR) will appear to have thrown +this error. Any exception beyond \fBerror\fR (e.g.,\ \fBbreak\fR, +etc.) is treated as and converted to an error. +.RE .SH NOTES Some of the functions supported in channels defined in Tcl's C interface are not available to channels reflected to the Tcl level. diff --git a/doc/string.n b/doc/string.n index 7cd53ca..aefe485 100644 --- a/doc/string.n +++ b/doc/string.n @@ -319,9 +319,10 @@ specified as for the \fBindex\fR method. If \fInewstring\fR is specified, then it is placed in the removed character range. If \fIfirst\fR is less than zero then it is treated as if it were zero, and if \fIlast\fR is greater than or equal to the length of the string -then it is treated as if it were \fBend\fR. If \fIfirst\fR is greater -than \fIlast\fR or the length of the initial string, or \fIlast\fR is -less than 0, then the initial string is returned untouched. +then it is treated as if it were \fBend\fR. The initial string is +returned untouched, if \fIfirst\fR is greater than \fIlast\fR, or if +\fIfirst\fR is equal to or greater than the length of the initial string, +or \fIlast\fR is less than 0. .TP \fBstring reverse \fIstring\fR . @@ -404,7 +405,7 @@ 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 CESU\-8 with a +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 @@ -413,10 +414,10 @@ 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 it is likely that this subcommand will be -withdrawn in a future version of Tcl. It is better to use the -\fBencoding convertto\fR command to convert a string to a known -encoding and then apply \fBstring length\fR to that. +\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] @@ -298,9 +298,9 @@ environment variables: .SH "SEE ALSO" package(n), Tcl Improvement Proposal #189 .QW "\fITcl Modules\fR" -(online at http://tip.tcl.tk/189.html), Tcl Improvement Proposal #190 +(online at https://tip.tcl-lang.org/189.html), Tcl Improvement Proposal #190 .QW "\fIImplementation Choices for Tcl Modules\fR" -(online at http://tip.tcl.tk/190.html) +(online at https://tip.tcl-lang.org/190.html) .SH "KEYWORDS" modules, package .\" Local Variables: diff --git a/doc/unload.n b/doc/unload.n index 0a8e99b..00b709b 100644 --- a/doc/unload.n +++ b/doc/unload.n @@ -13,9 +13,9 @@ unload \- Unload machine code .SH SYNOPSIS \fBunload \fR?\fIswitches\fR? \fIfileName\fR .br -\fBunload \fR?\fIswitches\fR? \fIfileName packageName\fR +\fBunload \fR?\fIswitches\fR? \fIfileName prefix\fR .br -\fBunload \fR?\fIswitches\fR? \fIfileName packageName interp\fR +\fBunload \fR?\fIswitches\fR? \fIfileName prefix interp\fR .BE .SH DESCRIPTION .PP @@ -24,7 +24,7 @@ with \fBload\fR from the application's address space. \fIfileName\fR is the name of the file containing the library file to be unload; it must be the same as the filename provided to \fBload\fR for loading the library. -The \fIpackageName\fR argument is the name of the package (as +The \fIprefix\fR argument is the prefix (as determined by or passed to \fBload\fR), and is used to compute the name of the unload procedure; if not supplied, it is computed from \fIfileName\fR in the same manner as \fBload\fR. @@ -66,12 +66,12 @@ proper reference count. \fBunload\fR works in the opposite direction. As a first step, \fBunload\fR will check whether the library is unloadable: an unloadable library exports a special unload procedure. The name of the unload procedure is determined by -\fIpackageName\fR and whether or not the target interpreter +\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 \fIpkg\fB_Unload\fR, where \fIpkg\fR -is the same as \fIpackageName\fR except that the first letter is +procedure will have the form \fIpfx\fB_Unload\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 \fIpackageName\fR is +are converted to lower case. For example, if \fIprefix\fR is \fBfoo\fR or \fBFOo\fR, the initialization procedure's name will be \fBFoo_Unload\fR. If the target interpreter is a safe interpreter, then the name @@ -90,7 +90,7 @@ detached from the process. The unload procedure must match the following prototype: .PP .CS -typedef int \fBTcl_PackageUnloadProc\fR( +typedef int \fBTcl_LibraryUnloadProc\fR( Tcl_Interp *\fIinterp\fR, int \fIflags\fR); .CE @@ -114,19 +114,20 @@ the \fIflags\fR argument will be set to \fBTCL_UNLOAD_DETACH_FROM_PROCESS\fR. .PP The \fBunload\fR command cannot unload libraries that are statically linked with the application. -If \fIfileName\fR is an empty string, then the \fIpackageName\fR argument must +If \fIfileName\fR is an empty string, then the \fIprefix\fR argument must be specified. .PP -If \fIpackageName\fR is omitted or specified as an empty string, -Tcl tries to guess the name of the package. -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 \fIfileName\fR, strip off the first -three characters if they are \fBlib\fR, and use any following -alphabetic and underline characters as the module name. -For example, the command \fBunload libxyz4.2.so\fR uses the module -name \fBxyz\fR and the command \fBunload bin/last.so {}\fR uses the -module name \fBlast\fR. +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 +\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. +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. .SH "PORTABILITY ISSUES" .TP \fBUnix\fR\0\0\0\0\0 diff --git a/doc/zipfs.n b/doc/zipfs.n index da2e026..a75a70b 100644 --- a/doc/zipfs.n +++ b/doc/zipfs.n @@ -84,7 +84,7 @@ Return a list of all files in the mounted zipfs, or just those matching \fIpattern\fR (optionally controlled by the option parameters). The order of the names in the list is arbitrary. .TP -\fBzipfs mount ?\fImountpoint\fR? ?\fIzipfile\fR? ?\fIpassword\fR? +\fBzipfs mount\fR ?\fImountpoint\fR? ?\fIzipfile\fR? ?\fIpassword\fR? . The \fBzipfs mount\fR command mounts a ZIP archive file as a Tcl virtual filesystem at \fImountpoint\fR. After this command executes, files contained @@ -146,6 +146,8 @@ the ZIP archive, otherwise the file returned by \fBinfo nameofexecutable\fR (see \fBzipfs mkkey\fR) is placed between the image and ZIP chunks of the output file and the contents of the ZIP chunk are protected with that password. +If the starting image has a ZIP archive already attached to it, it is removed +from the copy in \fIoutfile\fR before the new ZIP archive is added. .PP If there is a file, \fBmain.tcl\fR, in the root directory of the resulting archive and the image file that the archive is attached to is a \fBtclsh\fR |