1. Overview

What follows here provides a thorough description of how to use Stroll’s library.

Basically, Stroll library is a basic C framework that provides definitions usefull to carry out common C/C++ applicative tasks. The library is implemented to run on GNU Linux / glibc platforms only (although porting to alternate C library such as musl libc should not be much of a hassle).

Stroll library API is organized around the following functional areas which you can refer to for further details :

Stroll sources are distributed under the GNU Lesser General Public License whereas documentation manuals are distributed under the GNU General Public License.

2. Build configuration

At Build configuration time, multiple build options are available to customize final Stroll build. From client code, you may eventually refer to the corresponding C macros listed below:

3. Common definitions

Stroll library exposes various C preprocessor macros used to implement Stroll internals and meant for application development purposes. These are:

4. Assertions

When compiled with the CONFIG_STROLL_ASSERT build configuration option enabled, the Stroll library exposes the stroll_assert macro so that developper may perform standard assertion checking.

5. Bit operations

When compiled with the CONFIG_STROLL_BOPS build configuration option enabled, the Stroll library provides support for bit manipulation operations. These are:

6. Bitmaps

When compiled with the CONFIG_STROLL_BMAP build configuration option enabled, the Stroll library provides support for bitmap operations. These are:

7. Length-Value Strings

When compiled with the CONFIG_STROLL_LVSTR build configuration option enabled, the Stroll library provides support for stroll_lvstr length-value strings.

This framework ease the management of C strings life-cycle. In addition, it caches the length of string registered into it to mitigate client code string length computation overhead.

The following manipulations are available:

8. Reference

8.1. Configuration macros

8.1.1. CONFIG_STROLL_ASSERT

CONFIG_STROLL_ASSERT

Assertion.

Build stroll library assertion framework exposing a programmatic assertion API for use by client code. See <stroll/assert.h>.

8.1.2. CONFIG_STROLL_ASSERT_API

CONFIG_STROLL_ASSERT_API

API assertion.

Build stroll library with high-level API assertions enabled to ensure that API functions exposed by Stroll will perform full verification of arguments consistency.

8.1.3. CONFIG_STROLL_ASSERT_INTERN

CONFIG_STROLL_ASSERT_INTERN

Internal assertion.

Build stroll library with internal assertions enabled to check for internal Stroll behavioral consistency.

8.1.4. CONFIG_STROLL_UTEST

CONFIG_STROLL_UTEST

Unit tests.

Build stroll library unit test suite.

8.1.5. CONFIG_STROLL_VALGRIND

CONFIG_STROLL_VALGRIND

Valgrind support.

Build stroll library unit test suite with Valgrind support enabled. For debugging purposes only: do not use in production.

8.1.6. CONFIG_STROLL_BOPS

CONFIG_STROLL_BOPS

Bit operations.

Build stroll library bit operations framework exposing functions to perform bitwise operations upon words in memory such as:

  • find first bit set,

  • find first bit cleared,

  • find last bit set,

  • compute hamming weight,

  • etc… See <stroll/bops.h>.

8.1.7. CONFIG_STROLL_BMAP

CONFIG_STROLL_BMAP

Bitmap.

Build stroll library with bitmap framework exposing functions to perform usual operations over bitmaps stored into memory words such as:

  • and / or / xor operations,

  • test bit / mask / bit range,

  • hamming weight,

  • iteration,

  • etc… See <stroll/bmap.h>.

8.1.8. CONFIG_STROLL_LVSTR

CONFIG_STROLL_LVSTR

Length-Value String.

Build stroll library with length-value string framework meant to ease the life-cycle of C strings. See <stroll/lvstr.h>.

8.2. Macros

8.2.1. __align

__align(_size)

Declare a variable or type to the compiler as requiring minimum alignment.

Tell the compiler that a minimum alignment is required for the variable or structure field, measured in bytes. When specified, alignment must be an integer constant power of 2.

See also

Parameters:

  • _size – [in] required alignment in bytes

8.2.2. __const

__const

Declare a function to the compiler as const.

Tell compiler that a function return value is not affected by changes to the observable state of the program and that this function have no observable effects on such state other than to return a value.

The __const attribute prohibits a function from reading objects that affect its return value between successive invocations. However, functions declared with the attribute can safely read objects that do not change their return value, such as non-volatile constants.

The __const attribute imposes greater restrictions on a function’s definition than the similar __pure attribute. Declaring the same function with both the __const and the __pure attribute is diagnosed.

Because a __const function cannot have any observable side effects it does not make sense for it to return void. Declaring such a function is diagnosed.

See also

GCC common function attributes

8.2.3. __ctor

__ctor(_prio)

Declare a function to the compiler as a constructor.

Tell the compiler that a function must be called automatically before execution enters main(). The attributes also accept an integer argument to specify a priority to control the order in which constructor functions are run. A constructor with a smaller priority number runs before a constructor with a larger priority number.

See also

GCC common function attributes

Parameters:

  • _prio – [in] constructor invocation order

Note

Priorities 0-100 are reserved.

8.2.4. __dtor

__dtor(_prio)

Declare a function to the compiler as a destructor.

Tell the compiler that a function must be called automatically after main() completes or exit() is called. The attributes also accept an integer argument to specify a priority to control the order in which destructor functions are run. A destructor with a larger priority number runs before a constructor with a smaller priority number.

See also

GCC common function attributes

Parameters:

  • _prio – [in] destructor invocation order

Note

Priorities 0-100 are reserved.

8.2.5. __export_public

__export_public

Assign public visibility to a function, variable or type.

Attach “default” visibility to a function, variable or type declaration linkage. On ELF, default visibility means that the declaration is visible to other modules and, in shared libraries, means that the declared entity may be overridden.

See also

8.2.6. __export_protect

__export_protect

Assign protected visibility to a function, variable or type.

Attach “protected” visibility to a function, variable or type declaration linkage. On ELF, protected visibility is like default visibility except that it indicates that references within the defining module bind to the definition in that module. That is, the declared entity cannot be overridden by another module.

See also

8.2.7. __leaf

__leaf

Declare a function to the compiler as a leaf.

Tell compiler that a call to an external function with this attribute must return to the current compilation unit only by return or by exception handling.

See also

GCC common function attributes

8.2.8. __nonull

__nonull(_arg_index, ...)

Declare to the compiler a that function argument should be a non-null pointer.

When applied to a function, tell compiler that the specified arguments must be non-null pointers.

See also

GCC common function attributes

Parameters:

  • _arg_index – [in] index of first non-null pointer argument

  • ... – [in] subsequent non-null pointer argument indices

8.2.9. __noreturn

__noreturn

Tell compiler that a function cannot return.

See also

GCC common function attributes

8.2.10. __nothrow

__nothrow

Tell compiler that a function does not throw exceptions.

See also

GCC common function attributes

8.2.11. __packed

__packed

Declare a variable or type to the compiler as packed.

When assigned to a variable, tell the compiler that a structure member should have the smallest possible alignment—one bit for a bit-field and one byte otherwise, unless a larger value is specified with the aligned attribute. The attribute does not apply to non-member objects.

When attached to a struct, union, or C++ class type definition, tell the compiler that each of its members (other than zero-width bit-fields) is placed to minimize the memory required. This is equivalent to specifying the packed attribute on each of the members. When attached to an enum definition, the packed attribute indicates that the smallest integral type should be used. Specifying the -fshort-enums flag on the command line is equivalent to specifying the packed attribute on all enum definitions.

See also

8.2.12. __printf

__printf(_format_index, _arg_index)

Tell compiler to check for printf() style format string argument consistency.

See also

GCC common function attributes

Parameters:

  • _format_index – [in] index of printf() format string argument

  • _arg_index – [in] index of first type checked argument

8.2.13. __pure

__pure

Declare a function to the compiler as pure.

Tell compiler that a function has no observable effects on the state of the program other than to return a value.

Functions declared with the __pure attribute can safely read any non-volatile objects, and modify the value of objects in a way that does not affect their return value or the observable state of the program.

The __pure attribute imposes similar but looser restrictions on a function’s definition than the __const attribute: __pure allows the function to read any non-volatile memory, even if it changes in between successive invocations of the function.

Because a __pure function cannot have any observable side effects it does not make sense for such a function to return void.

See also

GCC common function attributes

8.2.14. __returns_nonull

__returns_nonull

Tell compiler that a function return value should be a non-null pointer.

See also

GCC common function attributes

8.2.15. __unused

__unused

Tell compiler that a function, variable, type or (goto) label may possibly be unused.

May be used to prevent compiler from warning about unused functions, parameters, variables, etc…

See also

8.2.16. __warn_result

__warn_result

Declare to the compiler a function return value must be used.

Request compiler to emit a warning when a caller of the function with this attribute does not use its return value.

See also

GCC common function attributes

8.2.17. STROLL_BMAP_INIT_CLEAR

STROLL_BMAP_INIT_CLEAR

Static initialize a machine word bitmap with all bits cleared.

8.2.18. STROLL_BMAP_INIT_SET

STROLL_BMAP_INIT_SET

Static initialize a machine word bitmap with all bits set.

8.2.19. STROLL_BMAP32_INIT_CLEAR

STROLL_BMAP32_INIT_CLEAR

Static initialize a 32-bits bitmap with all bits cleared.

8.2.20. STROLL_BMAP32_INIT_SET

STROLL_BMAP32_INIT_SET

Static initialize a 32-bits bitmap with all bits set.

8.2.21. STROLL_BMAP64_INIT_CLEAR

STROLL_BMAP64_INIT_CLEAR

Static initialize a 64-bits bitmap with all bits cleared.

8.2.22. STROLL_BMAP64_INIT_SET

STROLL_BMAP64_INIT_SET

Static initialize a 64-bits bitmap with all bits set.

8.2.23. STROLL_CONCAT

STROLL_CONCAT(_a, _b)

Concatenate 2 preprocessor tokens.

Concatenate _a with _b during C preprocessor macro expansion.

See also

GCC Concatenation

Parameters:

  • _a – [in] first token

  • _b – [in] second token

8.2.24. STROLL_CONST_ABS

STROLL_CONST_ABS(_a)

Return the absolute value of the given preprocessing argument.

Use STROLL_CONST_ABS() within preprocessor directives where argument is subject to restrictions as stated into GCC If.

More specifically STROLL_CONST_ABS() should be used with a constant argument known at preprocessing time only. Use stroll_abs() otherwise.

Parameters:

  • _a – [in] first argument

Returns:

absolute value of _a

Warning

Argument evaluation is subject to runtime side-effects.

8.2.25. STROLL_CONST_MAX

STROLL_CONST_MAX(_a, _b)

Return the greatest of 2 preprocessing arguments.

Use STROLL_CONST_MAX() within preprocessor directives where arguments are subject to restrictions as stated into GCC If.

More specifically STROLL_CONST_MAX() should be used with constant arguments known at preprocessing time only. Use stroll_max() otherwise.

Parameters:

  • _a – [in] first argument

  • _b – [in] second argument

Returns:

greatest argument

Warning

Arguments evaluation is subject to runtime side-effects.

8.2.26. STROLL_CONST_MIN

STROLL_CONST_MIN(_a, _b)

Return the smallest of 2 preprocessing arguments.

Use STROLL_CONST_MIN() within preprocessor directives where arguments are subject to restrictions as stated into GCC If.

More specifically STROLL_CONST_MIN() should be used with constant arguments known at preprocessing time only. Use stroll_min() otherwise.

Parameters:

  • _a – [in] first argument

  • _b – [in] second argument

Returns:

smallest argument

Warning

Arguments evaluation is subject to runtime side-effects.

8.2.27. STROLL_LVSTR_INIT

STROLL_LVSTR_INIT

Static initialize an empty stroll_lvstr.

Behavior is similar to stroll_lvstr_init() but for static initialization purpose.

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

8.2.28. STROLL_LVSTR_INIT_LEND

STROLL_LVSTR_INIT_LEND(_cstr)

Static initialize a non-owning stroll_lvstr with a string which length is not known.

Behavior is similar to stroll_lvstr_init_lend() but for static initialization purpose.

Parameters:

  • _cstr – [in] A C string literal to register

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

Warning

Will generate an error at compile time if _cstr is not a constant string literal.

8.2.29. STROLL_LVSTR_INIT_NLEND

STROLL_LVSTR_INIT_NLEND(_cstr, _len)

Static initialize a non-owning stroll_lvstr with a string which length is known.

Behavior is similar to stroll_lvstr_init_nlend() but for static initialization purpose.

Parameters:

  • _cstr – [in] C string to register

  • _len – [in] length of _cstr

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

8.2.30. STROLL_LVSTR_INIT_NCEDE

STROLL_LVSTR_INIT_NCEDE(_cstr, _len)

Static initialize an owning stroll_lvstr with a string which length is known.

Behavior is similar to stroll_lvstr_init_ncede() but for static initialization purpose. _cstr MUST NOT be a constant string since it will be free(3) ‘ed at release time.

Parameters:

  • _cstr – [in] C string to register

  • _len – [in] length of _cstr

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

Warning

Will generate an error at compile time if _cstr is a constant string literal.

8.2.31. STROLL_LVSTR_LEN_MAX

STROLL_LVSTR_LEN_MAX

Maximum length of a C string that may be registered into a stroll_lvstr.

8.2.32. STROLL_STRING

STROLL_STRING(_token)

Convert a preprocessor token into a string constant.

Convert _a into a string during C preprocessor macro expansion.

See also

GCC Stringizing

Parameters:

  • _token – [in] token to convert

8.2.33. STROLL_UNIQ

STROLL_UNIQ(_token)

Generate unique preprocessor token.

Preprocessor magic generating a unique identifier from a primary token. STROLL_UNIQ() basically relies upon GCC __COUNTER__ predefined macro to form a unique identifier composed of the concatenation of :

  • __stroll_uniq__ literal,

  • _token,

  • a unique sequential integral values starting from 0.

This may be usefull to prevent GCC from warning about shadowed variables used into preprocessor macros defining local variables. See stroll_min() / stroll_max() for practical examples.

See also

GCC Common predefined macros

Parameters:

  • _token – [in] base preprocessor identifier

8.2.34. array_nr

array_nr(_array)

Return the number of elements of a constant array expression.

Parameters:

  • _array – [in] array to retrieve number of elements for

Returns:

Number of elements of _array.

Note

Borrowed from Linux’s kernel.h header file.

8.2.35. compile_eval

compile_eval(_expr, _stmt, _msg)

Evaluate constant expression at compile time.

Generate a compile time error with error message _msg when constant expression _expr is zero / false. “Returns” value of _stmt evaluation otherwise.

Parameters:

  • _expr – [in] constant conditional expression

  • _stmt – [in] constant statement

  • _msg – [in] compile error message string

Returns:

_stmt statement evaluation

Note

Borrowed from Gnulib’s verify.h header file.

8.2.36. compile_assert

compile_assert(_expr)

Abort compilation if constant expression evaluates to zero / false.

Generate a compile time error with error message _msg when constant expression _expr is zero / false.

Parameters:

  • _expr – [in] constant conditional expression

Note

Borrowed from Gnulib’s verify.h header file.

8.2.37. compile_choose

compile_choose(_expr, _true_stmt, _false_stmt)

Evaluate code depending on the result of a constant expression.

Use compile_choose() to evaluate code depending on the value _expr constant expression. This returns _true_stmt if _expr, which is an integer constant expression, is nonzero. Otherwise it returns _false_stmt.

This function macro is analogous to the ‘? :’ operator in C, except that the expression returned has its type unaltered by promotion rules. Also, the compile_choose() does not evaluate the expression that is not chosen.

See also

GCC Other Built-in Functions

Parameters:

  • _expr – [in] constant conditional expression

  • _true_stmt – [in] statement to evaluate if _expr is true / nonzero

  • _false_stmt – [in] statement to evaluate if _expr is false / zero

Returns:

value of selected statement evaluation

Note

the unused statement may still generate syntax errors.

8.2.38. stroll_abs

stroll_abs(_a)

Return the absolute value of the given argument.

Argument is evaluated only once to prevent from runtime side-effects.

Parameters:

  • _a – [in] argument

Returns:

absolute value of _a

8.2.39. stroll_assert

stroll_assert(_prefix, _expr)

Check an assertion.

Parameters:

  • _prefix – [in] prefix prepended to message generated when assertion fails

  • _expr – [in] expression to check assertion for

8.2.40. stroll_bmap_foreach_clear

stroll_bmap_foreach_clear(_iter, _bmap, _bit_no)

Iterater over all bits cleared in a machine word bitmap.

Given an uninitialed bitmap iter, iterate over bits cleared in bmap bitmap and update bit_no to reflect current bit cleared

Parameters:

  • _iter – [in] Temporary iteration bitmap

  • _bmap – [in] Bitmap to iterate over

  • _bit_no – [out] Current bit number

8.2.41. stroll_bmap_foreach_set

stroll_bmap_foreach_set(_iter, _bmap, _bit_no)

Iterater over all bits set in a machine word bitmap.

Given an uninitialed bitmap iter, iterate over bits set in bmap bitmap and update bit_no to reflect current bit set.

Parameters:

  • _iter – [in] Temporary iteration bitmap

  • _bmap – [in] Bitmap to iterate over

  • _bit_no – [out] Current bit number

8.2.42. stroll_bmap32_foreach_clear

stroll_bmap32_foreach_clear(_iter, _bmap, _bit_no)

Iterater over all bits cleared in a 32-bits word bitmap.

Given an uninitialed bitmap iter, iterate over bits cleared in bmap bitmap and update bit_no to reflect current bit cleared

Parameters:

  • _iter – [in] Temporary iteration bitmap

  • _bmap – [in] Bitmap to iterate over

  • _bit_no – [out] Current bit number

8.2.43. stroll_bmap32_foreach_set

stroll_bmap32_foreach_set(_iter, _bmap, _bit_no)

Iterater over all bits set in a 32-bits word bitmap.

Given an uninitialed bitmap iter, iterate over bits set in bmap bitmap and update bit_no to reflect current bit set.

Parameters:

  • _iter – [in] Temporary iteration bitmap

  • _bmap – [in] Bitmap to iterate over

  • _bit_no – [out] Current bit number

8.2.44. stroll_bmap64_foreach_clear

stroll_bmap64_foreach_clear(_iter, _bmap, _bit_no)

Iterater over all bits cleared in a 64-bits word bitmap.

Given an uninitialed bitmap iter, iterate over bits cleared in bmap bitmap and update bit_no to reflect current bit cleared

Parameters:

  • _iter – [in] Temporary iteration bitmap

  • _bmap – [in] Bitmap to iterate over

  • _bit_no – [out] Current bit number

8.2.45. stroll_bmap64_foreach_set

stroll_bmap64_foreach_set(_iter, _bmap, _bit_no)

Iterater over all bits set in a 64-bits word bitmap.

Given an uninitialed bitmap iter, iterate over bits set in bmap bitmap and update bit_no to reflect current bit set.

Parameters:

  • _iter – [in] Temporary iteration bitmap

  • _bmap – [in] Bitmap to iterate over

  • _bit_no – [out] Current bit number

8.2.46. stroll_min

stroll_min(_a, _b)

Return the smallest of 2 arguments.

Both argument types MUST be compatible. A warning will be generated otherwise. Both arguments are evaluated only once respectively to prevent from runtime side-effects.

Parameters:

  • _a – [in] first argument

  • _b – [in] second argument

Returns:

smallest argument

8.2.47. stroll_max

stroll_max(_a, _b)

Return the greatest of 2 arguments.

Both argument types MUST be compatible. A warning will be generated otherwise. Both arguments are evaluated only once respectively to prevent from runtime side-effects.

Parameters:

  • _a – [in] first argument

  • _b – [in] second argument

Returns:

greatest argument

8.3. Structures

8.3.1. stroll_lvstr

struct stroll_lvstr

Length-Value string.

Holds data to ease the management of C strings life-cycle.

In addition, it caches the length of string registered into it to mitigate client code string length computation overhead.

8.4. Functions

8.4.1. stroll_bmap_and

static inline unsigned long stroll_bmap_and(unsigned long bmap, unsigned long mask)

Perform bitwise mask based AND operation on machine word bitmap.

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • mask – [in] Mask to perform operation with

Returns:

bmap & mask

8.4.2. stroll_bmap_and_range

static inline unsigned long stroll_bmap_and_range(unsigned long bmap, unsigned int start_bit, unsigned int bit_count)

Perform bitwise range based AND operation on machine word bitmap.

Compute a mask according to start_bit and bit_count range given in argument then use it to perform a bitwise AND operation over given bmap bitmap.

Mask is computed thanks to stroll_bmap_mask().

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • start_bit – [in] Index of first mask bit set

  • bit_count – [in] Number of bits set in mask

Returns:

Result of the bitwise AND operation

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be less than the maximum number of bits contained within a machine word. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.3. stroll_bmap_clear

static inline void stroll_bmap_clear(unsigned long *bmap, unsigned int bit_no)

Clear a bit in a machine word bitmap.

Clear bit specified by bit_no into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [inout] Bitmap to clear

  • bit_no – [in] Index of bit to clear

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_no is greater than or equal to the maximum number of bits contained within a machine word, result is undefined. An assertion is triggered otherwise.

8.4.4. stroll_bmap_clear_mask

static inline void stroll_bmap_clear_mask(unsigned long *bmap, unsigned long mask)

Clear bits of machine word bitmap according to mask given in argument.

Clear all bits of bmap bitmap which are set into mask.

Parameters:

  • bmap – [inout] Bitmap to clear

  • mask – [in] Mask of bits to clear

8.4.5. stroll_bmap_clear_range

static inline void stroll_bmap_clear_range(unsigned long *bmap, unsigned int start_bit, unsigned int bit_count)

Clear bits in a machine word bitmap according to specified range.

Compute a mask according to start_bit and bit_count range given in argument. Then, clear all bits in bmap bitmap which are set into this computed mask.

Mask is computed thanks to stroll_bmap_mask().

Parameters:

  • bmap – [inout] Bitmap to clear

  • start_bit – [in] Index of first bit to clear

  • bit_count – [in] Number of bits to clear

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be less than the maximum number of bits contained within a machine word. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.6. stroll_bmap_clear_all

static inline void stroll_bmap_clear_all(unsigned long *bmap)

Clear all bits of a machine word bitmap.

Parameters:

  • bmap – [out] Bitmap to clear

8.4.7. stroll_bmap_hweight

static inline unsigned int stroll_bmap_hweight(unsigned long bmap)

Compute the number of bits set over a machine word bitmap.

Returns the Hamming weight of a machine word bitmap. The Hamming weight of a number is the total number of bits set in it.

Parameters:

  • bmap – [in] Bitmap to search

Returns:

Number of bits set

8.4.8. stroll_bmap_mask

static inline unsigned long stroll_bmap_mask(unsigned int start_bit, unsigned int bit_count)

Compute a machine word mask.

Compute a mask over a machine word where all bits are set starting from bit which index is start_bit to start_bit + bit_count - 1. Bit indices starts from 0.

Parameters:

  • start_bit – [in] Index of first mask bit set starting from 0

  • bit_count – [in] Number of bits set in mask

Returns:

Computed mask

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be less than the maximum number of bits contained within a machine word. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.9. stroll_bmap_or

static inline unsigned long stroll_bmap_or(unsigned long bmap, unsigned long mask)

Perform bitwise mask based OR operation on machine word bitmap.

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • mask – [in] Mask to perform operation with

Returns:

bmap | mask

8.4.10. stroll_bmap_or_range

static inline unsigned long stroll_bmap_or_range(unsigned long bmap, unsigned int start_bit, unsigned int bit_count)

Perform bitwise range based OR operation on machine word bitmap.

Compute a mask according to start_bit and bit_count range given in argument then use it to perform a bitwise OR operation over given bmap bitmap.

Mask is computed thanks to stroll_bmap_mask().

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • start_bit – [in] Index of first mask bit set

  • bit_count – [in] Number of bits set in mask

Returns:

Result of the bitwise OR operation

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be less than the maximum number of bits contained within a machine word. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.11. stroll_bmap_set

static inline void stroll_bmap_set(unsigned long *bmap, unsigned int bit_no)

Set a bit in a machine word bitmap.

Set bit specified by bit_no into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [inout] Bitmap to set

  • bit_no – [in] Index of bit to set

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_no is greater than or equal to the maximum number of bits contained within a machine word, result is undefined. An assertion is triggered otherwise.

8.4.12. stroll_bmap_set_mask

static inline void stroll_bmap_set_mask(unsigned long *bmap, unsigned long mask)

Set bits of machine word bitmap according to mask given in argument.

Set all bits of bmap bitmap which are set into mask.

Parameters:

  • bmap – [inout] Bitmap to set

  • mask – [in] Mask of bits to set

8.4.13. stroll_bmap_set_range

static inline void stroll_bmap_set_range(unsigned long *bmap, unsigned int start_bit, unsigned int bit_count)

Set bits in a machine word bitmap according to specified range.

Compute a mask according to start_bit and bit_count range given in argument. Then, set all bits in bmap bitmap which are set into this computed mask.

Mask is computed thanks to stroll_bmap_mask().

Parameters:

  • bmap – [inout] Bitmap to set

  • start_bit – [in] Index of first bit to set

  • bit_count – [in] Number of bits to set

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be less than the maximum number of bits contained within a machine word. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.14. stroll_bmap_set_all

static inline void stroll_bmap_set_all(unsigned long *bmap)

Set all bits of a machine word bitmap.

Parameters:

  • bmap – [out] Bitmap to set

8.4.15. stroll_bmap_setup_clear

static inline void stroll_bmap_setup_clear(unsigned long *bmap)

Setup a machine word bitmap with all bits cleared.

Parameters:

  • bmap – [out] Bitmap to setup.

8.4.16. stroll_bmap_setup_set

static inline void stroll_bmap_setup_set(unsigned long *bmap)

Setup a machine word bitmap with all bits set.

Parameters:

  • bmap – [out] Bitmap to setup.

8.4.17. stroll_bmap_test

static inline bool stroll_bmap_test(unsigned long bmap, unsigned int bit_no)

Test wether a bit in a machine word bitmap is set or not.

Test wether the bit specified by bit_no is set into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [in] Bitmap to test

  • bit_no – [in] Index of bit to test starting from 0

Return values:

  • true – tested bit is set

  • false – tested bit is cleared

Returns:

Test result

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_no is greater than or equal to the maximum number of bits contained within a machine word, result is undefined. An assertion is triggered otherwise.

8.4.18. stroll_bmap_test_all

static inline bool stroll_bmap_test_all(unsigned long bmap)

Test wether a machine word bitmap contains bits set or not.

Parameters:

  • bmap – [in] Bitmap to test

Return values:

  • true – One or multiple tested bits are set into bmap

  • false – No tested bits are set into bmap

Returns:

Test result

8.4.19. stroll_bmap_test_mask

static inline bool stroll_bmap_test_mask(unsigned long bmap, unsigned long mask)

Test wether bits in a machine word bitmap are set or not.

Test wether a set of bits specified by mask are nonzero into bmap.

Parameters:

  • bmap – [in] Bitmap to test

  • mask – [in] The set of bits to test

Return values:

  • true – One or multiple tested bits are set into bmap

  • false – No tested bits are set into bmap

Returns:

Test result

8.4.20. stroll_bmap_test_range

static inline bool stroll_bmap_test_range(unsigned long bmap, unsigned int start_bit, unsigned int bit_count)

Test wether a range of bits in a machine word bitmap are set or not.

Compute a mask according to start_bit and bit_count range given in argument. Then, check wether, within the given range, there are bits set into the bmap bitmap or not.

Mask is computed thanks to stroll_bmap_mask().

Parameters:

  • bmap – [in] Bitmap to test

  • start_bit – [in] Index of first bit to test

  • bit_count – [in] Number of bits to test

Return values:

  • true – One or multiple tested bits are set into bmap

  • false – No tested bits are set into bmap

Returns:

Test result

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be less than the maximum number of bits contained within a machine word. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.21. stroll_bmap_toggle

static inline void stroll_bmap_toggle(unsigned long *bmap, unsigned int bit_no)

Toggle state of a single machine word bitmap bit.

Invert value of bit specified by bit_no into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [inout] Bitmap which bit to toggle

  • bit_no – [in] Index of bit to toggle

8.4.22. stroll_bmap_toggle_mask

static inline void stroll_bmap_toggle_mask(unsigned long *bmap, unsigned long mask)

Toggle state of bits of a machine word bitmap according to given mask.

Invert value of bmap bitmap bits which are set into mask.

Parameters:

  • bmap – [inout] Bitmap which bits to toggle

  • mask – [in] Mask of bits to toggle

8.4.23. stroll_bmap_toggle_range

static inline void stroll_bmap_toggle_range(unsigned long *bmap, unsigned int start_bit, unsigned int bit_count)

Toggle state of bits of a machine word bitmap according to specified range.

Compute a mask according to start_bit and bit_count range given in argument. Then, invert value of all bits in bmap bitmap which are set into this computed mask.

Mask is computed thanks to stroll_bmap_mask().

Parameters:

  • bmap – [inout] Bitmap which bits to toggle

  • start_bit – [in] Index of first bit to toggle

  • bit_count – [in] Number of bits to toggle

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be less than the maximum number of bits contained within a machine word. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.24. stroll_bmap_toggle_all

static inline void stroll_bmap_toggle_all(unsigned long *bmap)

Toggle all bits of a machine word bitmap.

Invert the value of all bits of bmap bitmap.

Parameters:

  • bmap – [out] Bitmap which bits to toggle

8.4.25. stroll_bmap_xor

static inline unsigned long stroll_bmap_xor(unsigned long bmap, unsigned long mask)

Perform bitwise mask based XOR operation on machine word bitmap.

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • mask – [in] Mask to perform operation with

Returns:

bmap ^ mask

8.4.26. stroll_bmap_xor_range

static inline unsigned long stroll_bmap_xor_range(unsigned long bmap, unsigned int start_bit, unsigned int bit_count)

Perform bitwise range based XOR operation on machine word bitmap.

Compute a mask according to start_bit and bit_count range given in argument then use it to perform a bitwise XOR operation over given bmap bitmap.

Mask is computed thanks to stroll_bmap_mask().

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • start_bit – [in] Index of first mask bit set

  • bit_count – [in] Number of bits set in mask

Returns:

Result of the bitwise XOR operation

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be less than the maximum number of bits contained within a machine word. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.27. stroll_bmap32_and

static inline uint32_t stroll_bmap32_and(uint32_t bmap, uint32_t mask)

Perform bitwise mask based AND operation on 32-bits word bitmap.

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • mask – [in] Mask to perform operation with

Returns:

bmap & mask

8.4.28. stroll_bmap32_and_range

static inline uint32_t stroll_bmap32_and_range(uint32_t bmap, unsigned int start_bit, unsigned int bit_count)

Perform bitwise range based AND operation on 32-bits word bitmap.

Compute a mask according to start_bit and bit_count range given in argument then use it to perform a bitwise AND operation over given bmap bitmap.

Mask is computed thanks to stroll_bmap32_mask().

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • start_bit – [in] Index of first mask bit set

  • bit_count – [in] Number of bits set in mask

Returns:

Result of the bitwise AND operation

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 32. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.29. stroll_bmap32_clear

static inline void stroll_bmap32_clear(uint32_t *bmap, unsigned int bit_no)

Clear a bit in a 32-bits word bitmap.

Clear bit specified by bit_no into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [inout] Bitmap to clear

  • bit_no – [in] Index of bit to clear

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_no is >= 32, result is undefined. An assertion is triggered otherwise.

8.4.30. stroll_bmap32_clear_mask

static inline void stroll_bmap32_clear_mask(uint32_t *bmap, uint32_t mask)

Clear bits of 32-bits word bitmap according to mask given in argument.

Clear all bits of bmap bitmap which are set into mask.

Parameters:

  • bmap – [inout] Bitmap to clear

  • mask – [in] Mask of bits to clear

8.4.31. stroll_bmap32_clear_range

static inline void stroll_bmap32_clear_range(uint32_t *bmap, unsigned int start_bit, unsigned int bit_count)

Clear bits in a 32-bits word bitmap according to specified range.

Compute a mask according to start_bit and bit_count range given in argument. Then, clear all bits in bmap bitmap which are set into this computed mask.

Mask is computed thanks to stroll_bmap32_mask().

Parameters:

  • bmap – [inout] Bitmap to clear

  • start_bit – [in] Index of first bit to clear

  • bit_count – [in] Number of bits to clear

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 32. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.32. stroll_bmap32_clear_all

static inline void stroll_bmap32_clear_all(uint32_t *bmap)

Clear all bits of a 32-bits word bitmap.

Parameters:

  • bmap – [out] Bitmap to clear

8.4.33. stroll_bmap32_hweight

static inline unsigned int stroll_bmap32_hweight(uint32_t bmap)

Compute the number of bits set over a 32-bits bitmap.

Returns the Hamming weight of a 32-bits bitmap. The Hamming weight of a number is the total number of bits set in it.

Parameters:

  • bmap – [in] Bitmap to search

Returns:

Number of bits set

8.4.34. stroll_bmap32_mask

static inline uint32_t stroll_bmap32_mask(unsigned int start_bit, unsigned int bit_count)

Compute a 32-bits word mask.

Compute a 32-bits mask where all bits are set starting from bit which index is start_bit to start_bit + bit_count - 1. Bit indices starts from 0.

Parameters:

  • start_bit – [in] Index of first mask bit set starting from 0

  • bit_count – [in] Number of bits set in mask

Returns:

Computed mask

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 32. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.35. stroll_bmap32_or

static inline uint32_t stroll_bmap32_or(uint32_t bmap, uint32_t mask)

Perform bitwise mask based OR operation on 32-bits word bitmap.

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • mask – [in] Mask to perform operation with

Returns:

bmap | mask

8.4.36. stroll_bmap32_or_range

static inline uint32_t stroll_bmap32_or_range(uint32_t bmap, unsigned int start_bit, unsigned int bit_count)

Perform bitwise range based OR operation on 32-bits word bitmap.

Compute a mask according to start_bit and bit_count range given in argument then use it to perform a bitwise OR operation over given bmap bitmap.

Mask is computed thanks to stroll_bmap32_mask().

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • start_bit – [in] Index of first mask bit set

  • bit_count – [in] Number of bits set in mask

Returns:

Result of the bitwise OR operation

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 32. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.37. stroll_bmap32_set

static inline void stroll_bmap32_set(uint32_t *bmap, unsigned int bit_no)

Set a bit in a 32-bits word bitmap.

Set bit specified by bit_no into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [inout] Bitmap to set

  • bit_no – [in] Index of bit to set

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_no is >= 32, result is undefined. An assertion is triggered otherwise.

8.4.38. stroll_bmap32_set_mask

static inline void stroll_bmap32_set_mask(uint32_t *bmap, uint32_t mask)

Set bits of 32-bits word bitmap according to mask given in argument.

Set all bits of bmap bitmap which are set into mask.

Parameters:

  • bmap – [inout] Bitmap to set

  • mask – [in] Mask of bits to set

8.4.39. stroll_bmap32_set_range

static inline void stroll_bmap32_set_range(uint32_t *bmap, unsigned int start_bit, unsigned int bit_count)

Set bits in a 32-bits word bitmap according to specified range.

Compute a mask according to start_bit and bit_count range given in argument. Then, set all bits in bmap bitmap which are set into this computed mask.

Mask is computed thanks to stroll_bmap32_mask().

Parameters:

  • bmap – [inout] Bitmap to set

  • start_bit – [in] Index of first bit to set

  • bit_count – [in] Number of bits to set

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 32. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.40. stroll_bmap32_set_all

static inline void stroll_bmap32_set_all(uint32_t *bmap)

Set all bits of a 32-bits word bitmap.

Parameters:

  • bmap – [out] Bitmap to set

8.4.41. stroll_bmap32_setup_clear

static inline void stroll_bmap32_setup_clear(uint32_t *bmap)

Setup a 32-bits bitmap with all bits cleared.

Parameters:

  • bmap – [out] Bitmap to setup.

8.4.42. stroll_bmap32_setup_set

static inline void stroll_bmap32_setup_set(uint32_t *bmap)

Setup a 32-bits bitmap with all bits set.

Parameters:

  • bmap – [out] Bitmap to setup.

8.4.43. stroll_bmap32_test

static inline bool stroll_bmap32_test(uint32_t bmap, unsigned int bit_no)

Test wether a bit in a 32-bits word bitmap is set or not.

Test wether the bit specified by bit_no is set into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [in] Bitmap to test

  • bit_no – [in] Index of bit to test starting from 0

Return values:

  • true – tested bit is set

  • false – tested bit is cleared

Returns:

Test result

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_no is >= 32, result is undefined. An assertion is triggered otherwise.

8.4.44. stroll_bmap32_test_all

static inline bool stroll_bmap32_test_all(uint32_t bmap)

Test wether a 32-bits word bitmap contains bits set or not.

Parameters:

  • bmap – [in] Bitmap to test

Return values:

  • true – One or multiple tested bits are set into bmap

  • false – No tested bits are set into bmap

Returns:

Test result

8.4.45. stroll_bmap32_test_mask

static inline bool stroll_bmap32_test_mask(uint32_t bmap, uint32_t mask)

Test wether bits in a 32-bits word bitmap are set or not.

Test wether a set of bits specified by mask are nonzero into bmap.

Parameters:

  • bmap – [in] Bitmap to test

  • mask – [in] The set of bits to test

Return values:

  • true – One or multiple tested bits are set into bmap

  • false – No tested bits are set into bmap

Returns:

Test result

8.4.46. stroll_bmap32_test_range

static inline bool stroll_bmap32_test_range(uint32_t bmap, unsigned int start_bit, unsigned int bit_count)

Test wether a range of bits in a 32-bits word bitmap are set or not.

Compute a mask according to start_bit and bit_count range given in argument. Then, check wether, within the given range, there are bits set into the bmap bitmap or not.

Mask is computed thanks to stroll_bmap32_mask().

Parameters:

  • bmap – [in] Bitmap to test

  • start_bit – [in] Index of first bit to test

  • bit_count – [in] Number of bits to test

Return values:

  • true – One or multiple tested bits are set into bmap

  • false – No tested bits are set into bmap

Returns:

Test result

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 32. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.47. stroll_bmap32_toggle

static inline void stroll_bmap32_toggle(uint32_t *bmap, unsigned int bit_no)

Toggle state of a single 32-bits word bitmap bit.

Invert value of bit specified by bit_no into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [inout] Bitmap which bit to toggle

  • bit_no – [in] Index of bit to toggle

8.4.48. stroll_bmap32_toggle_mask

static inline void stroll_bmap32_toggle_mask(uint32_t *bmap, uint32_t mask)

Toggle state of bits of a 32-bits word bitmap according to given mask.

Invert value of bmap bitmap bits which are set into mask.

Parameters:

  • bmap – [inout] Bitmap which bits to toggle

  • mask – [in] Mask of bits to toggle

8.4.49. stroll_bmap32_toggle_range

static inline void stroll_bmap32_toggle_range(uint32_t *bmap, unsigned int start_bit, unsigned int bit_count)

Toggle state of bits of a 32-bits word bitmap according to specified range.

Compute a mask according to start_bit and bit_count range given in argument. Then, invert value of all bits in bmap bitmap which are set into this computed mask.

Mask is computed thanks to stroll_bmap32_mask().

Parameters:

  • bmap – [inout] Bitmap which bits to toggle

  • start_bit – [in] Index of first bit to toggle

  • bit_count – [in] Number of bits to toggle

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 32. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.50. stroll_bmap32_toggle_all

static inline void stroll_bmap32_toggle_all(uint32_t *bmap)

Toggle all bits of a 32-bits word bitmap.

Invert the value of all bits of bmap bitmap.

Parameters:

  • bmap – [out] Bitmap which bits to toggle

8.4.51. stroll_bmap32_xor

static inline uint32_t stroll_bmap32_xor(uint32_t bmap, uint32_t mask)

Perform bitwise mask based XOR operation on 32-bits word bitmap.

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • mask – [in] Mask to perform operation with

Returns:

bmap ^ mask

8.4.52. stroll_bmap32_xor_range

static inline uint32_t stroll_bmap32_xor_range(uint32_t bmap, unsigned int start_bit, unsigned int bit_count)

Perform bitwise range based XOR operation on 32-bits word bitmap.

Compute a mask according to start_bit and bit_count range given in argument then use it to perform a bitwise XOR operation over given bmap bitmap.

Mask is computed thanks to stroll_bmap32_mask().

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • start_bit – [in] Index of first mask bit set

  • bit_count – [in] Number of bits set in mask

Returns:

Result of the bitwise XOR operation

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 32. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.53. stroll_bmap64_and

static inline uint64_t stroll_bmap64_and(uint64_t bmap, uint64_t mask)

Perform bitwise mask based AND operation on 64-bits word bitmap.

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • mask – [in] Mask to perform operation with

Returns:

bmap & mask

8.4.54. stroll_bmap64_and_range

static inline uint64_t stroll_bmap64_and_range(uint64_t bmap, unsigned int start_bit, unsigned int bit_count)

Perform bitwise range based AND operation on 64-bits word bitmap.

Compute a mask according to start_bit and bit_count range given in argument then use it to perform a bitwise AND operation over given bmap bitmap.

Mask is computed thanks to stroll_bmap64_mask().

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • start_bit – [in] Index of first mask bit set

  • bit_count – [in] Number of bits set in mask

Returns:

Result of the bitwise AND operation

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 64. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.55. stroll_bmap64_clear

static inline void stroll_bmap64_clear(uint64_t *bmap, unsigned int bit_no)

Clear a bit in a 64-bits word bitmap.

Clear bit specified by bit_no into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [inout] Bitmap to clear

  • bit_no – [in] Index of bit to clear

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_no is >= 64, result is undefined. An assertion is triggered otherwise.

8.4.56. stroll_bmap64_clear_mask

static inline void stroll_bmap64_clear_mask(uint64_t *bmap, uint64_t mask)

Clear bits of 64-bits word bitmap according to mask given in argument.

Clear all bits of bmap bitmap which are set into mask.

Parameters:

  • bmap – [inout] Bitmap to clear

  • mask – [in] Mask of bits to clear

8.4.57. stroll_bmap64_clear_range

static inline void stroll_bmap64_clear_range(uint64_t *bmap, unsigned int start_bit, unsigned int bit_count)

Clear bits in a 64-bits word bitmap according to specified range.

Compute a mask according to start_bit and bit_count range given in argument. Then, clear all bits in bmap bitmap which are set into this computed mask.

Mask is computed thanks to stroll_bmap64_mask().

Parameters:

  • bmap – [inout] Bitmap to clear

  • start_bit – [in] Index of first bit to clear

  • bit_count – [in] Number of bits to clear

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 64. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.58. stroll_bmap64_clear_all

static inline void stroll_bmap64_clear_all(uint64_t *bmap)

Clear all bits of a 64-bits word bitmap.

Parameters:

  • bmap – [out] Bitmap to clear

8.4.59. stroll_bmap64_hweight

static inline unsigned int stroll_bmap64_hweight(uint64_t bmap)

Compute the number of bits set over a 64-bits bitmap.

Returns the Hamming weight of a 64-bits bitmap. The Hamming weight of a number is the total number of bits set in it.

Parameters:

  • bmap – [in] Bitmap to search

Returns:

Number of bits set

8.4.60. stroll_bmap64_mask

static inline uint64_t stroll_bmap64_mask(unsigned int start_bit, unsigned int bit_count)

Compute a 64-bits word mask.

Compute a 64-bits mask where all bits are set starting from bit which index is start_bit to start_bit + bit_count - 1. Bit indices starts from 0.

Parameters:

  • start_bit – [in] Index of first mask bit set starting from 0

  • bit_count – [in] Number of bits set in mask

Returns:

Computed mask

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 64. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.61. stroll_bmap64_or

static inline uint64_t stroll_bmap64_or(uint64_t bmap, uint64_t mask)

Perform bitwise mask based OR operation on 64-bits word bitmap.

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • mask – [in] Mask to perform operation with

Returns:

bmap | mask

8.4.62. stroll_bmap64_or_range

static inline uint64_t stroll_bmap64_or_range(uint64_t bmap, unsigned int start_bit, unsigned int bit_count)

Perform bitwise range based OR operation on 64-bits word bitmap.

Compute a mask according to start_bit and bit_count range given in argument then use it to perform a bitwise OR operation over given bmap bitmap.

Mask is computed thanks to stroll_bmap64_mask().

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • start_bit – [in] Index of first mask bit set

  • bit_count – [in] Number of bits set in mask

Returns:

Result of the bitwise OR operation

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 64. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.63. stroll_bmap64_set

static inline void stroll_bmap64_set(uint64_t *bmap, unsigned int bit_no)

Set a bit in a 64-bits word bitmap.

Set bit specified by bit_no into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [inout] Bitmap to set

  • bit_no – [in] Index of bit to set

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_no is >= 64, result is undefined. An assertion is triggered otherwise.

8.4.64. stroll_bmap64_set_mask

static inline void stroll_bmap64_set_mask(uint64_t *bmap, uint64_t mask)

Set bits of 64-bits word bitmap according to mask given in argument.

Set all bits of bmap bitmap which are set into mask.

Parameters:

  • bmap – [inout] Bitmap to set

  • mask – [in] Mask of bits to set

8.4.65. stroll_bmap64_set_range

static inline void stroll_bmap64_set_range(uint64_t *bmap, unsigned int start_bit, unsigned int bit_count)

Set bits in a 64-bits word bitmap according to specified range.

Compute a mask according to start_bit and bit_count range given in argument. Then, set all bits in bmap bitmap which are set into this computed mask.

Mask is computed thanks to stroll_bmap64_mask().

Parameters:

  • bmap – [inout] Bitmap to set

  • start_bit – [in] Index of first bit to set

  • bit_count – [in] Number of bits to set

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 64. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.66. stroll_bmap64_set_all

static inline void stroll_bmap64_set_all(uint64_t *bmap)

Set all bits of a 64-bits word bitmap.

Parameters:

  • bmap – [out] Bitmap to set

8.4.67. stroll_bmap64_setup_clear

static inline void stroll_bmap64_setup_clear(uint64_t *bmap)

Setup a 64-bits bitmap with all bits cleared.

Parameters:

  • bmap – [out] Bitmap to setup.

8.4.68. stroll_bmap64_setup_set

static inline void stroll_bmap64_setup_set(uint64_t *bmap)

Setup a 64-bits bitmap with all bits set.

Parameters:

  • bmap – [out] Bitmap to setup.

8.4.69. stroll_bmap64_test

static inline bool stroll_bmap64_test(uint64_t bmap, unsigned int bit_no)

Test wether a bit in a 64-bits word bitmap is set or not.

Test wether the bit specified by bit_no is set into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [in] Bitmap to test

  • bit_no – [in] Index of bit to test starting from 0

Return values:

  • true – tested bit is set

  • false – tested bit is cleared

Returns:

Test result

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_no is >= 64, result is undefined. An assertion is triggered otherwise.

8.4.70. stroll_bmap64_test_all

static inline bool stroll_bmap64_test_all(uint64_t bmap)

Test wether a 64-bits word bitmap contains bits set or not.

Parameters:

  • bmap – [in] Bitmap to test

Return values:

  • true – One or multiple tested bits are set into bmap

  • false – No tested bits are set into bmap

Returns:

Test result

8.4.71. stroll_bmap64_test_mask

static inline bool stroll_bmap64_test_mask(uint64_t bmap, uint64_t mask)

Test wether bits in a 64-bits word bitmap are set or not.

Test wether a set of bits specified by mask are nonzero into bmap.

Parameters:

  • bmap – [in] Bitmap to test

  • mask – [in] The set of bits to test

Return values:

  • true – One or multiple tested bits are set into bmap

  • false – No tested bits are set into bmap

Returns:

Test result

8.4.72. stroll_bmap64_test_range

static inline bool stroll_bmap64_test_range(uint64_t bmap, unsigned int start_bit, unsigned int bit_count)

Test wether a range of bits in a 64-bits word bitmap are set or not.

Compute a mask according to start_bit and bit_count range given in argument. Then, check wether, within the given range, there are bits set into the bmap bitmap or not.

Mask is computed thanks to stroll_bmap64_mask().

Parameters:

  • bmap – [in] Bitmap to test

  • start_bit – [in] Index of first bit to test

  • bit_count – [in] Number of bits to test

Return values:

  • true – One or multiple tested bits are set into bmap

  • false – No tested bits are set into bmap

Returns:

Test result

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 64. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.73. stroll_bmap64_toggle

static inline void stroll_bmap64_toggle(uint64_t *bmap, unsigned int bit_no)

Toggle state of a single 64-bits word bitmap bit.

Invert value of bit specified by bit_no into bmap bitmap. Bit indices starts from 0.

Parameters:

  • bmap – [inout] Bitmap which bit to toggle

  • bit_no – [in] Index of bit to toggle

8.4.74. stroll_bmap64_toggle_mask

static inline void stroll_bmap64_toggle_mask(uint64_t *bmap, uint64_t mask)

Toggle state of bits of a 64-bits word bitmap according to given mask.

Invert value of bmap bitmap bits which are set into mask.

Parameters:

  • bmap – [inout] Bitmap which bits to toggle

  • mask – [in] Mask of bits to toggle

8.4.75. stroll_bmap64_toggle_range

static inline void stroll_bmap64_toggle_range(uint64_t *bmap, unsigned int start_bit, unsigned int bit_count)

Toggle state of bits of a 64-bits word bitmap according to specified range.

Compute a mask according to start_bit and bit_count range given in argument. Then, invert value of all bits in bmap bitmap which are set into this computed mask.

Mask is computed thanks to stroll_bmap64_mask().

Parameters:

  • bmap – [inout] Bitmap which bits to toggle

  • start_bit – [in] Index of first bit to toggle

  • bit_count – [in] Number of bits to toggle

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 64. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.76. stroll_bmap64_toggle_all

static inline void stroll_bmap64_toggle_all(uint64_t *bmap)

Toggle all bits of a 64-bits word bitmap.

Invert the value of all bits of bmap bitmap.

Parameters:

  • bmap – [out] Bitmap which bits to toggle

8.4.77. stroll_bmap64_xor

static inline uint64_t stroll_bmap64_xor(uint64_t bmap, uint64_t mask)

Perform bitwise mask based XOR operation on 64-bits word bitmap.

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • mask – [in] Mask to perform operation with

Returns:

bmap ^ mask

8.4.78. stroll_bmap64_xor_range

static inline uint64_t stroll_bmap64_xor_range(uint64_t bmap, unsigned int start_bit, unsigned int bit_count)

Perform bitwise range based XOR operation on 64-bits word bitmap.

Compute a mask according to start_bit and bit_count range given in argument then use it to perform a bitwise XOR operation over given bmap bitmap.

Mask is computed thanks to stroll_bmap64_mask().

Parameters:

  • bmap – [in] Bitmap to perform operation on

  • start_bit – [in] Index of first mask bit set

  • bit_count – [in] Number of bits set in mask

Returns:

Result of the bitwise XOR operation

Warning

  • When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and bit_count is zero, result is undefined. A zero bit_count triggers an assertion otherwise.

  • The sum start_bit + bit_count MUST be <= 64. If not, an undefined result is returned when the CONFIG_STROLL_ASSERT_API build option is disabled. An assertion is triggered otherwise.

8.4.79. stroll_bops_ffc

static inline unsigned int stroll_bops_ffc(unsigned long value)

Find First (least-significant) bit Cleared over a machine word.

Parameters:

  • value – [in] word to search

Returns:

Index of bit starting from 1, 0 when no cleared bits were found.

8.4.80. stroll_bops_ffs

static inline unsigned int stroll_bops_ffs(unsigned long value)

Find First (least-significant) bit Set over a machine word.

Parameters:

  • value – [in] word to search

Returns:

Index of bit starting from 1, 0 when no set bits were found.

8.4.81. stroll_bops_fls

static inline unsigned int stroll_bops_fls(unsigned long value)

Find Last (most-significant) bit over a machine word.

Parameters:

  • value – [in] word to search

Returns:

Index of bit starting from 1

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and a value is zero, result is undefined. A zero value triggers an assertion otherwise.

8.4.82. stroll_bops_hweight

static inline unsigned int stroll_bops_hweight(unsigned long value)

Find the number of set bits over a machine word.

Returns the Hamming weight of a word. The Hamming weight of a number is the total number of bits set in it.

Parameters:

  • value – [in] word to search

Returns:

Number of set bits

8.4.83. stroll_bops32_ffc

static inline unsigned int stroll_bops32_ffc(uint32_t value)

Find First (least-significant) bit Cleared over 32 bits word.

Parameters:

  • value – [in] word to search

Returns:

Index of bit starting from 1, 0 when no cleared bits were found.

8.4.84. stroll_bops64_ffc

static inline unsigned int stroll_bops64_ffc(uint64_t value)

Find First (least-significant) bit Cleared over 64 bits word.

Parameters:

  • value – [in] word to search

Returns:

Index of bit starting from 1, 0 when no cleared bits were found.

8.4.85. stroll_bops32_ffs

static inline unsigned int stroll_bops32_ffs(uint32_t value)

Find First (least-significant) bit Set over 32 bits word.

Parameters:

  • value – [in] word to search

Returns:

Index of bit starting from 1, 0 when no set bits were found.

8.4.86. stroll_bops64_ffs

static inline unsigned int stroll_bops64_ffs(uint64_t value)

Find First (least-significant) bit Set over 64 bits word.

Parameters:

  • value – [in] word to search

Returns:

Index of bit starting from 1, 0 when no set bits were found.

8.4.87. stroll_bops32_fls

static inline unsigned int stroll_bops32_fls(uint32_t value)

Find Last (most-significant) bit Set over 32 bits word.

Parameters:

  • value – [in] word to search

Returns:

Index of bit starting from 1

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and a value is zero, result is undefined. A zero value triggers an assertion otherwise.

8.4.88. stroll_bops64_fls

static inline unsigned int stroll_bops64_fls(uint64_t value)

Find Last (most-significant) bit Set over 64 bits word.

Parameters:

  • value – [in] word to search

Returns:

Index of bit starting from 1

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and a value is zero, result is undefined. A zero value triggers an assertion otherwise.

8.4.89. stroll_bops32_hweight

static inline unsigned int stroll_bops32_hweight(uint32_t value)

Find the number of set bits over 32 bits word.

Returns the Hamming weight of a 32 bits word. The Hamming weight of a number is the total number of bits set in it.

Parameters:

  • value – [in] word to search

Returns:

Number of set bits

8.4.90. stroll_bops64_hweight

static inline unsigned int stroll_bops64_hweight(uint64_t value)

Find the number of set bits over 64 bits word.

Returns the Hamming weight of a 64 bits word. The Hamming weight of a number is the total number of bits set in it.

Parameters:

  • value – [in] word to search

Returns:

Number of set bits

8.4.91. stroll_lvstr_cede

int stroll_lvstr_cede(struct stroll_lvstr *lvstr, char *cstr)

Register a C string which length is not known and grant lvstr ownership of it.

Register a NULL terminated string and make lvstr the owner of it.

cstr MUST be a valid C string, i.e., a NULL byte terminated string which length is smaller than or equal to STROLL_LVSTR_LEN_MAX.

lvstr is allowed to free cstr at release time, i.e., whenever the registered string is replaced or when stroll_lvstr_fini() is called. Use this when lvstr should handle cstr life-cycle.

A previously registered C string is released before registration of cstr. Release operation may involve calling free() on the previously registered string if lvstr was made the owner of it.

See also

Parameters:

  • lvstr – [inout] Length-Value String

  • cstr – [in] C string to register

Return values:

  • 0 – success

  • -E2BIG – cstr is invalid

Returns:

an errno-like error code

8.4.92. stroll_lvstr_cstr

static inline const char *stroll_lvstr_cstr(const struct stroll_lvstr *lvstr)

Return registered C string.

Parameters:

  • lvstr – [in] Length-Value String

Returns:

Registered NULL terminated string or NULL if no string is registered.

8.4.93. stroll_lvstr_dup

int stroll_lvstr_dup(struct stroll_lvstr *lvstr, const char *cstr)

Duplicate a C string which length is not known and grant lvstr ownership of it.

Duplicate a NULL terminated string into newly allocated memory and make lvstr the owner of duplicated string.

cstr MUST be a valid C string, i.e., a NULL byte terminated string which length is smaller than or equal to STROLL_LVSTR_LEN_MAX.

lvstr is allowed to free cstr at release time, i.e., whenever the registered string is replaced or when stroll_lvstr_fini() is called. Use this when lvstr should handle cstr life-cycle.

A previously registered C string is released before registration of cstr duplicate. Release operation may involve calling free() on the previously registered string if lvstr was made the owner of it.

See also

Parameters:

  • lvstr – [inout] Length-Value String

  • cstr – [in] C string to register

Return values:

  • 0 – success

  • -E2BIG – cstr is invalid

  • -ENOMEM – duplicate allocation failed

Returns:

an errno-like error code

8.4.94. stroll_lvstr_fini

void stroll_lvstr_fini(struct stroll_lvstr *lvstr)

Finalize an empty stroll_lvstr.

Release resources allocated for lvstr when required. Once called, you MUST NOT re-use lvstr unless re-initialized first.

If lvstr in an owning instance of stroll_lvstr, a previously registered C string (if any) will be free(3) ‘ed.

See also

Parameters:

  • lvstr – [inout] Length-Value String

8.4.95. stroll_lvstr_init

static inline void stroll_lvstr_init(struct stroll_lvstr *lvstr)

Initialize an empty stroll_lvstr.

See also

STROLL_LVSTR_INIT

Parameters:

  • lvstr – [out] Length-Value String

8.4.96. stroll_lvstr_init_cede

int stroll_lvstr_init_cede(struct stroll_lvstr *lvstr, char *cstr)

Initialize an owning stroll_lvstr with a string which length is not known.

This function is similar to stroll_lvstr_cede() but do not release previously registered C string.

It is meant for stroll_lvstr initialization / first usage purpose only.

See also

stroll_lvstr_init_ncede()

Parameters:

  • lvstr – [out] Length-Value String

  • cstr – [in] C string to register

Return values:

  • 0 – success

  • -E2BIG – cstr is invalid

Returns:

an errno-like error code

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

8.4.97. stroll_lvstr_init_dup

int stroll_lvstr_init_dup(struct stroll_lvstr *lvstr, const char *cstr)

Initialize an owning stroll_lvstr with a duplicated string which length is not known.

This function is similar to stroll_lvstr_ndup() but do not release previously registered C string.

It is meant for stroll_lvstr initialization / first usage purpose only.

See also

stroll_lvstr_init_ndup()

Parameters:

  • lvstr – [out] Length-Value String

  • cstr – [in] C string to register

Return values:

  • 0 – success

  • -E2BIG – cstr is invalid

  • -ENOMEM – duplicate allocation failed

Returns:

an errno-like error code

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

8.4.98. stroll_lvstr_init_lend

int stroll_lvstr_init_lend(struct stroll_lvstr *lvstr, const char *cstr)

Initialize a non-owning stroll_lvstr with a string which length is not known.

This function is similar to stroll_lvstr_lend() but do not release previously registered C string.

It is meant for stroll_lvstr initialization / first usage purpose only.

See also

stroll_lvstr_init_nlend()

Parameters:

  • lvstr – [out] Length-Value String

  • cstr – [in] C string to register

Return values:

  • 0 – success

  • -E2BIG – cstr is invalid

Returns:

an errno-like error code

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

8.4.99. stroll_lvstr_init_ncede

static inline void stroll_lvstr_init_ncede(struct stroll_lvstr *lvstr, char *cstr, size_t len)

Initialize an owning stroll_lvstr with a string which length is known.

This function is similar to stroll_lvstr_ncede() but do not release previously registered C string.

It is meant for stroll_lvstr initialization / first usage purpose only.

See also

Parameters:

  • lvstr – [out] Length-Value String

  • cstr – [in] C string to register

  • len – [in] length of cstr

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

Warning

8.4.100. stroll_lvstr_init_ndup

int stroll_lvstr_init_ndup(struct stroll_lvstr *lvstr, const char *cstr, size_t len)

Initialize an owning stroll_lvstr with a duplicated string which length is known.

This function is similar to stroll_lvstr_ndup() but do not release previously registered C string.

It is meant for stroll_lvstr initialization / first usage purpose only.

See also

stroll_lvstr_init_dup()

Parameters:

  • lvstr – [out] Length-Value String

  • cstr – [in] C string to register

  • len – [in] length of cstr

Return values:

  • 0 – success

  • -ENOMEM – duplicate allocation failed

Returns:

an errno-like error code

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

Warning

8.4.101. stroll_lvstr_init_nlend

static inline void stroll_lvstr_init_nlend(struct stroll_lvstr *lvstr, const char *cstr, size_t len)

Initialize a non-owning stroll_lvstr with a string which length is known.

This function is similar to stroll_lvstr_nlend() but do not release previously registered C string.

It is meant for stroll_lvstr initialization / first usage purpose only.

See also

Parameters:

  • lvstr – [out] Length-Value String

  • cstr – [in] C string to register

  • len – [in] length of cstr

Note

Once client code is done with the stroll_lvstr, it MUST call stroll_lvstr_fini() to release allocated resources.

Warning

8.4.102. stroll_lvstr_len

static inline size_t stroll_lvstr_len(const struct stroll_lvstr *lvstr)

Return length of registered C string.

See also

stroll_lvstr_cstr()

Parameters:

  • lvstr – [in] Length-Value String

Returns:

Length of registered string excluding the terminating NULL byte

Warning

When compiled with the CONFIG_STROLL_ASSERT_API build option disabled and there is no registered C string, result is undefined. An assertion is triggered otherwise.

8.4.103. stroll_lvstr_lend

int stroll_lvstr_lend(struct stroll_lvstr *lvstr, const char *cstr)

Register a C string which length is not known.

Register a NULL terminated string but do not make lvstr the owner of it.

cstr MUST be a valid C string, i.e., a NULL byte terminated string which length is smaller than or equal to STROLL_LVSTR_LEN_MAX.

lvstr is instructed to avoid freeing cstr at release time, i.e., when the registered string is replaced or when stroll_lvstr_fini() is called. Use this when lvstr should not handle cstr life-cycle at all.

A previously registered C string is released before registration of cstr. Release operation may involve calling free() on the previously registered string if lvstr was made the owner of it.

See also

Parameters:

  • lvstr – [inout] Length-Value String

  • cstr – [in] C string to register

Return values:

  • 0 – success

  • -E2BIG – cstr is invalid

Returns:

an errno-like error code

8.4.104. stroll_lvstr_ncede

void stroll_lvstr_ncede(struct stroll_lvstr *lvstr, char *cstr, size_t len)

Register a C string which length is known and grant lvstr ownership of it.

Register a NULL terminated string and make lvstr the owner of it.

cstr MUST be a valid C string, i.e., a NULL byte terminated string which length len is smaller than or equal to STROLL_LVSTR_LEN_MAX.

lvstr is allowed to free cstr at release time, i.e., whenever the registered string is replaced or when stroll_lvstr_fini() is called. Use this when lvstr should handle cstr life-cycle.

A previously registered C string is released before registration of cstr. Release operation may involve calling free() on the previously registered string if lvstr was made the owner of it.

See also

Parameters:

  • lvstr – [inout] Length-Value String

  • cstr – [in] C string to register

  • len – [in] length of cstr

Warning

8.4.105. stroll_lvstr_ndup

int stroll_lvstr_ndup(struct stroll_lvstr *lvstr, const char *cstr, size_t len)

Duplicate a C string which length is known and grant lvstr ownership of it.

Duplicate a NULL terminated string into newly allocated memory and make lvstr the owner of duplicated string.

cstr MUST be a valid C string, i.e., a NULL byte terminated string which length is greater than or equal to len, with len smaller than or equal to STROLL_LVSTR_LEN_MAX. The duplicated string will contain characters over the range [0..len] only and will be terminated by a NULL byte.

lvstr is allowed to free cstr at release time, i.e., whenever the registered string is replaced or when stroll_lvstr_fini() is called. Use this when lvstr should handle cstr life-cycle.

A previously registered C string is released before registration of cstr duplicate. Release operation may involve calling free() on the previously registered string if lvstr was made the owner of it.

See also

Parameters:

  • lvstr – [inout] Length-Value String

  • cstr – [in] C string to register

  • len – [in] length of cstr

Return values:

  • 0 – success

  • -ENOMEM – duplicate allocation failed

Returns:

an errno-like error code

Warning

8.4.106. stroll_lvstr_nlend

void stroll_lvstr_nlend(struct stroll_lvstr *lvstr, const char *cstr, size_t len)

Register a C string which length is known.

Register a NULL terminated string but do not make lvstr the owner of it.

cstr MUST be a valid C string, i.e. a NULL byte terminated string which length len is smaller than or equal to STROLL_LVSTR_LEN_MAX.

lvstr is instructed to avoid freeing cstr at release time, i.e., when the registered string is replaced or when stroll_lvstr_fini() is called. Use this when lvstr should not handle cstr life-cycle at all.

A previously registered C string is released before registration of cstr. Release operation may involve calling free(3) on the previously registered string if lvstr was made the owner of it.

See also

Parameters:

  • lvstr – [inout] Length-Value String

  • cstr – [in] C string to register

  • len – [in] length of cstr

Warning