Improve docs. Add an option to create installable distribution.

1 files changed, 129 insertions, 0 deletions

diff --git a/doc/grecs_malloc.3 b/doc/grecs_malloc.3
new file mode 100644
index 0000000..58cc9a0
--- /dev/null
+++ b/doc/grecs_malloc.3
@@ -0,0 +1,129 @@
+.\" 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:
+