git: 2515e3f6776a - main - cdefs(9): encourage __nodiscard over __result_use_check

The branch main has been updated by brooks:

URL: https://cgit.FreeBSD.org/src/commit/?id=2515e3f6776a3f95c888be5e58b28df0ffbe3dd8

commit 2515e3f6776a3f95c888be5e58b28df0ffbe3dd8
Author:     Brooks Davis <brooks@FreeBSD.org>
AuthorDate: 2026-06-26 16:41:40 +0000
Commit:     Brooks Davis <brooks@FreeBSD.org>
CommitDate: 2026-06-26 16:41:40 +0000

    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
---
 share/man/man9/cdefs.9 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

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