[//]: # (DO NOT DIRECTLY MODIFY THIS FILE:) [//]: # (The code in this file is generated from scripts/s2n_safety_macros.py and any modifications) [//]: # (should be in there.) # S2N Safety Macros ## Macros for functions that return `S2N_RESULT` ### RESULT_BAIL(error) Sets the global `s2n_errno` to `error` and returns with an `S2N_RESULT_ERROR` ### RESULT_ENSURE(condition, error) Ensures the `condition` is `true`, otherwise the function will `RESULT_BAIL` with `error` ### RESULT_DEBUG_ENSURE(condition, error) Ensures the `condition` is `true`, otherwise the function will `RESULT_BAIL` with `error` NOTE: The condition will _only_ be checked when the code is compiled in debug mode. In release mode, the check is removed. ### RESULT_ENSURE_OK(result, error) Ensures `s2n_result_is_ok(result)`, otherwise the function will `RESULT_BAIL` with `error` This can be useful for overriding the global `s2n_errno` ### RESULT_ENSURE_GTE(a, b) Ensures `a` is greater than or equal to `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error ### RESULT_ENSURE_LTE(a, b) Ensures `a` is less than or equal to `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error ### RESULT_ENSURE_GT(a, b) Ensures `a` is greater than `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error ### RESULT_ENSURE_LT(a, b) Ensures `a` is less than `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error ### RESULT_ENSURE_EQ(a, b) Ensures `a` is equal to `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error ### RESULT_ENSURE_NE(a, b) Ensures `a` is not equal to `b`, otherwise the function will `RESULT_BAIL` with a `S2N_ERR_SAFETY` error ### RESULT_ENSURE_INCLUSIVE_RANGE(min, n, max) Ensures `min <= n <= max`, otherwise the function will `RESULT_BAIL` with `S2N_ERR_SAFETY` ### RESULT_ENSURE_EXCLUSIVE_RANGE(min, n, max) Ensures `min < n < max`, otherwise the function will `RESULT_BAIL` with `S2N_ERR_SAFETY` ### RESULT_ENSURE_REF(x) Ensures `x` is a readable reference, otherwise the function will `RESULT_BAIL` with `S2N_ERR_NULL` ### RESULT_ENSURE_MUT(x) Ensures `x` is a mutable reference, otherwise the function will `RESULT_BAIL` with `S2N_ERR_NULL` ### RESULT_PRECONDITION(result) Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal `RESULT_PRECONDITION` should be used at the beginning of a function to make assertions about the provided arguments. By default, it is functionally equivalent to `RESULT_GUARD(result)` but can be altered by a testing environment to provide additional guarantees. ### RESULT_POSTCONDITION(result) Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal NOTE: The condition will _only_ be checked when the code is compiled in debug mode. In release mode, the check is removed. `RESULT_POSTCONDITION` should be used at the end of a function to make assertions about the resulting state. In debug mode, it is functionally equivalent to `RESULT_GUARD(result)`. In production builds, it becomes a no-op. This can also be altered by a testing environment to provide additional guarantees. ### RESULT_CHECKED_MEMCPY(destination, source, len) Performs a safer memcpy. The following checks are performed: * `destination` is non-null * `source` is non-null Callers will still need to ensure the following: * The size of the data pointed to by both the `destination` and `source` parameters, shall be at least `len` bytes. ### RESULT_CHECKED_MEMSET(destination, value, len) Performs a safer memset The following checks are performed: * `destination` is non-null Callers will still need to ensure the following: * The size of the data pointed to by the `destination` parameter shall be at least `len` bytes. ### RESULT_GUARD(result) Ensures `s2n_result_is_ok(result)`, otherwise the function will return `S2N_RESULT_ERROR` ### RESULT_GUARD_OSSL(result, error) Ensures `result == _OSSL_SUCCESS`, otherwise the function will `RESULT_BAIL` with `error` ### RESULT_GUARD_POSIX(result) Ensures `(result) > S2N_FAILURE`, otherwise the function will return `S2N_RESULT_ERROR` ### RESULT_GUARD_PTR(result) Ensures `(result) != NULL`, otherwise the function will return `S2N_RESULT_ERROR` Does not set s2n_errno to S2N_ERR_NULL, so is NOT a direct replacement for RESULT_ENSURE_REF. ## Macros for functions that return `int` (POSIX error signal) ### POSIX_BAIL(error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Sets the global `s2n_errno` to `error` and returns with an `S2N_FAILURE` ### POSIX_ENSURE(condition, error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures the `condition` is `true`, otherwise the function will `POSIX_BAIL` with `error` ### POSIX_DEBUG_ENSURE(condition, error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures the `condition` is `true`, otherwise the function will `POSIX_BAIL` with `error` NOTE: The condition will _only_ be checked when the code is compiled in debug mode. In release mode, the check is removed. ### POSIX_ENSURE_OK(result, error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `(result) > S2N_FAILURE`, otherwise the function will `POSIX_BAIL` with `error` This can be useful for overriding the global `s2n_errno` ### POSIX_ENSURE_GTE(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is greater than or equal to `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error ### POSIX_ENSURE_LTE(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is less than or equal to `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error ### POSIX_ENSURE_GT(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is greater than `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error ### POSIX_ENSURE_LT(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is less than `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error ### POSIX_ENSURE_EQ(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is equal to `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error ### POSIX_ENSURE_NE(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is not equal to `b`, otherwise the function will `POSIX_BAIL` with a `S2N_ERR_SAFETY` error ### POSIX_ENSURE_INCLUSIVE_RANGE(min, n, max) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `min <= n <= max`, otherwise the function will `POSIX_BAIL` with `S2N_ERR_SAFETY` ### POSIX_ENSURE_EXCLUSIVE_RANGE(min, n, max) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `min < n < max`, otherwise the function will `POSIX_BAIL` with `S2N_ERR_SAFETY` ### POSIX_ENSURE_REF(x) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `x` is a readable reference, otherwise the function will `POSIX_BAIL` with `S2N_ERR_NULL` ### POSIX_ENSURE_MUT(x) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `x` is a mutable reference, otherwise the function will `POSIX_BAIL` with `S2N_ERR_NULL` ### POSIX_PRECONDITION(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal `POSIX_PRECONDITION` should be used at the beginning of a function to make assertions about the provided arguments. By default, it is functionally equivalent to `POSIX_GUARD_RESULT(result)` but can be altered by a testing environment to provide additional guarantees. ### POSIX_POSTCONDITION(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal NOTE: The condition will _only_ be checked when the code is compiled in debug mode. In release mode, the check is removed. `POSIX_POSTCONDITION` should be used at the end of a function to make assertions about the resulting state. In debug mode, it is functionally equivalent to `POSIX_GUARD_RESULT(result)`. In production builds, it becomes a no-op. This can also be altered by a testing environment to provide additional guarantees. ### POSIX_CHECKED_MEMCPY(destination, source, len) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Performs a safer memcpy. The following checks are performed: * `destination` is non-null * `source` is non-null Callers will still need to ensure the following: * The size of the data pointed to by both the `destination` and `source` parameters, shall be at least `len` bytes. ### POSIX_CHECKED_MEMSET(destination, value, len) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Performs a safer memset The following checks are performed: * `destination` is non-null Callers will still need to ensure the following: * The size of the data pointed to by the `destination` parameter shall be at least `len` bytes. ### POSIX_GUARD(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `(result) > S2N_FAILURE`, otherwise the function will return `S2N_FAILURE` ### POSIX_GUARD_OSSL(result, error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `result == _OSSL_SUCCESS`, otherwise the function will `POSIX_BAIL` with `error` ### POSIX_GUARD_RESULT(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `s2n_result_is_ok(result)`, otherwise the function will return `S2N_FAILURE` ### POSIX_GUARD_PTR(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `(result) != NULL`, otherwise the function will return `S2N_FAILURE` Does not set s2n_errno to S2N_ERR_NULL, so is NOT a direct replacement for POSIX_ENSURE_REF. ## Macros for functions that return a pointer ### PTR_BAIL(error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Sets the global `s2n_errno` to `error` and returns with an `NULL` ### PTR_ENSURE(condition, error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures the `condition` is `true`, otherwise the function will `PTR_BAIL` with `error` ### PTR_DEBUG_ENSURE(condition, error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures the `condition` is `true`, otherwise the function will `PTR_BAIL` with `error` NOTE: The condition will _only_ be checked when the code is compiled in debug mode. In release mode, the check is removed. ### PTR_ENSURE_OK(result, error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `(result) != NULL`, otherwise the function will `PTR_BAIL` with `error` This can be useful for overriding the global `s2n_errno` ### PTR_ENSURE_GTE(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is greater than or equal to `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error ### PTR_ENSURE_LTE(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is less than or equal to `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error ### PTR_ENSURE_GT(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is greater than `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error ### PTR_ENSURE_LT(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is less than `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error ### PTR_ENSURE_EQ(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is equal to `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error ### PTR_ENSURE_NE(a, b) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `a` is not equal to `b`, otherwise the function will `PTR_BAIL` with a `S2N_ERR_SAFETY` error ### PTR_ENSURE_INCLUSIVE_RANGE(min, n, max) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `min <= n <= max`, otherwise the function will `PTR_BAIL` with `S2N_ERR_SAFETY` ### PTR_ENSURE_EXCLUSIVE_RANGE(min, n, max) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `min < n < max`, otherwise the function will `PTR_BAIL` with `S2N_ERR_SAFETY` ### PTR_ENSURE_REF(x) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `x` is a readable reference, otherwise the function will `PTR_BAIL` with `S2N_ERR_NULL` ### PTR_ENSURE_MUT(x) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `x` is a mutable reference, otherwise the function will `PTR_BAIL` with `S2N_ERR_NULL` ### PTR_PRECONDITION(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal `PTR_PRECONDITION` should be used at the beginning of a function to make assertions about the provided arguments. By default, it is functionally equivalent to `PTR_GUARD_RESULT(result)` but can be altered by a testing environment to provide additional guarantees. ### PTR_POSTCONDITION(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures the `result` is `S2N_RESULT_OK`, otherwise the function will return an error signal NOTE: The condition will _only_ be checked when the code is compiled in debug mode. In release mode, the check is removed. `PTR_POSTCONDITION` should be used at the end of a function to make assertions about the resulting state. In debug mode, it is functionally equivalent to `PTR_GUARD_RESULT(result)`. In production builds, it becomes a no-op. This can also be altered by a testing environment to provide additional guarantees. ### PTR_CHECKED_MEMCPY(destination, source, len) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Performs a safer memcpy. The following checks are performed: * `destination` is non-null * `source` is non-null Callers will still need to ensure the following: * The size of the data pointed to by both the `destination` and `source` parameters, shall be at least `len` bytes. ### PTR_CHECKED_MEMSET(destination, value, len) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Performs a safer memset The following checks are performed: * `destination` is non-null Callers will still need to ensure the following: * The size of the data pointed to by the `destination` parameter shall be at least `len` bytes. ### PTR_GUARD(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `(result) != NULL`, otherwise the function will return `NULL` ### PTR_GUARD_OSSL(result, error) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `result == _OSSL_SUCCESS`, otherwise the function will `PTR_BAIL` with `error` ### PTR_GUARD_RESULT(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `s2n_result_is_ok(result)`, otherwise the function will return `NULL` ### PTR_GUARD_POSIX(result) DEPRECATED: all methods (except those in s2n.h) should return s2n_result. Ensures `(result) > S2N_FAILURE`, otherwise the function will return `NULL`