.\" -*-nroff-*-
.TH alloc 3 "8 May 1999" "mLib"
.\" @xmalloc
.\" @xrealloc
.\" @xstrdup
.SH NAME
alloc \- mLib low-level memory allocation
.SH SYNOPSIS
.nf
.B "#include <mLib/alloc.h>"

.BI "void *xmalloc(size_t " sz );
.BI "void *xrealloc(void *" p ", size_t " sz );
.BI "char *xstrdup(const char *" s );
.fi
.SH DESCRIPTION
These functions allocate and return blocks of memory.  If insufficient
memory is available, an
.B EXC_NOMEM
exception is raised.
.PP
The
.B xmalloc
and
.B xrealloc
functions are veneers over the standard
.BR malloc (3)
and
.BR realloc (3)
functions.
.B xmalloc
allocates a block of
.I sz
bytes and returns a pointer to the base of the block;
.B xrealloc
is given a pointer 
.I p
to a block of memory, and returns the address of a new block of size
.I sz
bytes with the same contents as the original one (either truncated, if
the new block is smaller, or padded with rubbish at the end if bigger).
.PP
The
.B xstrdup
function allocates and returns a block of memory containing a copy of
the null-terminated string
.IR p .
The block is just large enough for the string and its null terminator.
.PP
The memory blocks allocated by these functions can be released by
calling the standard
.BR free (3)
function.
.SH "RETURN VALUE"
The
.BR xmalloc ,
.B xrealloc
and
.B xstrdup
functions return pointers to the blocks they allocated.  They do not
return if a block couldn't be allocated; instead, the exception
.B EXC_NOMEM
is raised.
.SH "SEE ALSO"
.BR malloc (3),
.BR realloc (3),
.BR free (3),
.BR exc (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@nsict.org>