libc: C23 conformance for <assert.h>

[kfv]

• Add __STDC_VERSION_ASSERT_H__ feature-test macro
• Restrict static_assert macro definition to pre-C23 modes
• Make assert variadic as per C23
• Update assert.3 accordingly

[github-actions]

Thank you for taking the time to contribute to FreeBSD!

Some of files have special handling:

Important

@concussious wants to review changes to share/man/

[clausecker]

CC @bsdimp

Some thoughts on this one:

• I think we can safely define assert to take the variable argument list in all modes as an extension, preventing friction when code bases are gradually extended to C23.

• not sure what _assert is. Should we touch it at all?

• document __STDC_VERSION_ASSERT_H__ please

• your documentation change is somewhat obtuse. It “takes a variable argument list,” not “takes an ellipsis.” But even with that change, the average programmer will have a hard time understanding what that means. Perhaps it would be better to explain that starting with C23, the macro is set up such that expressions including the comma operator can be used, whereas in previous versions of the C standard, such expressions would cause syntax error. Give examples and explain how to work around this shortcoming in older language revisions (by using double parentheses)

• if we chose to have assert(...) in all modes (which I recommend), document that this is supported as an extension

• please check the output of your manpage with the mandoc command. In particular, .Fn just produces the argument typeset as a function name. It does not write “function” before the function name, so if you write

  The
  .Fn foo
  is bar
  

  you get something like “the foo is bar,” which is nonsensical. Try writing

  The
  .Fn foo
  macro is bar
  

  or something similar.

[kfv]

• I think we can safely define assert to take the variable argument list in all modes as an extension, preventing friction when code bases are gradually extended to C23.

Agreed. Done.

• not sure what _assert is. Should we touch it at all?

Not sure if we should still keep it, but I think its sole purpose is backward compatibility as same-name functions with a leading underscore were seen as implementation internals back in early days of UNIX. I was not born back then, though, so I could be completely wrong.

• document __STDC_VERSION_ASSERT_H__ please

Why should we document feature test macros? That's not something user needs to be concerned with.

• your documentation change is somewhat obtuse. It “takes a variable argument list,” not “takes an ellipsis.” But even with that change, the average programmer will have a hard time understanding what that means.

It is not wrong, I believe. I've frequently seen "macros with an ellipsis parameter", "variadic macros", and similar terms—especially in the standard, proposal documents, and compiler documentation. But I understand your point, I'll take care of it shortly.

Perhaps it would be better to explain that starting with C23, the macro is set up such that expressions including the comma operator can be used, whereas in previous versions of the C standard, such expressions would cause syntax error. Give examples and explain how to work around this shortcoming in older language revisions (by using double parentheses)

Right, I'll take care of it tomorrow.

• if we chose to have assert(...) in all modes (which I recommend), document that this is supported as an extension

Sure, I'll add a note for that.

• please check the output of your manpage with the mandoc command. In particular, .Fn just produces the argument typeset as a function name. It does not write “function” before the function name, so if you write

  The
  .Fn foo
  is bar
  

  you get something like “the foo is bar,” which is nonsensical. Try writing

  The
  .Fn foo
  macro is bar
  

  or something similar.

I deliberately didn't use it for lines 105-107, but you're right about line 80. Sure. I'll do an update on the manpage tomorrow evening (better phrasing, new examples, etc.)

[kfv]

By the way, please accept my apologies if the branch is named libc/__STDC_VERSION_XXXX_H__. I started out adding missing feature test macros but ended up taking care of <assert.h>.

[clausecker]

Why should we document feature test macros? That's not something user needs to be concerned with.

The macro is part of the C standard, but in retrospect I didn't add it to <stdbit.h> either, so maybe it's ok to not have it?

It is not wrong, I believe. I've frequently seen "macros with an ellipsis parameter", "variadic macros", and similar terms—especially in the standard, proposal documents, and compiler documentation. But I understand your point, I'll take care of it shortly.

The important thing is that whatever term we use is consistent within FreeBSD's documentation. Perhaps @concussious can say more here.

Looking forwards to your updates and don't worry about the branch name.

[clausecker]

Another thing: please add to HISTORY the version in which assert() was extended to handle commas in its argument list (this should indicate 15.2 as the first version with the feature).

[kfv]

The macro is part of the C standard, but in retrospect I didn't add it to <stdbit.h> either, so maybe it's ok to not have it?

Conforming implementations must define __STDC_VERSION_XXXX_H__ macros for all headers listed in the standard, so omitting them is not acceptable, I believe. You also have it set correctly in <stdbit.h>. For more details, see the final edition of C23 Implications for C Libraries by Jens Gustedt.

In the meantime, I am working on a separate PR to address the remaining missing __STDC_VERSION_XXXX_H__ macros across the tree and will submit it within the next few hours.

As mentioned in the shared document, the macro can be defined before full conformance (e.g. as an include guard only) as long as its value is empty or a smaller number like 0. Once that header is fully conforming to C23, the value must be 202311L.

The important thing is that whatever term we use is consistent within FreeBSD's documentation. Perhaps @concussious can say more here.

You're right, it now makes complete sense to me. Fair point. Thanks.

Looking forwards to your updates and don't worry about the branch name.

Thanks, Robert.

Another thing: please add to HISTORY the version in which assert() was extended to handle commas in its argument list (this should indicate 15.2 as the first version with the feature).

Sure, will do.

[kfv]

In the meantime, I am working on a separate PR to address the remaining missing __STDC_VERSION_XXXX_H__ macros across the tree and will submit it within the next few hours.

Just opened the PR as a draft. I'll add description and mark it as ready for review once my tests complete, but happy to hear any early feedback or requests in the meantime.

[bms]

OT: An adjacent data point to consider for assert(): if you're profiling code bases for source code complexity metric, allegedly its use bloats the SonarSource metric. as measured by clang-tidy, and this requires a specific workaround. Found because I've been doing background research to support falsifying certain other... hypotheses.

[kfv]

OT: An adjacent data point to consider for assert(): if you're profiling code bases for source code complexity metric, allegedly its use bloats the SonarSource metric. as measured by clang-tidy, and this requires a specific workaround. Found because I've been doing background research to support falsifying certain other... hypotheses.

Interesting! Thanks for the point. I'd love to hear more about your findings.

[kfv]

Addressed Robert's notes as best I could. I kept the ellipsis term but tried to clarify the macro signature description around it (I'm open to removing it altogether, but couldn't think of a better phrasing, to be honest). Let me know if you any suggestions.

Cc: @clausecker, @concussious

[clausecker]

More corrections.

Is the complicated definition of assert() something Jens Gustedt cooked up?

[clausecker]

Please use .Vn for S.

[kfv]

Did you mean .Vt? .Vn doesn't appear to exist in mdoc(7). I used .Vt here, though .Sy would also be reasonable — happy to switch if you have a preference. By the way, I didn't fold it into a fixup since the file was untouched by my previous commits.

[clausecker]

Oh sorry, I meant .Va for variable name. .Vt is for variable types, though I think you are right that it is better. Not sure in any case.

[kfv]

Is the complicated definition of assert() something Jens Gustedt cooked up?

No, Peter Sommerlad.

[clausecker]

@kfv Please try to avoid force-pushing unless you merely do a rebase. Force pushes make it really hard to see what changes you did relatively to the previous state. It's better if you push fix-up commits; we'll squash them on commit.

[kfv]

@kfv Please try to avoid force-pushing unless you merely do a rebase. Force pushes make it really hard to see what changes you did relatively to the previous state. It's better if you push fix-up commits; we'll squash them on commit.

Understood, sure, will do.

[clausecker]

I think this looks pretty good.
Will do some final checks if this works in C99 mode, too, and if it does, land the change set.

[bsdimp]

I'm almost positive _Bool will work in c99 and c89 compilation environments. Both gcc and clang have these always on. They do for other __foo things.