chiark - git - mdw - mLib/blob - man/alloc.3

   1 .\" -*-nroff-*-
   2 .TH alloc 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
   3 .\" @xmalloc
   4 .\" @xrealloc
   5 .\" @xstrdup
   6 .\" @xfree
   7 .\" @x_alloc
   8 .\" @x_strdup
   9 .\" @x_realloc
  10 .\" @x_free
  11 .SH NAME
  12 alloc \- mLib low-level memory allocation
  13 .SH SYNOPSIS
  14 .nf
  15 .B "#include <mLib/alloc.h>"
  16
  17 .BI "void *x_alloc(arena *" a ", size_t " sz );
  18 .BI "char *x_strdup(arena *" a ", const char *" s );
  19 .BI "void *x_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  20 .BI "void x_free(arena *" a ", void *" p );
  21
  22 .BI "void *xmalloc(size_t " sz );
  23 .BI "void *xrealloc(void *" p ", size_t " sz ", size_t " osz );
  24 .BI "char *xstrdup(const char *" s );
  25 .BI "void xfree(void *" p );
  26 .fi
  27 .SH DESCRIPTION
  28 These functions allocate and return blocks of memory.  If insufficient
  29 memory is available, an
  30 .B EXC_NOMEM
  31 exception is raised.
  32 .PP
  33 The functions
  34 .BR x_alloc ,
  35 .BR x_realloc ,
  36 .BR x_strdup
  37 and
  38 .BR x_free
  39 work with a given arena (see
  40 .BR arena (3)).
  41 .B x_alloc
  42 allocates a block of a given size;
  43 .B x_realloc
  44 resizes an allocated block;
  45 .B x_strdup
  46 allocates a copy of a null-terminated string; and
  47 .B x_free
  48 releases a block.
  49 .RB ( x_free
  50 is supplied for orthogonality's sake: it's equivalent to calling the
  51 .BR A_FREE (3)
  52 macro.)
  53 .PP
  54 The
  55 .BR xmalloc ,
  56 .BR xrealloc ,
  57 .BR xstrdup
  58 and
  59 .BR xfree
  60 macros are provided as a convenient interface to failsafe memory
  61 allocation from the current arena
  62 .BR arena_global (3).
  63 .SH "SEE ALSO"
  64 .BR arena (3),
  65 .BR exc (3),
  66 .BR mLib (3).
  67 .SH AUTHOR
  68 Mark Wooding, <mdw@distorted.org.uk>
  69