Document __foo symbol variants and their uses in the library sources.

[Carlos O'Donell]

On 04/23/2014 10:59 AM, Joseph S. Myers wrote:
> On Mon, 14 Apr 2014, Carlos O'Donell wrote:
> 
>> In response to some questions on libc-help here is a 
>> first attempt at documenting some of the conventions
>> behind calling the double-underscore versions of the
>> public API functions from within the library (to avoid
>> the PLT indirect and maintain internal consistency).
>>
>> https://sourceware.org/glibc/wiki/Style_and_Conventions#Double-underscore_names_for_public_API_functions
>>
>> I would appreciate any review.
> 
> That appears to confuse two things.
> 
> * hidden_proto / hidden_def (etc.) are about PLT avoidance (and may also 
> enable better code generation in some cases because the compiler knows 
> it's calling a hidden symbol which must be in the same library).  They may 
> be used both on names starting with __ and names that aren't so-prefixed.  
> They are irrelevant when a function in one library is calling a function 
> in another library.
> 
> * __-prefixed names are about being namespace-clean, where the user calls 
> a function in one standard and that function internally uses a function 
> from another standard, or not in any standard.  In such cases, you need to 
> use __-prefixed names, whether or not the function being called is in the 
> same library, to avoid conflicts with the user's own symbols in the static 
> linking case.  If the function called is in another library, the 
> __-prefixed function *also* needs to be exported at GLIBC_PRIVATE so that 
> the call can work in the dynamic linking case - unless there's a reason 
> for it to be exported at a public symbol version.  (For example, if a 
> macro definition of a public function in an installed header uses the 
> __-prefixed function, or libstdc++ should use it, or redirection for 
> _FILE_OFFSET_BITS=64 should use it, then it may be necessary to export at 
> a public version, in which case you don't need a redundant GLIBC_PRIVATE 
> export.)  And if the function is in the same library you should still use 
> hidden_proto / hidden_def.

I was looking at this text today for other reasons and updated it to talk
about both namespace and PLT avoidance issues.

Thank you for the review.

Cheers,
Carlos.