.\" -*-nroff-*-
.\"
.\" Manual for general memory allocation
.\"
.\" (c) 1999--2002, 2005, 2009, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH alloc 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @x_alloc
.\" @x_allocv
.\" @X_NEW
.\" @X_NEWV
.\" @x_strdup
.\" @x_realloc
.\" @x_reallocv
.\" @X_RENEWV
.\" @x_free
.
.\" @xmalloc
.\" @xmallocv
.\" @XNEW
.\" @XNEWV
.\" @xstrdup
.\" @xrealloc
.\" @xreallocv
.\" @XRENEWV
.\" @xfree
.
.\"--------------------------------------------------------------------------
.SH NAME
alloc \- mLib low-level memory allocation
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/alloc.h>"
.PP
.BI "void *x_alloc(arena *" a ", size_t " sz );
.BI "void *x_allocv(arena *" a ", size_t " n ", size_t " sz );
.BI "X_NEW(" type " *" p ", arena *" a );
.BI "X_NEWV(" type " *" p ", arena *" a ", size_t " n );
.BI "void *x_allocv(arena *" a ", size_t " n ", 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 );
.ta \w'\fBvoid *x_reallocv('u
.BI "void *x_reallocv(arena *" a ", void *" p ,
.BI "	size_t " n ", size_t " on ", size_t " sz );
.BI "X_RENEWV(" type " *" p ", arena *" a ", size_t " n ", size_t " on );
.BI "void x_free(arena *" a ", void *" p );
.PP
.BI "void *xmalloc(size_t " sz );
.BI "void *xmallocv(size_t " n ", size_t " sz );
.BI "XNEW(" type " *" p );
.BI "XNEWV(" type " *" p ", size_t " n );
.BI "char *xstrdup(const char *" s );
.BI "void *xrealloc(void *" p ", size_t " sz ", size_t " osz );
.BI "void *xreallocv(void *" p ", size_t " n ", size_t " on ", size_t " sz );
.BI "XRENEWV(" type " *" p ", size_t " n ", size_t " on );
.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_allocv ,
.BR x_realloc ,
.BR x_reallocv ,
.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.)
The
.B x_allocv
and
.B x_reallocv
functions
allocate space for arrays.
They check for potential overflow before proceeding.
.PP
The
.B X_NEW
macro sets a pointer
.I p
to point to freshly allocated memory large enough for the type that
.I p
points to;
The
.B X_NEWV
macro sets
.I p
to point to freshly allocated memory large enough for
.I n
elements, each of the type that
.I p
points to.
The
.B X_RENEWV
resizes the block that
.I p
points to, so that it now has space for
.I n
elements of the appropriate type, having previously had space for
.I on
elements;
.PP
The
.BR xmalloc ,
.BR xmallocv ,
.BR XNEW ,
.BR XNEWV ,
.BR xrealloc ,
.BR xreallocv ,
.BR XRENEWV ,
.BR xstrdup
and
.BR xfree
macros are provided as a convenient interface to failsafe memory
allocation from the current arena
.BR arena_global (3).
.PP
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR arena (3),
.BR exc (3),
.BR mLib (3).
.
.\"--------------------------------------------------------------------------
.SH AUTHOR
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------