From 38a87927cf6adb2f3db0ee2a9ac195e4dd7853d4 Mon Sep 17 00:00:00 2001 From: pooryorick Date: Sun, 26 Mar 2023 22:18:05 +0000 Subject: Update reference-counting advice for Tcl_ObjSetVar2 and friends. --- doc/SetVar.3 | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/SetVar.3 b/doc/SetVar.3 index eb8333b..d061a2b 100644 --- a/doc/SetVar.3 +++ b/doc/SetVar.3 @@ -250,18 +250,18 @@ and \fBTcl_ObjGetVar2\fR is (if non-NULL) a value with a reference of at least 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. +may be an arbitrary reference count value. Its reference count is +incremented on success. On failure, if is reference count is zero, it is +decremented and freed so the caller need do nothing with it. .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. +The \fIpart1Ptr\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR can +have any reference count. These functions never modify it. .PP -The \fIpart2\fR argument to \fBTcl_ObjSetVar2\fR and \fBTcl_ObjGetVar2\fR, if +The \fIpart2Ptr\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). +retain a reference to it, particularly when it is used to create an array +element that did not previously exist, and decrementing the reference count +later would leave them pointing to a freed Tcl_Obj. .SH "SEE ALSO" Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar -- cgit v0.12