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

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