manual: Document replacing malloc [BZ #20424]

Message ID 20170413120959.AAC4A401E7152@oldenburg.str.redhat.com
State New
Headers show

Commit Message

Florian Weimer April 13, 2017, 12:09 p.m.
2017-04-13  Florian Weimer  <fweimer@redhat.com>

	[BZ #20424]
	* manual/memory.texi (Replacing malloc): New section.
	(Allocating Storage For Program Data): Reference it.
	(The GNU Allocator): Likewise.

Comments

Andreas Schwab April 13, 2017, 12:21 p.m. | #1
On Apr 13 2017, fweimer@redhat.com (Florian Weimer) wrote:

> diff --git a/manual/memory.texi b/manual/memory.texi
> index 38d3c3a..adf3f89 100644
> --- a/manual/memory.texi
> +++ b/manual/memory.texi
> @@ -167,6 +167,7 @@ special to @theglibc{} and GNU Compiler.
>  * Unconstrained Allocation::    The @code{malloc} facility allows fully general
>  		 		 dynamic allocation.
>  * Allocation Debugging::        Finding memory leaks and not freed memory.
> +* Replacing malloc::            You can use your own @code{malloc}-style allocator.

This line is too long.

> +It is possible to use your own custom @code{malloc} instead of the
> +built-in allocator provided by @theglibc{}.  @xref{Replacing malloc}

Period after @xref.

Andreas.
Florian Weimer April 13, 2017, 12:27 p.m. | #2
On 04/13/2017 02:21 PM, Andreas Schwab wrote:
> On Apr 13 2017, fweimer@redhat.com (Florian Weimer) wrote:
> 
>> diff --git a/manual/memory.texi b/manual/memory.texi
>> index 38d3c3a..adf3f89 100644
>> --- a/manual/memory.texi
>> +++ b/manual/memory.texi
>> @@ -167,6 +167,7 @@ special to @theglibc{} and GNU Compiler.
>>   * Unconstrained Allocation::    The @code{malloc} facility allows fully general
>>   		 		 dynamic allocation.
>>   * Allocation Debugging::        Finding memory leaks and not freed memory.
>> +* Replacing malloc::            You can use your own @code{malloc}-style allocator.
> 
> This line is too long.

I'm not sure if it's possible to wrap lines there without altering the 
Info output.

I'll change it to:

* Replacing malloc::            Using your own @code{malloc}-style 
allocator.

(On a single line, in case Thunderbird wraps it.)  This should avoid the 
issue.

>> +It is possible to use your own custom @code{malloc} instead of the
>> +built-in allocator provided by @theglibc{}.  @xref{Replacing malloc}
> 
> Period after @xref.

Thanks, fixed.

Florian
Andreas Schwab April 13, 2017, 12:37 p.m. | #3
On Apr 13 2017, Florian Weimer <fweimer@redhat.com> wrote:

> On 04/13/2017 02:21 PM, Andreas Schwab wrote:
>> On Apr 13 2017, fweimer@redhat.com (Florian Weimer) wrote:
>>
>>> diff --git a/manual/memory.texi b/manual/memory.texi
>>> index 38d3c3a..adf3f89 100644
>>> --- a/manual/memory.texi
>>> +++ b/manual/memory.texi
>>> @@ -167,6 +167,7 @@ special to @theglibc{} and GNU Compiler.
>>>   * Unconstrained Allocation::    The @code{malloc} facility allows fully general
>>>   		 		 dynamic allocation.
>>>   * Allocation Debugging::        Finding memory leaks and not freed memory.
>>> +* Replacing malloc::            You can use your own @code{malloc}-style allocator.
>>
>> This line is too long.
>
> I'm not sure if it's possible to wrap lines there without altering the
> Info output.

I don't userstand.  Folding menu lines is nothing unusual, see above.

Andreas.
Florian Weimer April 13, 2017, 12:40 p.m. | #4
On 04/13/2017 02:37 PM, Andreas Schwab wrote:
> On Apr 13 2017, Florian Weimer <fweimer@redhat.com> wrote:
> 
>> On 04/13/2017 02:21 PM, Andreas Schwab wrote:
>>> On Apr 13 2017, fweimer@redhat.com (Florian Weimer) wrote:
>>>
>>>> diff --git a/manual/memory.texi b/manual/memory.texi
>>>> index 38d3c3a..adf3f89 100644
>>>> --- a/manual/memory.texi
>>>> +++ b/manual/memory.texi
>>>> @@ -167,6 +167,7 @@ special to @theglibc{} and GNU Compiler.
>>>>    * Unconstrained Allocation::    The @code{malloc} facility allows fully general
>>>>    		 		 dynamic allocation.
>>>>    * Allocation Debugging::        Finding memory leaks and not freed memory.
>>>> +* Replacing malloc::            You can use your own @code{malloc}-style allocator.
>>>
>>> This line is too long.
>>
>> I'm not sure if it's possible to wrap lines there without altering the
>> Info output.
> 
> I don't userstand.  Folding menu lines is nothing unusual, see above.

The folding is propagated into the Info output, even though the line is 
not overly long there because the @code is elided.

Florian

Patch

diff --git a/manual/memory.texi b/manual/memory.texi
index 38d3c3a..adf3f89 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -167,6 +167,7 @@  special to @theglibc{} and GNU Compiler.
 * Unconstrained Allocation::    The @code{malloc} facility allows fully general
 		 		 dynamic allocation.
 * Allocation Debugging::        Finding memory leaks and not freed memory.
+* Replacing malloc::            You can use your own @code{malloc}-style allocator.
 * Obstacks::                    Obstacks are less general than malloc
 				 but more efficient and convenient.
 * Variable Size Automatic::     Allocation of variable-sized blocks
@@ -299,6 +300,9 @@  A more detailed technical description of the GNU Allocator is maintained in
 the @glibcadj{} wiki. See
 @uref{https://sourceware.org/glibc/wiki/MallocInternals}.
 
+It is possible to use your own custom @code{malloc} instead of the
+built-in allocator provided by @theglibc{}.  @xref{Replacing malloc}
+
 @node Unconstrained Allocation
 @subsection Unconstrained Allocation
 @cindex unconstrained memory allocation
@@ -1907,6 +1911,59 @@  from line 33 in the source file @file{/home/drepper/tst-mtrace.c} four
 times without freeing this memory before the program terminates.
 Whether this is a real problem remains to be investigated.
 
+@node Replacing malloc
+@subsection Replacing @code{malloc}
+
+@cindex @code{malloc} interposition
+@cindex replacing @code{malloc}
+@cindex interposing @code{malloc}
+@cindex preempting @code{malloc}
+@cindex alternative @code{malloc} implementations
+@Theglibc{} supports replacing the built-in @code{malloc} implementation
+with a different allocator with the same interface.  For dynamically
+linked programs, this happens through ELF symbol interposition.  For
+static linking, the @code{malloc} replacement library must be linked in
+before linking against @code{libc.a} (explicitly or implicitly).
+
+The minimum set of functions which has to be provided by a custom
+@code{malloc} is given in the table below.
+
+@table @code
+@item malloc
+@item free
+@item calloc
+@item realloc
+@end table
+
+These @code{malloc}-related functions are required for @theglibc{} to
+work.@footnote{Versions of @theglibc{} before 2.25 required that a
+custom @code{malloc} defines @code{__libc_memalign} (with the same
+interface as the @code{memalign} function).}
+
+The @code{malloc} implementation in @theglibc{} provides additional
+functionality, which is often used by other system libraries and
+applications.  Failure to provide these functions can lead to linking
+failures and crashes at run time.  These additional functions are listed
+in the following table.
+
+@table @code
+@item aligned_alloc
+@item malloc_usable_size
+@item memalign
+@item posix_memalign
+@item pvalloc
+@item valloc
+@end table
+
+In addition, old applications may use the obsolete @code{cfree}
+function.
+
+Further @code{malloc}-related functions such as @code{mallopt} or
+@code{mallinfo} will not have any effect or return incorrect statistics
+when a replacement @code{malloc} is in use.  However, failure to replace
+these functions typically does not result in crashes or other incorrect
+application behavior.
+
 @node Obstacks
 @subsection Obstacks
 @cindex obstacks