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