[PATCH] manual: Document replacing malloc [BZ #20424]

[Florian Weimer]

* DJ Delorie:

> fweimer@redhat.com (Florian Weimer) writes:
>> +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).
>
> Note that in statically linked cases, it's important to make sure that
> ALL your API functions are linked in.  If your allocator is a library,
> with one function per object, you might get only some of your functions
> - and then try to get the rest from glibc, which will of course fail.

That's what I meant with “linking failures and crashes at run time”
below.

I don't think it matters whether you have one object file or multiple
ones.

>> +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.
>
> Might be useful to clarify that the first list is what glibc itself
> needs, and the second is functions not used by glibc but (as noted)
> possibly used by your application.
>
> I.e. /functionality/functionality which is not used within glibc itself/

“functions which is not not used by the library itself, but which is
often used”?

I dont't want to repeat @theglibc{}.

>> +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.
>
> mallopt() is in our malloc.c so that would cause a link failure when
> static linking, though.

So add this?

“It may result in static linking failures, though.”

Have you double-checked the list of symbols?  Should we say something
about the hooks?  I prefer not to, considering that they are
deprecated.