mdw@git.distorted.org.uk Git - mLib/blob - mem/alloc.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for general memory allocation
   4 .\"
   5 .\" (c) 1999--2002, 2005, 2009, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH alloc 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @x_alloc
  33 .\" @x_allocv
  34 .\" @X_NEW
  35 .\" @X_NEWV
  36 .\" @x_strdup
  37 .\" @x_realloc
  38 .\" @x_reallocv
  39 .\" @X_RENEWV
  40 .\" @x_free
  41 .
  42 .\" @xmalloc
  43 .\" @xmallocv
  44 .\" @XNEW
  45 .\" @XNEWV
  46 .\" @xstrdup
  47 .\" @xrealloc
  48 .\" @xreallocv
  49 .\" @XRENEWV
  50 .\" @xfree
  51 .
  52 .\"--------------------------------------------------------------------------
  53 .SH NAME
  54 alloc \- mLib low-level memory allocation
  55 .
  56 .\"--------------------------------------------------------------------------
  57 .SH SYNOPSIS
  58 .
  59 .nf
  60 .B "#include <mLib/alloc.h>"
  61 .PP
  62 .BI "void *x_alloc(arena *" a ", size_t " sz );
  63 .BI "void *x_allocv(arena *" a ", size_t " n ", size_t " sz );
  64 .BI "X_NEW(" type " *" p ", arena *" a );
  65 .BI "X_NEWV(" type " *" p ", arena *" a ", size_t " n );
  66 .BI "void *x_allocv(arena *" a ", size_t " n ", size_t " sz );
  67 .BI "char *x_strdup(arena *" a ", const char *" s );
  68 .BI "void *x_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  69 .ta \w'\fBvoid *x_reallocv('u
  70 .BI "void *x_reallocv(arena *" a ", void *" p ,
  71 .BI "   size_t " n ", size_t " on ", size_t " sz );
  72 .BI "X_RENEWV(" type " *" p ", arena *" a ", size_t " n ", size_t " on );
  73 .BI "void x_free(arena *" a ", void *" p );
  74 .PP
  75 .BI "void *xmalloc(size_t " sz );
  76 .BI "void *xmallocv(size_t " n ", size_t " sz );
  77 .BI "XNEW(" type " *" p );
  78 .BI "XNEWV(" type " *" p ", size_t " n );
  79 .BI "char *xstrdup(const char *" s );
  80 .BI "void *xrealloc(void *" p ", size_t " sz ", size_t " osz );
  81 .BI "void *xreallocv(void *" p ", size_t " n ", size_t " on ", size_t " sz );
  82 .BI "XRENEWV(" type " *" p ", size_t " n ", size_t " on );
  83 .BI "void xfree(void *" p );
  84 .fi
  85 .
  86 .\"--------------------------------------------------------------------------
  87 .SH DESCRIPTION
  88 .
  89 These functions allocate and return blocks of memory.  If insufficient
  90 memory is available, an
  91 .B EXC_NOMEM
  92 exception is raised.
  93 .PP
  94 The functions
  95 .BR x_alloc ,
  96 .BR x_allocv ,
  97 .BR x_realloc ,
  98 .BR x_reallocv ,
  99 .BR x_strdup
 100 and
 101 .BR x_free
 102 work with a given arena (see
 103 .BR arena (3)).
 104 .B x_alloc
 105 allocates a block of a given size;
 106 .B x_realloc
 107 resizes an allocated block;
 108 .B x_strdup
 109 allocates a copy of a null-terminated string; and
 110 .B x_free
 111 releases a block.
 112 .RB ( x_free
 113 is supplied for orthogonality's sake: it's equivalent to calling the
 114 .BR A_FREE (3)
 115 macro.)
 116 The
 117 .B x_allocv
 118 and
 119 .B x_reallocv
 120 functions
 121 allocate space for arrays.
 122 They check for potential overflow before proceeding.
 123 .PP
 124 The
 125 .B X_NEW
 126 macro sets a pointer
 127 .I p
 128 to point to freshly allocated memory large enough for the type that
 129 .I p
 130 points to;
 131 The
 132 .B X_NEWV
 133 macro sets
 134 .I p
 135 to point to freshly allocated memory large enough for
 136 .I n
 137 elements, each of the type that
 138 .I p
 139 points to.
 140 The
 141 .B X_RENEWV
 142 resizes the block that
 143 .I p
 144 points to, so that it now has space for
 145 .I n
 146 elements of the appropriate type, having previously had space for
 147 .I on
 148 elements;
 149 .PP
 150 The
 151 .BR xmalloc ,
 152 .BR xmallocv ,
 153 .BR XNEW ,
 154 .BR XNEWV ,
 155 .BR xrealloc ,
 156 .BR xreallocv ,
 157 .BR XRENEWV ,
 158 .BR xstrdup
 159 and
 160 .BR xfree
 161 macros are provided as a convenient interface to failsafe memory
 162 allocation from the current arena
 163 .BR arena_global (3).
 164 .PP
 165 .
 166 .\"--------------------------------------------------------------------------
 167 .SH "SEE ALSO"
 168 .
 169 .BR arena (3),
 170 .BR exc (3),
 171 .BR mLib (3).
 172 .
 173 .\"--------------------------------------------------------------------------
 174 .SH AUTHOR
 175 .
 176 Mark Wooding, <mdw@distorted.org.uk>
 177 .
 178 .\"----- That's all, folks --------------------------------------------------