ws_assert.h File Reference

#include <ws_symbol_export.h>
#include <ws_attributes.h>
#include <stdbool.h>
#include <string.h>
#include <wsutil/wslog.h>
#include <wsutil/wmem/wmem.h>

Go to the source code of this file.

Macros
#define	WS_ASSERT_ENABLED   1
#define	ws_assert_if_active(active, expr)
	Conditionally assert an expression.
#define	ws_abort_if_fail(expr)    ws_assert_if_active(true, expr)
	Unconditionally assert an expression, typically for static analysis.
#define	ws_assert(expr)    ws_assert_if_active(WS_ASSERT_ENABLED, expr)
	Unconditionally assert an expression when assertions are enabled.
#define	ws_assert_streq(s1, s2)    ws_assert((s1) && (s2) && strcmp((s1), (s2)) == 0)
	Assert that two strings are non-NULL and equal.
#define	ws_assert_utf8(str, len)
	Assert that a string is valid UTF-8 when assertions are enabled.
#define	ws_assert_not_reached()    ws_error("assertion \"not reached\" failed")
	Unconditionally abort execution if reached; always indicates a programming error.
#define	ws_warn_badarg(str)
	Log a warning for an invalid function argument.
#define	ws_return_str_if(expr, scope)
	Return a formatted error string if an expression is true and assertions are enabled.
#define	ws_return_val_if(expr, val)
	Return a value if an expression is true and assertions are enabled.

Detailed Description

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Macro Definition Documentation

ws_abort_if_fail

#define ws_abort_if_fail

(

expr

)

ws_assert_if_active(true, expr)

Unconditionally assert an expression, typically for static analysis.

Always evaluates expr and triggers an error via ws_error() if it fails. Intended to satisfy static analyzers by ensuring the expression is checked, regardless of runtime assertion settings.

Parameters

expr	Expression to assert.

ws_assert

#define ws_assert

(

expr

)

ws_assert_if_active(WS_ASSERT_ENABLED, expr)

Unconditionally assert an expression when assertions are enabled.

Evaluates expr only if WS_ASSERT_ENABLED is true. The expression must not produce side effects, as assertion state should not alter program behavior. If the assertion fails, triggers an error via ws_error().

Parameters

expr	Expression to assert.

ws_assert_if_active

#define ws_assert_if_active	(		active,
			expr
	)

Value:

        do {                                                \
            if ((active) && !(expr))                        \
                ws_error("assertion failed: %s", #expr);    \
        } while (0)

Conditionally assert an expression.

Evaluates the expression expr when active is true. If the expression evaluates to false, triggers an error with a descriptive message via ws_error(). When active is false, the expression is wrapped in a dead branch to avoid execution while suppressing unused variable warnings, allowing the compiler to optimize it away.

Parameters

active	Flag indicating whether assertions are enabled.
expr	Expression to be asserted.

ws_assert_not_reached

#define ws_assert_not_reached

(

)

ws_error("assertion \"not reached\" failed")

Unconditionally abort execution if reached; always indicates a programming error.

This macro is used to mark code paths that should never be executed. Unlike conditional assertions, it is always active—even when assertions are disabled— to prevent compiler warnings and ensure that unreachable code is clearly flagged. Invoking this macro will trigger an error via ws_error() and terminate execution.

ws_assert_streq

#define ws_assert_streq	(		s1,
			s2
	)		ws_assert((s1) && (s2) && strcmp((s1), (s2)) == 0)

Assert that two strings are non-NULL and equal.

Checks that both s1 and s2 are non-NULL and that their contents match. If the assertion fails, triggers an error via ws_error().

Parameters

s1	First string to compare.
s2	Second string to compare.

ws_assert_utf8

#define ws_assert_utf8	(		str,
			len
	)

Value:

        do {                                                            \
            const char *__assert_endptr;                                \
            if (WS_ASSERT_ENABLED &&                                    \
                        !g_utf8_validate(str, len, &__assert_endptr)) { \
                ws_log_utf8_full(LOG_DOMAIN_UTF_8, LOG_LEVEL_ERROR,     \
                                    __FILE__, __LINE__, __func__,       \
                                    str, len, __assert_endptr);         \
            }                                                           \
        } while (0)

Assert that a string is valid UTF-8 when assertions are enabled.

Validates that the given string str of length len is well-formed UTF-8. If validation fails and assertions are enabled, logs an error with full context including the location of the failure.

Parameters

str	Pointer to the string to validate.
len	Length of the string in bytes.

ws_return_str_if

#define ws_return_str_if	(		expr,
			scope
	)

Value:

        do { \
            if (WS_ASSERT_ENABLED && (expr)) { \
                ws_warn_badarg(#expr); \
                return wmem_strdup_printf(scope, "(invalid argument: %s)", #expr); \
            } \
        } while (0)

Return a formatted error string if an expression is true and assertions are enabled.

Checks expr when WS_ASSERT_ENABLED is true. If the expression evaluates to true, logs a warning with the expression string and returns a formatted error string allocated in the given scope.

Parameters

expr	Expression to evaluate.
scope	Memory scope for allocating the returned error string.

ws_return_val_if

#define ws_return_val_if	(		expr,
			val
	)

Value:

        do { \
            if (WS_ASSERT_ENABLED && (expr)) { \
                ws_warn_badarg(#expr); \
                return (val); \
            } \
        } while (0)

Return a value if an expression is true and assertions are enabled.

Checks expr when WS_ASSERT_ENABLED is true. If the expression evaluates to true, logs a warning with the expression string and returns the specified value val.

Parameters

expr	Expression to evaluate.
val	Value to return if the expression is true.

ws_warn_badarg

#define ws_warn_badarg

(

str

)

Value:

    ws_log_full(LOG_DOMAIN_EINVAL, LOG_LEVEL_WARNING, \
                    __FILE__, __LINE__, __func__, \
                    "invalid argument: %s", str)

Log a warning for an invalid function argument.

Emits a warning message indicating that the argument str is invalid. Intended for use in macros that assert argument correctness without causing inconsistent program state. Can be paired with a fatal log domain for debugging purposes.

Parameters

str	String representation of the invalid argument expression.