Package bsla [Package Group bsl]

Provide macros for portable use of compiler annotations. More...

Components
	Component bsla_annotations
	Provide support for compiler annotations for compile-time safety.
	Component bsla_deprecated
	Provide compiler-hint macros to indicate deprecated entities.
	Component bsla_error
	Provide a macro to emit an error message when a function is called.
	Component bsla_fallthrough
	Provide a macro to suppress warnings on switch fall-throughs.
	Component bsla_format
	Provide a macro to indicate that a return value is a format string.
	Component bsla_maybeunused
	Provide a macro to suppress "unused" warnings.
	Component bsla_nodiscard
	Provide a macro for warning about ignored function results.
	Component bsla_nonnullarg
	Provide macros to hint at null arguments to functions.
	Component bsla_noreturn
	Provide a macro to issue a compiler warning if a function returns.
	Component bsla_nullterminated
	Provide macros for use with NULL-terminated variadic functions.
	Component bsla_printf
	Provide a macro to indicate printf-style arguments.
	Component bsla_scanf
	Provide a macro for checking scanf-style format strings.
	Component bsla_unreachable
	Provide a compiler-hint macro to indicate unreachable code.
	Component bsla_unused: DEPRECATED
	Provide a macro to suppress "unused" warnings.
	Component bsla_used
	Provide a macro to prevent elision of unused entities.
	Component bsla_warning
	Provide a macro to emit a warning when a function is called.

---

Detailed Description

Outline

• Purpose
• MNEMONIC: Basic Standard Library Annotations (bsla)
• Description
  • Hierarchical Synopsis
  • Component Synopsis
  • Component Overview
    • bsla_annotations
    • bsla_deprecated
    • bsla_error
    • bsla_fallthrough
    • bsla_format
    • bsla_maybeunused
    • bsla_nodiscard
    • bsla_nonnullarg
    • bsla_noreturn
    • bsla_nullterminated
    • bsla_printf
    • bsla_scanf
    • bsla_unreachable
    • bsla_unused
    • bsla_used
    • bsla_warning

Purpose:

Provide macros for portable use of compiler annotations.

MNEMONIC: Basic Standard Library Annotations (bsla):

Description:

The bsla package provides a variety of macros that expand to annotations to provide hints to the compiler, to suppress or emit compiler warnings or errors.

The annotations themselves are not supported on all compilers, and sometimes different annotations are required for different compilers to have a given effect. The macros provided in this package either expand to the correct annotation for the current compiler, or, if the compiler does not support any form of the given annotation, the macros expand to nothing.

For every macro, BSLA_{X}, there is a corresponding macro, BSLA_{X}_IS_ACTIVE, which is always defined to an integer, and expands to 0 if BSLA_{X} expands to nothing and 1 if BSLA_{X} expands to an annotation and the annotation works. There are situations where compilers will "tolerate" an annotation -- the annotation won't be reported as a syntax error, but it will have no effect. In those cases, BSLA_{X} will expand to nothing and BSLA_{X}_IS_ACTIVE will be 0.

Hierarchical Synopsis:

The bsla package currently has 16 components having 3 levels of physical dependency. The list below shows the hierarchical ordering of the components. The order of components within each level is not architecturally significant, just alphabetical.

  3. bsla_annotations

  2. bsla_used

  1. bsla_deprecated
     bsla_error
     bsla_fallthrough
     bsla_format
     bsla_maybeunused
     bsla_nodiscard
     bsla_nonnullarg
     bsla_noreturn
     bsla_nullterminated
     bsla_printf
     bsla_scanf
     bsla_unreachable
     bsla_unused                                         !DEPRECATED!
     bsla_warning

Component Synopsis:

bsla_annotations:
Provide support for compiler annotations for compile-time safety.

bsla_deprecated:
Provide compiler-hint macros to indicate deprecated entities.

bsla_error:
Provide a macro to emit an error message when a function is called.

bsla_fallthrough:
Provide a macro to suppress warnings on switch fall-throughs.

bsla_format:
Provide a macro to indicate that a return value is a format string.

bsla_maybeunused:
Provide a macro to suppress "unused" warnings.

bsla_nodiscard:
Provide a macro for warning about ignored function results.

bsla_nonnullarg:
Provide macros to hint at null arguments to functions.

bsla_noreturn:
Provide a macro to issue a compiler warning if a function returns.

bsla_nullterminated:
Provide macros for use with NULL-terminated variadic functions.

bsla_printf:
Provide a macro to indicate printf-style arguments.

bsla_scanf:
Provide a macro for checking scanf-style format strings.

bsla_unreachable:
Provide a compiler-hint macro to indicate unreachable code.

bsla_unused: DEPRECATED
Provide a macro to suppress "unused" warnings.

bsla_used:
Provide a macro to prevent elision of unused entities.

bsla_warning:
Provide a macro to emit a warning when a function is called.

Component Overview:

This section provides a brief introduction to some of the components in the bsla package. See the documentation in each component for full details.

bsla_annotations:

This component exists to provide a single component whose header can be included to transitively include all of the annotation macros defined in the bsla package. The macros that are transitively included by this component correspond to various compiler features, and can be used to annotate code for specific compile-time safety checks.

bsla_deprecated:

This component provides a preprocessor macro that hints to the compile that a function, variable, or type is deprecated.

bsla_error:

This component provides a preprocessor macro that flags a function such that a compiler error will occur when the function is called. On platforms where the appropriate attribute is not supported, the macro expands to nothing.

bsla_fallthrough:

This component provides a preprocessor macro that suppresses compiler warnings about flow of control fall-through from one case or default of a switch statement to another. On compilers where the appropriate attribute is not supported, the macro expands to nothing.

bsla_format:

This component provides a preprocessor macro to indicate that an indexed argument of a function is a printf-style format specification, and that the function will return a printf-style format string with an equivalent specification.

bsla_maybeunused:

This component provides a preprocessor macro that will suppress "unused" warnings on a locally defined function, type, or variable that is not used.

bsla_nodiscard:

This component provides a preprocessor macro that annotates a function such that a compiler warning will be generated if the return value of the function is ignored.

bsla_nonnullarg:

This component provides preprocessor macros that define compiler-specific compile-time annotations. These macros instruct the compiler to warn if null is passed to certain arguments to a function, or, on platforms where the feature is not supported, expand to nothing.

bsla_noreturn:

This component provides a preprocessor macro that annotates a function as never returning, resulting in a compiler warning if a path of control exists such that the function does return.

bsla_nullterminated:

This component provides preprocessor macros to indicate that a variadic function's arguments are terminated by a NULL value, or, in the case of BSLA_NULLTERMINATEDAT, by a NULL value at a certain index. Note that the terminating NULL must actually be NULL; passing 0 in it's place will result in a warning.

bsla_printf:

This component provides a preprocessor macro that allows the designation of a given function argument as a printf-style format string, and arguments starting at a certain index in the argument list to be formatted according to that string.

bsla_scanf:

This component provides a preprocessor macro that indicates that one of the arguments to a function is a scanf-style format string, and that the arguments starting at a certain index are to be checked for compatibility with that format string.

bsla_unreachable:

This component provides a preprocessor macro that hints to the compile that a statement in the code is intended to be unreachable.

bsla_unused:

This component provides a preprocessor macro that will suppress "unused" warnings on a locally defined function, type, or variable that is not used.

bsla_used:

This component provides a preprocessor macro that will guarantee the emission of a local function, type, or variable whether it is used or not.

bsla_warning:

This component provides a macro that indicates that a compiler warning should be emitted when a given function is called.