.\" This file is part of grecs -*- nroff -*-
.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
.\"
.\" Grecs is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" Grecs 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 General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Grecs.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH GRECS_MALLOC 3 "May 7, 2011" "GRECS" "Grecs User Reference"
.SH NAME
grecs_malloc, grecs_zalloc, grecs_calloc, grecs_realloc \- Allocate
dynamic memory for \fBGrecs\fR.
.SH SYNOPSIS
.nf
.B #include <grecs.h>
.sp
.BI "void *grecs_malloc(size_t " "size" );
.br
.BI "void *grecs_zalloc(size_t " "size" );
.br
.BI "void *grecs_calloc(size_t " "nmemb" ", size_t " "size" );
.br
.BI "void *grecs_realloc(void " "*ptr" ", size_t " "size" );
.br
.BI "void grecs_free(void " "*ptr" );
.br
.BI "void grecs_alloc_die(void);"
.sp
.BI "void *(*grecs_malloc_fun)(size_t " "size" );
.br
.BI "void *(*grecs_realloc_fun)(void " "*ptr" ", size_t " "size" );
.br
.BI "void (*grecs_free_fun)(void " "*ptr" );
.br
.BI "void (*grecs_alloc_die_fun)(void);"
.SH DESCRIPTION
.PP
The \fBgrecs_malloc\fR, \fBgrecs_calloc\fR and \fBgrecs_realloc\fR
functions work exactly as they \fIlibc\fR counterparts do, except that
if unable to allocate memory they terminate the program, by calling
\fBgrecs_alloc_die\fR function.
.PP
.BR grecs_calloc ()
allocates memory for an array of
.I nmemb
elements of
.I size
bytes each and returns a pointer to the allocated memory.
The memory is set to zero.
.PP
.BR grecs_malloc ()
allocates
.I size
bytes and returns a pointer to the allocated memory.
The memory is not cleared.
.PP
.BR grecs_realloc ()
changes the size of the memory block pointed to by
.I ptr
to
.I size
bytes.
The contents will be unchanged to the minimum of the old and new
sizes;
newly allocated memory will be uninitialized.
.PP
.BR grecs_zalloc ()
allocates
.I size
bytes and returns a pointer to the allocated memory.  The memory is
set to zero.
.PP
.BR grecs_free ()
frees the memory space pointed to by \fBptr\fR, which must have been
returned by a previous call to one of the memory allocation functions
discussed above.
.PP
The \fBgrecs_malloc_fun\fR hook is used \fBgrecs_malloc\fR,
\fBgrecs_calloc\fR and \fBgrecs_zalloc\fR to allocate new memory
chunk.  By default it points to
.BR malloc (3).
.PP
Similarly, the \fBgrecs_realloc_fun\fR, is used by
\fBgrecs_realloc\fR function. By default it points to
.BR realloc (3).
.PP
The \fBgrecs_free_fun\fR is used by
.BR grecs_free ().
By default it points to
.BR free (3).
.PP
These hooks provide a way for the calling program to use its custom
memory allocation routines.
.PP
.BR grecs_alloc_die ()
This function is called when memory allocation fails.  It prints
appropriate diagnostics using \fBgrecs_error(3)\fR and aborts the
program.  If \fBgrecs_alloc_die_fun\fR, it is called prior to
outputting the diagnostics.

.SH "RETURN VALUE"
For \fBgrecs_malloc\fR, \fBgrecs_calloc\fR, \fBgrecs_zalloc\fR and
\fBgrecs_realloc\fR return a pointer to the allocated memory, which is
suitably aligned for any kind of variable.
.PP
On error, \fBgrecs_alloc_die\fR is called and the program is terminated.
.SH "SEE ALSO"
.BR grecs_strdup (3)
.SH AUTHORS
Sergey Poznyakoff.
.SH "BUG REPORTS"
Report bugs to <gray+grecs@gnu.org.ua>.
.SH COLOPHON
The \fBGrecs\fR library is constantly changing, so this manual page
may be incorrect or out-of-date.  For the latest copy of \fBGrecs\fR
documentation, visit <http://www.gnu.org.ua/software/grecs>.
.SH COPYRIGHT
Copyright \(co 2011 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end: