sys/cdefs.h: Introduce __maybe_unused attribute

[rosenfeld_grumpf.hope-2000.org]

Summary

The maybe_unused attribute should be used for variables which may or
may not be used, such as when their only use is in an assertion. This
attribute is functionally identical to unused, suppressing compiler
warnings for particular variable if it remains unused.

[rosenfeld_grumpf.hope-2000.org]

Note that I did not remove all existing definitions of __maybe_unused, only the one in linuxkpi which was causing build issues. There's another one in OpenZFS (two actually, one for Linux and one for FreeBSD) and one in the WPA utils.

[minsoochoo0122_proton.me]

Since we have [[maybe_unused]] in C23, could you elaborate why we need this to be in <sys/cdefs.h>?

[rosenfeld_grumpf.hope-2000.org]

In D56517#1294475, @minsoochoo0122_proton.me wrote:

Since we have [[maybe_unused]] in C23, could you elaborate why we need this to be in <sys/cdefs.h>?

There's currently four individual definitions of __maybe_unused the source tree, I'm just moving them to a central place as suggested by Ed.

Yes, I know about [[maybe_unused]] in C23. I don't know whether the whole FreeBSD source is considered fit for C23 already, but even then I wouldn't really want to depend on it in portable code such as bhyve (at least for a while).

[emaste]

Yes we might be able to use C23 [[maybe_unused]] in the future but we have a lot of places (headers, code shared with other projects) where we cannot require C23.

[minsoochoo0122_proton.me]

In D56517#1294491, @rosenfeld_grumpf.hope-2000.org wrote:

There's currently four individual definitions of __maybe_unused the source tree, I'm just moving them to a central place as suggested by Ed.

Make sense. LGTM!

[mhorne]

Please also add an entry to the share/man/man9/cdefs.9 man page.

[imp]

This is fine for now. I'd like to see it become [[maybe_unused]] conditionally in the future as C23 picks up steam and compilers give better diagnostics. Though the semantic differences between unused and maybe unused are a bit thin today (eg __unused means to the compiler don't warn if not used, which is what you want with maybe unused, though maybe it would be nice to have something that then warns if it is used anyway (though I've never wanted that).

[rosenfeld_grumpf.hope-2000.org]

Update manpage.

[minsoochoo0122_proton.me]

share/man/man9/cdefs.9

92

If __unused and __maybe_unused are both __attribute(__unused__) under the hood, shouldn't they have the same description?

[rosenfeld_grumpf.hope-2000.org]

share/man/man9/cdefs.9

92

Not necessarily, although that's really more of a philosophical question rather than a technical one.

I think of it this way: __unused was introduced to silence unused variable warnings, and as you can tell from the manpage it probably was intended to mean "this may be unused" rather than "this is definitely unused". But apparently the latter meaning stuck in people's minds, and thats why we eventually got __maybe_unused, too, to make the programmer intent clear. The compiler (currently) doesn't care and uses it only to silence warnings, but who can tell how this may evolve. At least we can expect that one day, __maybe_unused will likely be defined to [[maybe_unused]], while __unused becomes [[unused]].

[minsoochoo0122_proton.me]

share/man/man9/cdefs.9

92

<sys/cdefs.h> can be used in C++ as well where __maybe_unused (originally [[maybe_unused]] has already took __unused's role in C for "usually arguments" part. In other words, the man page is only valid for C not C++.

One might ask who would use __maybe_unused over [[maybe_unused]] in C++, and that's a fair point. But because this is a manual page, I think it's good to note that __unused and __maybe_unused are same thing under the hood, which is also same as [[maybe_unused]] according to the clang documentation (I don't know if GCC treats them same as well).

Also I hope the definition of __maybe_unused becomes more in detail like __nodiscard where the declaration varies by C/C++ and has/doesn't have attribute, etc:

#if defined(__cplusplus) && defined(__has_cpp_attribute)
#if __has_cpp_attribute(nodiscard)
#define	__nodiscard	[[nodiscard]]
#endif
#elif defined(__STDC_VERSION__) && defined(__has_c_attribute)
#if __has_c_attribute(__nodiscard__)
#define	__nodiscard	[[__nodiscard__]]
#endif
#endif

but [[maybe_unused]] should be selected on C23 and later as well, not only in C++.

[rosenfeld_grumpf.hope-2000.org]

Update manpage as requested.

[minsoochoo0122_proton.me]

LGTM!

sys/sys/cdefs.h

155

Some might want #if defined(<attribute>), but the end result is the same so no need here.