[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. |
---|
| 3 | '\" |
---|
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 6 | '\" |
---|
| 7 | '\" RCS: @(#) $Id: Alloc.3,v 1.10 2006/06/05 10:04:33 dkf Exp $ |
---|
| 8 | '\" |
---|
| 9 | .so man.macros |
---|
| 10 | .TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures" |
---|
| 11 | .BS |
---|
| 12 | .SH NAME |
---|
| 13 | Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory |
---|
| 14 | .SH SYNOPSIS |
---|
| 15 | .nf |
---|
| 16 | \fB#include <tcl.h>\fR |
---|
| 17 | .sp |
---|
| 18 | char * |
---|
| 19 | \fBTcl_Alloc\fR(\fIsize\fR) |
---|
| 20 | .sp |
---|
| 21 | void |
---|
| 22 | \fBTcl_Free\fR(\fIptr\fR) |
---|
| 23 | .sp |
---|
| 24 | char * |
---|
| 25 | \fBTcl_Realloc\fR(\fIptr, size\fR) |
---|
| 26 | .sp |
---|
| 27 | char * |
---|
| 28 | \fBTcl_AttemptAlloc\fR(\fIsize\fR) |
---|
| 29 | .sp |
---|
| 30 | char * |
---|
| 31 | \fBTcl_AttemptRealloc\fR(\fIptr, size\fR) |
---|
| 32 | .sp |
---|
| 33 | char * |
---|
| 34 | \fBckalloc\fR(\fIsize\fR) |
---|
| 35 | .sp |
---|
| 36 | void |
---|
| 37 | \fBckfree\fR(\fIptr\fR) |
---|
| 38 | .sp |
---|
| 39 | char * |
---|
| 40 | \fBckrealloc\fR(\fIptr, size\fR) |
---|
| 41 | .sp |
---|
| 42 | char * |
---|
| 43 | \fBattemptckalloc\fR(\fIsize\fR) |
---|
| 44 | .sp |
---|
| 45 | char * |
---|
| 46 | \fBattemptckrealloc\fR(\fIptr, size\fR) |
---|
| 47 | .SH ARGUMENTS |
---|
| 48 | .AS char *size |
---|
| 49 | .AP int size in |
---|
| 50 | Size in bytes of the memory block to allocate. |
---|
| 51 | .AP char *ptr in |
---|
| 52 | Pointer to memory block to free or realloc. |
---|
| 53 | .BE |
---|
| 54 | |
---|
| 55 | .SH DESCRIPTION |
---|
| 56 | .PP |
---|
| 57 | These procedures provide a platform and compiler independent interface |
---|
| 58 | for memory allocation. Programs that need to transfer ownership of |
---|
| 59 | memory blocks between Tcl and other modules should use these routines |
---|
| 60 | rather than the native \fBmalloc()\fR and \fBfree()\fR routines |
---|
| 61 | provided by the C run-time library. |
---|
| 62 | .PP |
---|
| 63 | \fBTcl_Alloc\fR returns a pointer to a block of at least \fIsize\fR |
---|
| 64 | bytes suitably aligned for any use. |
---|
| 65 | .PP |
---|
| 66 | \fBTcl_Free\fR makes the space referred to by \fIptr\fR available for |
---|
| 67 | further allocation. |
---|
| 68 | .PP |
---|
| 69 | \fBTcl_Realloc\fR changes the size of the block pointed to by |
---|
| 70 | \fIptr\fR to \fIsize\fR bytes and returns a pointer to the new block. |
---|
| 71 | The contents will be unchanged up to the lesser of the new and old |
---|
| 72 | sizes. The returned location may be different from \fIptr\fR. If |
---|
| 73 | \fIptr\fR is NULL, this is equivalent to calling \fBTcl_Alloc\fR with |
---|
| 74 | just the \fIsize\fR argument. |
---|
| 75 | .PP |
---|
| 76 | \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR are identical in |
---|
| 77 | function to \fBTcl_Alloc\fR and \fBTcl_Realloc\fR, except that |
---|
| 78 | \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR will not cause the Tcl |
---|
| 79 | interpreter to \fBpanic\fR if the memory allocation fails. If the |
---|
| 80 | allocation fails, these functions will return NULL. Note that on some |
---|
| 81 | platforms, but not all, attempting to allocate a zero-sized block of |
---|
| 82 | memory will also cause these functions to return NULL. |
---|
| 83 | .PP |
---|
| 84 | The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR, |
---|
| 85 | \fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented |
---|
| 86 | as macros. Normally, they are synonyms for the corresponding |
---|
| 87 | procedures documented on this page. When Tcl and all modules |
---|
| 88 | calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however, |
---|
| 89 | these macros are redefined to be special debugging versions |
---|
| 90 | of these procedures. To support Tcl's memory debugging within a |
---|
| 91 | module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc. |
---|
| 92 | |
---|
| 93 | .SH KEYWORDS |
---|
| 94 | alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG |
---|