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 <[EMAIL PROTECTED]>
* 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 ----
