Date: Sat, 30 May 2026 13:44:30 +0000 From: Robert Clausecker <fuz@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Cc: Faraz Vahedi <kfv@kfv.io> Subject: git: c115aad996d5 - main - assert.3: Update as per C23 Message-ID: <6a1ae9be.30c08.1685e514@gitrepo.freebsd.org>
index | next in thread | raw e-mail
The branch main has been updated by fuz: URL: https://cgit.FreeBSD.org/src/commit/?id=c115aad996d52f5270ccd22b27d1f34b4f0f4160 commit c115aad996d52f5270ccd22b27d1f34b4f0f4160 Author: Faraz Vahedi <kfv@kfv.io> AuthorDate: 2026-05-20 07:22:19 +0000 Commit: Robert Clausecker <fuz@FreeBSD.org> CommitDate: 2026-05-30 13:43:52 +0000 assert.3: Update as per C23 Signed-off-by: Faraz Vahedi <kfv@kfv.io> Reviewed by: fuz MFC after: 1 month Pull Request: https://github.com/freebsd/freebsd-src/pull/2203 --- share/man/man3/assert.3 | 76 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 61 insertions(+), 15 deletions(-) diff --git a/share/man/man3/assert.3 b/share/man/man3/assert.3 index f219aa1d6743..2782ffe7de18 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 May 17, 2026 .Dt ASSERT 3 .Os .Sh NAME @@ -40,15 +40,14 @@ .Sh DESCRIPTION The .Fn assert -macro tests the given -.Ar expression +macro tests the given scalar +.Ar expression , and if it is false, -the calling process is terminated. -A diagnostic message is written to +a diagnostic message is written to .Dv stderr and the function .Xr abort 3 -is called, effectively terminating the program. +is called, effectively terminating the calling process. .Pp If .Ar expression @@ -57,6 +56,22 @@ the .Fn assert macro does nothing. .Pp +In all compilation modes, +.Fn assert +is defined as a macro with an ellipsis parameter, consistent with the +C23 standard. +This allows expressions containing commas to be passed directly without +requiring an extra pair of enclosing parentheses. +Only a single scalar expression is evaluated. +Supplying multiple arguments is prohibited, and hence are top-level comma +operators. +In particular, this guards against accidentally writing +.Fn assert +in the style of +.Fn static_assert , +which would otherwise silently evaluate as always true via the comma +operator. +.Pp The .Fn assert macro @@ -73,7 +88,7 @@ may be included multiple times. Each time whether or not .Dv NDEBUG is defined determines the behavior of assert from that point forward -until the end of the unit or another include of +until the end of the unit or another inclusion of .In assert.h . .Pp The @@ -82,9 +97,9 @@ macro should only be used for ensuring the developer's expectations hold true. It is not appropriate for regular run-time error detection. .Pp -The +In pre-C23 compilation modes .Fn static_assert -macro expands to +is implemented as a macro and expands to .Fn _Static_assert , and, contrarily to .Fn assert , @@ -94,8 +109,14 @@ message including the string literal message, if provided. The initial form of the .Fn _Static_assert containing a string literal message was introduced in C11 standard, and -the other form with no string literal is to be implemented by C2x and -some compilers may lack its adoption at present. +the other form with no string literal conforms to C23 standard. +.Pp +In C23 and later, +.Fn static_assert +is a language keyword, and +.Fn _Static_assert +is provided as an obsolescent alternative spelling that should not be +used for new code and development. .Sh EXAMPLES The assertion: .Dl "assert(1 == 0);" @@ -111,7 +132,20 @@ Second, the code will disappear if .Dv NDEBUG is defined, changing the semantics of the program. .Pp -The following asserts that the size of the S structure is 16. +The following example asserts that the +.Va iov_len +member of the compound literal, reflecting the value of +.Va len , +is non-zero. +The compound literal contains a comma that is not protected by +parentheses, which the variadic +.Fn assert +macro handles transparently: +.Dl assert((struct iovec){ buf, len }.iov_len); +.Pp +The following asserts that the size of the +.Vt S +structure is 16. Otherwise, it produces a diagnostic message which points at the constraint and includes the provided string literal: .Dl "static_assert(sizeof(struct S) == 16, ""size mismatch"");" @@ -123,14 +157,26 @@ If none is provided, it only points at the constraint. The .Fn assert macro conforms to -.St -isoC-99 . +.St -isoC-2023 . .Pp The .Fn static_assert macro conforms to .St -isoC-2011 . +In +.St -isoC-2023 , +it is a language keyword; whether the macro is defined or not +depends on compilation mode. .Sh HISTORY -An +The .Nm -macro appeared in +macro first appeared in .At v7 . +Starting with +.Fx 15.2 , +it accepts a variadic argument list, allowing expressions +containing commas, such as compound literals, to be passed +without requiring extra enclosing parentheses. +This conforms to +.St -isoC-2023 , +but made available in all compilation modes.home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?6a1ae9be.30c08.1685e514>