bin/58570: ATF_CHECK_ERRNO semantics and/or documentation is confusing

[campbell+netbsd%mumble.net@localhost]

>Number:         58570
>Category:       bin
>Synopsis:       ATF_CHECK_ERRNO semantics and/or documentation is confusing
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          sw-bug
>Submitter-Id:   net
>Arrival-Date:   Sat Aug 10 14:00:00 +0000 2024
>Originator:     Taylor R Campbell
>Release:        current, 10, 9, ...
>Organization:
The NetATF Errnodation
>Environment:
>Description:
Every time I read or reach for ATF_CHECK_ERRNO or ATF_REQUIRE_ERRNO, I have to look at the documentation to confirm what they mean.  That would be fine, except I don't understand what they are actually checking/requiring from the text in the man page:

     ATF_CHECK_ERRNO() and ATF_REQUIRE_ERRNO() take, first, the error code
     that the check is expecting to find in the errno variable and, second, a
     boolean expression that, if evaluates to true, means that a call failed
     and errno has to be checked against the first value.

So I have to look at the source code to confirm what they mean.

I think (I hope) what they mean is:

    ATF_CHECK_ERRNO(EWOTSIT, foo() == -1) checks that foo() == -1 is true, _and_ that errno == EWOTSIT.
>How-To-Repeat:
read or reach for ATF_CHECK_ERRNO/ATF_REQUIRE_ERRNO
>Fix:
Yes, please!

Clarifying the language in the man page would save me a lot of time.