FreeBSD Manual Pages
CDEFS(9) Kernel Developer's Manual 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 lan- guage features to appear in header files. The header files assume a com- piler 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 ex- tension 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 in- terface. __packed Do not have space between structure elements for natural alignment. Used when communicating with external proto- cols. __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 spec- ifies the format argument with fmtarg and where the ar- guments formatted by that format start with the firstvararg, with 0 meaning that va_arg is used and can- not be checked. __scanflike(fmtarg,firstvararg)Function is similar to scanf() which speci- fies the format argument with fmtarg and where the argu- ments formatted by that format start with the firstvararg, with 0 meaning that va_arg is used and can- not 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 spec- ifies the format argument with fmtarg and where the ar- guments formatted by that format start with the firstvararg, with 0 meaning that va_arg is used and can- not be checked. __strtimelike(fmtarg,firstvararg)Function is similar to scanf() which spec- ifies the format argument with fmtarg and where the ar- guments formatted by that format start with the firstvararg, with 0 meaning that va_arg is used and can- not 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 key- words 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 compila- tion 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 cer- tain things about the build environment. Macro Description __LONG_LONG_SUPPORTEDVariables may be declared "long long". This is de- fined 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 lan- guage 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 visibil- ity 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 compila- tion environment is dependent on compilers supporting this configu- ration. 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 (aISO C17a) __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") including ANSI X3.159-1989 ("ANSI C89") _POSIX_C_SOURCE = 1IEEE Std 1003.1-1988 ("POSIX.1") including ANSI X3.159-1989 ("ANSI C89") _POSIX_C_SOURCE = 2ISO/IEC 9945-1:1990 ("POSIX.1") including ANSI X3.159-1989 ("ANSI C89") _POSIX_C_SOURCE = 199309IEEE Std 1003.1b-1993 ("POSIX.1") including ANSI X3.159-1989 ("ANSI C89") _POSIX_C_SOURCE = 199506IEEE Std 1003.1c-1995 ("POSIX.1") including ANSI X3.159-1989 ("ANSI C89") _POSIX_C_SOURCE = 200112IEEE Std 1003.1-2001 ("POSIX.1") including ISO/IEC 9899:1999 ("ISO C99") _POSIX_C_SOURCE = 200809IEEE Std 1003.1-2008 ("POSIX.1") including ISO/IEC 9899:1999 ("ISO C99") _POSIX_C_SOURCE = 202405IEEE Std 1003.1-2024 ("POSIX.1") including ISO/IEC 9899:2018 ("ISO C17"), _XOPEN_SOURCE definedISO/IEC 9945-1:1990 ("POSIX.1") with XPG Extensions to Version 1 of the Single UNIX Specification ("SUSv1") including ANSI X3.159-1989 ("ANSI C89"). However, FreeBSD implements this as a NOP because too much soft- ware breaks with the correct strict environment. _XOPEN_SOURCE = 500IEEE Std 1003.1c-1995 ("POSIX.1") and XPG extensions to Version 2 of the Single UNIX Specification ("SUSv2") including ANSI X3.159-1989 ("ANSI C89") _XOPEN_SOURCE = 600IEEE Std 1003.1-2001 ("POSIX.1") and XPG extensions to Version 3 of the Single UNIX Specification ("SUSv3") including ISO/IEC 9899:1999 ("ISO C99") _XOPEN_SOURCE = 700IEEE Std 1003.1-2008 ("POSIX.1") and XPG extensions to Version 4 of the Single UNIX Specification ("SUSv4") including ISO/IEC 9899:1999 ("ISO C99") _XOPEN_SOURCE = 800IEEE Std 1003.1-2024 ("POSIX.1") and XPG extensions to Version 5 of the Single UNIX Specification (aSUSv5a) including ISO/IEC 9899:2018 (aISO C17a) _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 se- lects 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"), defi- nitions 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 stan- dards. 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, cor- responding 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 IEEE Std 1003.1-1988 ("POSIX.1") and 199209 ISO/IEC 9945-1:1990 ("POSIX.1"). __ISO_C_VISIBLE The C level that's visible. Possible values include 1990, 1999, 2011, 2017 and 2023 for ISO/IEC 9899:1990 ("ISO C90"), ISO/IEC 9899:1999 ("ISO C99"), ISO/IEC 9899:2011 ("ISO C11"), ISO/IEC 9899:2018 ("ISO C17"), and ISO/IEC 9899:2024 ("ISO C23"), respectively. __BSD_VISIBLE 1 if the FreeBSD extensions are visible, 0 otherwise. __EXT1_VISIBLE 1 if the ISO/IEC 9899:2011 ("ISO C11") 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 environ- ments 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. FreeBSD ports 15.quarterly May 9, 2025 CDEFS(9)
NAME | DESCRIPTION | Supported Compilers | Macros and Magic for Programming Environment | Supported C Environments | Supported C++ Environments | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=cdefs&sektion=9&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>