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 - Compilers supported for building FreeBSD itself:
-
Compiler Major Versions Supported gcc 12, 13, 14 clang 16, 17, 18
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, |
| __inline | expands to inline in C++ and C89 and newer environments, |
| __restrict | expands to restrict in C99 and newer environments, or |
| __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. |
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 | Variable may be unused (usually arguments), so do not |
| __maybe_unused | Variable may be unused (usually arguments), so do not |
| __used | Function really is used, so emit it even if it appears unused. |
| __deprecated | Function interface has been deprecated, and clients |
| __deprecated1(msg) | Function interface has been deprecated, and clients |
| __packed | Do not have space between structure elements for natural alignment. |
| __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. |
| __alloc_size(x) | The function always returns at least the number of |
| __alloc_size2(x,n) | The function always returns an array, whose size |
| __alloc_align(x) | Function either returns a pointer aligned to x, bytes |
| __min_size | Declare the array to have a certain, minimum size |
| __malloc_like | Function behaves like the |
| __pure | Function has no side effects |
| __always_inline | Always inline this function when called |
| __fastcall | Use the |
| __result_use_check | Warn if function caller does not use its return value |
| __nodiscard | Equivalent to the standard |
| __returns_twice | Returns multiple times, like |
| __unreachable | This code is not reachable at runtime |
| __predict_true(x) | Hint to the compiler that |
| __predict_false(x) | Hint to the compiler that |
| __null_sentinel | The varadic function contains a parameter that is |
| __exported | |
| __hidden | |
| __printflike(fmtarg,firstvararg) | Function is similar to |
| __scanflike(fmtarg,firstvararg) | Function is similar to |
| __format_arg(f) | Specifies that arg |
| __strfmonlike(fmtarg,firstvararg) | Function is similar to |
| __strtimelike(fmtarg,firstvararg) | Function is similar to |
| __printf0like(fmtarg,firstvararg) | Exactly the same |
| __nonstring | Specify that an array of |
| __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 |
| _Static_assert(x, y) | Compile time assertion that |
| _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 |
| __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 ISO/IEC 9899:2024 (“ISO C23”). Compilers make compiling in this mode increasingly difficult and support for it may ultimately be removed from the tree.
- ANSI X3.159-1989 (“ANSI C89”)
-
__STDC__ is defined, however __STDC_VERSION__ is not.
Strict environment selected with _ANSI_SOURCE.
- ISO/IEC 9899:1999 (“ISO C99”)
-
__STDC_VERSION__ = 199901L
Strict environment selected with _C99_SOURCE.
- ISO/IEC 9899:2011 (“ISO C11”)
-
__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.
- ISO/IEC 9899:2024 (“ISO C23”)
-
__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 | IEEE Std 1003.1-1988 (“POSIX.1”) ANSI X3.159-1989 (“ANSI C89”) |
| _POSIX_C_SOURCE = 1 | IEEE Std 1003.1-1988 (“POSIX.1”) ANSI X3.159-1989 (“ANSI C89”) |
| _POSIX_C_SOURCE = 2 | ISO/IEC 9945-1:1990 (“POSIX.1”) ANSI X3.159-1989 (“ANSI C89”) |
| _POSIX_C_SOURCE = 199309 | IEEE Std 1003.1b-1993 (“POSIX.1b”) ANSI X3.159-1989 (“ANSI C89”) |
| _POSIX_C_SOURCE = 199506 | IEEE Std 1003.1c-1995 (“POSIX.1c”) ANSI X3.159-1989 (“ANSI C89”) |
| _POSIX_C_SOURCE = 200112 | IEEE Std 1003.1-2001 (“POSIX.1”) ISO/IEC 9899:1999 (“ISO C99”) |
| _POSIX_C_SOURCE = 200809 | IEEE Std 1003.1-2008 (“POSIX.1”) ISO/IEC 9899:1999 (“ISO C99”) |
| _POSIX_C_SOURCE = 202405 | IEEE Std 1003.1-2024 (“POSIX.1”) |
| _XOPEN_SOURCE defined | ISO/IEC 9945-1:1990 (“POSIX.1”) Version 1 of the Single UNIX Specification (“SUSv1”) ANSI X3.159-1989 (“ANSI C89”). |
| _XOPEN_SOURCE = 500 | IEEE Std 1003.1c-1995 (“POSIX.1c”) Version 2 of the Single UNIX Specification (“SUSv2”) ANSI X3.159-1989 (“ANSI C89”) |
| _XOPEN_SOURCE = 600 | IEEE Std 1003.1-2001 (“POSIX.1”) Version 3 of the Single UNIX Specification (“SUSv3”) ISO/IEC 9899:1999 (“ISO C99”) |
| _XOPEN_SOURCE = 700 | IEEE Std 1003.1-2008 (“POSIX.1”) Version 4 of the Single UNIX Specification (“SUSv4”) ISO/IEC 9899:1999 (“ISO C99”) |
| _XOPEN_SOURCE = 800 | IEEE Std 1003.1-2024 (“POSIX.1”) |
| _ANSI_SOURCE | ANSI X3.159-1989 (“ANSI C89”) |
| _C99_SOURCE | ISO/IEC 9899:1999 (“ISO C99”) |
| _C11_SOURCE | ISO/IEC 9899:2011 (“ISO C11”) |
| _C23_SOURCE | ISO/IEC 9899:2024 (“ISO C23”) |
| _BSD_SOURCE | Everything, including FreeBSD extensions |
Note: IEEE Std 1003.1-2024 (“POSIX.1”) 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 IEEE Std 1003.1-2008 (“POSIX.1”), definitions for ISO/IEC 9899:2011 (“ISO C11”) are also included. Likewise, when C23 dialog is selected with IEEE Std 1003.1-2008 (“POSIX.1”) or IEEE Std 1003.1-2024 (“POSIX.1”), definitions for ISO/IEC 9899:2024 (“ISO C23”) 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. |
| __POSIX_VISIBLE | Make symbols associated with certain standards versions visible. |
| __ISO_C_VISIBLE | The C level that's visible. |
| __BSD_VISIBLE | 1 if the |
| __EXT1_VISIBLE | 1 if the |
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.