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