From 065a39d1ff7eb9dba34f3a4020be752a53546a43 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Sun, 20 Jul 2008 18:25:12 +0200 Subject: [PATCH] Improve documentation. --- ChangeLog | 5 +++++ lib/c-stack.c | 30 ------------------------------ lib/c-stack.h | 27 +++++++++++++++++++++++++-- 3 files changed, 30 insertions(+), 32 deletions(-) diff --git a/ChangeLog b/ChangeLog index 20d30e03ef..e79b2aec14 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2008-07-20 Bruno Haible + + * lib/c-stack.h (c_stack_action): Add documentation. + * lib/c-stack.c (c_stack_action): Remove incomplete documentation. + 2008-07-20 Bruno Haible * modules/canonicalize-lgpl (License): Relicense under LGPLv2+. diff --git a/lib/c-stack.c b/lib/c-stack.c index c81fbfa782..c46c231361 100644 --- a/lib/c-stack.c +++ b/lib/c-stack.c @@ -189,21 +189,6 @@ overflow_handler (int emergency, 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)) { @@ -298,21 +283,6 @@ segv_handler (int signo, siginfo_t *info, } # 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)) { diff --git a/lib/c-stack.h b/lib/c-stack.h index 5f80457398..8c06541fd6 100644 --- a/lib/c-stack.h +++ b/lib/c-stack.h @@ -1,6 +1,6 @@ /* Stack overflow handling. - Copyright (C) 2002, 2004 Free Software Foundation, Inc. + 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,4 +15,27 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . */ -int c_stack_action (void (*) (int)); + +/* 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)); -- 2.30.2