1.\"- 2.\" Copyright (c) 2024 M. Warner Losh <imp@FreeBSD.org> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd July 20, 2024 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 __packed Ta \&Do not have space between structure elements for natural alignment. 95Used when communicating with external protocols. 96.It Sy __aligned(x) Ta Specify in bytes the minimum alignment for the specified field, structure or variable 97.It Sy __section(x) Ta Place function or variable in section Fa x 98.It Sy __writeonly Ta Hint that the variable is only assigned to, but do not warn about it. 99Useful for macros and other places the eventual use of the result is unknown. 100.It Sy __alloc_size(x) Ta The function always returns at least the number of 101bytes determined by argument number Fa x 102.It Sy __alloc_size2(x,n) Ta The function always returns an array, whose size 103is at least the number of bytes determined by argument number Fa x times the 104number of elements specified by argument number Fa n 105.It Sy __alloc_align(x) Ta Function either returns a pointer aligned to Fa x bytes 106or Dv NULL. 107.It Sy __min_size Ta Declare the array to have a certain, minimum size 108.It Sy __malloc_like Ta Function behaves like the 109.Dq malloc 110family of functions. 111.It Sy __pure Ta Function has no side effects 112.It Sy __always_inline Ta Always inline this function when called 113.It Sy __fastcall Ta Use the 114.Dq fastcall 115ABI to call and name mangle this function. 116.It Sy __result_use_check Ta Warn if function caller does not use it's return value 117.It Sy __result_use_or_ignore_check Ta Warn if function caller does not use it's return value. 118Allows the value to be explicitly ignored with a (void) cast. 119.It Sy __returns_twice Ta Returns multiple times, like 120.Xr fork 2 121.It Sy __unreachable Ta This code is not reachable at runtime 122.It Sy __predict_true(x) Ta Hint to the compiler that 123.Fa x 124is true most of the time. 125Should only be used when performance is improved for a frequently called bit of code. 126.It Sy __predict_false(x) Ta Hint to the compiler that 127.Fa x 128is false most of the time. 129Should only be used when performance is improved for a frequently called bit of code. 130.It Sy __null_sentinel Ta The varadic function contains a parameter that is 131a NULL sentinel to mark the end of its arguments. 132.It Sy __exported Ta 133.It Sy __hidden Ta 134.It Sy __printflike(fmtarg,firstvararg) Ta Function is similar to 135.Fn printf 136which specifies the format argument with 137.Fa fmtarg 138and where the arguments formatted by that format start with the 139.Fa firstvararg , 140with 0 meaning that 141.Dv va_arg 142is used and cannot be checked. 143.It Sy __scanflike(fmtarg,firstvararg) Ta Function is similar to 144.Fn scanf 145which specifies the format argument with 146.Fa fmtarg 147and where the arguments formatted by that format start with the 148.Fa firstvararg , 149with 0 meaning that 150.Dv va_arg 151is used and cannot be checked. 152.It Sy __format_arg(f) Ta Specifies that arg 153.Fa f 154contains a string that will be passed to a function like 155.Fn printf 156or 157.Fa scanf 158after being translated in some way. 159.It Sy __strfmonlike(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 __strtimelike(fmtarg,firstvararg) Ta Function is similar to 169.Fn scanf 170which specifies the format argument with 171.Fa fmtarg 172and where the arguments formatted by that format start with the 173.Fa firstvararg , 174with 0 meaning that 175.Dv va_arg 176is used and cannot be checked. 177.It Sy __printf0like(fmtarg,firstvararg) Ta Exactly the same 178as 179.Sy __printflike 180except 181.Fa fmtarg 182may be 183.Dv NULL. 184.It Sy __strong_reference(sym,aliassym) Ta 185.It Sy __weak_reference(sym,alias) Ta 186.It Sy __warn_references(sym,msg) Ta 187.It Sy __sym_compat(sym,impl,verid) Ta 188.It Sy __sym_default(sym,impl,verid) Ta 189.It Sy __GLOBAL(sym) Ta 190.It Sy __WEAK(sym) Ta 191.It Sy __DECONST(type,var) Ta 192.It Sy __DEVOLATILE(type,var) Ta 193.It Sy __DEQUALIFY(type,var) Ta 194.It Sy __RENAME(x) Ta 195.It Sy __arg_type_tag Ta 196.It Sy __datatype_type_tag Ta 197.It Sy __align_up(x,y) Ta 198.It Sy __align_down(x,y) Ta 199.It Sy __is_aligned(x,y) Ta 200.El 201.Ss Locking and Debugging Macros 202Macros for lock annotation and debugging, as well as some general debugging 203macros for address sanitizers. 204.Bl -column "---------------" 205.It Sy __lock_annotate(x) Ta 206.It Sy __lockable Ta 207.It Sy __locks_exclusive Ta 208.It Sy __locks_shared Ta 209.It Sy __trylocks_exclusive Ta 210.It Sy __trylocks_shared Ta 211.It Sy __unlocks Ta 212.It Sy __asserts_exclusive Ta 213.It Sy __asserts_shared Ta 214.It Sy __requires_exclusive Ta 215.It Sy __requires_shared Ta 216.It Sy __requires_unlocked Ta 217.It Sy __no_lock_analysis Ta 218.It Sy __nosanitizeaddress Ta 219.It Sy __nosanitizememory Ta 220.It Sy __nosanitizethread Ta 221.It Sy __nostackprotector Ta 222.It Sy __guarded_by(x) Ta 223.It Sy __pt_guarded_by(x) Ta 224.El 225.Ss Emulated Keywords 226As C evolves, many of the old macros we once used have been incorporated into 227the standard language. 228As this happens, we add support for these keywords as macros for older 229compilation environments. 230Sometimes this results in a nop in the older environment. 231.Bl -column "---------------" 232.It Sy Keyword Ta Sy Description 233.It Sy _Alignas(x) Ta 234.It Sy _Alignof(x) Ta 235.It Sy _Noreturn Ta Expands to 236.Dq [[noreturn]] 237in C++-11 and newer compilation environments, otherwise 238.Dq __dead2 239.It Sy _Static_assert(x, y) Ta Compile time assertion that 240.Fa x 241is true, otherwise emit 242.Fa y 243as the error message. 244.It Sy _Thread_local Ta Designate variable as thread local storage 245.It Sy __generic Ta implement _Generic-like features which aren't entirely possible to emulate the _Generic keyword 246.It Sy __noexcept Ta to emulate the C++11 argument-less noexcept form 247.It Sy __noexcept_if Ta to emulate the C++11 conditional noexcept form 248.It Sy _Nonnull Ta 249.It Sy _Nullable Ta 250.It Sy _Null_unspecified Ta 251.El 252.Ss Support Macros 253The following macros are defined, or have specific values, to denote certain 254things about the build environment. 255.Bl -column "---------------" 256.It Sy Macro Ta Sy Description 257.It Sy __LONG_LONG_SUPPORTED Ta Variables may be declared 258.Dq long long . 259This is defined for C99 or newer and C++ environments. 260.It Sy __STDC_LIMIT_MACROS Ta 261.It Sy __STDC_CONSTANT_MACROS Ta 262.El 263.Ss Convenience Macros 264These macros make it easier to do a number of things, even though strictly 265speaking the standard places their normal form in another header. 266.Bl -column "---------------" 267.It Sy Macro Ta Sy Description 268.It Sy __offsetof(type,field) Ta 269.It Sy __rangeof(type,start,end) Ta 270.It Sy __containerof(x,s,m) Ta 271.El 272.Ss ID Strings 273This section is deprecated, but is kept around because too much contrib software 274still uses these. 275.Bl -column "---------------" 276.It Sy Macro Ta Sy Description 277.It Sy __IDSTRING(name,string) Ta 278.It Sy __FBSDID(s) Ta 279.It Sy __RCSID(s) Ta 280.It Sy __RCSID_SOURCE(s) Ta 281.It Sy __SCCSID(s) Ta 282.It Sy __COPYRIGHT(s) Ta 283.El 284.Sh Supported C Environments 285.Fx 286supports a number C standard environments. 287Selection of the language dialect is a compiler-dependent command line option, 288though it is usually 289.Fl std=XX 290where XX is the standard to set for compiling, such as c89 or c23. 291.Fx 292provides a number of selection macros to control visibility of symbols. 293Please see the section on Selection Macros for the specifics. 294.Pp 295.Bl -tag 296.It K \*(Am R 297Pre-ANSI Kernighan and Ritchie C. 298Sometimes called 299.Dq knr 300or 301.Dq C78 302to distinguish it from newer standards. 303Support for this compilation environment is dependent on compilers supporting 304this configuration. 305Most of the old forms of C have been deprecated or removed in 306ISO/IEC 9899:2024 (“ISO C23”). 307Compilers make compiling in this mode increasingly difficult and support for it 308may ultimately be removed from the tree. 309.It St -ansiC 310.Dv __STDC__ 311is defined, however 312.Dv __STDC_VERSION__ 313is not. 314.Pp 315Strict environment selected with 316.Dv _ANSI_SOURCE . 317.It St -isoC-99 318.Dv __STDC_VERSION__ = 199901L 319.Pp 320Strict environment selected with 321.Dv _C99_SOURCE . 322.It St -isoC-2011 323.Dv __STDC_VERSION__ = 201112L 324.Pp 325Strict environment selected with 326.Dv _C11_SOURCE . 327.It ISO/IEC 9899:2018 (“ISO C17”) 328.Dv __STDC_VERSION__ = 201710L 329.Pp 330Strict environment selected with 331.Dv _C11_SOURCE 332since there are no new C17 only symbols or macros. 333.Pp 334This version of the standard did not introduce any new features, only made 335minor, technical corrections. 336.It ISO/IEC 9899:2024 (“ISO C23”) 337.Dv __STDC_VERSION__ = 202311L 338Strict environment selected with 339.Dv _C23_SOURCE 340though this is not yet implemented. 341.El 342.Pp 343For more information on C standards, see 344.Xr c 7 . 345.Ss Programming Environment Selection Macros 346Defining the macros outlined below requests that the system header files provide 347only the functions, structures and macros (symbols) defined by the appropriate 348standard, while suppressing all extensions. 349However, system headers not defined by that standard may define extensions. 350.Bl -column "---------------" 351.It Sy Macro Ta Sy Environment 352.It Dv _POSIX_SOURCE Ta St -p1003.1-88 including St -ansiC 353.It Dv _POSIX_C_SOURCE = 1 Ta St -p1003.1-88 including St -ansiC 354.It Dv _POSIX_C_SOURCE = 2 Ta St -p1003.1-90 including St -ansiC 355.It Dv _POSIX_C_SOURCE = 199309 Ta St -p1003.1b-93 including St -ansiC 356.It Dv _POSIX_C_SOURCE = 199506 Ta St -p1003.1c-95 including St -ansiC 357.It Dv _POSIX_C_SOURCE = 200112 Ta St -p1003.1-2001 including St -isoC-99 358.It Dv _POSIX_C_SOURCE = 200809 Ta St -p1003.1-2008 including St -isoC-99 359.It Dv _POSIX_C_SOURCE = 202405 Ta in the future IEEE Std 1003.1-2024 (“POSIX.1”) including ISO/IEC 9899:2024 (“ISO C23”) 360.It Dv _XOPEN_SOURCE = 500 Ta St -p1003.1c-95 and XPG extensions to St -susv2 including St -ansiC 361.It Dv _XOPEN_SOURCE = 600 Ta St -p1003.1-2001 and XPG extensions to St -susv3 including St -isoC-99 362.It Dv _XOPEN_SOURCE = 700 Ta St -p1003.1-2008 and XPG extensions to St -susv4 including St -isoC-99 363.It Dv _XOPEN_SOURCE = 800 Ta in the future IEEE Std 1003.1-2024 (“POSIX.1”) and XPG extensions to Version 5 of the Single UNIX Specification (“SUSv5”) including ISO/IEC 9899:2024 (“ISO C23”) 364.It Dv _ANSI_SOURCE Ta St -ansiC 365.It Dv _C99_SOURCE Ta St -isoC-99 366.It Dv _C11_SOURCE Ta St -isoC-2011 367.It Dv _C23_SOURCE Ta in the future ISO/IEC 9899:2024 (“ISO C23”) 368.It Dv _BSD_SOURCE Ta Everything, including Fx extensions 369.El 370.Pp 371When both POSIX and C environments are selected, the POSIX environment selects 372which C environment is used. 373However, when C11 dialect is selected with 374.St -p1003.1-2008 , 375definitions for 376.St -isoC-2011 377are included. 378.Ss Header Visibility Macros 379These macros are set by 380.Nm 381to control the visibility of different standards. 382Users should not use these, but they are documented here for developers. 383.Bl -column "---------------" 384.It Dv __XSI_VISIBLE Ta Restricts the visibility of XOPEN Single Unix Standard version. 385Possible values are 500, 600, 700 or 800, corresponding to Issue 5, 6, 7, or 8 386of the Single Unix Standard. 387These are extra functions in addition to the normal POSIX ones. 388.It Dv __POSIX_VISIBLE Ta Make symbols associated with certain standards versions visible. 389Set to the value assigned to 390.Dv _POSIX_C_SOURCE 391by convention with 199009 for 392.St -p1003.1-88 393and 199209 394.St -p1003.1-90 . 395.It Dv __ISO_C_VISIBLE Ta The C level that's visible. 396Possible values include 1990, 1999, and 2011 for 397.St -isoC-90 , 398.St -isoC-99 399and 400.St -isoC-2011 401respectively. 402In the future, 2023 will be used for ISO C2023. 403.It Dv __BSD_VISIBLE Ta 1 if the 404.Fx 405extensions are visible, 0 otherwise. 406.It Dv __EXT1_VISIBLE Ta 1 if the 407.St -isoC-2011 408Appendix K 3.7.4.1 409extensions are visible, 0 otherwise. 410.El 411.Sh Supported C++ Environments 412.Fx 413supports C++11 and newer standards fully. 414.Bl -tag 415.It ISO/IEC 14882:1998 ("C++98") 416.Dv __cplusplus = 199711 417.Pp 418The first standardized version of C++. 419Unlike K \*(Am R support in C, compilers dropped support for versions of 420the language prior to C++98. 421.It ISO/IEC 14882:2003 ("C++03") 422.Dv __cplusplus = 199711 423.Pp 424Note, this is the same value as C++98. 425C++03 did not define a new value for 426.Dv __cplusplus . 427There is no way, at compile time, to detect the difference. 428The standard resolved a number of defect reports and slightly 429expanded value initialization. 430Most compilers support it the same as C++98. 431.It ISO/IEC 14882:2011 ("C++11") 432.Dv __cplusplus = 201103 433.It ISO/IEC 14882:2014 ("C++14") 434.Dv __cplusplus = 201402 435.It ISO/IEC 14882:2017 ("C++17") 436.Dv __cplusplus = 201703 437.It ISO/IEC 14882:2020 ("C++20") 438.Dv __cplusplus = 202002 439.It ISO/IEC 14882:2023 ("C++23") 440.Dv __cplusplus = 202302 441.El 442.Pp 443.Fx 444uses llvm project's libc++. 445However, they are removing support for C++ prior to C++11. 446While programs can still build with earlier environments for now, these changes 447mean that 448.Fl pedantic-errors 449cannot be reliably enabled for standards older than C++11. 450.Sh HISTORY 451.In sys/cdefs.h 452first appeared in 453.Bx 4.3 NET/2 . 454