[doco/threads] document internal thread signals on gnu/linux

[Michael Elizabeth Chastain <mec at shout dot net>]

This patch adds some doco about the existence and side effects
of thread internal signals in GNU/Linux systems.

It should be, errr, self-documenting.  If you can't figure out
what I'm talking about, then I need to rewrite this.

I'm motivated to write this because one of our test programs actually
has a coding error in it, and this doco explains why the test program is
badly written and what happens when such a program is run under gdb.

I'm looking for two kinds of comments: (1) is the content okay,
and (2) is the formatting okay.

Michael C

2003-10-23  Michael Chastain  <mec@shout.net>

	* gdb.texinfo (Threads): Document the existence and side effects
	of thread internal signals in GNU/Linux systems.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.183
diff -c -3 -p -r1.183 gdb.texinfo
*** gdb.texinfo	23 Oct 2003 00:11:59 -0000	1.183
--- gdb.texinfo	24 Oct 2003 01:16:19 -0000
*************** signal happened.  @value{GDBN} alerts yo
*** 2257,2262 ****
--- 2257,2289 ----
  message of the form @samp{[Switching to @var{systag}]} to identify the
  thread.
  
+ @cindex signals, internal for threads
+ @cindex threads, internal signals
+ On @sc{gnu}/Linux systems, the thread library generates extra internal
+ signals when it detects that your program is running under @value{GDBN}.
+ This leads to an undesirable interaction: if some of the threads in your
+ program are blocked inside system calls, and your program performs
+ certain tasks such as creating a thread or destroying a thread, then the
+ system calls in other threads may return prematurely.
+ 
+ To handle this problem, your program should check the return value
+ of each system call and react appropriately.  This is good programming
+ style anyways.
+ 
+ For example, do not write code like this:
+ 
+ @smallexample
+   sleep (10);
+ @end smallexample
+ 
+ Instead, write this:
+ 
+ @smallexample
+   int unslept = 10;
+   while (unslept > 0)
+     unslept = sleep (unslept);
+ @end smallexample
+ 
  @xref{Thread Stops,,Stopping and starting multi-thread programs}, for
  more information about how @value{GDBN} behaves when you stop and start
  programs with multiple threads.