From 0891377fe0b57a8f6526148a40d218fcbccf3c58 Mon Sep 17 00:00:00 2001 From: dkf Date: Mon, 5 Jun 2006 10:04:32 +0000 Subject: Documentation improvements (including Tcl_Realloc(NULL,x) behaviour) --- ChangeLog | 6 ++++++ doc/Alloc.3 | 10 ++++++---- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/ChangeLog b/ChangeLog index dca36e9..9c89faa 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2006-06-05 Donal K. Fellows + + * doc/Alloc.3: Added documentation of promise that Tcl_Realloc(NULL,x) + is the same as Tcl_Alloc(x), as discussed in comp.lang.tcl. Also fixed + nonsense sentence to say something meaningful. + 2006-05-29 Jeff Hobbs * generic/tcl.h (Tcl_DecrRefCount): use if/else construct to allow diff --git a/doc/Alloc.3 b/doc/Alloc.3 index 541f300..2027d6c 100644 --- a/doc/Alloc.3 +++ b/doc/Alloc.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: Alloc.3,v 1.9 2004/09/06 09:44:56 dkf Exp $ +'\" RCS: @(#) $Id: Alloc.3,v 1.10 2006/06/05 10:04:33 dkf Exp $ '\" .so man.macros .TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures" @@ -69,15 +69,17 @@ further allocation. \fBTcl_Realloc\fR changes the size of the block pointed to by \fIptr\fR to \fIsize\fR bytes and returns a pointer to the new block. The contents will be unchanged up to the lesser of the new and old -sizes. The returned location may be different from \fIptr\fR. +sizes. The returned location may be different from \fIptr\fR. If +\fIptr\fR is NULL, this is equivalent to calling \fBTcl_Alloc\fR with +just the \fIsize\fR argument. .PP \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR are identical in 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. Note that on some -platforms, attempting to allocate a block of memory will also cause -these functions to return NULL. +platforms, but not all, attempting to allocate a zero-sized block of +memory will also cause these functions to return NULL. .PP The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR, \fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented -- cgit v0.12