From a250b602bbacce9038f853923b404d201515d375 Mon Sep 17 00:00:00 2001 From: hobbs Date: Tue, 26 Feb 2002 02:22:20 +0000 Subject: * doc/Alloc.3: * doc/LinkVar.3: * doc/ObjectType.3: * doc/PkgRequire.3: * doc/Preserve.3: * doc/TCL_MEM_DEBUG.3: Updated documentation to describe the ckalloc, ckfree, ckrealloc, attemptckalloc, and attemptckrealloc macros, and to accurately describe when and how they are used. [Bug #497459] (dgp) --- doc/Alloc.3 | 32 +++++++++++++++++++++++++++++--- doc/LinkVar.3 | 4 ++-- doc/ObjectType.3 | 6 +++--- doc/PkgRequire.3 | 4 ++-- doc/Preserve.3 | 6 +++--- doc/TCL_MEM_DEBUG.3 | 4 ++-- 6 files changed, 41 insertions(+), 15 deletions(-) diff --git a/doc/Alloc.3 b/doc/Alloc.3 index ff7abf8..a671564 100644 --- a/doc/Alloc.3 +++ b/doc/Alloc.3 @@ -4,13 +4,13 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Alloc.3,v 1.5 2001/04/06 23:14:08 andreas_kupries Exp $ +'\" RCS: @(#) $Id: Alloc.3,v 1.6 2002/02/26 02:22:20 hobbs Exp $ '\" .so man.macros .TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc \- allocate or free heap memory +Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory .SH SYNOPSIS .nf \fB#include \fR @@ -18,6 +18,7 @@ Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc \- alloca char * \fBTcl_Alloc\fR(\fIsize\fR) .sp +void \fBTcl_Free\fR(\fIptr\fR) .sp char * @@ -28,6 +29,21 @@ char * .sp char * \fBTcl_AttemptRealloc\fR(\fIptr, size\fR) +.sp +char * +\fBckalloc\fR(\fIsize\fR) +.sp +void +\fBckfree\fR(\fIptr\fR) +.sp +char * +\fBckrealloc\fR(\fIptr, size\fR) +.sp +char * +\fBattemptckalloc\fR(\fIsize\fR) +.sp +char * +\fBattemptckrealloc\fR(\fIptr, size\fR) .SH ARGUMENTS .AS char *size .AP int size in @@ -60,5 +76,15 @@ function to \fBTcl_Alloc\fR and \fBTcl_Realloc\fR, except that \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR will not cause the Tcl interpreter to \fBpanic\fR if the memory allocation fails. If the allocation fails, these functions will return NULL. +.PP +The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR, +\fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented +as macros. Normally, they are synonyms for the correponding +procedures documented on this page. When Tcl and all modules +calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however, +these macros are redefined to be special debugging versions of +of these procedures. To support Tcl's memory debugging within a +module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc. + .SH KEYWORDS -alloc, allocation, free, malloc, memory, realloc +alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG diff --git a/doc/LinkVar.3 b/doc/LinkVar.3 index 48d4f9e..7d07d01 100644 --- a/doc/LinkVar.3 +++ b/doc/LinkVar.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: LinkVar.3,v 1.4 2002/02/15 14:28:47 dkf Exp $ +'\" RCS: @(#) $Id: LinkVar.3,v 1.5 2002/02/26 02:22:20 hobbs Exp $ '\" .so man.macros .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" @@ -97,7 +97,7 @@ Tcl errors. The C variable is of type \fBchar *\fR. .VS If its value is not null then it must be a pointer to a string -allocated with \fBTcl_Alloc\fR. +allocated with \fBTcl_Alloc\fR or \fBckalloc\fR. .VE Whenever the Tcl variable is modified the current C string will be freed and new memory will be allocated to hold a copy of the variable's diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index eee70e5..17ce609 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ObjectType.3,v 1.5 2002/01/25 21:36:09 dgp Exp $ +'\" RCS: @(#) $Id: ObjectType.3,v 1.6 2002/02/26 02:22:20 hobbs Exp $ '\" .so man.macros .TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures" @@ -147,8 +147,8 @@ We require the string representation's byte array to have a null after the last byte, at offset \fIlength\fR; this allows string representations that do not contain null bytes to be treated as conventional null character-terminated C strings. -Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR. -Note that \fIupdateStringProc\fRs must allocate +Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR +or \fBckalloc\fR. Note that \fIupdateStringProc\fRs must allocate enough storage for the string's bytes and the terminating null byte. The \fIupdateStringProc\fR for Tcl's builtin list type, for example, builds an array of strings for each element object diff --git a/doc/PkgRequire.3 b/doc/PkgRequire.3 index 3164259..f16288a 100644 --- a/doc/PkgRequire.3 +++ b/doc/PkgRequire.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: PkgRequire.3,v 1.5 2001/04/04 16:07:20 kennykb Exp $ +'\" RCS: @(#) $Id: PkgRequire.3,v 1.6 2002/02/26 02:22:20 hobbs Exp $ '\" .so man.macros .TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures" @@ -33,7 +33,7 @@ int int \fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR) .SH ARGUMENTS -.AS Tcl_FreeProc clientDataPtr +.AS ClientData clientDataPtr .AP Tcl_Interp *interp in Interpreter where package is needed or available. .AP "CONST char" *name in diff --git a/doc/Preserve.3 b/doc/Preserve.3 index b240022..b0197db 100644 --- a/doc/Preserve.3 +++ b/doc/Preserve.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Preserve.3,v 1.3 2001/12/13 00:58:26 hobbs Exp $ +'\" RCS: @(#) $Id: Preserve.3,v 1.4 2002/02/26 02:22:20 hobbs Exp $ '\" .so man.macros .TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures" @@ -91,8 +91,8 @@ reasons, but the value is the same. .PP When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR refers to storage allocated and returned by a prior call to -\fBTcl_Alloc\fR or another function of the Tcl library, then the -\fIfreeProc\fR argument should be given the special value of +\fBTcl_Alloc\fR, \fBckalloc\fR, or another function of the Tcl library, +then the \fIfreeProc\fR argument should be given the special value of \fBTCL_DYNAMIC\fR. .PP This mechanism can be used to solve the problem described above diff --git a/doc/TCL_MEM_DEBUG.3 b/doc/TCL_MEM_DEBUG.3 index 8d5646b..4d1ce8e 100644 --- a/doc/TCL_MEM_DEBUG.3 +++ b/doc/TCL_MEM_DEBUG.3 @@ -3,7 +3,7 @@ '\" Copyright (c) 2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.4 2001/12/10 15:50:46 dgp Exp $ +'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.5 2002/02/26 02:22:20 hobbs Exp $ '\" .so man.macros .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures" @@ -74,7 +74,7 @@ of the caller, but they can actually be anything you want. Remember to remove the calls after you find the problem. .SH "SEE ALSO" -memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory +ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory .SH KEYWORDS memory, debug -- cgit v0.12