[PATCH] extend.texi: Expand on the perils of using the 'leaf' attribute.

[Carlos O'Donell <carlos at redhat dot com>]

Using the 'leaf' attribute is difficult in certain use cases, and the
documentation rightly points out that signals is one such problem.

We should additionally document the following caveats:

* Indirect function resolvers (thanks to Florian Weimer for catching this).
* Indirect function implementations
* ELF symbol interposition.

Note that neither the C nor C++ standards talks at all about how
memory is synchronized between the current execution context and that
of a signal handler. Therefore this patch rewords the text to say
"There is no standards compliant way..." although in practice is just
works and one would expect the standards (POSIX) to adopt such language
that existing practice works.

Lastly, we mention that the 'leaf' attribute might simply be removed
if that is the easiest option.

OK to checkin?

For completeness the motivating example from a user was like this:
cat >> leaf.c <<EOF
#include <stdlib.h>
#include <signal.h>
#include <unistd.h>
#include <pthread.h>

static int tst;

void my_h(int sig)
{
  if (tst == 1)
    _exit (0);
  _exit (1);
}

int main()
{
  signal(SIGUSR1, my_h);
  tst++;
  pthread_kill(pthread_self(), SIGUSR1);
  tst--;
  return 2;
}
EOF
gcc -g3 -O3 -o leaf leaf.c -lpthread
./test; echo $?
1

Where the global write of tst is elided by the compiler because
pthread_kill is marked __THROW (includes leaf). It's an open
question if pthread_kill should or should not use __THROWNL.
Even if we fix that in glibc, the changes below to the docs are
still important clarifications.

gcc/
2016-03-14  Carlos O'Donell  <carlos@redhat.com>

	* doc/extend.texi (Common Function Attributes): Describe ifunc impact
	on leaf attribute.

Index: extend.texi
===================================================================
--- extend.texi	(revision 234183)
+++ extend.texi	(working copy)
@@ -2786,9 +2786,17 @@
 is a leaf function, but @code{qsort} is not.
 
 Note that leaf functions might invoke signals and signal handlers might be
-defined in the current compilation unit and use static variables.  The only
-compliant way to write such a signal handler is to declare such variables
-@code{volatile}.
+defined in the current compilation unit and use static variables.  Similarly,
+when lazy symbol resolution is in effect, leaf functions might invoke indirect
+functions whose resolver function or implementation function might be defined
+in the current compilation unit and use static variables. There is no standards
+compliant way to write such a signal handler, resolver function, or
+implementation function, and the best that you can do is to remove the leaf
+attribute or mark all such variables @code{volatile}.  Lastly, for ELF-based
+systems which support symbol interposition one should take care that functions
+defined in the current compilation unit do not unexpectedly interpose other
+symbols based on the defined standards mode otherwise an inadvertent callback
+would be added.
 
 The attribute has no effect on functions defined within the current compilation
 unit.  This is to allow easy merging of multiple compilation units into one,
--
Cheers,
Carlos.