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

[DJ Delorie]

Florian Weimer <fw@deneb.enyo.de> writes:

> * 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.

My point was, just putting your *.a first in the link line is
insufficient to make sure all your *.o are included, and if
some-but-not-all of your *.o are pulled from your library, that's an
additional problem for you to solve.  Or at least watch out for.

Some ways to avoid this are: use one *.o, make sure your app *uses* all
the API functions, or link with --whole-archive.

>>> +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{}.

Whatever, I'm just thinking a slight rewording might make it more
obvious that the second list is optional *only to glibc*.

Something like this?

"The @code{malloc} implementation in @theglibc() provides additional
functionality that it does not itself use, but provides for applications
and other libraries.  If your application uses these extensions, you may
need to implement them as well."

> So add this?
>
> “It may result in static linking failures, though.”

That would do.  Maybe one general warning about static linking rather
than repeating it throughout, 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.

Other implementations don't provide the hooks, I wouldn't bother
mentioning them.  Keep it simple.

I didn't double-check the list of symbols; I think only one of us needs
to write that perl script ;-)