CDEFS(9)

NAME
cdefs - compiler portability macro definitions

DESCRIPTION
<sys/cdefs.h> defines macros for compiler, C language standard portability, POSIX standards compliance and symbol visibility. It defines programming interfaces for the system header files to adopt to the many environments FreeBSD supports compilation for. It defines convenience macros for the FreeBSD sources, tailored to the base system's needs.

Most of these macros are for use inside the FreeBSD sources only. They are not intended as a general portability layer.

Supported Compilers

Compilers supported for building programs on FreeBSD:
    Compiler | Versions
    gcc | 9, 10, 11, 12, 13, 14
    clang | 10, 11, 12, 13, 14, 15, 16, 17, 18
    TinyC (tcc) | 0.9
    pcc | 1.1

    Due to testing constraints, tcc and pcc may not always work.

Compilers supported for building FreeBSD itself:
    Compiler | Major Versions Supported
    gcc | 12, 13, 14
    clang | 16, 17, 18

    Please note: Not every single minor versions of these compilers will work or are supported.

Macros and Magic for Programming Environment
cdefs defines (or refrains from defining) a number of macros to increase portability of compiled programs. These are to allow more advanced language features to appear in header files. The header files assume a compiler that accepts C prototype function declarations. They also assume that the compiler accepts ANSI C89 keywords for all language dialects.

  General Macros
General macros that facilitate multiple language environments and language dialects.
Macro | Description
__volatile | expands to volatile in C++ and C89 and newer environments,
__volatile in pre-ANSI environments that support this extension or nothing otherwise.
__inline | expands to inline in C++ and C89 and newer environments,
__inline in pre-ANSI environments that support this extension or nothing otherwise.
__restrict | expands to restrict in C99 and newer environments, or
__restrict otherwise.
__CONCAT | used to paste two pre-processor tokens.
__STRING | used to convert the argument to a string.
__BEGIN_DECLS | Start a group of functions.
__END_DECLS | End a group of functions.
In a C environment, these are defined as nothing. In a C++ environment, these declare the functions to have “C” linkage.

  Function, Structure and Variable Modifiers
Macro | Description
__weak_symbol | Declare the symbol to be a weak symbol
__dead2 | Function will not return
__pure2 | Function has no side effects
__unused | To Variable may be unused (usually arguments), so do not
warn about it
__used | Function really is used, so emit it even if it appears unused.
__deprecated | Function interface has been deprecated, and clients
should migrate to a new interface. A warning will be issued for clients of this interface.
__deprecated1(msg) | Function interface has been deprecated, and clients
should migrate to a new interface. The string msg will be included in a warning issued for clients of this interface.
__packed | “not have space between structure elements for natural alignment.
Used when communicating with external protocols.
__aligned(x) | Specify in bytes the minimum alignment for the specified field, structure or variable
__section(x) | Place function or variable in section x
__writeonly | Hint that the variable is only assigned to, but do not warn about it.
Useful for macros and other places the eventual use of the result is unknown.
__alloc_size(x) | The function always returns at least the number of
bytes determined by argument number Fa x
__alloc_size2(x,n) | The function always returns an array, whose size
is at least the number of bytes determined by argument number Fa x times the number of elements specified by argument number Fa n
__alloc_align(x) | Function either returns a pointer aligned to x bytes
or Dv NULL.
__min_size | Declare the array to have a certain, minimum size
__malloc_like | Function behaves like the
“malloc” family of functions.
__pure | Function has no side effects
__always_inline | Always inline this function when called
__fastcall | Use the
“fastcall” ABI to call and name mangle this function.
__result_use_check | Warn if function caller does not use its return value
__nodiscard | Equivalent to the standard
“[[nodiscard]]” attribute. If applied to a function, warn if function caller does not use its return value. The warning may be silenced using a cast to void, or in C++, using an assignment to std::ignore. If applied to a struct, C++ class or enum, this applies to all functions returning values of that type. If applied to a C++ constructor, this applies to creating instances of the class using that constructor.
__returns_twice | Returns multiple times, like
fork(2)
__unreachable | This code is not reachable at runtime
__predict_true(x) | Hint to the compiler that
x is true most of the time. Should only be used when performance is improved for a frequently called bit of code.
__predict_false(x) | Hint to the compiler that
x is false most of the time. Should only be used when performance is improved for a frequently called bit of code.
__null_sentinel | The varadic function contains a parameter that is
a NULL sentinel to mark the end of its arguments.
__exported |
__hidden |
__printflike(fmtarg,firstvararg) | Function is similar to
printf() which specifies the format argument with fmtarg and where the arguments formatted by that format start with the firstvararg, with 0 meaning that va_arg is used and cannot be checked.
__scanflike(fmtarg,firstvararg) | Function is similar to
scanf() which specifies the format argument with fmtarg and where the arguments formatted by that format start with the firstvararg, with 0 meaning that va_arg is used and cannot be checked.
__format_arg(f) | Specifies that arg
f contains a string that will be passed to a function like printf() or scanf after being translated in some way.
__strfmonlike(fmtarg,firstvararg) | Function is similar to
scanf() which specifies the format argument with fmtarg and where the arguments formatted by that format start with the firstvararg, with 0 meaning that va_arg is used and cannot be checked.
__strtimelike(fmtarg,firstvararg) | Function is similar to
scanf() which specifies the format argument with fmtarg and where the arguments formatted by that format start with the firstvararg, with 0 meaning that va_arg is used and cannot be checked.
__printf0like(fmtarg,firstvararg) | Exactly the same
as __printflike except fmtarg may be NULL.
__strong_reference(sym,aliassym) |
__weak_reference(sym,alias) |
__warn_references(sym,msg) |
__sym_compat(sym,impl,verid) |
__sym_default(sym,impl,verid) |
__GLOBAL(sym) |
__WEAK(sym) |
__DECONST(type,var) |
__DEVOLATILE(type,var) |
__DEQUALIFY(type,var) |
__RENAME(x) |
__arg_type_tag |
__datatype_type_tag |
__align_up(x,y) |
__align_down(x,y) |
__is_aligned(x,y) |

  Locking and Debugging Macros
Macros for lock annotation and debugging, as well as some general debugging macros for address sanitizers.
__lock_annotate(x) |
__lockable |
__locks_exclusive |
__locks_shared |
__trylocks_exclusive |
__trylocks_shared |
__unlocks |
__asserts_exclusive |
__asserts_shared |
__requires_exclusive |
__requires_shared |
__requires_unlocked |
__no_lock_analysis |
__nosanitizeaddress |
__nosanitizememory |
__nosanitizethread |
__nostackprotector |
__guarded_by(x) |
__pt_guarded_by(x) |

  Emulated Keywords
As C evolves, many of the old macros we once used have been incorporated into the standard language. As this happens, we add support for these keywords as macros for older compilation environments. Sometimes this results in a nop in the older environment.
Keyword | Description
_Alignas(x) |
_Alignof(x) |
_Noreturn | Expands to
“[[noreturn]]” in C++-11 and newer compilation environments, otherwise “__dead2”
_Static_assert(x, y) | Compile time assertion that
x is true, otherwise emit y as the error message.
_Thread_local | Designate variable as thread local storage
__generic | implement _Generic-like features which aren't entirely possible to emulate the _Generic keyword
__noexcept | to emulate the C++11 argument-less noexcept form
__noexcept_if | to emulate the C++11 conditional noexcept form
_Nonnull |
_Nullable |
_Null_unspecified |

  Support Macros
The following macros are defined, or have specific values, to denote certain things about the build environment.
Macro | Description
__LONG_LONG_SUPPORTED | Variables may be declared
“long long”. This is defined for C99 or newer and C++ environments.
__STDC_LIMIT_MACROS |
__STDC_CONSTANT_MACROS |

  Convenience Macros
These macros make it easier to do a number of things, even though strictly speaking the standard places their normal form in another header.
Macro | Description
__offsetof(type,field) |
__rangeof(type,start,end) |
__containerof(x,s,m) |

  ID Strings
This section is deprecated, but is kept around because too much contrib software still uses these.
Macro | Description
__IDSTRING(name,string) |
__FBSDID(s) |
__RCSID(s) |
__RCSID_SOURCE(s) |
__SCCSID(s) |
__COPYRIGHT(s) |

Supported C Environments
FreeBSD supports a number C standard environments. Selection of the language dialect is a compiler-dependent command line option, though it is usually -std=XX where XX is the standard to set for compiling, such as c89 or c23. FreeBSD provides a number of selection macros to control visibility of symbols. Please see the section on Selection Macros for the specifics.

K R Pre-ANSI Kernighan and Ritchie C. Sometimes called “knr” or “C78” to distinguish it from newer standards. Support for this compilation environment is dependent on compilers supporting this configuration. Most of the old forms of C have been deprecated or removed in isoC-2023. Compilers make compiling in this mode increasingly difficult and support for it may ultimately be removed from the tree.

ansiC
    __STDC__ is defined, however __STDC_VERSION__ is not.

    Strict environment selected with _ANSI_SOURCE.

isoC-99
    __STDC_VERSION__ = 199901L

    Strict environment selected with _C99_SOURCE.

isoC-2011
    __STDC_VERSION__ = 201112L

    Strict environment selected with _C11_SOURCE.

ISO/IEC 9899:2018 (“ISO C17”)
    __STDC_VERSION__ = 201710L

    Strict environment selected with _C11_SOURCE since there are no new C17 only symbols or macros.

    This version of the standard did not introduce any new features, only made minor, technical corrections.

isoC-2023
    __STDC_VERSION__ = 202311L Strict environment selected with _C23_SOURCE though ISO C23 support is only partially implemented.

For more information on C standards, see c(7).

  Programming Environment Selection Macros
Defining the macros outlined below requests that the system header files provide only the functions, structures and macros (symbols) defined by the appropriate standard, while suppressing all extensions. However, system headers not defined by that standard may define extensions. You may only define one of the following for any compilation unit.
Macro | Environment
_POSIX_SOURCE | p1003.1-88 including ansiC
_POSIX_C_SOURCE = 1 | p1003.1-88 including ansiC
_POSIX_C_SOURCE = 2 | p1003.1-90 including ansiC
_POSIX_C_SOURCE = 199309 | p1003.1b-93 including ansiC
_POSIX_C_SOURCE = 199506 | p1003.1c-95 including ansiC
_POSIX_C_SOURCE = 200112 | p1003.1-2001 including isoC-99
_POSIX_C_SOURCE = 200809 | p1003.1-2008 including isoC-99
_POSIX_C_SOURCE = 202405 | p1003.1-2024 including ISO/IEC 9899:2018 ("ISO C17"),
_XOPEN_SOURCE defined | p1003.1-90 with XPG Extensions to susv1 including ansiC.
However, FreeBSD implements this as a NOP because too much software breaks with the correct strict environment.
_XOPEN_SOURCE = 500 | p1003.1c-95 and XPG extensions to susv2 including ansiC
_XOPEN_SOURCE = 600 | p1003.1-2001 and XPG extensions to susv3 including isoC-99
_XOPEN_SOURCE = 700 | p1003.1-2008 and XPG extensions to susv4 including isoC-99
_XOPEN_SOURCE = 800 | p1003.1-2024 and XPG extensions to Version 5 of the Single UNIX Specification (“SUSv5”) including ISO/IEC 9899:2018 (“ISO C17”)
_ANSI_SOURCE | ansiC
_C99_SOURCE | isoC-99
_C11_SOURCE | isoC-2011
_C23_SOURCE | isoC-2023
_BSD_SOURCE | Everything, including FreeBSD extensions

Note: p1003.1-2024 and XPG extensions to Version 5 of the Single UNIX Specification ("SUSv5") support is incomplete.

When both POSIX and C environments are selected, the POSIX environment selects which C environment is used. However, when C11 dialect is selected with p1003.1-2008, definitions for isoC-2011 are also included. Likewise, when C23 dialog is selected with p1003.1-2008 or p1003.1-2024, definitions for isoC-2023 are also included.

  Header Visibility Macros
These macros are set by cdefs to control the visibility of different standards. Users must not define these, and doing so will produced undefined results. They are documented here for developers working on system's header files.
__XSI_VISIBLE | Restricts the visibility of XOPEN Single Unix Standard version.
Possible values are 500, 600, 700 or 800, corresponding to Issue 5, 6, 7, or 8 of the Single Unix Standard. These are extra functions in addition to the normal POSIX ones.
__POSIX_VISIBLE | Make symbols associated with certain standards versions visible.
Set to the value assigned to _POSIX_C_SOURCE by convention with 199009 for p1003.1-88 and 199209 p1003.1-90.
__ISO_C_VISIBLE | The C level that's visible.
Possible values include 1990, 1999, 2011, 2017 and 2023 for isoC-90, isoC-99, isoC-2011, ISO/IEC 9899:2018 ("ISO C17"), and isoC-2023, respectively.
__BSD_VISIBLE | 1 if the
FreeBSD extensions are visible, 0 otherwise.
__EXT1_VISIBLE | 1 if the
isoC-2011 Appendix K 3.7.4.1 extensions are visible, 0 otherwise.

Supported C++ Environments
FreeBSD supports C++11 and newer standards fully.

ISO/IEC 14882:1998 ("C++98")
    __cplusplus = 199711

    The first standardized version of C++. Unlike K R support in C, compilers dropped support for versions of the language prior to C++98.

ISO/IEC 14882:2003 ("C++03")
    __cplusplus = 199711

    Note, this is the same value as C++98. C++03 did not define a new value for __cplusplus. There is no way, at compile time, to detect the difference. The standard resolved a number of defect reports and slightly expanded value initialization. Most compilers support it the same as C++98.

ISO/IEC 14882:2011 ("C++11")
    __cplusplus = 201103

ISO/IEC 14882:2014 ("C++14")
    __cplusplus = 201402

ISO/IEC 14882:2017 ("C++17")
    __cplusplus = 201703

ISO/IEC 14882:2020 ("C++20")
    __cplusplus = 202002

ISO/IEC 14882:2023 ("C++23")
    __cplusplus = 202302

FreeBSD uses llvm project's libc++. However, they are removing support for C++ prior to C++11. While programs can still build with earlier environments for now, these changes mean that -pedantic-errors cannot be reliably enabled for standards older than C++11.

HISTORY
<sys/cdefs.h> first appeared in 4.3BSD NET/2.