Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 154 insertions, 0 deletions

diff --git a/man/man3/malloc_hook.3 b/man/man3/malloc_hook.3
new file mode 100644
index 0000000..5b10cfd
--- /dev/null
+++ b/man/man3/malloc_hook.3
@@ -0,0 +1,154 @@
+.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
+.\"
+.\" SPDX-License-Identifier: GPL-1.0-or-later
+.\"
+.\" Heavily based on glibc documentation
+.\" Polished, added docs, removed glibc doc bug, 2002-07-20, aeb
+.\"
+.TH __malloc_hook 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+__malloc_hook, __malloc_initialize_hook,
+__memalign_hook, __free_hook, __realloc_hook,
+__after_morecore_hook \- malloc debugging variables (DEPRECATED)
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B "#include <malloc.h>"
+.P
+.BI "void *(*volatile __malloc_hook)(size_t " size ", const void *" caller );
+.P
+.BI "void *(*volatile __realloc_hook)(void *" ptr ", size_t " size ,
+.BI "                         const void *" caller );
+.P
+.BI "void *(*volatile __memalign_hook)(size_t " alignment ", size_t " size ,
+.BI "                         const void *" caller );
+.P
+.BI "void (*volatile __free_hook)(void *" ptr ", const void *" caller );
+.P
+.B "void (*__malloc_initialize_hook)(void);"
+.P
+.B "void (*volatile __after_morecore_hook)(void);"
+.fi
+.SH DESCRIPTION
+The GNU C library lets you modify the behavior of
+.BR malloc (3),
+.BR realloc (3),
+and
+.BR free (3)
+by specifying appropriate hook functions.
+You can use these hooks
+to help you debug programs that use dynamic memory allocation,
+for example.
+.P
+The variable
+.B __malloc_initialize_hook
+points at a function that is called once when the malloc implementation
+is initialized.
+This is a weak variable, so it can be overridden in
+the application with a definition like the following:
+.P
+.in +4n
+.EX
+void (*__malloc_initialize_hook)(void) = my_init_hook;
+.EE
+.in
+.P
+Now the function
+.IR my_init_hook ()
+can do the initialization of all hooks.
+.P
+The four functions pointed to by
+.BR __malloc_hook ,
+.BR __realloc_hook ,
+.BR __memalign_hook ,
+.B __free_hook
+have a prototype like the functions
+.BR malloc (3),
+.BR realloc (3),
+.BR memalign (3),
+.BR free (3),
+respectively, except that they have a final argument
+.I caller
+that gives the address of the caller of
+.BR malloc (3),
+etc.
+.P
+The variable
+.B __after_morecore_hook
+points at a function that is called each time after
+.BR sbrk (2)
+was asked for more memory.
+.SH STANDARDS
+GNU.
+.SH NOTES
+The use of these hook functions is not safe in multithreaded programs,
+and they are now deprecated.
+From glibc 2.24 onwards, the
+.B __malloc_initialize_hook
+variable has been removed from the API,
+and from glibc 2.34 onwards, all
+the hook variables have been removed from the API.
+.\" https://bugzilla.redhat.com/show_bug.cgi?id=450187
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=9957
+Programmers should instead preempt calls to the relevant functions
+by defining and exporting
+.BR malloc (),
+.BR free (),
+.BR realloc (),
+and
+.BR calloc ().
+.SH EXAMPLES
+Here is a short example of how to use these variables.
+.P
+.EX
+#include <stdio.h>
+#include <malloc.h>
+\&
+/* Prototypes for our hooks */
+static void my_init_hook(void);
+static void *my_malloc_hook(size_t, const void *);
+\&
+/* Variables to save original hooks */
+static void *(*old_malloc_hook)(size_t, const void *);
+\&
+/* Override initializing hook from the C library */
+void (*__malloc_initialize_hook)(void) = my_init_hook;
+\&
+static void
+my_init_hook(void)
+{
+    old_malloc_hook = __malloc_hook;
+    __malloc_hook = my_malloc_hook;
+}
+\&
+static void *
+my_malloc_hook(size_t size, const void *caller)
+{
+    void *result;
+\&
+    /* Restore all old hooks */
+    __malloc_hook = old_malloc_hook;
+\&
+    /* Call recursively */
+    result = malloc(size);
+\&
+    /* Save underlying hooks */
+    old_malloc_hook = __malloc_hook;
+\&
+    /* printf() might call malloc(), so protect it too */
+    printf("malloc(%zu) called from %p returns %p\en",
+            size, caller, result);
+\&
+    /* Restore our own hooks */
+    __malloc_hook = my_malloc_hook;
+\&
+    return result;
+}
+.EE
+.SH SEE ALSO
+.BR mallinfo (3),
+.BR malloc (3),
+.BR mcheck (3),
+.BR mtrace (3)