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

   1 .\" -*-nroff-*-
   2 .TH alloc 3 "8 May 1999" "mLib"
   3 .\" @xmalloc
   4 .\" @xrealloc
   5 .\" @xstrdup
   6 .SH NAME
   7 alloc \- mLib low-level memory allocation
   8 .SH SYNOPSIS
   9 .nf
  10 .B "#include <mLib/alloc.h>"
  11
  12 .BI "void *xmalloc(size_t " sz );
  13 .BI "void *xrealloc(void *" p ", size_t " sz );
  14 .BI "char *xstrdup(const char *" s );
  15 .fi
  16 .SH DESCRIPTION
  17 These functions allocate and return blocks of memory.  If insufficient
  18 memory is available, an
  19 .B EXC_NOMEM
  20 exception is raised.
  21 .PP
  22 The
  23 .B xmalloc
  24 and
  25 .B xrealloc
  26 functions are veneers over the standard
  27 .BR malloc (3)
  28 and
  29 .BR realloc (3)
  30 functions.
  31 .B xmalloc
  32 allocates a block of
  33 .I sz
  34 bytes and returns a pointer to the base of the block;
  35 .B xrealloc
  36 is given a pointer
  37 .I p
  38 to a block of memory, and returns the address of a new block of size
  39 .I sz
  40 bytes with the same contents as the original one (either truncated, if
  41 the new block is smaller, or padded with rubbish at the end if bigger).
  42 .PP
  43 The
  44 .B xstrdup
  45 function allocates and returns a block of memory containing a copy of
  46 the null-terminated string
  47 .IR p .
  48 The block is just large enough for the string and its null terminator.
  49 .PP
  50 The memory blocks allocated by these functions can be released by
  51 calling the standard
  52 .BR free (3)
  53 function.
  54 .SH "RETURN VALUE"
  55 The
  56 .BR xmalloc ,
  57 .B xrealloc
  58 and
  59 .B xstrdup
  60 functions return pointers to the blocks they allocated.  They do not
  61 return if a block couldn't be allocated; instead, the exception
  62 .B EXC_NOMEM
  63 is raised.
  64 .SH "SEE ALSO"
  65 .BR malloc (3),
  66 .BR realloc (3),
  67 .BR free (3),
  68 .BR exc (3),
  69 .BR mLib (3).
  70 .SH AUTHOR
  71 Mark Wooding, <mdw@nsict.org>
  72