diff options
Diffstat (limited to 'doc/argot_malloc.3')
-rw-r--r-- | doc/argot_malloc.3 | 141 |
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: + |