/* * Copyright (C) Internet Systems Consortium, Inc. ("ISC") * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, you can obtain one at https://mozilla.org/MPL/2.0/. * * See the COPYRIGHT file distributed with this work for additional * information regarding copyright ownership. */ #ifndef ISC_UTIL_H #define ISC_UTIL_H 1 #include <inttypes.h> /*! \file isc/util.h * NOTE: * * This file is not to be included from any <isc/???.h> (or other) library * files. * * \brief * Including this file puts several macros in your name space that are * not protected (as all the other ISC functions/macros do) by prepending * ISC_ or isc_ to the name. */ /*** *** General Macros. ***/ /*% * Use this to hide unused function arguments. * \code * int * foo(char *bar) * { * UNUSED(bar); * } * \endcode */ #define UNUSED(x) (void)(x) #if __GNUC__ >= 8 && !defined(__clang__) #define ISC_NONSTRING __attribute__((nonstring)) #else /* if __GNUC__ >= 8 && !defined(__clang__) */ #define ISC_NONSTRING #endif /* __GNUC__ */ #if HAVE_FUNC_ATTRIBUTE_CONSTRUCTOR && HAVE_FUNC_ATTRIBUTE_DESTRUCTOR #define ISC_CONSTRUCTOR __attribute__((constructor)) #define ISC_DESTRUCTOR __attribute__((destructor)) #elif WIN32 #define ISC_CONSTRUCTOR #define ISC_DESTRUCTOR #endif /*% * The opposite: silent warnings about stored values which are never read. */ #define POST(x) (void)(x) #define ISC_MAX(a, b) ((a) > (b) ? (a) : (b)) #define ISC_MIN(a, b) ((a) < (b) ? (a) : (b)) #define ISC_CLAMP(v, x, y) ((v) < (x) ? (x) : ((v) > (y) ? (y) : (v))) /*% * Use this to remove the const qualifier of a variable to assign it to * a non-const variable or pass it as a non-const function argument ... * but only when you are sure it won't then be changed! * This is necessary to sometimes shut up some compilers * (as with gcc -Wcast-qual) when there is just no other good way to avoid the * situation. */ #define DE_CONST(konst, var) \ do { \ union { \ const void *k; \ void *v; \ } _u; \ _u.k = konst; \ var = _u.v; \ } while (0) #define ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0])) /*% * Use this in translation units that would otherwise be empty, to * suppress compiler warnings. */ #define EMPTY_TRANSLATION_UNIT extern int isc__empty; /*% * We use macros instead of calling the routines directly because * the capital letters make the locking stand out. * We RUNTIME_CHECK for success since in general there's no way * for us to continue if they fail. */ #ifdef ISC_UTIL_TRACEON #define ISC_UTIL_TRACE(a) a #include <stdio.h> /* Required for fprintf/stderr when tracing. */ #else /* ifdef ISC_UTIL_TRACEON */ #define ISC_UTIL_TRACE(a) #endif /* ifdef ISC_UTIL_TRACEON */ #include <isc/result.h> /* Contractual promise. */ #define LOCK(lp) \ do { \ ISC_UTIL_TRACE(fprintf(stderr, "LOCKING %p %s %d\n", (lp), \ __FILE__, __LINE__)); \ RUNTIME_CHECK(isc_mutex_lock((lp)) == ISC_R_SUCCESS); \ ISC_UTIL_TRACE(fprintf(stderr, "LOCKED %p %s %d\n", (lp), \ __FILE__, __LINE__)); \ } while (0) #define UNLOCK(lp) \ do { \ RUNTIME_CHECK(isc_mutex_unlock((lp)) == ISC_R_SUCCESS); \ ISC_UTIL_TRACE(fprintf(stderr, "UNLOCKED %p %s %d\n", (lp), \ __FILE__, __LINE__)); \ } while (0) #define BROADCAST(cvp) \ do { \ ISC_UTIL_TRACE(fprintf(stderr, "BROADCAST %p %s %d\n", (cvp), \ __FILE__, __LINE__)); \ RUNTIME_CHECK(isc_condition_broadcast((cvp)) == \ ISC_R_SUCCESS); \ } while (0) #define SIGNAL(cvp) \ do { \ ISC_UTIL_TRACE(fprintf(stderr, "SIGNAL %p %s %d\n", (cvp), \ __FILE__, __LINE__)); \ RUNTIME_CHECK(isc_condition_signal((cvp)) == ISC_R_SUCCESS); \ } while (0) #define WAIT(cvp, lp) \ do { \ ISC_UTIL_TRACE(fprintf(stderr, "WAIT %p LOCK %p %s %d\n", \ (cvp), (lp), __FILE__, __LINE__)); \ RUNTIME_CHECK(isc_condition_wait((cvp), (lp)) == \ ISC_R_SUCCESS); \ ISC_UTIL_TRACE(fprintf(stderr, "WAITED %p LOCKED %p %s %d\n", \ (cvp), (lp), __FILE__, __LINE__)); \ } while (0) /* * isc_condition_waituntil can return ISC_R_TIMEDOUT, so we * don't RUNTIME_CHECK the result. * * XXX Also, can't really debug this then... */ #define WAITUNTIL(cvp, lp, tp) isc_condition_waituntil((cvp), (lp), (tp)) #define RWLOCK(lp, t) \ do { \ ISC_UTIL_TRACE(fprintf(stderr, "RWLOCK %p, %d %s %d\n", (lp), \ (t), __FILE__, __LINE__)); \ RUNTIME_CHECK(isc_rwlock_lock((lp), (t)) == ISC_R_SUCCESS); \ ISC_UTIL_TRACE(fprintf(stderr, "RWLOCKED %p, %d %s %d\n", \ (lp), (t), __FILE__, __LINE__)); \ } while (0) #define RWUNLOCK(lp, t) \ do { \ ISC_UTIL_TRACE(fprintf(stderr, "RWUNLOCK %p, %d %s %d\n", \ (lp), (t), __FILE__, __LINE__)); \ RUNTIME_CHECK(isc_rwlock_unlock((lp), (t)) == ISC_R_SUCCESS); \ } while (0) /* * List Macros. */ #include <isc/list.h> /* Contractual promise. */ #define LIST(type) ISC_LIST(type) #define INIT_LIST(type) ISC_LIST_INIT(type) #define LINK(type) ISC_LINK(type) #define INIT_LINK(elt, link) ISC_LINK_INIT(elt, link) #define HEAD(list) ISC_LIST_HEAD(list) #define TAIL(list) ISC_LIST_TAIL(list) #define EMPTY(list) ISC_LIST_EMPTY(list) #define PREV(elt, link) ISC_LIST_PREV(elt, link) #define NEXT(elt, link) ISC_LIST_NEXT(elt, link) #define APPEND(list, elt, link) ISC_LIST_APPEND(list, elt, link) #define PREPEND(list, elt, link) ISC_LIST_PREPEND(list, elt, link) #define UNLINK(list, elt, link) ISC_LIST_UNLINK(list, elt, link) #define ENQUEUE(list, elt, link) ISC_LIST_APPEND(list, elt, link) #define DEQUEUE(list, elt, link) ISC_LIST_UNLINK(list, elt, link) #define INSERTBEFORE(li, b, e, ln) ISC_LIST_INSERTBEFORE(li, b, e, ln) #define INSERTAFTER(li, a, e, ln) ISC_LIST_INSERTAFTER(li, a, e, ln) #define APPENDLIST(list1, list2, link) ISC_LIST_APPENDLIST(list1, list2, link) /*% * Performance */ #include <isc/likely.h> #ifdef HAVE_BUILTIN_UNREACHABLE #define ISC_UNREACHABLE() __builtin_unreachable(); #else /* ifdef HAVE_BUILTIN_UNREACHABLE */ #define ISC_UNREACHABLE() #endif /* ifdef HAVE_BUILTIN_UNREACHABLE */ #if !defined(__has_feature) #define __has_feature(x) 0 #endif /* if !defined(__has_feature) */ /* GCC defines __SANITIZE_ADDRESS__, so reuse the macro for clang */ #if __has_feature(address_sanitizer) #define __SANITIZE_ADDRESS__ 1 #endif /* if __has_feature(address_sanitizer) */ #if __has_feature(thread_sanitizer) #define __SANITIZE_THREAD__ 1 #endif /* if __has_feature(thread_sanitizer) */ #if __SANITIZE_THREAD__ #define ISC_NO_SANITIZE_THREAD __attribute__((no_sanitize("thread"))) #else /* if __SANITIZE_THREAD__ */ #define ISC_NO_SANITIZE_THREAD #endif /* if __SANITIZE_THREAD__ */ #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR >= 6) #define STATIC_ASSERT(cond, msg) _Static_assert(cond, msg) #elif __has_feature(c_static_assert) #define STATIC_ASSERT(cond, msg) _Static_assert(cond, msg) #else /* if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR >= 6) */ #define STATIC_ASSERT(cond, msg) INSIST(cond) #endif /* if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR >= 6) */ #ifdef UNIT_TESTING extern void mock_assert(const int result, const char *const expression, const char *const file, const int line); /* * Allow clang to determine that the following code is not reached * by calling abort() if the condition fails. The abort() will * never be executed as mock_assert() and _assert_true() longjmp * or exit if the condition is false. */ #define REQUIRE(expression) \ ((!(expression)) \ ? (mock_assert(0, #expression, __FILE__, __LINE__), abort()) \ : (void)0) #define ENSURE(expression) \ ((!(int)(expression)) \ ? (mock_assert(0, #expression, __FILE__, __LINE__), abort()) \ : (void)0) #define INSIST(expression) \ ((!(expression)) \ ? (mock_assert(0, #expression, __FILE__, __LINE__), abort()) \ : (void)0) #define INVARIANT(expression) \ ((!(expression)) \ ? (mock_assert(0, #expression, __FILE__, __LINE__), abort()) \ : (void)0) #define _assert_true(c, e, f, l) \ ((c) ? (void)0 : (_assert_true(0, e, f, l), abort())) #define _assert_int_equal(a, b, f, l) \ (((a) == (b)) ? (void)0 : (_assert_int_equal(a, b, f, l), abort())) #define _assert_int_not_equal(a, b, f, l) \ (((a) != (b)) ? (void)0 : (_assert_int_not_equal(a, b, f, l), abort())) #else /* UNIT_TESTING */ #ifndef CPPCHECK /* * Assertions */ #include <isc/assertions.h> /* Contractual promise. */ /*% Require Assertion */ #define REQUIRE(e) ISC_REQUIRE(e) /*% Ensure Assertion */ #define ENSURE(e) ISC_ENSURE(e) /*% Insist Assertion */ #define INSIST(e) ISC_INSIST(e) /*% Invariant Assertion */ #define INVARIANT(e) ISC_INVARIANT(e) #else /* CPPCHECK */ /*% Require Assertion */ #define REQUIRE(e) \ if (!(e)) \ abort() /*% Ensure Assertion */ #define ENSURE(e) \ if (!(e)) \ abort() /*% Insist Assertion */ #define INSIST(e) \ if (!(e)) \ abort() /*% Invariant Assertion */ #define INVARIANT(e) \ if (!(e)) \ abort() #endif /* CPPCHECK */ #endif /* UNIT_TESTING */ /* * Errors */ #include <isc/error.h> /* Contractual promise. */ /*% Unexpected Error */ #define UNEXPECTED_ERROR isc_error_unexpected /*% Fatal Error */ #define FATAL_ERROR isc_error_fatal #ifdef UNIT_TESTING #define RUNTIME_CHECK(expression) \ ((!(expression)) \ ? (mock_assert(0, #expression, __FILE__, __LINE__), abort()) \ : (void)0) #else /* UNIT_TESTING */ #ifndef CPPCHECK /*% Runtime Check */ #define RUNTIME_CHECK(cond) ISC_ERROR_RUNTIMECHECK(cond) #else /* ifndef CPPCHECK */ #define RUNTIME_CHECK(e) \ if (!(e)) \ abort() #endif /* ifndef CPPCHECK */ #endif /* UNIT_TESTING */ /*% * Time */ #define TIME_NOW(tp) RUNTIME_CHECK(isc_time_now((tp)) == ISC_R_SUCCESS) #define TIME_NOW_HIRES(tp) \ RUNTIME_CHECK(isc_time_now_hires((tp)) == ISC_R_SUCCESS) /*% * Alignment */ #ifdef __GNUC__ #define ISC_ALIGN(x, a) (((x) + (a)-1) & ~((typeof(x))(a)-1)) #else /* ifdef __GNUC__ */ #define ISC_ALIGN(x, a) (((x) + (a)-1) & ~((uintmax_t)(a)-1)) #endif /* ifdef __GNUC__ */ #if HAVE_FUNC_ATTRIBUTE_RETURNS_NONNULL #define ISC_ATTR_RETURNS_NONNULL __attribute__((returns_nonnull)) #else #define ISC_ATTR_RETURNS_NONNULL #endif /* * Support for malloc attributes. */ #ifdef HAVE_FUNC_ATTRIBUTE_MALLOC /* * Indicates that a function is malloc-like, i.e., that the * pointer P returned by the function cannot alias any other * pointer valid when the function returns. */ #define ISC_ATTR_MALLOC __attribute__((malloc)) #if HAVE_MALLOC_EXT_ATTR /* * Associates deallocator as a suitable deallocation function * for pointers returned from the function marked with the attribute. */ #define ISC_ATTR_DEALLOCATOR(deallocator) __attribute__((malloc(deallocator))) /* * Similar to ISC_ATTR_DEALLOCATOR, but allows to speficy an index "idx", * which denotes the positional argument to which when the pointer is passed * in calls to deallocator has the effect of deallocating it. */ #define ISC_ATTR_DEALLOCATOR_IDX(deallocator, idx) \ __attribute__((malloc(deallocator, idx))) /* * Combines both ISC_ATTR_MALLOC and ISC_ATTR_DEALLOCATOR attributes. */ #define ISC_ATTR_MALLOC_DEALLOCATOR(deallocator) \ __attribute__((malloc, malloc(deallocator))) /* * Similar to ISC_ATTR_MALLOC_DEALLOCATOR, but allows to speficy an index "idx", * which denotes the positional argument to which when the pointer is passed * in calls to deallocator has the effect of deallocating it. */ #define ISC_ATTR_MALLOC_DEALLOCATOR_IDX(deallocator, idx) \ __attribute__((malloc, malloc(deallocator, idx))) #else /* #ifdef HAVE_MALLOC_EXT_ATTR */ /* * There is support for malloc attribute but not for * extended attributes, so macros that combine attribute malloc * with a deallocator will only expand to malloc attribute. */ #define ISC_ATTR_DEALLOCATOR(deallocator) #define ISC_ATTR_DEALLOCATOR_IDX(deallocator, idx) #define ISC_ATTR_MALLOC_DEALLOCATOR(deallocator) ISC_ATTR_MALLOC #define ISC_ATTR_MALLOC_DEALLOCATOR_IDX(deallocator, idx) ISC_ATTR_MALLOC #endif #else /* #ifdef HAVE_FUNC_ATTRIBUTE_MALLOC */ /* * There is no support for malloc attribute. */ #define ISC_ATTR_MALLOC #define ISC_ATTR_DEALLOCATOR(deallocator) #define ISC_ATTR_DEALLOCATOR_IDX(deallocator, idx) #define ISC_ATTR_MALLOC_DEALLOCATOR(deallocator) #define ISC_ATTR_MALLOC_DEALLOCATOR_IDX(deallocator, idx) #endif /* HAVE_FUNC_ATTRIBUTE_MALLOC */ /*% * Misc */ #include <isc/deprecated.h> #endif /* ISC_UTIL_H */