.TH ALLOC 3 "$Revision$"
.ad
.SH NAME
Malloc, Salloc, Realloc, Srealloc, st_alloc, st_free\ \-\ low level memory allocation routines
.SH SYNOPSIS
.B #include <alloc.h>
.PP
.B char *Malloc(unsigned int size)
.PP
.B char *Salloc(char *str, unsigned int size)
.PP
.B char *Realloc(char *buf, unsigned int size)
.PP
.B char *Srealloc(char *str, unsigned int size)
.PP
.B char *st_alloc(char **phead, unsigned int size, int count)
.PP
.B st_free(char *ptr, char **phead, unsigned int size)
.PP
.B void clear(char *ptr, unsigned int size)
.PP
.void No_Mem()
.PP
.SH DESCRIPTION
This set of routines provides a checking memory allocation mechanism.
.PP
\fIMalloc\fR returns a pointer to a block of at least \fIsize\fR
bytes, beginning on a boundary suitable for any data type.
.PP
\fISalloc\fR returns a pointer to a block of at least \fIsize\fR
bytes, initialized with the null-terminated string \fIstr\fR.
.PP
\fIRealloc\fR changes the size of
the block at \fIbuf\fR to \fIsize\fR bytes, and returns a pointer to the
(possibly moved) block. If \fIbuf\fP is a null pointer, \fIRealloc\fP
behaves as \fIMalloc\fP.
.PP
\fISrealloc\fR reallocates
the string at \fIstr\fR to \fIsize\fR bytes.
It actually does the same as \fIRealloc\fP, and exists only for
backwards compatibility.
.PP
All these routines use \fImalloc\fR and \fIrealloc\fR.
The routine \fIfree\fR can be used on pointers returned by these routines.
.PP
\fISt_alloc\fR and \fIst_free\fR provide a mechanism for maintaining free lists
of structures.
\fISt_alloc\fR takes three parameters: \fIphead\fR is a pointer to a field
containing the head of the free list, \fIsize\fR contains the size of the
structures, and \fIcount\fR indicates how many new structures must be allocated
in case the free list is exhausted.
It returns a pointer to a zero-initialized structure.
\fISt_free\fR also takes three parameters: \fIptr\fR is a pointer to
the structure to be freed, \fIphead\fR is again a pointer to a field
containing the head of the free list, and \fIsize\fR again contains the size
of the structures.
These last two routines are best used in a macro.
.PP
\fIClear\fR clears \fIsize\fR bytes, starting at \fIptr\fR.
.SH FILES
.nf
~em/modules/h/alloc.h
~em/modules/lib/liballoc.a
.fi
.SH "MODULES USED"
system(3)
.SH "SEE ALSO"
malloc(3)
.SH DIAGNOSTICS
\fIMalloc\fR, \fISalloc\fR, \fIRealloc\fP, \fISrealloc\fR, and \fIst_alloc\fR
call a routine \fINo_Mem\fR if there is no memory available. This routine
is not supposed to return. A default one, that
gives an error message and stops execution, is provided.
.SH BUGS
The
.I st_alloc
mechanism only works for structures that are large enough to contain one
pointer.
Also,
.I st_free
actually is a macro, and references its arguments more than once, so they
better not have side-effects.