svn commit: r334306 - in head: lib/libc/stdlib share/man/man3

[Bruce Evans]

On Tue, 29 May 2018, Eric van Gyzen wrote:

> Log:
>  Cross-reference abort2(2) from a few man pages
>
>  I didn't know abort2 existed until it was mentioned on a mailing list.
>  Mention it in related pages so others can find it easily.
>
>  MFC after:	3 days
>  Sponsored by:	Dell EMC
>
> Modified:
>  head/lib/libc/stdlib/abort.3
>  head/lib/libc/stdlib/exit.3
>  head/share/man/man3/assert.3

exit(3) is negatively related.  abort2() exists mainly because it is invalid
to call non-signal-safe functions like exit() from signal handlers.

exit(3) correctly doesn't reference abort(3) or any of the many other
functions that call it, e.g., perror(3) or err(3), or many functions
that it calls.  The references correctly go only towards exit() from
its callers, This is especially interesting for abort() -- since abort()
calls exit(), it is broken as specified and cannot be called from
signal handlers.  Its man page doesn't actually say that it calls
exit(), but says that
- it flushes and closes any open streams
- it is thread-safe
- it is unknown if it is async-signal state
Its reference to exit(3) is the usual nodescript one in the SEE ALSO section
with no hint about why the other man pages might be relevant.  Readers must
read and understand the closure of the tree of cross references to determine
the relevances.

I just remembered that abort() flushing and closing open streams and
possibly calling exit() is not a design error, but just a bug in some OS's
and some versions of POSIX.

In C99, flushing and closing of open streams in abort() is
implementation-defined.  Only systems with primitive signal handling
can hope to flush or close open streams in async-signal handlers
(mostly by not supporting any such handlers).

POSIX might have been such a system, and it required closing open
streams in at least its 1990 and 2001 versions.  These versions also
didn't require abort() to be async-signal-safe.

This is fixed in POSIX in at least its 2007 version.  This version
requires abort() to be async-signal-safe and permits but doesn't require
abort() to fclose() open streams.

[Free]BSD has never been such a system.  Its abort() was async-signal
safe before 1996 when it was broken to POSIX spec at the time.  It
hasn't caught up with 2007 POSIX yet: its implementation still calls
stdio and says in a comment that POSIX requires this, and its man page
still claims to not know what the implementation does.  (The man page
is trying to echo the fuzziness of the C standard for abort(), FreeBSD
should document the non-fuzzy although sometimes broken POSIX behaviour,
and the full C standard requires implementations to document their
choices for implementation details.)

Bruce