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