.\" -*-nroff-*-
.TH alloc 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @xmalloc
.\" @xrealloc
.\" @xstrdup
.\" @xfree
.\" @x_alloc
.\" @x_strdup
.\" @x_realloc
.\" @x_free
.SH NAME
alloc \- mLib low-level memory allocation
.SH SYNOPSIS
.nf
.B "#include <mLib/alloc.h>"

.BI "void *x_alloc(arena *" a ", size_t " sz );
.BI "char *x_strdup(arena *" a ", const char *" s );
.BI "void *x_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
.BI "void x_free(arena *" a ", void *" p );

.BI "void *xmalloc(size_t " sz );
.BI "void *xrealloc(void *" p ", size_t " sz ", size_t " osz );
.BI "char *xstrdup(const char *" s );
.BI "void xfree(void *" p );
.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 functions
.BR x_alloc ,
.BR x_realloc ,
.BR x_strdup
and
.BR x_free
work with a given arena (see
.BR arena (3)).
.B x_alloc
allocates a block of a given size;
.B x_realloc
resizes an allocated block;
.B x_strdup
allocates a copy of a null-terminated string; and
.B x_free
releases a block.
.RB ( x_free
is supplied for orthogonality's sake: it's equivalent to calling the
.BR A_FREE (3)
macro.)
.PP
The
.BR xmalloc ,
.BR xrealloc ,
.BR xstrdup
and
.BR xfree
macros are provided as a convenient interface to failsafe memory
allocation from the current arena
.BR arena_global (3).
.SH "SEE ALSO"
.BR arena (3),
.BR exc (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@nsict.org>