tcl/doc/Alloc.3

   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$
   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.
  73 .PP
  74 \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR are identical in
  75 function to \fBTcl_Alloc\fR and \fBTcl_Realloc\fR, except that
  76 \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR will not cause the Tcl
  77 interpreter to \fBpanic\fR if the memory allocation fails.  If the
  78 allocation fails, these functions will return NULL.  Note that on some
  79 platforms, attempting to allocate a block of memory will also cause
  80 these functions to return NULL.
  81 .PP
  82 The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR,
  83 \fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented
  84 as macros.  Normally, they are synonyms for the corresponding
  85 procedures documented on this page.  When Tcl and all modules
  86 calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however,
  87 these macros are redefined to be special debugging versions of
  88 of these procedures.  To support Tcl's memory debugging within a
  89 module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc.
  90
  91 .SH KEYWORDS
  92 alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG