chiark - git - mdw - 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 .\" @xmalloc
  33 .\" @xrealloc
  34 .\" @xstrdup
  35 .\" @xfree
  36 .\" @x_alloc
  37 .\" @x_strdup
  38 .\" @x_realloc
  39 .\" @x_free
  40 .
  41 .\"--------------------------------------------------------------------------
  42 .SH NAME
  43 alloc \- mLib low-level memory allocation
  44 .
  45 .\"--------------------------------------------------------------------------
  46 .SH SYNOPSIS
  47 .
  48 .nf
  49 .B "#include <mLib/alloc.h>"
  50 .PP
  51 .BI "void *x_alloc(arena *" a ", size_t " sz );
  52 .BI "char *x_strdup(arena *" a ", const char *" s );
  53 .BI "void *x_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  54 .BI "void x_free(arena *" a ", void *" p );
  55 .PP
  56 .BI "void *xmalloc(size_t " sz );
  57 .BI "void *xrealloc(void *" p ", size_t " sz ", size_t " osz );
  58 .BI "char *xstrdup(const char *" s );
  59 .BI "void xfree(void *" p );
  60 .fi
  61 .
  62 .\"--------------------------------------------------------------------------
  63 .SH DESCRIPTION
  64 .
  65 These functions allocate and return blocks of memory.  If insufficient
  66 memory is available, an
  67 .B EXC_NOMEM
  68 exception is raised.
  69 .PP
  70 The functions
  71 .BR x_alloc ,
  72 .BR x_realloc ,
  73 .BR x_strdup
  74 and
  75 .BR x_free
  76 work with a given arena (see
  77 .BR arena (3)).
  78 .B x_alloc
  79 allocates a block of a given size;
  80 .B x_realloc
  81 resizes an allocated block;
  82 .B x_strdup
  83 allocates a copy of a null-terminated string; and
  84 .B x_free
  85 releases a block.
  86 .RB ( x_free
  87 is supplied for orthogonality's sake: it's equivalent to calling the
  88 .BR A_FREE (3)
  89 macro.)
  90 .PP
  91 The
  92 .BR xmalloc ,
  93 .BR xrealloc ,
  94 .BR xstrdup
  95 and
  96 .BR xfree
  97 macros are provided as a convenient interface to failsafe memory
  98 allocation from the current arena
  99 .BR arena_global (3).
 100 .
 101 .\"--------------------------------------------------------------------------
 102 .SH "SEE ALSO"
 103 .
 104 .BR arena (3),
 105 .BR exc (3),
 106 .BR mLib (3).
 107 .
 108 .\"--------------------------------------------------------------------------
 109 .SH AUTHOR
 110 .
 111 Mark Wooding, <mdw@distorted.org.uk>
 112 .
 113 .\"----- That's all, folks --------------------------------------------------