| Wireshark 4.7.0 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Macros
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.