git: b381d0980221 - main - stddef.h: add unreachable() for C23 compliance

The branch main has been updated by fuz:

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

commit b381d0980221b476cadbef862a8e5973d675fb7a
Author:     Robert Clausecker <fuz@FreeBSD.org>
AuthorDate: 2025-11-27 20:19:49 +0000
Commit:     Robert Clausecker <fuz@FreeBSD.org>
CommitDate: 2025-11-28 15:56:49 +0000

    stddef.h: add unreachable() for C23 compliance
    
    unreachable() is a hint to the compiler that it is unreachable.
    Add a new man page unreachable(3) to document this macro.
    
    Reviewed by:    imp
    Approved by:    markj (mentor)
    MFC after:      1 month
    Differential Revision:  https://reviews.freebsd.org/D53967
---
 include/stddef.h             |  4 ++
 share/man/man3/Makefile      |  3 +-
 share/man/man3/assert.3      |  5 ++-
 share/man/man3/unreachable.3 | 89 ++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 98 insertions(+), 3 deletions(-)

diff --git a/include/stddef.h b/include/stddef.h
index 3ba9a9946b01..2ac8e9fe3f77 100644
--- a/include/stddef.h
+++ b/include/stddef.h
@@ -61,6 +61,10 @@ typedef	__max_align_t	max_align_t;
 #endif
 #endif
 
+#if __ISO_C_VISIBLE >= 2023
+#define unreachable(x) __unreachable(x)
+#endif
+
 #ifndef offsetof
 #define	offsetof(type, field)	__builtin_offsetof(type, field)
 #endif
diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile
index bce57291f073..e5e790194ffc 100644
--- a/share/man/man3/Makefile
+++ b/share/man/man3/Makefile
@@ -35,7 +35,8 @@ MAN=		alloca.3 \
 		sysexits.3 \
 		tgmath.3 \
 		timeradd.3 \
-		tree.3
+		tree.3 \
+		unreachable.3
 
 MLINKS=		arb.3 ARB8_ENTRY.3 \
 		arb.3 ARB8_HEAD.3 \
diff --git a/share/man/man3/assert.3 b/share/man/man3/assert.3
index f219aa1d6743..cbaedb49010a 100644
--- a/share/man/man3/assert.3
+++ b/share/man/man3/assert.3
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd April 20, 2021
+.Dd November 27, 2025
 .Dt ASSERT 3
 .Os
 .Sh NAME
@@ -118,7 +118,8 @@ constraint and includes the provided string literal:
 If none is provided, it only points at the constraint.
 .Sh SEE ALSO
 .Xr abort2 2 ,
-.Xr abort 3
+.Xr abort 3 ,
+.Xr unreachable 3
 .Sh STANDARDS
 The
 .Fn assert
diff --git a/share/man/man3/unreachable.3 b/share/man/man3/unreachable.3
new file mode 100644
index 000000000000..8a1c2d142578
--- /dev/null
+++ b/share/man/man3/unreachable.3
@@ -0,0 +1,89 @@
+.\"
+.\" Copyright (c) 2025 Robert Clausecker <fuz@FreeBSD.org>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd November 27, 2025
+.Dt UNREACHABLE 3
+.Os
+.Sh NAME
+.Nm unreachable
+.Nd the unreachable macro
+.Sh SYNOPSIS
+.In stddef.h
+.Fd #define unreachable()
+.Sh DESCRIPTION
+If the
+.Fn unreachable
+macro is reached during execution, behavior is undefined.
+This can be useful to hint to the compiler that some invariant is guaranteed to
+hold or that some case cannot occur.
+.Sh EXAMPLES
+Suppose a floating-point number
+.Va x
+is to be classified using the
+.Xr fpclassify 3
+macro and a different action is to be taken based on the result of the
+classification.
+As the set of possible return values is known, the
+.Fn unreachable
+macro can be used to hint to the compiler that it can omit checks for
+other possible return values:
+.Bd -literal -offset 3n
+#include <math.h>
+#include <stddef.h>
+#include <stdio.h>
+
+void print_classification(double x)
+{
+	printf("%f: ", x);
+
+	switch (fpclassify(x)) {
+	case FP_INFINITE:
+		puts("infinite");
+		break;
+
+	case FP_NAN:
+		puts("not a number");
+		break;
+
+	case FP_NORMAL:
+		puts("normal");
+		break;
+
+	case FP_SUBNORMAL:
+		puts("subnormal");
+		break;
+
+	case FP_ZERO:
+		puts("zero");
+		break;
+
+	default:
+		unreachable();
+}
+.Ed
+.Sh SEE ALSO
+.Xr assert 3
+.Sh STANDARDS
+The
+.Fn unreachable
+macro conforms to
+.St -isoC-2023 .
+.Sh HISTORY
+A
+.Dv /*NOTREACHED*/
+conventional comment was supported by the historical
+.Xr lint 1
+utility to suppress warnings about unreachable statements during static
+analysis.
+The
+.Fn unreachable
+macro was added in
+.Fx 15.1
+based on the earlier private
+.Fn __unreachable
+macro for compliance with
+.St -isoC-2023 .
+.Sh AUTHOR
+.Ah Robert Clausecker Aq Mt fuz@FreeBSD.org