c-stack: improve documentation

[Bruno Haible]

Hi,

The documentation of the c_stack_action function is
  - hard to find inside the (long) c-stack.c file,
  - incomplete: it does not mention that
      - non-stackoverflows SIGSEGVs are also caught,
      - something is written to standard error,
      - the value of the variable 'exit_failure' is used.

I'm applying this improved documentation:


2008-07-20  Bruno Haible  <address@hidden>

        * lib/c-stack.h (c_stack_action): Add documentation.
        * lib/c-stack.c (c_stack_action): Remove incomplete documentation.

*** lib/c-stack.h.orig  2008-07-20 18:22:06.000000000 +0200
--- lib/c-stack.h       2008-07-20 18:20:45.000000000 +0200
***************
*** 1,6 ****
  /* Stack overflow handling.
  
!    Copyright (C) 2002, 2004 Free Software Foundation, Inc.
  
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
--- 1,6 ----
  /* Stack overflow handling.
  
!    Copyright (C) 2002, 2004, 2008 Free Software Foundation, Inc.
  
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
***************
*** 15,18 ****
     You should have received a copy of the GNU General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  
! int c_stack_action (void (*) (int));
--- 15,41 ----
     You should have received a copy of the GNU General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  
! 
! /* Set up ACTION so that it is invoked on C stack overflow and on other,
!    stack-unrelated, segmentation violation.
!    Return -1 (setting errno) if this cannot be done.
! 
!    When a stack overflow or segmentation violation occurs:
!    1) ACTION is called.  It is passed an argument equal to
!         - 0, for a stack overflow,
!         - SIGSEGV, for a segmentation violation that does not appear related
!           to stack overflow.
!       On many platforms the two cases are hard to distinguish; when in doubt,
!       zero is passed.
!    2) If ACTION returns, a message is written to standard error, and the
!       program is terminated: in the case of stack overflow, with exit code
!       exit_failure (see "exitfail.h"), otherwise through a signal SIGSEGV.
! 
!    A null ACTION acts like an action that does nothing.
! 
!    ACTION must be async-signal-safe.  ACTION together with its callees
!    must not require more than SIGSTKSZ bytes of stack space.  Also,
!    ACTION should not call longjmp, because this implementation does
!    not guarantee that it is safe to return to the original stack.  */
! 
! extern int c_stack_action (void (* /*action*/) (int));
*** lib/c-stack.c.orig  2008-07-20 18:22:06.000000000 +0200
--- lib/c-stack.c       2008-07-20 18:03:05.000000000 +0200
***************
*** 189,209 ****
    die ((!emergency || segv_handler_missing) ? 0 : SIGSEGV);
  }
  
- /* Set up ACTION so that it is invoked on C stack overflow.  Return -1
-    (setting errno) if this cannot be done.
- 
-    When ACTION is called, it is passed an argument equal to SIGSEGV
-    for a segmentation violation that does not appear related to stack
-    overflow, and is passed zero otherwise.  On many platforms it is
-    hard to tell; when in doubt, zero is passed.
- 
-    A null ACTION acts like an action that does nothing.
- 
-    ACTION must be async-signal-safe.  ACTION together with its callees
-    must not require more than SIGSTKSZ bytes of stack space.  Also,
-    ACTION should not call longjmp, because this implementation does
-    not guarantee that it is safe to return to the original stack.  */
- 
  int
  c_stack_action (void (*action) (int))
  {
--- 189,194 ----
***************
*** 298,318 ****
  }
  # endif
  
- /* Set up ACTION so that it is invoked on C stack overflow.  Return -1
-    (setting errno) if this cannot be done.
- 
-    When ACTION is called, it is passed an argument equal to SIGSEGV
-    for a segmentation violation that does not appear related to stack
-    overflow, and is passed zero otherwise.  On many platforms it is
-    hard to tell; when in doubt, zero is passed.
- 
-    A null ACTION acts like an action that does nothing.
- 
-    ACTION must be async-signal-safe.  ACTION together with its callees
-    must not require more than SIGSTKSZ bytes of stack space.  Also,
-    ACTION should not call longjmp, because this implementation does
-    not guarantee that it is safe to return to the original stack.  */
- 
  int
  c_stack_action (void (*action) (int))
  {
--- 283,288 ----