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 porta- bility, 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 in- crease portability of compiled programs. These are to allow more ad- vanced 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 lan- guage dialects. General Macros General macros that facilitate multiple language environments and lan- guage 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 Do not have space between structure elements for natural alignment. Used when communicating with ex- ternal 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 func- tions. __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]]" at- tribute. 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++, us- ing an assignment to std::ignore. If applied to a struct, C++ class or enum, this applies to all func- tions returning values of that type. If applied to a C++ constructor, this applies to creating in- stances 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 im- proved 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 im- proved 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 ex- cept 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 de- bugging 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 incorpo- rated 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 compi- lation 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_SUPPORTEDVariables 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 con- trol 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 dep- recated or removed in . Compilers make compiling in this mode increasingly difficult and support for it may ultimately be re- moved 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 fea- tures, only made minor, technical corrections. __STDC_VERSION__ = 202311L Strict environment selected with _C23_SOURCE though ISO C23 support is only partially imple- mented. 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) de- fined by the appropriate standard, while suppressing all extensions. However, system headers not defined by that standard may define exten- sions. 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 = 202405 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 software breaks with the cor- rect 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 = 800 and XPG extensions to Version 5 of the Single UNIX Specification (SUSv5) including ISO/IEC 9899:2018 (ISO C17) _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 _BSD_SOURCE Everything, including FreeBSD extensions Note: 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 se- lected 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 , definitions for 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 un- defined 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 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 , respectively. __BSD_VISIBLE 1 if the FreeBSD extensions are visible, 0 other- wise. __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 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. 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>