* doc/autoconf.texi (Run Time): Document the exit status situation

with more accuracy and detail.

diff --git a/ChangeLog b/ChangeLog
index 82e9e07ff79562168316df9f6f258fc00c6b65dd..bde9073f8d8650ac40bccc3338f0b5b5b40e0dd0 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,10 +1,14 @@
 2006-04-23  Paul Eggert  <eggert@cs.ucla.edu>
 
+       * doc/autoconf.texi (Run Time): Document the exit status situation
+       with more accuracy and detail.
+
        * NEWS: Remove mention of AS_VAR_SET_BASENAME and AS_VAR_SET_DIRNAME.
        * doc/autoconf.texi (Programming in M4sh): Remove mention of
        AS_VAR_SET_BASENAME, AS_VAR_SET_DIRNAME, and AS_BASENAME.
        We have to keep AS_DIRNAME since it was part of a stable Autoconf,
        but AS_BASENAME doesn't have to be supported.
+
        * lib/m4sugar/m4sh.m4 (AS_BASENAME, AS_DIRNAME): Bring these back.
 
 2006-04-23  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 6f3202a90fa7ebf765f75b4b3727719198c710a3..96dd36f12b90c146ea588c5a7ffca80644f87e48 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -7666,14 +7666,10 @@ not run.  If the optional shell commands @var{action-if-cross-compiling}
 are given, they are run instead.  Otherwise, @command{configure} prints
 an error message and exits.
 
-In the @var{action-if-false} section, the exit status of the program is
-available in the shell variable @samp{$?}, but be very careful to limit
-yourself to positive values smaller than 127; bigger values should be
-saved into a file by the @var{program}.  Note also that you have simply
-no guarantee that this exit status is issued by the @var{program}, or by
-the failure of its compilation.  In other words, use this feature if
-sadist only, it was reestablished because the Autoconf maintainers grew
-tired of receiving ``bug reports''.
+In the @var{action-if-false} section, the failing exit status is
+available in the shell variable @samp{$?}.  This exit status might be
+that of a failed compilation, or it might be that of a failed program
+execution.
 
 It is customary to report unexpected failures with
 @code{AC_MSG_FAILURE}.
@@ -7701,6 +7697,30 @@ you can test whether the shell variable @code{cross_compiling} is set to
 @samp{yes}, and then use an alternate method to get the results instead
 of calling the macros.
 
+A C or C++ runtime test can exit with status @var{N} by returning
+@var{N} from the @code{main} function.  Portable programs are supposed
+to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
+status @code{EXIT_FAILURE} to fail, but in practice it is portable to
+fail by exiting with status 1, and test programs that assume Posix can
+fail by exiting with status values from 1 through 255.  Programs on
+SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
+status when @code{main} returned nonzero, but ancient systems like these
+are no longer of practical concern.
+
+A test can also exit with status @var{N} by passing @var{N} to the
+@code{exit} function, and a test can fail by calling the @code{abort}
+function.  If a test is specialized to just some platforms, it can fail
+by calling functions specific to those platforms, e.g., @code{_exit}
+(Posix) and @code{_Exit} (C99).  However, like other functions, an exit
+function should be declared, typically by including a header.  For
+example, if a test calls @code{exit}, it should include @file{stdlib.h}
+either directly or via the default includes (@pxref{Default Includes}).
+
+A test can fail due to undefined behavior such as dereferencing a null
+pointer, but this is not recommended as undefined behavior allows an
+implementation to do whatever it pleases and this includes exiting
+successfully.
+
 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
 function: the given status code is used to determine the success of the test
 (status is @code{0}) or its failure (status is different than @code{0}), as