1.\"- 2.\" Copyright (c) 2024 M. Warner Losh <imp@FreeBSD.org> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd May 9, 2025 7.Dt CDEFS 9 8.Os 9.Sh NAME 10.Nm cdefs 11.Nd compiler portability macro definitions 12.Sh DESCRIPTION 13.In sys/cdefs.h 14defines macros for compiler, C language standard portability, POSIX standards 15compliance and symbol visibility. 16It defines programming interfaces for the system header files to adopt to the 17many environments 18.Fx 19supports compilation for. 20It defines convenience macros for the 21.Fx 22sources, tailored to the base 23system's needs. 24.Pp 25Most of these macros are for use inside the 26.Fx 27sources only. 28They are not intended as a general portability layer. 29.Sh Supported Compilers 30.Bl -tag -offset 2n -width 0 31.It Compilers supported for building programs on Fx : 32.Bl -column -offset 0n indent-two 33.It Sy Compiler Ta Sy Versions 34.It gcc Ta 9, 10, 11, 12, 13, 14 35.It clang Ta 10, 11, 12, 13, 14, 15, 16, 17, 18 36.It TinyC (tcc) Ta 0.9 37.It pcc Ta 1.1 38.El 39.Pp 40Due to testing constraints, tcc and pcc may not always work. 41.It Compilers supported for building Fx itself: 42.Bl -column -offset 0n indent-two 43.It Sy Compiler Ta Sy Major Versions Supported 44.It gcc Ta 12, 13, 14 45.It clang Ta 16, 17, 18 46.El 47.Pp 48Please note: Not every single minor versions of these compilers 49will work or are supported. 50.El 51.Sh Macros and Magic for Programming Environment 52.Nm 53defines (or refrains from defining) a number of macros to increase portability 54of compiled programs. 55These are to allow more advanced language features to appear in header files. 56The header files assume a compiler that accepts C prototype function 57declarations. 58They also assume that the compiler accepts ANSI C89 keywords for all language 59dialects. 60.Ss General Macros 61General macros that facilitate multiple language environments and language 62dialects. 63.Bl -column "---------------" 64.It Sy Macro Ta Sy Description 65.It Dv __volatile Ta expands to volatile in C++ and C89 and newer environments, 66__volatile in pre-ANSI environments that support this extension or nothing 67otherwise. 68.It Dv __inline Ta expands to inline in C++ and C89 and newer environments, 69__inline in pre-ANSI environments that support this extension or nothing 70otherwise. 71.It Dv __restrict Ta expands to restrict in C99 and newer environments, or 72__restrict otherwise. 73.It Dv __CONCAT Ta used to paste two pre-processor tokens. 74.It Dv __STRING Ta used to convert the argument to a string. 75.It Dv __BEGIN_DECLS Ta Start a group of functions. 76.It Dv __END_DECLS Ta End a group of functions. 77In a C environment, these are defined as nothing. 78In a C++ environment, these declare the functions to have 79.Dq C 80linkage. 81.El 82.Ss Function, Structure and Variable Modifiers 83.Bl -column "---------------" 84.It Sy Macro Ta Sy Description 85.It Sy __weak_symbol Ta Declare the symbol to be a weak symbol 86.It Sy __dead2 Ta Function will not return 87.It Sy __pure2 Ta Function has no side effects 88.It Sy __unused Ta To Variable may be unused (usually arguments), so do not 89warn about it 90.It Sy __used Ta Function really is used, so emit it even if it appears unused. 91.It Sy __deprecated Ta Function interface has been deprecated, and clients 92should migrate to a new interface. 93A warning will be issued for clients of this interface. 94.It Sy __deprecated1(msg) Ta Function interface has been deprecated, and clients 95should migrate to a new interface. 96The string 97.Fa msg 98will be included in a warning issued for clients of this interface. 99.It Sy __packed Ta \&Do not have space between structure elements for natural alignment. 100Used when communicating with external protocols. 101.It Sy __aligned(x) Ta Specify in bytes the minimum alignment for the specified field, structure or variable 102.It Sy __section(x) Ta Place function or variable in section Fa x 103.It Sy __writeonly Ta Hint that the variable is only assigned to, but do not warn about it. 104Useful for macros and other places the eventual use of the result is unknown. 105.It Sy __alloc_size(x) Ta The function always returns at least the number of 106bytes determined by argument number Fa x 107.It Sy __alloc_size2(x,n) Ta The function always returns an array, whose size 108is at least the number of bytes determined by argument number Fa x times the 109number of elements specified by argument number Fa n 110.It Sy __alloc_align(x) Ta Function either returns a pointer aligned to Fa x bytes 111or Dv NULL. 112.It Sy __min_size Ta Declare the array to have a certain, minimum size 113.It Sy __malloc_like Ta Function behaves like the 114.Dq malloc 115family of functions. 116.It Sy __pure Ta Function has no side effects 117.It Sy __always_inline Ta Always inline this function when called 118.It Sy __fastcall Ta Use the 119.Dq fastcall 120ABI to call and name mangle this function. 121.It Sy __result_use_check Ta Warn if function caller does not use its return value 122.It Sy __nodiscard Ta Equivalent to the standard 123.Dq [[nodiscard]] 124attribute. 125If applied to a function, warn if function caller does not use its 126return value. 127The warning may be silenced using a cast to 128.Vt void , 129or in C++, using an assignment to 130.Va std::ignore . 131If applied to a struct, C++ class or enum, this applies to all functions 132returning values of that type. 133If applied to a C++ constructor, this applies to creating instances of 134the class using that constructor. 135.It Sy __returns_twice Ta Returns multiple times, like 136.Xr fork 2 137.It Sy __unreachable Ta This code is not reachable at runtime 138.It Sy __predict_true(x) Ta Hint to the compiler that 139.Fa x 140is true most of the time. 141Should only be used when performance is improved for a frequently called bit of code. 142.It Sy __predict_false(x) Ta Hint to the compiler that 143.Fa x 144is false most of the time. 145Should only be used when performance is improved for a frequently called bit of code. 146.It Sy __null_sentinel Ta The varadic function contains a parameter that is 147a NULL sentinel to mark the end of its arguments. 148.It Sy __exported Ta 149.It Sy __hidden Ta 150.It Sy __printflike(fmtarg,firstvararg) Ta Function is similar to 151.Fn printf 152which specifies the format argument with 153.Fa fmtarg 154and where the arguments formatted by that format start with the 155.Fa firstvararg , 156with 0 meaning that 157.Dv va_arg 158is used and cannot be checked. 159.It Sy __scanflike(fmtarg,firstvararg) Ta Function is similar to 160.Fn scanf 161which specifies the format argument with 162.Fa fmtarg 163and where the arguments formatted by that format start with the 164.Fa firstvararg , 165with 0 meaning that 166.Dv va_arg 167is used and cannot be checked. 168.It Sy __format_arg(f) Ta Specifies that arg 169.Fa f 170contains a string that will be passed to a function like 171.Fn printf 172or 173.Fa scanf 174after being translated in some way. 175.It Sy __strfmonlike(fmtarg,firstvararg) Ta Function is similar to 176.Fn scanf 177which specifies the format argument with 178.Fa fmtarg 179and where the arguments formatted by that format start with the 180.Fa firstvararg , 181with 0 meaning that 182.Dv va_arg 183is used and cannot be checked. 184.It Sy __strtimelike(fmtarg,firstvararg) Ta Function is similar to 185.Fn scanf 186which specifies the format argument with 187.Fa fmtarg 188and where the arguments formatted by that format start with the 189.Fa firstvararg , 190with 0 meaning that 191.Dv va_arg 192is used and cannot be checked. 193.It Sy __printf0like(fmtarg,firstvararg) Ta Exactly the same 194as 195.Sy __printflike 196except 197.Fa fmtarg 198may be 199.Dv NULL. 200.It Sy __strong_reference(sym,aliassym) Ta 201.It Sy __weak_reference(sym,alias) Ta 202.It Sy __warn_references(sym,msg) Ta 203.It Sy __sym_compat(sym,impl,verid) Ta 204.It Sy __sym_default(sym,impl,verid) Ta 205.It Sy __GLOBAL(sym) Ta 206.It Sy __WEAK(sym) Ta 207.It Sy __DECONST(type,var) Ta 208.It Sy __DEVOLATILE(type,var) Ta 209.It Sy __DEQUALIFY(type,var) Ta 210.It Sy __RENAME(x) Ta 211.It Sy __arg_type_tag Ta 212.It Sy __datatype_type_tag Ta 213.It Sy __align_up(x,y) Ta 214.It Sy __align_down(x,y) Ta 215.It Sy __is_aligned(x,y) Ta 216.El 217.Ss Locking and Debugging Macros 218Macros for lock annotation and debugging, as well as some general debugging 219macros for address sanitizers. 220.Bl -column "---------------" 221.It Sy __lock_annotate(x) Ta 222.It Sy __lockable Ta 223.It Sy __locks_exclusive Ta 224.It Sy __locks_shared Ta 225.It Sy __trylocks_exclusive Ta 226.It Sy __trylocks_shared Ta 227.It Sy __unlocks Ta 228.It Sy __asserts_exclusive Ta 229.It Sy __asserts_shared Ta 230.It Sy __requires_exclusive Ta 231.It Sy __requires_shared Ta 232.It Sy __requires_unlocked Ta 233.It Sy __no_lock_analysis Ta 234.It Sy __nosanitizeaddress Ta 235.It Sy __nosanitizememory Ta 236.It Sy __nosanitizethread Ta 237.It Sy __nostackprotector Ta 238.It Sy __guarded_by(x) Ta 239.It Sy __pt_guarded_by(x) Ta 240.El 241.Ss Emulated Keywords 242As C evolves, many of the old macros we once used have been incorporated into 243the standard language. 244As this happens, we add support for these keywords as macros for older 245compilation environments. 246Sometimes this results in a nop in the older environment. 247.Bl -column "---------------" 248.It Sy Keyword Ta Sy Description 249.It Sy _Alignas(x) Ta 250.It Sy _Alignof(x) Ta 251.It Sy _Noreturn Ta Expands to 252.Dq [[noreturn]] 253in C++-11 and newer compilation environments, otherwise 254.Dq __dead2 255.It Sy _Static_assert(x, y) Ta Compile time assertion that 256.Fa x 257is true, otherwise emit 258.Fa y 259as the error message. 260.It Sy _Thread_local Ta Designate variable as thread local storage 261.It Sy __generic Ta implement _Generic-like features which aren't entirely possible to emulate the _Generic keyword 262.It Sy __noexcept Ta to emulate the C++11 argument-less noexcept form 263.It Sy __noexcept_if Ta to emulate the C++11 conditional noexcept form 264.It Sy _Nonnull Ta 265.It Sy _Nullable Ta 266.It Sy _Null_unspecified Ta 267.El 268.Ss Support Macros 269The following macros are defined, or have specific values, to denote certain 270things about the build environment. 271.Bl -column "---------------" 272.It Sy Macro Ta Sy Description 273.It Sy __LONG_LONG_SUPPORTED Ta Variables may be declared 274.Dq long long . 275This is defined for C99 or newer and C++ environments. 276.It Sy __STDC_LIMIT_MACROS Ta 277.It Sy __STDC_CONSTANT_MACROS Ta 278.El 279.Ss Convenience Macros 280These macros make it easier to do a number of things, even though strictly 281speaking the standard places their normal form in another header. 282.Bl -column "---------------" 283.It Sy Macro Ta Sy Description 284.It Sy __offsetof(type,field) Ta 285.It Sy __rangeof(type,start,end) Ta 286.It Sy __containerof(x,s,m) Ta 287.El 288.Ss ID Strings 289This section is deprecated, but is kept around because too much contrib software 290still uses these. 291.Bl -column "---------------" 292.It Sy Macro Ta Sy Description 293.It Sy __IDSTRING(name,string) Ta 294.It Sy __FBSDID(s) Ta 295.It Sy __RCSID(s) Ta 296.It Sy __RCSID_SOURCE(s) Ta 297.It Sy __SCCSID(s) Ta 298.It Sy __COPYRIGHT(s) Ta 299.El 300.Sh Supported C Environments 301.Fx 302supports a number C standard environments. 303Selection of the language dialect is a compiler-dependent command line option, 304though it is usually 305.Fl std=XX 306where XX is the standard to set for compiling, such as c89 or c23. 307.Fx 308provides a number of selection macros to control visibility of symbols. 309Please see the section on Selection Macros for the specifics. 310.Pp 311.Bl -tag 312.It K \*(Am R 313Pre-ANSI Kernighan and Ritchie C. 314Sometimes called 315.Dq knr 316or 317.Dq C78 318to distinguish it from newer standards. 319Support for this compilation environment is dependent on compilers supporting 320this configuration. 321Most of the old forms of C have been deprecated or removed in 322.St -isoC-2023 . 323Compilers make compiling in this mode increasingly difficult and support for it 324may ultimately be removed from the tree. 325.It St -ansiC 326.Dv __STDC__ 327is defined, however 328.Dv __STDC_VERSION__ 329is not. 330.Pp 331Strict environment selected with 332.Dv _ANSI_SOURCE . 333.It St -isoC-99 334.Dv __STDC_VERSION__ = 199901L 335.Pp 336Strict environment selected with 337.Dv _C99_SOURCE . 338.It St -isoC-2011 339.Dv __STDC_VERSION__ = 201112L 340.Pp 341Strict environment selected with 342.Dv _C11_SOURCE . 343.It ISO/IEC 9899:2018 (“ISO C17”) 344.Dv __STDC_VERSION__ = 201710L 345.Pp 346Strict environment selected with 347.Dv _C11_SOURCE 348since there are no new C17 only symbols or macros. 349.Pp 350This version of the standard did not introduce any new features, only made 351minor, technical corrections. 352.It St -isoC-2023 353.Dv __STDC_VERSION__ = 202311L 354Strict environment selected with 355.Dv _C23_SOURCE 356though ISO C23 support is only partially implemented. 357.El 358.Pp 359For more information on C standards, see 360.Xr c 7 . 361.Ss Programming Environment Selection Macros 362Defining the macros outlined below requests that the system header files provide 363only the functions, structures and macros (symbols) defined by the appropriate 364standard, while suppressing all extensions. 365However, system headers not defined by that standard may define extensions. 366You may only define one of the following for any compilation unit. 367.Bl -column "---------------" 368.It Sy Macro Ta Sy Environment 369.It Dv _POSIX_SOURCE Ta St -p1003.1-88 including St -ansiC 370.It Dv _POSIX_C_SOURCE = 1 Ta St -p1003.1-88 including St -ansiC 371.It Dv _POSIX_C_SOURCE = 2 Ta St -p1003.1-90 including St -ansiC 372.It Dv _POSIX_C_SOURCE = 199309 Ta St -p1003.1b-93 including St -ansiC 373.It Dv _POSIX_C_SOURCE = 199506 Ta St -p1003.1c-95 including St -ansiC 374.It Dv _POSIX_C_SOURCE = 200112 Ta St -p1003.1-2001 including St -isoC-99 375.It Dv _POSIX_C_SOURCE = 200809 Ta St -p1003.1-2008 including St -isoC-99 376.It Dv _POSIX_C_SOURCE = 202405 Ta St -p1003.1-2024 including ISO/IEC 9899:2018 ("ISO C17"), 377.It Dv _XOPEN_SOURCE defined Ta St -p1003.1-90 with XPG Extensions to St -susv1 including St -ansiC . 378However, 379.Fx 380implements this as a NOP because too much software breaks with the correct strict environment. 381.It Dv _XOPEN_SOURCE = 500 Ta St -p1003.1c-95 and XPG extensions to St -susv2 including St -ansiC 382.It Dv _XOPEN_SOURCE = 600 Ta St -p1003.1-2001 and XPG extensions to St -susv3 including St -isoC-99 383.It Dv _XOPEN_SOURCE = 700 Ta St -p1003.1-2008 and XPG extensions to St -susv4 including St -isoC-99 384.It Dv _XOPEN_SOURCE = 800 Ta St -p1003.1-2024 and XPG extensions to Version 5 of the Single UNIX Specification (“SUSv5”) including ISO/IEC 9899:2018 (“ISO C17”) 385.It Dv _ANSI_SOURCE Ta St -ansiC 386.It Dv _C99_SOURCE Ta St -isoC-99 387.It Dv _C11_SOURCE Ta St -isoC-2011 388.It Dv _C23_SOURCE Ta St -isoC-2023 389.It Dv _BSD_SOURCE Ta Everything, including Fx extensions 390.El 391.Pp 392Note: 393.St -p1003.1-2024 394and XPG extensions to Version 5 of the Single UNIX Specification ("SUSv5") 395support is incomplete. 396.Pp 397When both POSIX and C environments are selected, the POSIX environment selects 398which C environment is used. 399However, when C11 dialect is selected with 400.St -p1003.1-2008 , 401definitions for 402.St -isoC-2011 403are also included. 404Likewise, when C23 dialog is selected with 405.St -p1003.1-2008 406or 407.St -p1003.1-2024 , 408definitions for 409.St -isoC-2023 410are also included. 411.Ss Header Visibility Macros 412These macros are set by 413.Nm 414to control the visibility of different standards. 415Users must not define these, and doing so will produced undefined results. 416They are documented here for developers working on system's header files. 417.Bl -column "---------------" 418.It Dv __XSI_VISIBLE Ta Restricts the visibility of XOPEN Single Unix Standard version. 419Possible values are 500, 600, 700 or 800, corresponding to Issue 5, 6, 7, or 8 420of the Single Unix Standard. 421These are extra functions in addition to the normal POSIX ones. 422.It Dv __POSIX_VISIBLE Ta Make symbols associated with certain standards versions visible. 423Set to the value assigned to 424.Dv _POSIX_C_SOURCE 425by convention with 199009 for 426.St -p1003.1-88 427and 199209 428.St -p1003.1-90 . 429.It Dv __ISO_C_VISIBLE Ta The C level that's visible. 430Possible values include 1990, 1999, 2011, 2017 and 2023 for 431.St -isoC-90 , 432.St -isoC-99 , 433.St -isoC-2011 , 434ISO/IEC 9899:2018 ("ISO C17"), and 435.St -isoC-2023 , 436respectively. 437.It Dv __BSD_VISIBLE Ta 1 if the 438.Fx 439extensions are visible, 0 otherwise. 440.It Dv __EXT1_VISIBLE Ta 1 if the 441.St -isoC-2011 442Appendix K 3.7.4.1 443extensions are visible, 0 otherwise. 444.El 445.Sh Supported C++ Environments 446.Fx 447supports C++11 and newer standards fully. 448.Bl -tag 449.It ISO/IEC 14882:1998 ("C++98") 450.Dv __cplusplus = 199711 451.Pp 452The first standardized version of C++. 453Unlike K \*(Am R support in C, compilers dropped support for versions of 454the language prior to C++98. 455.It ISO/IEC 14882:2003 ("C++03") 456.Dv __cplusplus = 199711 457.Pp 458Note, this is the same value as C++98. 459C++03 did not define a new value for 460.Dv __cplusplus . 461There is no way, at compile time, to detect the difference. 462The standard resolved a number of defect reports and slightly 463expanded value initialization. 464Most compilers support it the same as C++98. 465.It ISO/IEC 14882:2011 ("C++11") 466.Dv __cplusplus = 201103 467.It ISO/IEC 14882:2014 ("C++14") 468.Dv __cplusplus = 201402 469.It ISO/IEC 14882:2017 ("C++17") 470.Dv __cplusplus = 201703 471.It ISO/IEC 14882:2020 ("C++20") 472.Dv __cplusplus = 202002 473.It ISO/IEC 14882:2023 ("C++23") 474.Dv __cplusplus = 202302 475.El 476.Pp 477.Fx 478uses llvm project's libc++. 479However, they are removing support for C++ prior to C++11. 480While programs can still build with earlier environments for now, these changes 481mean that 482.Fl pedantic-errors 483cannot be reliably enabled for standards older than C++11. 484.Sh HISTORY 485.In sys/cdefs.h 486first appeared in 487.Bx 4.3 NET/2 . 488