aboutsummaryrefslogtreecommitdiff
path: root/doc/argot_malloc.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/argot_malloc.3')
-rw-r--r--doc/argot_malloc.3141
1 files changed, 141 insertions, 0 deletions
diff --git a/doc/argot_malloc.3 b/doc/argot_malloc.3
new file mode 100644
index 0000000..0059bbb
--- /dev/null
+++ b/doc/argot_malloc.3
@@ -0,0 +1,141 @@
+.\" This file is part of argot -*- nroff -*-
+.\" Copyright (C) 2007-2016 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 ARGOT_MALLOC 3 "May 7, 2011" "ARGOT" "Grecs User Reference"
+.SH NAME
+argot_malloc, argot_zalloc, argot_calloc, argot_realloc \- Allocate
+dynamic memory for \fBGrecs\fR.
+.SH SYNOPSIS
+.nf
+.B #include <argot.h>
+.sp
+.BI "void *argot_malloc(size_t " "size" );
+.br
+.BI "void *argot_zalloc(size_t " "size" );
+.br
+.BI "void *argot_calloc(size_t " "nmemb" ", size_t " "size" );
+.br
+.BI "void *argot_realloc(void " "*ptr" ", size_t " "size" );
+.br
+.BI "void argot_free(void " "*ptr" );
+.br
+.BI "void argot_alloc_die(void);"
+.sp
+.BI "void *(*argot_malloc_fun)(size_t " "size" );
+.br
+.BI "void *(*argot_realloc_fun)(void " "*ptr" ", size_t " "size" );
+.br
+.BI "void (*argot_free_fun)(void " "*ptr" );
+.br
+.BI "void (*argot_alloc_die_fun)(void);"
+.SH DESCRIPTION
+.PP
+The \fBargot_malloc\fR, \fBargot_calloc\fR and \fBargot_realloc\fR
+functions work exactly as they \fIlibc\fR counterparts do, except that
+if unable to allocate memory they terminate the program, by calling
+\fBargot_alloc_die\fR function.
+.PP
+.BR argot_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 argot_malloc ()
+allocates
+.I size
+bytes and returns a pointer to the allocated memory.
+The memory is not cleared.
+.PP
+.BR argot_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 argot_zalloc ()
+allocates
+.I size
+bytes and returns a pointer to the allocated memory. The memory is
+set to zero.
+.PP
+.BR argot_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 \fBargot_malloc_fun\fR hook is used \fBargot_malloc\fR,
+\fBargot_calloc\fR and \fBargot_zalloc\fR to allocate new memory
+chunk. By default it points to
+.BR malloc (3).
+.PP
+Similarly, the \fBargot_realloc_fun\fR, is used by
+\fBargot_realloc\fR function. By default it points to
+.BR realloc (3).
+.PP
+The \fBargot_free_fun\fR is used by
+.BR argot_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 argot_alloc_die ()
+This function is called when memory allocation fails. It prints
+appropriate diagnostics using \fBargot_error(3)\fR and aborts the
+program. If \fBargot_alloc_die_fun\fR, it is called prior to
+outputting the diagnostics.
+
+.SH "RETURN VALUE"
+For \fBargot_malloc\fR, \fBargot_calloc\fR, \fBargot_zalloc\fR and
+\fBargot_realloc\fR return a pointer to the allocated memory, which is
+suitably aligned for any kind of variable.
+.PP
+On error, \fBargot_alloc_die\fR is called and the program is terminated.
+.SH "SEE ALSO"
+.BR argot_strdup (3)
+.SH AUTHORS
+Sergey Poznyakoff.
+.SH "BUG REPORTS"
+Report bugs to <gray+argot@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/argot>.
+.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:
+

Return to:

Send suggestions and report system problems to the System administrator.