CDEFS(9)

📦 version 15.1, in freebsd 15.1, nixpkgs unstable

CDEFS(9) — compiler portability macro definitions 💅

okay so real talk: this is the CDEFS(9) page from the Kernel Developer's Manual, and it's basically the group chat of <sys/cdefs.h>. bestie, this header is doing so much — compiler portability, C language standard portability, POSIX standards compliance, symbol visibility, all of it. it defines the programming interfaces that system header files use to adapt to the many environments FreeBSD supports compilation for, and it also defines convenience macros for the FreeBSD sources, tailored to the base system's needs. ✨

🫶 heads up bestie: most of these macros are for use inside the FreeBSD sources only. they are not intended as a general portability layer, no cap.

Supported Compilers 🧚

compilers we support for building programs on FreeBSD

  • gcc — versions 9, 10, 11, 12, 13, 14
  • clang — versions 10, 11, 12, 13, 14, 15, 16, 17, 18
  • TinyC (tcc) — version 0.9
  • pcc — version 1.1
😭 okay so due to testing constraints, tcc and pcc may not always work. they're on the list, they just might ghost you on a bad day.

compilers we support for building FreeBSD itself

  • gcc — major versions 12, 13, 14
  • clang — major versions 16, 17, 18
💀 please note: not every single minor version of these compilers will work or is supported. iykyk.

Macros and Magic for Programming Environment 🎀

cdefs defines (or refrains from defining, king of boundaries) a number of macros to increase portability of compiled programs. the whole point is letting more advanced language features show up in header files. these header files assume a compiler that accepts C prototype function declarations, and they also assume the compiler accepts ANSI C89 keywords for all language dialects. periodt.

General Macros ✨

general macros that facilitate multiple language environments and language dialects.

  • __volatile — expands to volatile in C++ and C89 and newer environments, to __volatile in pre-ANSI environments that support this extension, or nothing otherwise.
  • __inline — expands to inline in C++ and C89 and newer environments, to __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 💅

  • __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 don't 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 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 don't warn about it. useful for macros and other places where 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 x.
  • __alloc_size2(x,n) — the function always returns an array, whose size is at least the number of bytes determined by argument number x times the number of elements specified by argument number n.
  • __alloc_align(x) — function either returns a pointer aligned to x bytes or 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 — (no description on this page, it's just sitting here being iconic)
  • __hidden — (no description on this page either, lowkey mysterious 🕵️)
  • __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) — (no description on this page)
  • __weak_reference(sym,alias) — (no description on this page)
  • __warn_references(sym,msg) — (no description on this page)
  • __sym_compat(sym,impl,verid) — (no description on this page)
  • __sym_default(sym,impl,verid) — (no description on this page)
  • __GLOBAL(sym) — (no description on this page)
  • __WEAK(sym) — (no description on this page)
  • __DECONST(type,var) — (no description on this page)
  • __DEVOLATILE(type,var) — (no description on this page)
  • __DEQUALIFY(type,var) — (no description on this page)
  • __RENAME(x) — (no description on this page)
  • __arg_type_tag — (no description on this page)
  • __datatype_type_tag — (no description on this page)
  • __align_up(x,y) — (no description on this page)
  • __align_down(x,y) — (no description on this page)
  • __is_aligned(x,y) — (no description on this page)

Locking and Debugging Macros 🔥

macros for lock annotation and debugging, plus some general debugging macros for address sanitizers. ngl this section is a whole mood board of names with no descriptions attached on this page, so here they all are, verbatim and unbothered:

  • __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 — cute, harmless, slaying nothing. 💫

  • _Alignas(x) — (no description on this page)
  • _Alignof(x) — (no description on this page)
  • _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 — (no description on this page)
  • _Nullable — (no description on this page)
  • _Null_unspecified — (no description on this page)

Support Macros 🦋

the following macros are defined, or have specific values, to denote certain things about the build environment.

  • __LONG_LONG_SUPPORTED — variables may be declared “long long”. this is defined for C99 or newer and C++ environments.
  • __STDC_LIMIT_MACROS — (no description on this page)
  • __STDC_CONSTANT_MACROS — (no description on this page)

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. so convenient, so thoughtful, we stan. 💖

  • __offsetof(type,field) — (no description on this page)
  • __rangeof(type,start,end) — (no description on this page)
  • __containerof(x,s,m) — (no description on this page)

ID Strings 👑

🙈 this section is deprecated, but it's kept around because too much contrib software still uses these. yes it's giving legacy, but we don't abandon our friends.
  • __IDSTRING(name,string) — (no description on this page)
  • __FBSDID(s) — (no description on this page)
  • __RCSID(s) — (no description on this page)
  • __RCSID_SOURCE(s) — (no description on this page)
  • __SCCSID(s) — (no description on this page)
  • __COPYRIGHT(s) — (no description on this page)

✨ Supported C Environments ✨

okay so FreeBSD supports a whole bunch of C standard environments, and bestie, picking which one is a compiler-dependent command line option — usually it's -std=XX where XX is the standard you're compiling for, like c89 or c23. FreeBSD also tosses you a bunch of selection macros to control symbol visibility. specifics go in the Selection Macros section, iykyk.

  • K & R — Pre-ANSI Kernighan and Ritchie C. Sometimes called "knr" or "C78" to tell it apart from the newer standards. Whether you can actually use this depends on your compiler supporting it. Most of the old forms of C have been deprecated or removed in . 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. 💅
  • __STDC_VERSION__ = 202311L Strict environment selected with _C23_SOURCE though ISO C23 support is only partially implemented. 🙈

For more info on C standards, go peep c(7).

🎀 Programming Environment Selection Macros 🎀

Defining the macros down 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. one. single. one. periodt.

  • _POSIX_SOURCE — IEEE Std 1003.1-1988 ("POSIX.1") including ANSI X3.159-1989 ("ANSI C89")
  • _POSIX_C_SOURCE = 1 — IEEE Std 1003.1-1988 ("POSIX.1") including ANSI X3.159-1989 ("ANSI C89")
  • _POSIX_C_SOURCE = 2 — ISO/IEC 9945-1:1990 ("POSIX.1") including ANSI X3.159-1989 ("ANSI C89")
  • _POSIX_C_SOURCE = 199309 — IEEE Std 1003.1b-1993 ("POSIX.1") including ANSI X3.159-1989 ("ANSI C89")
  • _POSIX_C_SOURCE = 199506 — IEEE Std 1003.1c-1995 ("POSIX.1") including ANSI X3.159-1989 ("ANSI C89")
  • _POSIX_C_SOURCE = 200112 — IEEE Std 1003.1-2001 ("POSIX.1") including ISO/IEC 9899:1999 ("ISO C99")
  • _POSIX_C_SOURCE = 200809 — IEEE 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 defined — ISO/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 correct strict environment. 😭 iconic behaviour tbh.
  • _XOPEN_SOURCE = 500 — IEEE 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 = 600 — IEEE 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 = 700 — IEEE 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. the whole buffet, no crumbs left behind 🍓
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 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 , 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 undefined results. They're documented here for developers working on system's header files. so like, look but don't touch, bestie 🫶

  • __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 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. slay.

  • 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. 😭 cannot believe they did that to us.
  • 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.

and that's the whole page bestie, you ate it 💅✨ this lil' edition is from Debian and it's dated May 9, 2025 — go forth and compile responsibly, mwah 🎀🦋💖

📦 where this page comes from