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

[Joseph S. Myers]

On Tue, 5 Aug 2014, Mike Frysinger wrote:

> only way around it would be for the public xxx symbol to be marked weak.  a 
> cursory scan of my current libc.so shows that is how most are declared, but 
> not all.  should we enshrine this as part of the policy ?

Yes, such aliases (foo as an alias of __foo, with __foo being used 
somewhere for namespace reasons) need to be weak.

Many strong aliases may be OK because they're not for namespace reasons 
(for example, if both names are in the implementation namespace), or 
harmless because the function doesn't actually get called anywhere else in 
glibc by either name.  Although then there's the question of whether both 
names are needed at all, or whether the code can be simplified by just 
defining the public name.  If a function is in ISO C90, for example, calls 
elsewhere in glibc can just use the public name (if it's in POSIX.1:1990 
then calls from POSIX, GNU etc. functions can use the public name, etc.).  
E.g. I see no reason for difftime to be defined as __difftime with a 
strong alias - it's a C90 function, and nothing in glibc calls it by 
either name.

-- 
Joseph S. Myers
joseph@codesourcery.com