aborts: Clarify documentation and comments

[ijackson]

In the docs for intrinsics::abort():

• Strengthen the recommendation by to use process::abort instead.
• Document the fact that it sometimes (ab)uses an LLVM debug trap and what the likely consequences are.
• State that the precise behaviour is unstable.

In the docs for process::abort():

• Promise that we have the same behaviour as C abort().
• Document the likely consequences, including, specifically, the consequences on Unix.

In the internal comment for unix::abort_internal:

• Refer to the public docs for the public API functions.
• Correct and expand the description of libc::abort. Specifically:
• Do not claim that abort() unregisters signal handlers. It doesn't; it honours the SIGABRT handler.
• Discuss, extensively, the issue with abort() flushing stdio buffers.
• Describe the glibc behaviour in some detail.

Co-authored-by: Mark Wooding mdw@distorted.org.uk
Signed-off-by: Ian Jackson ijackson@chiark.greenend.org.uk

Fixes#40230

[rust-highfive]

r? @m-ou-se

(rust-highfive has picked a reviewer for you, use r? to override)

[ijackson]

I have a WIP branch to make panic aborts all be libc::abort but it's not ready yet.

[Urgau]

I have a WIP branch to make panic aborts all be libc::abort but it's not ready yet.

How will you handle system that don't have libc or not even an OS ?

[ijackson]

How will you handle system that don't have libc or not even an OS ?

This is in std, and (IIRC, without reminding myself by looking at the code again) the answer is by calling abort_internal. But let us discuss that in the MR for that other branch when I have it prepared. Right now it doesn't actually work completely right :-).

[ojeda]

Perhaps mention it is implementation-defined as a first point (C18 7.22.4.1p1).

[ojeda]

It would be better to point to C18 (it is still 7.14.1.1p5).

[SimonSapin]

What motivated opening #40230 is that Servo has a "crash handler" registered for SEGV, ILL, IOT, and BUS signals that prints the stack/backtrace of the current thread then aborts the process. These backtraces have proven many times essential in debugging crashes that happen during automated CI.

When aborting with std::process::abort we encountered a bug where the signal handler would be called in a loop. This is consistent with this PR’s comment that libc::abort may trigger one of the registered signals. The best (least worse) work-around we found at the time was to use std::intrinsics::abort instead, despite the recommendation to prefer std::process::abort: servo/servo#16899. Now I realize that a better fix might have been to have the handler unregister itself the first time it runs?

[ijackson]

What motivated opening #40230 is that Servo has a "crash handler" registered for SEGV, ILL, IOT, and BUS signals that prints the stack/backtrace of the current thread then aborts the process. These backtraces have proven many times essential in debugging crashes that happen during automated CI.

Yes, this is not an uncommon technique. I'm not sure, though, why ABRT wasn't in your list there.

When aborting with std::process::abort we encountered a bug where the signal handler would be called in a loop. This is consistent with this PR’s comment that libc::abort may trigger one of the registered signals. The best (least worse) work-around we found at the time was to use std::intrinsics::abort instead, despite the recommendation to prefer std::process::abort: servo/servo#16899. Now I realize that a better fix might have been to have the handler unregister itself the first time it runs?

Yes, the usual approach to this problem is indeed to make sure the signal handler does not run recursively. You can easily have the kernel reset the signal handler for you: pass the SA_RESETHAND flag in sa_flags when calling sigaction.

Do you think my docs here would have been sufficient to help your former selves? :-)

[SimonSapin]

I'm not sure, though, why ABRT wasn't in your list there.

I’m not sure either. Presumably printing the stack is less useful in cases of deliberate abort than for crashes caused by Undefined Behavior?

I just realized that it’s the intrinsics::abort docs that mention SIGILL and SIGSEGV, but the process::abort docs only mention SIGART, which is not consistent with how we observed the looped/recursive handler at the time :/

[m-ou-se]

Two notes:

• I don't think there's much use in calling this 'abuse'.
• In the rest of std we use the word 'terminate' instead of 'die' for processes.

How about something like this?

Suggested change

	/// The current implementation of `intrinsics::abort` (ab)uses a debug trap
	/// on some popular platforms.
	/// On Unix, the
	/// process will probably die of a signal like `SIGABRT`, `SIGILL`, `SIGTRAP`, `SIGSEGV` or
	/// `SIGBUS`. The precise behaviour is not guaranteed and not stable.
	/// The current implementation of `intrinsics::abort` results in an invalid
	/// instruction on most platforms. On Unix, this will probably cause the
	/// process to be terminated with a signal like `SIGABRT`, `SIGILL`,
	/// `SIGTRAP`, `SIGSEGV` or `SIGBUS`. The precise behaviour is not
	/// guaranteed and not stable.

[ijackson]

Thaks for the attention. I have more-or-less adopted your suggestions. I preferred a more active voice.

[ijackson]

I have (belatedly) enabled the pre-push hook that stops me pushing those empty WIP commits. Apologies for the noise.

[bors]

☔ The latest upstream changes (presumably #86817) made this pull request unmergeable. Please resolve the merge conflicts.

[m-ou-se]

Applied a suggestion and rebased for a merge conflict.

@bors r+ rollup

[bors]

📌 Commit 08d912f has been approved by m-ou-se

[ijackson]

Mara Bos writes ("Re: [rust-lang/rust] aborts: Clarify documentation and comments (#85377)"):

Applied a suggestion and rebased for a merge conflict.

Oh, thank you!

…

-- Ian Jackson ***@***.***> These opinions are my own. Pronouns: they/he. If I emailed you from @fyvzl.net or @evade.org.uk, that is a private address which bypasses my fierce spamfilter.