cdefs(9): encourage __nodiscard over __result_use_check

__nodiscard is closer to (and sometimes expands to) [[nodiscard]] from
C23 and C++17 so prefer it to the homegrown __result_use_check.

When __nodiscard does expand to [[nodiscard]] it must appear entierly
before the function declaration (or between the function name
and argument list) so relocate as appropriate.  This differs from
__attribute__((__warn_unused_result__)) used by __result_use_check which
is more flexible.

Reviewed by:	imp, markj, emaste
Sponsored by:	DARPA, AFRL
Differential Revision:	https://reviews.freebsd.org/D57881

1 files changed, 7 insertions, 1 deletions

diff --git a/share/man/man9/cdefs.9 b/share/man/man9/cdefs.9
index 2bda50c3f875..9edfeec70bc6 100644
--- a/share/man/man9/cdefs.9
+++ b/share/man/man9/cdefs.9
@@ -3,7 +3,7 @@
 .\"
 .\" SPDX-License-Identifier: BSD-2-Clause
 .\"
-.Dd May 6, 2026
+.Dd June 26, 2026
 .Dt CDEFS 9
 .Os
 .Sh NAME
@@ -121,6 +121,9 @@ family of functions.
 .Dq fastcall
 ABI to call and name mangle this function.
 .It Sy __result_use_check Ta Warn if function caller does not use its return value
+Obsolete, use
+.Sy __nodiscard
+instead.
 .It Sy __nodiscard Ta Equivalent to the standard
 .Dq [[nodiscard]]
 attribute.
@@ -134,6 +137,9 @@ If applied to a struct, C++ class or enum, this applies to all functions
 returning values of that type.
 If applied to a C++ constructor, this applies to creating instances of
 the class using that constructor.
+Note that
+.Sy __nodiscard
+must appear before the function declaration.
 .It Sy __returns_twice Ta Returns multiple times, like
 .Xr fork 2
 .It Sy __unreachable Ta This code is not reachable at runtime