.\" 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/>.
.\" This file is part of SLB. 
.\" Copyright (C) 2011 Sergey Poznyakoff
.\"
.TH GRECS_MALLOC 3 "May 3, 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_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_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
If \fBgrecs_malloc_fun\fR is not \fINULL\fR, it will be used by
\fBgrecs_malloc\fR, \fBgrecs_calloc\fR and \fBgrecs_zalloc\fR to
allocate new memory chunk.  If it is not set, these function use
\fBmalloc(3)\fR.
.PP
Similarly, the \fBgrecs_realloc_fun\fR, if set, is used by
\fBgrecs_realloc\fR function.  Otherwise, this function uses
\fBrealloc(3)\fR.
.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: